App SDK 사용하기
App에서 필요한 PHP 기능과 프런트엔드 API를 찾고 설치된 SDK로 사용합니다.
App SDK 사용하기
SDK로 플랫폼 기능을 호출하고 App의 Resource, 화면, 연동 기능을 등록합니다. 필요한 작업부터 찾아보세요. 설치된 SDK를 사용하는 데 SDK 소스 체크아웃은 필요하지 않습니다.
SDK Capability Index
Call은 공개 함수·컴포넌트 또는 호스트 서비스를 사용하고, Implement는 App이 공개 인터페이스를 구현하며, Extend는 공개 SDK 기반 클래스를 상속하고, Configure는 공개 상수나 호스트 옵션을 설정하며, Create는 DTO·enum·어댑터를 구성한다는 뜻입니다. Contribution은 Core가 탐색하는 App 구현이며, 주입해서 호출하는 PHP host contract와 구분합니다. /host, /testing, root는 아래 import 표의 경로입니다.
전체 API 조회는 SDK 계약, Contribution 계약, React 컴포넌트와 훅에서 이어집니다. 이 표는 대표 API를 고르는 색인입니다.
| 하려는 작업 | 대표 공개 API / import | 사용 방식 | Core가 제공하는 부분 | App이 구현·지정하는 부분 | 상세 레퍼런스 |
|---|---|---|---|---|---|
| App 등록 | Nexia\AppRuntime\AbstractPackageAppManifest | Extend | Manifest 탐색과 경로 로딩 | App 정체성과 Contribution 위치 | App Manifest 계약 |
| 테넌트 작업 인가 | Nexia\Laravel\Access\Contracts\ResourceAuthorization, Nexia\Tenancy\Contracts\TenantSettings, Nexia\Tenancy\Contracts\TenantRunner | Call | 권한 평가, 테넌트 설정과 테넌트 복원 | 권한 선언과 신뢰할 수 있는 호스트 경계가 제공한 actor로 행·동작 규칙 적용 | SDK 계약 |
| HTTP 경로 보호 | Nexia\Http\Middleware | Configure | 등록된 인증·설치 상태·조직 문맥 middleware | 경로의 middleware 조합과 업무 권한 검사 | HTTP 미들웨어 |
| 조직·사용자·Party 조회 | Nexia\Organization\Contracts\OrganizationDirectory, Nexia\Identity\Contracts\ActorDirectory, Nexia\Laravel\Identity\Contracts\PartyDirectory; /host: useOrganizationListScope, NxOrganizationTargetSelector | Call | 범위에 따른 조회와 조직 선택 UI | 읽기 권한과 범위 축 선택, 업무상 적격성 판단 | SDK 계약, React 컴포넌트와 훅 |
| Resource 목록·필터·정렬 제공 | Nexia\Contribution\Contracts\ResourceCatalogContribution, Nexia\Laravel\Resources\ResourceListFields; /host: ResourceTable, useResourceListParams | Implement / Create / Call | 카탈로그, 목록 어댑터와 공통 테이블 UI | Resource 정체성, 인가된 쿼리, 필드·필터·정렬 선언 | Resource 계약 |
| 참조·요약 조회 | Nexia\ResourceReference\Contracts\ResourceReferences, Nexia\AppDescriptors\Contracts\ResourceSummaries, Nexia\AppDescriptors\Contracts\ResourceSummaryContribution | Call / Implement | 소유 App으로 요청 전달과 보호 결과 처리 | 권한을 적용한 참조 해석과 안전한 요약 projection | Resource Reference, Resource 계약 |
| 인가된 Resource Composition 쿼리 제공 | Nexia\ResourceComposition\Contracts\CompositionQueryContribution, Nexia\ResourceComposition\CompositionSpec | Implement / Create | 사람이 사용하는 Dashboard의 Descriptor 검증·계획·쿼리 실행 | Provider의 행 가시성·필드 가림·alias 선언 | Resource 계약 |
| Navigation·Command Palette·Dashboard Widget 추가 | Nexia\Navigation\Contracts\NavigationContribution, Nexia\Palette\Contracts\PaletteCommandContribution, Nexia\Dashboard\Contracts\DashboardWidgetContribution | Implement / Create | 탐색, 권한 gate와 Shell 표시 | 목적지, 명령 처리와 Widget 선언·데이터 | App Menu 목적지 추가, Command Palette 검색, Dashboard Widget 추가 |
| 이벤트 게시와 Inbox 처리 | Nexia\Events\Contracts\EventPublisher, Nexia\Events\Contracts\InboxConsumer, Nexia\Events\Contracts\AppEventListeners, Nexia\Events\Contracts\ActorDelegatedAppEventListeners | Call / Implement / Create | 내구성 있는 전달, consumer 실행, 테넌트 gate를 적용한 listener 등록 | 이벤트 schema, handler, 멱등성, 명시적 위임 actor 권한 | 이벤트와 비동기 작업 처리하기, SDK 계약 |
| 비동기 작업 추적과 Mutation 알림 | Nexia\AsyncWork\Contracts\BackgroundOperationStore, Nexia\Mutation\Contracts\MutationPublisher, Nexia\Mutation\MutationMatcher; /host: useResourceProjectionChange | Call / Create | Actor 소유 진행 상태와 commit 이후 브라우저 갱신 신호 | 실행 인가, 트랜잭션, 재시도 규칙과 정확한 식별자 | SDK 계약 |
| 첨부 목록·파일 읽기·업로드 | Nexia\Attachments\Contracts\AttachmentDirectory, Nexia\Attachments\Contracts\AuthorizedFileReader, Nexia\Attachments\Contracts\AttachmentStore; /host: useUploadFile, useUploadAttachment, NxFileDropzone | Call / Create | 인가된 파일 접근, 저장, 업로드 프로토콜과 공통 입력 UI | Resource target, 업로드 ability와 업무 변경 인가 | SDK 계약, React 컴포넌트와 훅 |
| 공통 Import·Export 사용 | Nexia\ResourceTransfer\Contracts\ResourceTransferExportSourceContribution, Nexia\ResourceImport\Contracts\ImportRecipeContribution, Nexia\ResourceImport\Contracts\ResourceImportPipelineContribution; /host: NxResourceTransferActions, NxResourceImportDialog, NxDatasetImportWorkspace, NxDatasetExportWorkspace | Implement / Call | 파일 형식, 업로드, mapping, preview, orchestration, polling과 공통 UI | Schema, 권한, scope filtering, export rows, 검증, 업무 저장과 retry 규칙 | Resource Transfer |
| 데이터 마이그레이션 화면 구성 | Nexia\DataMigration\Contracts\DataMigrationRunRecorder; /host: dataMigrationRegistry, useDataMigrationBackgroundOperation | Call / Create | Stage 레지스트리, 임시 작업 polling과 내구성 있는 실행 근거 | Target·stage 등록과 인가된 마이그레이션 실행 구현 | React 컴포넌트와 훅, SDK 계약 |
| Approval 제출·Process 실행 | Nexia\Approval\Contracts\ApprovalHost, Nexia\Process\Contracts\ProcessRuntime; /host: approvalComposerBusinessFormRegistry, processUserTaskFormRegistry | Call / Implement | 결재 생명주기와 Process 실행 | 업무 binding, work handler, 폼과 업무 인가 | 전자 결재 계약, 업무 프로세스 계약 |
| 문서·전자서명·직인·PDF 자산 사용 | Nexia\Signature\Contracts\SignatureHost, Nexia\Signature\Contracts\SignatureDocumentHost, Nexia\OfficialSeal\Contracts\OfficialSealUseService, Nexia\Documents\Contracts\PdfFontProvider | Call / Implement / Create | 서명 orchestration, 보호된 직인 사용과 로컬 PDF 글꼴 | 문서 데이터 provider, 업무 binding과 인가된 콘텐츠 | 전자 서명 계약, SDK 계약 |
| Setup Plan 태스크 기여 | Nexia\Setup\Contracts\SetupTaskContribution, Nexia\Setup\Contracts\SetupTaskEvaluator | Implement / Create | 태스크 탐색, 평가 orchestration과 Setup UI | 태스크 선언, 완료 기준과 업무 evaluator | Setup 태스크 기여 |
| Copyable Template·Fixture·Feature Guide 제공 | Nexia\Templates\Contracts\CopyableTemplateContribution, Nexia\Fixture\Contracts\FixtureContribution, Nexia\Guidance\Contracts\FeatureGuideContribution | Implement / Create | Template 선택, fixture 문맥과 guide 탐색·표시 | 복사 로직, 폐기 가능한 App 레코드와 guide 단계 | 설치 콘텐츠, Contribution 계약 |
| 폼·테이블 구성 | /host: NxFormField, NxResourceInformationForm, ResourceTable | Call / Create | 접근성 입력 UI, schema 렌더링과 테이블 동작 | 필드 선언, 값, 검증과 인가된 저장 handler | React 컴포넌트와 훅 |
| 캘린더·스케줄러·차트 표시 | /host: NxCalendar, NxResourceScheduler, NxBarChart, NxLineChart | Call / Create | 호스트 렌더러와 상호작용 | 인가된 일정·Resource·series와 동작 callback | React 컴포넌트와 훅 |
| Inspector·Work Tab 열기 | /host: resourceInspectorAdapterRegistry, ResourceInspectorPanel, useOpenResourceWorkTab, useMarkTabDirty | Call / Create | Inspector 스택, 탭 이동과 미저장 상태 | App 어댑터 등록, 경로 식별자와 dirty 상태 | React 컴포넌트와 훅 |
| 토스트·오류 파싱·포맷·debounce 사용 | /host: useMessage, parseMutationFormError, useDateTimeFormatter, useDebouncedValue; root: formatNumber | Call | 메시지 UI, 오류 매핑과 날짜·시간 문맥; 순수 숫자 헬퍼는 SDK 제공 | 피드백 문구, 필드명, 값, locale과 debounce 지연 | React 컴포넌트와 훅 |
| 공개 경계로 테스트 작성 | Nexia\Testing\Contracts\HostTestStore; /testing: appTestServer, appTestI18n | Call / Create | 테스트 전용 fixture와 설정된 프런트엔드 harness | App 시나리오, assertion과 요청 handler | App 테스트하기 |
공개·바인딩·사용 가능 여부 구분
SDK에 심볼이 공개되어 있다는 것은 import할 수 있다는 뜻입니다. PHP 서비스는 Core container binding이, /host의 위임 API는 Core의 resources/js/app-sdk/configure-host.ts 설정이 별도로 필요합니다. DTO·enum·순수 헬퍼에는 서비스 binding이 필요하지 않습니다. /host에서 SDK가 조합하는 헬퍼는 각각의 전용 binding 대신 설정된 API·훅을 사용합니다.
Binding이 있어도 현재 tenant/user의 사용 권한을 보장하지 않습니다. App 설치·운영 상태, tenant·actor 문맥, 조직 범위와 실행 시점 권한을 각각 충족해야 합니다. TenantRunner는 actor를 복원하지 않으며 UI 권한 조회도 서버의 변경 인가를 대신하지 않습니다.
Import·Export 기반 재사용
App은 위 Contribution과 UI를 연결해 공통 Import·Export 기반을 그대로 사용할 수 있습니다. Core가 파일 형식·업로드·mapping·preview·orchestration·polling·공통 UI를 제공하고, App은 schema·권한·범위 필터·내보낼 행·검증·업무 저장·재시도 규칙을 제공합니다. Recipe는 선언된 Resource action을 통해 저장하며, 자체 batch lifecycle이나 retry가 필요하면 pipeline을 선택합니다. 연결 절차와 세부 계약은 Resource Transfer를 따르세요.
PHP 기능 호출
Composer 패키지 amuzcorp/nexia-app-sdk-laravel의 네임스페이스는 Nexia\*입니다.
Laravel이 생성하는 클래스에는 인터페이스를 주입하세요. 이미 테넌트 문맥이 복원된
요청에서는 컨테이너로 직접 조회할 수도 있습니다.
use Nexia\Tenancy\Contracts\TenantSettings;
$timezone = app(TenantSettings::class)->businessTimezone();현재 테넌트의 업무 시간대를 반환합니다. 설정을 읽는 구현과 테넌트 문맥은 호스트가 제공하므로 App이 Core 설정 테이블을 조회할 필요가 없습니다. 바인딩을 찾지 못한다면 설치된 호스트가 해당 SDK 기능을 지원하는지 확인하세요.
프런트엔드 import 선택
| Import 경로 | 용도 |
|---|---|
@nexia/sdk | 공용 타입, 값, 순수 헬퍼 |
@nexia/sdk/host | 호스트에 연결된 컴포넌트, 훅, 레지스트리, api |
@nexia/sdk/testing | 테스트 호스트의 요청 모킹과 언어 설정 |
import { WorkSurface } from "@nexia/sdk/host";
export default function Overview() {
return <WorkSurface>App content</WorkSurface>;
}호스트 바인딩이 설정된 NEXIA 안에서 등록한 화면을 여세요. 등록 방법과 peer dependency는 React 컴포넌트와 훅, 첫 화면까지의 작업은 App 패키지 만들기에서 이어집니다.
호출·구현·생성 구분
- 호스트 기능 호출: 인터페이스를 주입하면 호스트 구현이 실행됩니다.
TenantSettings,ResourceAuthorization,SignatureHost가 여기에 해당합니다. - Contribution 구현: App 클래스가 공개 인터페이스를 구현하고 선언을 반환합니다. Core가 Manifest의 탐색 위치에서 클래스를 찾아 평가합니다. Contribution 계약을 참고하세요.
- 값 생성과 헬퍼 사용: DTO와 enum을 만들거나 모델 어댑터를 상속하고 순수 헬퍼를 호출합니다. 값 객체를 생성할 때는 서비스 바인딩이 필요하지 않습니다.
필요한 API가 보이지 않을 때
설치된 패키지의 export와 해당 참조 문서부터 확인하세요. App 고유 기능은 App에 두고,
App 간 연동에는 Resource Reference나 공개 이벤트를 사용합니다. 플랫폼 기능이 실제로
없다면 호스트와 SDK가 함께 지원한 이후에 소비할 수 있습니다. App\*, Core 프런트엔드
alias, 다른 App 구현을 import해 우회하지 마세요.
SDK 자체를 변경하는 작업에만 로컬 SDK checkout을 선택합니다. 로컬 설정을
마친 뒤에는 task apps:add PACKAGES=app-sdk로 추가하세요. 이 명령은 저장된 패키지 선택을 보존하고 Composer·frontend 로컬 overlay를 준비합니다. 소비자는 게시된 Laravel·React 패키지를 사용합니다.