리소스 데이터 가져오기·내보내기
전송 컬럼·조회 범위·입력 검증·가져오기 결과를 확인합니다.
리소스 데이터 가져오기·내보내기
개발 데이터 만들기의 테넌트 소유 Example로 시작합니다. 일반 생성에 이름만 필요한 모델입니다. 조직 소유 리소스는 별도의 대상 검증이 필요합니다.
허용 컬럼 선언
src/Models/Example.php에 다음 import와 멤버를 추가하세요. 생성된 모델 전체를 교체하지 않습니다:
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Database\Eloquent\Builder;
use Nexia\Laravel\ResourceTransfer\Concerns\ExportImportable;
use Nexia\ResourceTransfer\TransferSchema;
// Add inside the generated tenant-owned Example model; retain its other traits.
use ExportImportable;
public static function transferColumns(TransferSchema $schema): TransferSchema
{
return $schema->field('name', 'workshop.example.name.label', required: true);
}
public static function transferExportQuery(?Authenticatable $actor = null): Builder
{
abort_if($actor === null, 403);
return static::query()->visibleTo($actor);
}기본 전송 범위는 테넌트입니다. 생성된 Controller의 meta.resource_transfer와 목록의 전송 연결을 유지하세요. 파일 형식 처리는 호스트가, 앱 데이터 처리는 앱이 담당합니다. 숫자 키·테넌트 ID·비밀값·다른 앱 필드를 수정 가능한 컬럼으로 노출하지 않습니다.
목록에서 확인
- 프로젝트
nexia dev로 동기화합니다. - 테스트 사용자에게 테넌트 범위
system.data.export·system.data.import와 Example 조회·생성 권한을 부여합니다. - Examples에서 소량을 내보내고 목록과 비교합니다. Policy로 숨긴 레코드가 파일에도 없어야 합니다.
- 화면에서 제공하는 가져오기 양식을 내려받고 예제 이름 하나를 넣습니다. 미리보기·실행 후 목록과 행별 결과를 확인합니다.
- 필수 이름 누락·권한 없는 사용자·중복 입력을 확인합니다. 가져오기는 생성 전용이며 upsert가 아닙니다.
TransferSchema::key()로 선언한 필드는 중복 판단에 사용합니다. 위 예제의name은 고유값으로 선언하지 않았습니다.
모델 선언의 기본 한도는 내보내기 10,000행·가져오기 1,000행입니다. 실제 한도와 형식은 응답 metadata를 확인하세요. 일부 행 성공은 전체 업무의 단일 트랜잭션 성공이 아닙니다. 행별 결과를 보고 수정합니다.
업무 규칙 유지
createFromImport(array $attributes)는 앱이 소유하는 생성 hook입니다. 검증·파생값·연관 쓰기가 필요하면 재정의해 API와 같은 업무 로직을 호출하세요. 기본 구현은 모델을 바로 생성하므로 HTTP Request에만 작성한 검증이 자동 실행되지는 않습니다.
법인 소유 모델은 transferScope()를 self::TRANSFER_SCOPE_LEGAL_ENTITY로 지정하고, transferExportQuery()를 허용 레코드로 제한하며, 가져올 레코드의 소유자는 신뢰된 범위에서 구해야 합니다. 파일의 임의 조직 ID를 믿지 말고 조직 간 접근을 검증한 뒤 기능을 공개하세요.
TransferSchema는 field·key·참조·내보내기 제한을 제공합니다. 사용자 정의 내보내기는 SDK ResourceTransferExportSourceContribution과 ResourceTransferExportSource 계약을 구현하며 조회 권한 검사가 여전히 필요합니다. 정확한 인자 형태는 설치된 SDK 정의에서 확인합니다.
앱 코드 없이 데이터 센터 목록 제공
데이터 센터 작업을 제공하는 앱은 목록 선언을 resources/data-migrations.json에
둡니다. providers, targets, stages 배열에 기존 DataMigration*Registration
필드를 사용하되, 작업의 loader는 제외합니다. 각 선언의 ownerAppKey는 자신의
앱 키로 지정합니다. 메타데이터에는 번역 키를, 기존 언어 카탈로그에는 번역값을 둡니다.
앱 등록 모듈에서도 같은 JSON을 가져와 기존 지연 로딩 함수를 연결하세요.
이름·권한·선행 작업·파일 안내를 별도로 중복 선언하지 않습니다.
런타임 내보내기는 이 파일과 참조한 번역값을 검토 대상 카탈로그에 포함합니다. 파일이 없으면 데이터 센터 기여가 없는 앱으로 선언됩니다. Core는 테넌트가 선택한 카탈로그를 한 번에 읽고 작업을 선택한 뒤 필요한 앱만 실행합니다. 목록 정보는 가져오기 권한을 부여하지 않으며 실행 시 기존 런타임·업무 권한 검사를 거칩니다.
선언을 변경한 뒤에는 앱을 다시 빌드하고 새 버전을 심사에 제출하세요. 기존에 승인된 카탈로그는 바뀌지 않으며 플랫폼 업데이트만으로 앱의 선언이 갱신되지는 않습니다. 목록 정보가 없는 이전 카탈로그에는 업데이트 안내가 표시됩니다. 새 앱 버전이 워크스페이스에서 사용 가능해진 뒤 선택 목록을 확인하세요.
업무 규칙이 있는 가져오기는 앱 파이프라인으로 처리하기
업무 검증이나 승인이 필요한 가져오기는 Nexia\ResourceImport\Contracts\ResourceImportPipelineContribution을 구현하고 resourceImportPipelines()에서 ResourceImportPipelineDefinition을 반환합니다. 각 정의에 리소스 키, 전송 스키마, 앱 소유 핸들러 클래스, 권한과 지원 파일 형식을 선언합니다. 핸들러는 ResourceImportPipeline의 receive, validateRows, apply, retry를 구현합니다.
권한 검사, 트랜잭션, 중복 확인과 업무상 거절은 핸들러에 유지하세요. 거절된 행을 배치 결과에 표시하고 일반 생성 호출로 우회하지 않습니다. 같은 멱등 키로 동일한 파일·매핑·형식을 receive하면 기존 배치를 반환해야 하며, 내용이 다르면 충돌로 처리합니다. apply는 검증을 마치고 적용 가능한 배치만 반영합니다.
워크스페이스의 데이터 마이그레이션 선택에 앱 파이프라인이 나타나는지 확인하고 정상 파일, 거절할 행, 중복 접수를 검사하세요. 로컬 선언이나 업로드 완료만으로 데이터 반영이 입증되지는 않습니다. 검증부터 적용까지 사용자와 조직의 권한 범위를 유지합니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
공통 가져오기 화면 복구
공통 Dataset Import 화면은 대기를 별도로 표시하고 준비와 검증 사이의 진행 순서를 유지합니다. 다시 업로드하면 업무 데이터를 저장하거나 삭제하지 않고 이전 검토 결과를 비운 뒤 파일 선택으로 돌아갑니다. 불러오기 실패 시 다시 시도할 수 있으며, SDK 호환성 오류는 앱 프런트엔드를 호환되는 버전으로 다시 빌드해야 합니다.
가져오기 단계별 실행
IncrementalResourceImportPipeline은 청크 가져오기 계약의 선택형 확장입니다. 호환되는 백그라운드 실행기는 validateNext, applyNext를 호출하고, 진행 중이라는 결과가 확정된 경우에만 다음 실행을 예약합니다. 기존 파이프라인과 큐를 사용하지 않는 호출은 기존 메서드를 유지합니다. 앱에서 사용하기 전에 PHP SDK, Core 마이그레이션·실행기, 네이티브 Runtime을 함께 적용해야 합니다. PHP SDK 0.10.16·Core 0.8.170과 대응 테넌트 마이그레이션·Manager 런타임이 필요합니다.
WorkCheckpointedResourceImportPipeline을 구현하는 파이프라인은 정의에 supportsWorkCheckpoint: true를 선언할 수 있습니다. 런타임은 서명된 작업 ID를 applyNextForWork에 전달합니다. 앱은 해당 ID의 완료 결과와 업무 행을 같은 트랜잭션에 기록하고, 같은 ID가 다시 오면 다음 청크를 실행하지 않고 그 결과를 반환해야 합니다. ID를 원래 배치·사용자·법인에 묶고, 외부 쓰기 결과가 불확실하면 재실행하지 말고 검토 상태를 유지하세요. 호환되는 SDK, Core, Runtime을 함께 적용해야 하며 이전 런타임은 기존 applyNext를 사용합니다.
모든 계획 조회가 읽기 전용이면 파이프라인 정의에 supportsReadOnlyPlan: true를 선언할 수 있습니다. 최초 검토, 이전 배치, 요약에 포함된 페이지를 모두 확인하세요. 조회는 런타임 DB의 일관된 스냅샷을 사용하며 다른 작업이 동시에 저장할 수 있습니다. 검토 행 초기화와 행 잠금은 쓰기 단계에서 처리하고, 조회에서 파일이나 외부 서비스 상태를 변경하지 마세요. 호환 PHP SDK·Core·앱 런타임을 적용한 뒤 선언하세요. 생략하면 기존 배정 방식을 유지합니다. 쓰기 충돌 그룹 선택과 재시도 처리 방법은 백그라운드 작업을 참고하세요.
validateNext는 SeekableResourceImportRowSource를 받습니다. slice($offset, $limit)로 필요한 행만 읽으세요. 반복자의 키는 전체 원본에서 0부터 시작하는 위치이며, __line은 원래 스프레드시트 행 번호를 유지합니다. 처리 위치는 앱의 영속 저장소에서 관리합니다. 한 단위의 결과와 처리 위치를 같은 트랜잭션으로 저장한 뒤, 작업이 남으면 new ImportPipelineStep(null, $processed, $total)을 반환합니다. 전체 검증 또는 저장이 끝났을 때만 최종 ImportBatchState를 담아 반환합니다. 진행량에는 여러 검증 순회가 포함될 수 있습니다.
중복 검사는 파일 전체를 기준으로 유지하고, 검증 도중의 배치는 저장할 수 없게 해야 합니다. 매 실행에서 사용자, 회사, 매핑, 원본의 동일성을 확인합니다. 저장할 때는 업무 데이터와 저장 위치를 원자적으로 기록하고, 검토했던 참조가 여전히 유효한지 다시 확인합니다. 응답이 유실되거나 결과가 불확실하면 검토 대상으로 중단하며, 실행기가 안전하다고 가정해 재실행하지 않습니다. 취소는 다음 처리 단위를 막으며 이미 저장된 업무 행을 되돌리지는 않습니다.
실행기는 여러 호출에서 같은 매핑 원본을 유지하므로 지원 범위 안의 파일을 사용자가 나눌 필요가 없습니다. 이 계약 자체가 업로드·셀·메모리·보관 기간·전체 실행 시간 상한을 높이지는 않습니다. 출시 전에는 처리 단위를 넘는 중복, 저장 후 재개, 동시 재개, 권한 철회, 취소, Runtime 변경, 응답 유실을 검증하세요.
처리 결과 페이지 조회
ResourceImportPipelineDefinition에 resultRowsPath: '/api/my-app/imports/{batch}/result-rows'를 선언할 수 있습니다. 앱의 GET 경로는 status(all, ready, create, update, unchanged, error, conflict, skipped, not_processed), page(1부터), per_page(최대 100), 이관의 법인을 받아 {data, total, page, per_page}를 반환합니다. data는 ImportRowDisposition::toArray()와 같은 행 구조입니다. 요청마다 현재 사용자·법인·원래 배치 소유자를 확인하고, 앱에 보존한 전체 결과에서 요청한 페이지만 읽으세요. 미리보기인 rowDispositions의 크기를 늘리지 않습니다. 호스트는 현재 카탈로그의 경로만 사용하며 원래 실행자에게만 결과를 공개합니다. 필드를 선언하기 전에 이를 지원하는 SDK와 Runtime을 적용해야 합니다.
저장이 중단된 결과를 제공하려면 result_phase=applied 요청을 받고 응답에 result_phase: "applied"를 포함합니다. 저장이 확정된 행에만 create/update, 제외가 확인된 행에만 skipped, 반영되지 않았음이 확인된 행에만 not_processed를 사용하세요. 결과가 불확실한 쓰기를 성공이나 미반영으로 추측하지 마세요. Core는 이 확인 표시가 없는 부분 결과를 반영 내역으로 표시하지 않습니다. 결과는 기존 구간 트랜잭션에 기록하고 조회는 요청할 때만 수행해 저장을 지연시키지 않습니다.
dispositionCounts['not_processed']는 0이어도 포함해야 합니다. 이 값의 존재는
실패 단계의 집계가 미리보기 예정 수량이 아닌 확정된 처리 결과임을 나타냅니다.
과거에 상세 사유를 기록하지 않은 제외 행의 사유를 추측해 덮어쓰지 않습니다.
페이지 결과에는 음이 아닌 정수 rows, saved, unchanged, skipped, errors,
conflicts, not_processed와 불리언 stopped를 가진 summary를 포함할 수
있습니다. Core는 전체 행 본문을 로드하지 않고 보관된 결과 화면의 집계를 갱신합니다.
가져오기 진행 위치 저장과 재개
호스트는 실행 결과가 불확실한 작업을 체크포인트만으로 자동 재실행하지 않습니다. 작업 ID별로 결과를 기록하는 앱은 같은 ID의 요청에 기존 결과를 반환하고 업무 데이터를 다시 쓰지 않아야 합니다.
파이프라인을 활성화하기 전에 저장된 체크포인트 사이 재시작, 구간 간 중복, 적용 재시도, 권한 회수, 취소, 다른 배치 접근 거부와 응답 유실을 검증하세요. 진행 중 체크포인트는 검증 완료 배치가 아니며, 후속 작업 접수도 업무 완료가 아닙니다. 위 단계별 실행·결과 페이지 계약을 사용하고 사용자·조직·원본의 동일성을 유지합니다.
발행된 PHP 계약과 PHP SDK 0.10.16 변경 내역을 확인하세요. 기존 동기 파이프라인은 계속 지원하며, 새 계약이 업로드 한도를 높이지는 않습니다.
앱이 제공하는 검토 복구 동작
renderReferenceReview에 전달되는 선택적 onBlockedReviewActionChange 콜백으로 기준정보 생성·수정 동작을 제공할 수 있습니다. { label, disabled, onClick }를 전달하고 앱 화면과 동일한 처리 중 상태 및 권한 조건을 사용하세요. 복구 동작이 없거나 검토 화면이 종료되면 null로 해제합니다. 기준정보 수정 후 검토를 다시 실행해야 하며 이 콜백이 쓰기를 허용하거나 미해결 행을 저장 가능하게 만들지는 않습니다. 기존 앱은 생략할 수 있습니다. 이 초안 확장은 대응하는 React SDK 계약과 Core 호스트가 필요하므로 호출 앱을 출시하기 전에 호환되는 공개 버전을 적용하세요.
전체 검토·결과 목록
확장된 결과 페이지 제공자는 응답의 available_statuses로 지원하는 조회 조건을
알립니다. 기존 조건 외에 all, ready(create와 update의 합집합), create,
update를 제공할 수 있습니다. 이는 조회 조건이며 새로운 행 상태가 아닙니다.
응답 행은 원래 상태를 유지하고, 건수와 페이지는 미리보기를 넘어 전체 권한 있는
배치를 포함해야 합니다. 이 필드가 없는 제공자에는 기존 필터를 유지합니다.
이관 전 ready는 이관 가능한 행, 이관 후에는 저장된 행입니다. 미처리 행을
저장 완료로 표시하지 않습니다. all을 포함한 모든 조건에서 배치 소유자와
현재 법인 권한을 다시 확인해야 합니다.
공통 검토 화면은 ‘변경사항 검사’와 ‘이관하기’를 구분합니다. 전체 검사 후 결과를 먼저 검토하고 이관을 시작합니다. 기준정보 변경은 재검사가 필요하며, 최종 확인에서 오류로 제외할 행을 안내하고 동의받습니다. 이 확인은 앱별 업무 결정을 대신하거나 이관 불가능한 배치를 실행 가능하게 만들지 않습니다.
여러 페이지의 설정 선택 항목
대응하는 미출시 React SDK와 Core 호스트를 함께 적용하면
NxDatasetImportWorkspace의 renderPlanChoices에 선택적 loadAllChoices()가
전달됩니다. 현재 페이지 밖의 선택 항목이 필요한 설정 작업에서만 호출하고,
조회 중에도 현재 페이지와 입력 내용을 유지하세요. 반환값은 권한이 있는
choices, 현재 values, analyzedValues이며, 조회 도중 검토 상태가 바뀌면
실패합니다. 이전 요청의 응답을 새로 연 설정 창에 적용하지 말고, 실패하면
재시도를 제공하세요. paginatePlanChoices={false}로 전체 선택 목록을 표시해도
서버의 개별 조회 크기는 제한됩니다. 두 옵션은 쓰기 권한이나 최종 서버 검토를
대신하지 않습니다. SDK와 Core를 함께 적용한 후 사용하세요. 이전 호스트는
loadAllChoices를 제공하지 않을 수 있습니다.