런타임과 설치 라이프사이클

App이 나타나지 않으면 코드를 고치기 전에 아래에서 멈춘 단계를 찾으세요. 소스 체크아웃, Composer 설치, 테넌트 운영 상태, 행위자 접근 권한은 별개입니다. 처음 설정할 때는 App 패키지 만들기, 활성화·초기화·권한 진단에는 이 문서를 사용하세요.

개요

Composer에 존재하는 App은 사용자가 쓸 수 있는 App이 아닙니다. 그 사이에 다섯 단계가 있고, 각각 별개의 연산이며 실패 양상도 다릅니다.

단계별로 확인하세요. 소스나 설치 문제가 내비게이션 문제처럼 보일 수 있습니다.

단계	명령	범위	접근 권한을 주는가
패키지 소스	—	파일시스템	아니오
호스트 활성화	`nexia-apps:activate-package-app`	호스트 전체	아니오
테넌트 설치	`nexia-apps:install-tenant-app`	테넌트 하나	아니오
초기화	설치의 일부	테넌트 하나	아니오
Access Grant	관리자가 UI에서	행위자 하나	예

마지막 단계를 흔히 "Role 배정"이라 부르는데 그것은 UI 축약어입니다. 권한을 실어 나르는 레코드는 Access Grant이고, 행위자와 Role 하나 이상, Data scope, Subject population, 유효기간을 묶습니다. AccessGrant가 자신을 지속 권한의 유일한 출처로 문서화합니다. Role 멤버십만으로는 아무것도 부여되지 않습니다.

어떻게 맞물리는가: 단계별로

호스트 활성화

코드 예시

Shell

task artisan -- nexia-apps:activate-package-app workshop1

모든 패키지 정의의 전제 그래프를 검증하고, 패키지를 호스트 Composer 요구사항에 설치한 뒤 Permission 정의와 Core Role 정의를 동기화합니다.

속성	동작
전제 문제	누락·중복 키·순환이 있으면 호스트를 바꾸기 전에 활성화가 중단됨
데이터베이스	Manifest 동기화가 엄격 — 접근 불가면 명령이 실패
프런트엔드	`--build-assets` 없이는 실행 중인 Vite 재시작 필요
부여하는 것	권한 정의만. 권한은 아님

테넌트 설치

로컬 개발(APP_ENV=local)에서는 tenants:list의 대상 ID를 nexia_tenant에 지정합니다. 다음 명령은 게시 상태와 readiness를 바꾸지 않습니다. 운영에서는 카탈로그 게시와 private 테넌트 허용을 마친 뒤 nexia-apps:install-tenant-app을 사용합니다. App 릴리스하기를 따르세요.

코드 예시

Shell

task artisan -- nexia-apps:install-dev-app workshop --tenant="$nexia_tenant" --dry-run
task artisan -- nexia-apps:install-dev-app workshop --tenant="$nexia_tenant" --with-prerequisites12

App당 한 행을 tenant_app_installations에 쓰고, 운영 상태와 초기화 상태를 함께 둡니다.

상태	의미
`pending`	행은 썼고 initializer가 끝나지 않음
`initialized`	initializer 완료
`failed`	initializer 실패. 오류가 행에 기록됨

순서는 고정입니다. 전제 폐쇄 검증 → 선행 App부터 미적용 migration 실행 → pending 행 기록 → 테넌트 권한과 기준 Role 동기화 → 각 App의 initializer를 개별 트랜잭션으로 실행 → 계획을 initialized로 표시.

트랜잭션이 분리돼 있으므로 이미 커밋된 initializer는 되돌려지지 않습니다. 순서는 실패 지점에서 멈추고, 그 계획에서 아직 대기 중인 모든 항목이 함께 failed 표시됩니다. nexia-apps:repair-tenant-app은 미적용 migration을 포함한 일반 설치 계획을 다시 실행합니다. 미게시 로컬 App은 nexia-apps:install-dev-app을 다시 실행합니다.

Operational

App은 설치가 활성이고 초기화가 완료되고 모든 전제 App도 operational일 때만 노출됩니다.

App이 pending 또는 failed이면 app.installed:{app_key} 미들웨어가 요청을 거부합니다. PHP 경로가 등록되어 있더라도 해당 테넌트에서는 보호된 경로와 내비게이션, descriptor, 위젯을 사용할 수 없습니다.

코드 소유와 영속성

제품 선언은 코드 소유로 남지만 contribution discovery에는 별도의 영속 build artifact가 있습니다.

영속 제품 상태	생성되거나 코드 소유인 runtime surface
권한 정의	contribution interface-to-class manifest
Core Role 정의	그 manifest를 통해 읽는 navigation item과 descriptor
`tenant_app_installations` 행	색인된 class에서 파생되는 page element와 Route
initializer가 만든 행	로케일 카탈로그
템플릿이 만든 복사본	installed App map과 public Resource descriptor map

contribution source를 바꾼 뒤 생성된 두 map을 모두 다시 만드세요.

코드 예시

Shell

task artisan -- nexia-runtime:generate-app-map
task artisan -- nexia-runtime:refresh-runtime-caches
task artisan -- nexia-apps:activate-package-app workshop --build-assets123

그리고 장기 실행 프로세스를 재시작하세요. 큐 워커, Octane, Horizon, Vite입니다. 클래스가 생기기 전의 오토로드 맵을 쥔 프로세스는 그 클래스를 볼 수 없습니다.

경계 규칙

어느 가용성 단계도 권한을 부여하지 않습니다. 활성화·설치·초기화는 선언을 사용할 수 있게 할 뿐입니다. 보호된 목적지와 연산에는 해당 행위자의 유효한 권한이 필요합니다.

비활성화에는 순서가 있습니다. 의존하는 App이 활성인 동안 nexia-apps:deactivate-tenant-app은 거부됩니다.

전제는 라이프사이클만 제약합니다. prerequisite_apps는 설치와 활성화 순서에 영향을 줍니다. 전제 App의 데이터에 대한 접근을 주지 않습니다.

직접 수정하지 말고 repair하세요. 실패한 설치는 계획을 다시 실행하는 nexia-apps:repair-tenant-app으로 복구합니다. 설치 행을 직접 편집하면 initializer가 실제로 한 일과 상태가 어긋납니다.

App에 적용

packages/ 아래 폴더는 소스가 있다는 사실만 증명합니다. 테넌트 설치를 진단하기 전에 Composer가 패키지를 해석하고 생성된 App map에 포함했는지 확인하세요. 설치 후에는 초기화와 전제 App 상태를 확인하고 마지막으로 목적지가 요구하는 정확한 권한을 살펴봅니다. 권한을 요구하지 않는 개요와 보호된 Resource 경로는 가시성이 다를 수 있습니다.

App 라이프사이클

런타임과 설치 라이프사이클

개요

어떻게 맞물리는가: 단계별로

호스트 활성화

테넌트 설치

Operational

코드 소유와 영속성

경계 규칙

App에 적용

관련 문서