App 화면 만들기
생성된 Note 화면을 SDK 컴포넌트로 수정합니다.
App 화면 만들기
기본 Note 목록은 name을 주요 컬럼으로 사용합니다. resources/js/resources/notes/surface/NoteListSurface.tsx에서 라벨·너비·표현을 수정하세요. Inspector 연결을 유지하도록 기존 ResourcePrimaryCell과 행 선택을 보존합니다.
상태 필드와 enum은 기본 생성하지 않습니다. 업무에 필요할 때 migration·검증·타입·화면을 함께 추가하세요.
화면을 만들기 전에 프런트엔드 SDK와 실행 예제를 확인하세요. 요구사항을 충족하는 공개 호스트 공통 컴포넌트와 사용 방식을 우선 사용하고, 제공되지 않는 경우에만 직접 UI를 만듭니다. 설치된 SDK 버전을 확인하고 로딩·빈 결과·오류·권한 상태를 유지하세요.
확인
목록에서 읽을 수 있는 행을 선택해 Inspector·상세·수정을 확인하세요. 조회 권한이 없는 사용자는 접근이 거부되어야 합니다. 새 필드는 데이터 모델과 마이그레이션을 따라 추가합니다.
파일별 책임
| App 루트 기준 위치 | 담당 |
|---|---|
resources/js/resources/notes/note-resource-contract.ts | 레코드 타입, 권한 키, ResourceRef, Route 함수 |
resources/js/resources/notes/surface/ | 질의, URL 상태, 오류, 권한, 저장 완료 |
resources/js/index.ts | App 프런트엔드 진입점과 발견 |
App 내부는 #app/, 공개 타입은 @nexia/sdk, 호스트 컴포넌트는 @nexia/sdk/host에서 가져옵니다. @/, @shell/, @shared/ui 등 Core alias는 App API가 아닙니다.
생성된 흐름 확장
Resource가 없는 업무 화면은 다음 명령으로 생성합니다.
nexia make page LeaveCalendar --label-ko '휴가 달력' --navigation-group operations --sort 100src/Http/Controllers/LeaveCalendarController.php, src/Contribution/Pages/LeaveCalendarModule.php, resources/js/pages/LeaveCalendarSurface.tsx, resources/js/pages/leave-calendar-queries.ts를 생성합니다. 지연 로딩 화면, App Route, 테넌트 전체 조회 권한, 메뉴와 번역을 등록하며 Model·migration·ResourceModule은 만들지 않습니다. 권한을 확인하는 업무 질의와 응답 타입을 구현하기 전에는 API가 501을 반환합니다.
기본 생성에는 /:id, /:id/edit Route와 LeaveCalendarRecordSurface.tsx가 포함됩니다. 상세·수정이 필요 없으면 --no-record를 사용하세요. 두 Route는 같은 컴포넌트를 지연 로딩하고 등록 시 mode: 'read' | 'edit'를 지정합니다. 조회는 텍스트, 수정은 공통 draft·미저장 보호·저장 흐름을 사용합니다. Controller의 show·update와 화면 전용 레코드·입력 타입을 실제 업무에 맞게 구현하세요. 수정 권한은 별도이며 draft 연결이 Agent 저장 권한을 부여하지 않습니다. 메뉴가 없는 연결 화면은 --no-navigation을 사용합니다.
API는 메뉴 노출과 별개로 권한을 검사합니다. --dry-run으로 검토할 수 있으며 기존 파일은 덮어쓰지 않습니다. Manifest의 pageElementsExtras()와 프런트엔드 등록의 overrides에 있는 // nexia:pages:end 삽입 지점을 유지하세요.
폼에는 필수 이름, 서버 필드 오류, 미저장 변경, 생성 완료와 화면 이동 처리가 있습니다. 단순 submit handler로 갈아엎지 말고 새 필드를 여기에 연결하세요. Resource ID와 Route 함수는 계약 파일에 둡니다. 캐시 키에는 테넌트와 목록의 선택 대상을 유지합니다.
목록은 meta.list_schema로 허용 필터·정렬을 받고 ResourceTable로 표 기능을 구성하며 응답 actions로 가능한 동작을 표시합니다. 로딩·빈 상태·오류/재시도·권한 상태를 보존하세요. 저장된 보기 설정의 식별자인 tableId는 번역하지 않습니다.
Legal Entity 목록의 useOrganizationListScope는 Route Surface에서 사용하고 선택기를 NxPageFrame.organizationScope에 둡니다. 생성 폼은 하나의 대상을 고르고 상세·수정은 저장된 소유자를 보여 줍니다. 표준 테넌트 기준정보에는 조직 선택기를 넣지 않습니다. 법인 소유 Resource는 생성된 목록 선택기와 폼의 법인 입력을 유지하세요. 기본 생성기는 운영조직 소유 Resource를 만들지 않습니다. 추가 조직 규칙은 서버 권한·조회 범위까지 함께 구현해야 합니다.
화면 SDK 사용법과 칼럼 추가 예제를 참고하세요. 앱에서 생성·수정·저장 후 새로고침까지 확인합니다.
프런트엔드 호환성 선언하기
React SDK 0.8.9부터 프런트엔드 호환성 요구사항을 명시적으로 기록합니다. peerDependencies의 @nexia/sdk에는 확인한 지원 범위를 선언하고 의존성 lock 파일을 커밋합니다. @nexia/sdk/vite의 nexiaAppConfig(import.meta.url)을 사용하는 생성된 Vite 설정을 유지하세요. 빌드하면 앱 스타일시트 목록과 프런트엔드 요구사항이 nexia-host.json에 기록됩니다. 이 생성 파일을 직접 고치지 말고 다시 빌드합니다.
공개 SDK 진입점에서 이름을 지정해 import하세요. 호스트 패키지의 namespace import나 동적 import는 필요한 export를 확정할 수 없어 거절될 수 있습니다. 앱 자체 화면의 lazy import는 계속 지원합니다. 빌드에 사용한 SDK와 워크스페이스 SDK가 모두 선언한 범위를 만족하고 필요한 export를 제공해야 합니다.
화면에 APP_FRONTEND_UPDATE_REQUIRED가 표시되면 요구 버전과 제공 버전을 비교하세요. 의존성·import를 수정해 다시 빌드하거나 필요한 플랫폼 버전이 제공될 때까지 기다립니다. 오류를 숨기려고 지원 범위만 넓히지 마세요. 지원 중단 예정 별칭인 allowsManualAppFallback은 permitsManualFallback으로, isRetryableHandoffFailure는 isRetryableFailure로 바꿉니다. 제거 버전은 아직 정해지지 않았습니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
레코드 저장 전 미디어 업로드
useUploadMedia(tenantId).mutateAsync(file)로 App 레코드를 저장하기 전에 호스트 검사 절차를 거쳐 파일을 업로드할 수 있습니다. 파일은 인증된 업로더와 App에 한정되며 업무 소유 대상이나 법인이 자동 지정되지 않습니다. 대상별 증빙을 조회하기 전에 권한을 확인하고 연결하세요. 보호 첨부파일에는 소유 대상이 필요합니다. 파일 hook 예제를 참고하세요. Core 0.11.35 이상이 필요하며 SDK API 변경은 없습니다.
이 백엔드 수정 배포 후에는 인증된 App 요청에서 AttachmentStore::fileForAttachment($publicId)로 업로드 메타데이터를 조회하고 업로더·파일 형식·크기·검사 상태를 확인하세요. 재개할 수 있는 대기 레코드를 저장하고 커밋한 뒤 해당 레코드의 morph type, 내부 키, 공개 ID로 대상을 구성해 attach($file, $target, $actor)를 호출합니다. 호스트가 저장된 대상의 업로드 권한을 확인하고 그 대상의 법인을 사용합니다. 첨부 성공 후 제출을 확정하고, 재시도에는 같은 파일과 대상을 사용하세요. 보호 PDF에는 소유 대상 지정 업로드를 사용하세요.