본문으로 건너뛰기
참조

설치 콘텐츠

테넌트 설치 라이프사이클과 초기화 상태, 그리고 테넌트 행을 만드는 콘텐츠 출처 셋입니다.

설치 콘텐츠

개발 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사용자가 적용할 때편집 가능한 테넌트 소유 사본선택
개발 fixturenexia 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 Entitynull 가능
행위자적용한 사람
결과 상태성공 또는 실패
실패 이유실패 시
생성된 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을 사용하세요.

코드 예시
Shell
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()는 전달받은 문맥에서 편집 가능한 테넌트 사본을 만듭니다.

관련 문서

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

원본 위치: docs/developers/content/ko/app-sdk/installation-content.md