설치 콘텐츠
테넌트 설치 라이프사이클과 초기화 상태, 그리고 테넌트 행을 만드는 콘텐츠 출처 셋입니다.
설치 콘텐츠
개발 fixture와 운영 설치 초기화는 SDK ResourceReferences로 이미 활성화된 App을 조회할 수 있습니다. 실행 요청자의 실제 읽기 권한을 적용하며, 설치 관리 권한만으로 업무 데이터 접근을 허용하지 않습니다. 운영 Seeder는 SDK Actor로 설치 요청자를 확인할 수 있습니다. 같은 설치 계획에서 아직 활성화되지 않은 App은 조회할 수 없습니다.
개발 fixture와 운영 설치 요청은 실행 시작부터 최대 1시간이며, 운영 계획 전체가 이 기한을 공유합니다. 개별 조회·SQL 잠금·온라인 SQL 실행 제한은 유지됩니다. 조회와 커밋 직전에 실행 권한을 재확인하고, 실패하면 진행 중인 fixture 또는 초기화 버전을 롤백합니다. 이전에 완료한 버전과 외부 시스템의 변경은 되돌리지 않습니다.
대응하는 Core·Manager·런타임 이미지와 콜백 라우팅 설정을 함께 적용해야 합니다. 임의 Seeder 클래스 실행이나 migrate --seed 같은 별도 개발 DB 명령에는 이 fixture 권한을 부여하지 않습니다.
App 개발자는 자기 App에 migration과 공개 SDK contribution을 제공합니다. 테넌트 설치 관리자가 카탈로그에서 설치하면 플랫폼이 필수 데이터를 준비하고 성공한 App만 사용할 수 있게 합니다. App 개발자가 Core를 실행하거나 다른 앱의 Seeder를 수동으로 실행할 필요는 없습니다.
데이터의 용도와 실행 시점
| 출처 | 실행 시점 | 만드는 것 | 선택 여부 |
|---|---|---|---|
| App migration | 설치·업데이트 | App 소유 스키마와 필요한 데이터 이행 | 필수 |
| App initializer | 설치·새 초기화 버전을 포함한 업데이트 | 업무에 반드시 필요한 최소 행 | 필요한 앱만 구현; 선언하면 자동 실행 |
| Copyable template | 사용자가 적용할 때 | 편집 가능한 테넌트 소유 사본 | 선택 |
| 개발 fixture | nexia db seed <key> 요청 | 폐기 가능한 테스트 데이터 | 선택 |
Descriptor·Catalog는 정의를 제공하며 선언 자체가 업무 데이터를 만들지는 않습니다. 권한과 기본 역할 등 플랫폼 정의의 반영은 호스트가 수행합니다.
설치와 실패 처리
플랫폼은 필수 의존성·게시/설치 가능 여부를 확인하고 선행 App부터 migration, 필수 초기화, 활성화를 진행합니다. App별 초기화 데이터와 완료 버전은 같은 transaction에 기록합니다. 실패한 App과 아직 준비되지 않은 후속 App은 활성화하지 않습니다. 다른 App에서 이미 완료한 작업까지 하나의 transaction으로 되돌린다고 가정하지 마세요.
| 초기화 상태 | 의미 |
|---|---|
pending | 초기화 대기 또는 진행 중 |
initialized | 필요한 초기화가 완료됨 |
failed | 실패 원인을 해결한 뒤 재시도 필요 |
설치가 활성이고 필수 의존성·초기화가 준비됐을 때만 해당 App을 노출합니다. 설치 자체가 사용자 권한을 부여하지는 않습니다. 테넌트 관리자가 역할을 배정합니다. 복구는 플랫폼 설치 흐름에서 재시도하며 설치 원장이나 DB 행을 수동 수정하지 않습니다.
이미 적용한 migration은 변경·삭제하지 않고 새 migration으로 이행합니다. 앱 제거·비활성화·CLI 연결 종료는 기존 migration·테이블·데이터 삭제를 의미하지 않습니다. 고객이 수정한 기본값도 업데이트로 덮어쓰지 않습니다.
App initializer
새 앱은 VersionedTenantAppSeederContribution의 appKey()와 versions(): array를 구현하여 일반 Laravel 시더를 버전별로 등록합니다. 개발은 nexia db seed, 신규 설치·운영 업데이트는 플랫폼 준비 단계에서 미완료 버전만 실행합니다. 버전마다 DB 변경과 완료 기록을 함께 커밋하며, 실패한 버전만 수정 후 재시도합니다. 완료한 코드 변경은 개발에서 경고하고 게시 검증에서 차단합니다.
필수 설치 콘텐츠에 연결 코드와 개발·복구·업데이트 예제가 있습니다. id·public_id는 모델이 자동 생성합니다. 기존 두 초기화기 계약은 이전 동작으로 유지하며 새 계약과 동시에 등록하지 않습니다.
Copyable template
CopyableTemplateContributionRegistry가 코드로 정의된 출처를 발견합니다. 데이터베이스 카탈로그가 아닙니다. CopyableTemplateFacade가 그것들을 현재 ApprovalFormPresetCatalog 어댑터와 결합합니다.
하나를 적용하면 테넌트 안 template_applications 원장에 출처가 기록됩니다.
| 원장 필드 | 내용 |
|---|---|
| App key | 소유 App |
| Template 키와 버전 | 불변 소스 정체성 |
| 범위 | tenant 또는 legal_entity |
| Legal Entity | null 가능 |
| 행위자 | 적용한 사람 |
| 결과 상태 | 성공 또는 실패 |
| 실패 이유 | 실패 시 |
| 생성된 Resource 참조 | 사본이 만들어낸 것 |
원장은 출처 기록일 뿐입니다. 결코 Template 소스 카탈로그가 되지 않고, 사본에 대한 이후 편집을 추적하지도 않습니다.
이것을 전제로 계획을 세우기 전에 알아둘 현재 제약이 둘 있습니다.
- Approval form preset은 테넌트 범위이므로,
nexia-apps:apply-template에--legal-entity를 넘기면 그것들에 대해 실패합니다. - Process Template은 이 경로를 아예 거치지 않습니다. 하나를 선택하면 저장되지 않은 BPMN 편집기 문서가 바뀌고, 평범한 정의 저장과 게시가 영속화와 짝 결정 배포를 소유합니다.
App은 Nexia\Templates\Contracts\CopyableTemplateContribution으로 Template을 공개합니다. templates()가 소스를 선언하고 apply()는 행위자와 선택적 Legal Entity를 담은 TemplateApplicationContext를 받습니다. 발견과 실행, 출처 원장은 호스트가 소유합니다.
데모 데이터
개발용 데이터는 App이 공개한 Nexia\Fixture\Contracts\FixtureContribution의
fixture key로 실행합니다. 필수 설치 데이터와 분리하며 설치 전제 조건으로 사용하지 않습니다.
App은 자기 데이터만 만들고 반복 실행 시 중복과 사용자 수정 덮어쓰기를 피해야 합니다.
다른 App의 소스나 임의 Seeder 클래스는 전달하지 않습니다.
현재 앱 폴더에서 실행합니다. CLI는 앱 DB 작업을 요청합니다. 아래 Console 개발 데이터 이력은 별도의 설치 앱 fixture 작업이며 식별자와 상태 조회 경로를 혼용하지 않습니다. 다른 설치 앱의 fixture는 Console을 사용하세요.
nexia db seed <fixture-key>
nexia db status프로젝트 콘솔의 개발 데이터에서 사용 가능한 fixture와 최근 20개 작업을 확인할 수 있습니다. 샌드박스가 만료돼도 기존 실행 이력을 볼 수 있으며, 결과 확인 필요 상태는 실제 데이터를 확인한 뒤 처리합니다. 이 화면을 열거나 새로고침해도 시딩을 실행하지 않습니다.
CLI에 로그인한 프로젝트의 활성 샌드박스에 실제 설치되어 동작 중인 App만 선택할 수 있습니다.
queued는 실행 요청이 접수된 상태이며 완료가 아닙니다. 실행 직전과 데이터 반영 전에
연결 권한·샌드박스 만료를 다시 확인합니다. fixture는 앱을 설치하거나 활성화하지 않습니다.
응답을 잃으면 CLI가 출력한 요청 ID를 --request-id <request-id>로 다시 사용합니다.
같은 요청은 실행 중이거나 완료됐다면 다시 시딩하지 않습니다. needs_review는
데이터 반영 여부 확인이 필요하다는 뜻입니다. 새 요청을 만들기 전에 플랫폼 관리자에게
확인을 요청하세요. 자동 reset이나 데이터 삭제로 복구하지 않습니다.
FixtureContext는 호스트가 복원한 행위자와 스칼라 식별자를 제공합니다.
App 간 연동 데이터는 공개 Resource Reference를 사용합니다. 이 명령은 설치된 App의
선언된 fixture를 실행하며 임의 class·파일 경로·SQL을 실행하지 않습니다.
어떤 기능이 데모 데이터 입력 뒤에만 동작한다면, 필수 행을 설치 initializer로 옮기세요.
오류
| 증상 | 원인 | 해결 |
|---|---|---|
app.installed:{key}가 요청을 거부 | 설치가 pending이나 failed, 또는 전제가 operational이 아님 | 플랫폼 설치 상태와 실패 원인을 확인한 뒤 재시도 |
| 행을 쓰기 전에 설치가 멈춤 | 전제 누락, 키 중복, 순환 | 전제 그래프를 수정하고 필수 App 설치 |
| 활성화가 데이터베이스 연결에서 실패 | Manifest 동기화가 엄격함 | 플랫폼 운영자에게 샌드박스 연결 점검 요청 |
| App이 설치됐는데 사용자에게 안 보임 | 그 권한을 담은 Role이 없음 | 관리자가 App Role을 만들고 배정 |
| Template에서 Legal Entity 대상 거부 | Template이 테넌트 범위 | 테넌트 전체 적용 흐름 사용 |
| 신규 테넌트에서 기능이 깨지고 데모 테넌트에서는 괜찮음 | 필수 행이 데모 데이터에 있음 | 설치로 옮기기 |
실제 사용
선택 콘텐츠는 App의 CopyableTemplateContribution에서 확인하세요. 선언은 사용할 양식을 나열하고 apply()는 전달받은 문맥에서 편집 가능한 테넌트 사본을 만듭니다.
관련 문서
- 필수 설치 콘텐츠 — 출처 셋 중에서 고르기
- Artisan 명령어 — 위 모든 명령의 시그니처와 범위
- App 릴리스하기 — 설치가 런타임에서 놓이는 자리
- 설치 오류 해결 — 실패한 설치 진단
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.