App Package 구조

수정할 파일 찾기

App 하나는 독립 저장소이자 Composer 릴리스 단위입니다. App 패키지 만들기와 Resource 만들기를 마쳤다면 아래 표에서 수정할 곳을 찾으세요. 경로는 모두 App 루트 기준입니다.

바꿀 내용	파일·디렉터리
패키지 식별자·의존 버전 범위	`composer.json`
프런트엔드 peer 의존성·App 별칭	`package.json`
발견 위치·마이그레이션 경로	`src/WorkshopAppManifest.php`
저장 필드	`database/migrations/tenant/`, `src/Models/Note.php`
입력 검증·API 응답	`src/Http/Controllers/NoteController.php`
레코드 권한	`src/Policies/NotePolicy.php`
Resource 식별자·descriptor·permission·메뉴	`src/Contribution/Resources/NoteModule.php`
API Route	`routes/routes.php`
Resource 타입·Route 함수	`resources/js/resources/notes/note-resource-contract.ts`
상세·폼의 공통 필드 표현	`resources/js/resources/notes/note-information-schema.tsx`
페이지 상태·데이터 조회	`resources/js/resources/notes/surface/`
목록·폼·상세 조합	`resources/js/resources/notes/section/`
프런트엔드 등록	`resources/js/index.ts`
화면 라벨	`resources/lang/{locale}.json`
회귀 확인	`tests/`와 프런트엔드 테스트

Workshop/Note를 생성했을 때의 배치입니다. 기존 모든 App이 같은 내부 구성을 쓴다는 뜻은 아닙니다. 생성 근거는 app/Console/Commands/MakePackageResource.php와 stubs/package-resource/입니다.

한 기능에 연결된 부분 함께 바꾸기

필드를 추가하면 보통 저장 구조, 검증, 응답 타입, 화면을 함께 수정합니다. Descriptor에 필드만 선언해도 저장이나 폼 처리가 생기지는 않습니다. 데이터 모델과 마이그레이션 다음에 App 화면 만들기를 진행하세요.

App 내부 helper는 해당 기능 가까이에 둡니다. 비슷한 코드가 두 App에서 필요하다는 이유만으로 SDK에 넣지 않습니다. SDK 기능은 지속적인 플랫폼 책임을 표현해야 합니다. 다른 App의 데이터가 필요하면 App 간 연동 방식 선택하기를 확인하세요.

식별자와 발견 규칙

식별자	연결되는 대상
Composer 패키지 이름	의존성 선택·릴리스 설치
`app_key`	App 정체성·Route·permission 이름 공간
`app_table_prefix`	App 소유 테이블 이름
Resource key	Catalog·permission·참조·descriptor
Descriptor·event key	게시된 설정과 실행 중인 consumer

공개 key는 호환성 계약입니다. 라벨을 바꿀 때 key까지 바꿀 필요는 없습니다. 테이블 접두나 Resource key 변경에는 마이그레이션과 consumer 전환 계획이 필요하며, 일반적인 이름 정리로 처리하면 안 됩니다.

Contribution은 Manifest가 선언한 위치에서 발견합니다. 임의 폴더에 클래스를 넣는 것만으로 등록되지 않습니다. 생성기가 기본 위치를 준비하며, 새 contribution을 추가할 때는 확장 모델을 참고하세요. 메타데이터의 정확한 규격은 App Manifest 계약에 있습니다.

로컬 소스와 설치된 패키지

로컬 설정은 선택한 App 소스를 packages/ 아래에 둘 수 있습니다. 이는 편집 환경의 배치입니다. CI나 릴리스 호스트는 같은 패키지를 Composer로 vendor/에 설치할 수 있습니다. App 런타임은 어느 방식에서도 동작해야 합니다. Manifest 기준 상대 경로나 지원되는 SDK 메타데이터를 사용하고, Core 패키지 경로를 직접 조립하지 마세요. vendor/는 편집하지 않습니다.

PHP·프런트엔드·번역·마이그레이션은 하나의 패키지로 출시합니다. 버전 선택과 호스트 반영은 App 릴리스하기에 있습니다. 디스크에 소스가 있다는 사실만으로 Composer가 그 소스를 사용한다고 판단하면 안 됩니다.