필수 설치 콘텐츠
필수 App 행은 tenant migration으로 제공하고 host-only initializer와 구분하며 미적용 migration을 실행하는 설치 경로로 복구합니다.
App의 첫 업무 처리에 반드시 필요한 행만 기본 데이터로 제공합니다. 선택해서 쓰는 시작 데이터는 Copyable Template, 운영자가 직접 결정해야 하는 설정은 Setup 태스크 기여로 안내하세요.
필수 데이터 추가
- 데이터 모델과 마이그레이션에 따라 스키마를 만들고 Manifest에 테넌트 migration 경로를 공개합니다.
- 기본 행 없이는 업무가 불가능한 경우에만 별도의 데이터 migration을 만듭니다. App이 소유한 불변 고유 키를 기준으로 없는 행만 삽입하세요. 기존 사용자가 바꾼 값은 보존하고, 중간 실패 뒤 재실행해도 중복되지 않게 합니다.
- Resource 만들기를 따라 대상 테넌트에 App을 설치합니다. 설치 명령은 초기화 전에 App과 선행 App의 미적용 migration을 실행합니다.
packages/expenses/src/ExpensesAppManifest.php의 실제 경로 선언입니다.
public function tenantMigrationPaths(): array
{
return [__DIR__.'/../database/migrations/tenant'];
}이 코드는 migration 경로를 제공하는 사례이며 기본 행을 넣는 seeder는 아닙니다. 현재 initializer 인터페이스는 host의 App\AppRuntime에 있으므로 설치형 App에서 구현하거나 Core import로 가져올 수 없습니다.
결과 확인
새 테넌트에서 migration과 설치를 완료한 뒤 첫 업무가 수행되는지 확인합니다. 이미 수정된 설정이 있는 테넌트에서도 기존 값이 유지되고 중복 행이 생기지 않아야 합니다. 스키마·데이터와 설치 상태는 하나의 트랜잭션이 아니므로 각각 확인하세요. 테스트 컨텍스트는 App 테스트하기를 따릅니다.
실패한 단계 복구
| 명령 | 처리하는 일 |
|---|---|
tenants:migrate | Core와 설치 이력이 있는 App의 미적용 migration 실행(비활성 포함); 신규 App 설치나 설치 상태 복구는 하지 않음 |
nexia-apps:install-tenant-app | 미적용 App migration을 실행한 뒤 설치와 host 초기화 처리 |
nexia-apps:repair-tenant-app | 선행 App을 포함해 설치를 재계획하고 미적용 migration 실행; 완료된 migration은 재실행하지 않음 |
app/Console/Commands/RepairTenantApp.php는 --with-prerequisites를 지정해 install로 위임합니다. Host 초기화 트랜잭션은 app/AppRuntime/TenantAppLifecycleService.php가 담당합니다. 현재 버전의 초기화가 성공했다면 repair마다 다시 실행되지 않습니다.
테이블이나 필수 행이 빠졌다면 migration을 수정해 적용합니다. 설치가 실패했다면 기록된 원인을 고친 뒤 repair를 실행하세요. 설치 상태를 직접 바꿔 오류를 숨기지 않습니다. 명령과 초기화 수명주기의 세부 계약은 설치 콘텐츠에 있습니다.
필수 데이터가 사용자 권한을 부여하지는 않습니다. 테넌트가 복사한 템플릿을 덮어쓰거나 demo 데이터를 넣지 말고, 사용자가 관리하는 레코드를 지우는 rollback도 피하세요.
신규 테넌트에는 Core 스키마만 준비합니다. 이후 tenants:migrate는 비활성 App을 포함해 설치 이력이 있는 App을 갱신하며, 비활성화는 테이블과 데이터를 보존합니다. 미게시 로컬 App의 설치·복구는 nexia-apps:install-dev-app <app-key> --tenant=<tenant ID> --with-prerequisites를 사용합니다. 일반 설치와 repair는 배포 정책을 계속 검사합니다.