SDK 계약

아래에서 작업에 필요한 네임스페이스를 고르세요. 호출은 호스트 기능 주입, 구현은 App Contribution 게시, 생성은 값·헬퍼·어댑터의 직접 사용을 뜻합니다. 한 네임스페이스에 여러 종류가 함께 있을 수 있습니다.

호스트 기능 사용

use Nexia\Tenancy\Contracts\TenantSettings;

final class ReportClock
{
    public function __construct(private TenantSettings $settings) {}

    public function timezone(): string
    {
        return $this->settings->businessTimezone();
    }
}1234567891011

테넌트 문맥이 복원된 상태에서 Laravel 컨테이너로 ReportClock을 생성하면 해당 테넌트의 업무 시간대를 반환합니다. Resource 권한 처리는 Resource 계약, 프런트엔드 import는 React 컴포넌트와 훅에서 찾으세요.

PHP 네임스페이스 맵

결과 또는 반환: 인터페이스와 구현

플랫폼이 동작을 소유하는 곳에서는 SDK가 인터페이스를 공개하고 플랫폼이 구현을 바인딩합니다. SDK 자신도 Nexia\Laravel\Models adapter와 그 모델 concern, 프런트엔드 프리미티브와 훅을 배포합니다. 플랫폼 소유 동작의 패턴입니다.

직접 binding된 host contract는 컨테이너에서 해석하세요. 위 표의 optional batch 계약은 별도 binding이 아닙니다. Nexia\Identity\Contracts\PersonProfileDirectory, Nexia\Identity\Contracts\PersonLoginInvitations, Nexia\Laravel\Identity\Contracts\PartyDirectory를 주입하고 반환된 구현이 대응하는 batch 인터페이스를 구현하는지 확인한 뒤 사용합니다. 현재 Core 구현은 세 batch 계약을 모두 지원합니다. 플랫폼 클래스를 타입힌트하거나 Eloquent 모델을 App API로 사용하지 마세요.

Nexia\Tenancy\Contracts\TenantIdentity, Nexia\Identity\Contracts\Actor, Nexia\Identity\Contracts\Party는 문맥이나 호출 결과로 전달되는 정체성 계약입니다. 독립적으로 주입할 서비스라고 가정하지 마세요. Contribution과 App provider는 App이 구현하고, 테스트 host binding은 테스트 환경에서만 설정됩니다.

Batch profile·Party directory는 caller가 이미 복원한 tenant context 안에서만 조회합니다. 전달하는 key나 email은 cross-tenant selector가 아닙니다. Batch 로그인 초대 상태는 현재 Actor와 Legal Entity key도 요구하며, 그 actor에게 초대 권한이 없으면 NotAuthorized를 반환합니다.

PersonPartyProvisioner::ensureForDirectorySubject($displayName, $email)은 App 중립 Party 계약을 반환합니다. 호스트는 그 이메일에 대응하는 단 하나의 모호하지 않은 active person Party를 재사용하며, 이미 user와 연결된 Party도 포함합니다. 그런 Party가 없을 때만 새 person Party를 만듭니다. App은 호스트 모델을 받지 않으며 이메일 기반 identity 수렴을 직접 다시 구현하지 않습니다.

RecentAuthentication::isFresh($actor, $withinMinutes)는 보호된 동작에 추가하는 증명입니다. 기존 operation permission, 행, scope, 상태 검사는 그대로 유지합니다. App이 생성 PDF에 폰트를 포함해야 할 때 PdfFontProvider::forLocale()은 호스트 소유 로컬 PdfFontAsset을 반환합니다. App은 Core filesystem 경로를 재구성하면 안 됩니다.

PartyDirectory::searchActivePeople($search, $limit, $excludedKeys)는 불투명 key, public id, 표시 label, 선택적 contact email을 가진 PersonDirectoryEntry option을 반환합니다.

ResolvedResourceReference는 공개 fields와 protectedValues()를 분리합니다. 보호 값은 context가 includeProtectedValues를 명시한 exact resolve() 또는 resolveMany()에서만 허용됩니다. Search는 보호 값을 거부하고 snapshot, debug 출력, PHP serialization에도 보호 값이 포함되지 않습니다. People은 이 경계로 payroll.bank-export 목적의 exact 요청에만 계좌 값을 반환하므로 People 전용 지급 계약을 SDK에 둘 필요가 없습니다. 같은 owner는 asOf와 effectiveThrough로 범위를 정한 workforce.effective-planned-schedule 목적에 안전한 유효 계획 schedule projection을 추가할 수 있습니다. Actor가 없는 consumer는 가짜 actor를 만들지 않고 공개 Event와 local projection을 사용합니다.

테넌트 권한 snapshot

TenantPermissionSnapshotAuthorizer는 여러 테넌트 범위 permission key를 하나의 App 중립 계약으로 평가합니다.

$user에는 현재 요청의 인증된 사용자를 전달합니다. 아래 Core 권한 둘은 테넌트 범위 호출 예시입니다. 실제 화면이 필요로 하는 테넌트 범위 권한 목록으로 바꾸세요.

use Nexia\Laravel\Access\Contracts\TenantPermissionSnapshotAuthorizer;

$snapshot = app(TenantPermissionSnapshotAuthorizer::class)->forPermissions($user, [
    'system.apps.read',
    'system.data.export',
]);123456

결과에는 요청한 모든 문자열 key가 원문 그대로 들어갑니다. 알 수 없거나 폐기된 permission, 운영 상태가 아닌 App의 permission, 테넌트 범위가 아닌 permission, 해석할 수 없는 subject는 모두 false이고 문자열이 아닌 입력은 무시합니다. 이 계약은 현재 ambient tenant만 사용하며 Legal Entity나 Operating Unit 인자를 받지 않습니다. 메뉴나 버튼처럼 읽기 전용 affordance를 렌더링할 때 사용하세요. 쓰기 요청은 실제 요청 경로에서 시점 권한 검사를 다시 수행해야 합니다.

AttachmentDirectory::listForTargets()는 AttachmentTarget 목록을 받아 actor에게 보이는 첨부 요약을 반환합니다. 파일 바이트를 읽는 계약은 아닙니다. AuthorizedFileReader::read()에는 filePublicId를 전달합니다. 복원된 tenant와 요청의 Legal Entity 문맥에서 actor 권한·격리·clean 상태를 검사하며, 부재·거부·경계 위반·clean 실패에는 null을 반환합니다.

AttachmentStore::createGeneratedFile()은 생성 파일을 저장하고 attach()는 Resource target에 연결합니다. exists()는 attachment public id의 target 소속을, fileAttached()는 file public id가 이미 연결되었는지를 확인합니다. 이 확인 자체가 중복 방지 제약이나 업무 변경 인가를 대신하지는 않습니다. App은 저장·연결 전에 업무 권한을 적용하고 중복 처리를 구현해야 합니다. downloadHrefIfAuthorized()는 actor가 읽을 수 있을 때만 URL을 반환합니다.

Import 전용 업로드는 AuthorizedImportFileReader::read(uploadIntentPublicId, resourceKey, legalEntityKey, actor)로 claim하고 읽습니다. 메타데이터 재인가나 큰 파일의 임시 사본 처리는 AuthorizedImportFileStore::claim(), find(), withLocalCopy()를 사용합니다. 이 두 계약은 일반 Resource 첨부 목록 API와 구분합니다.

Party 관계와 Resource Summary 조회도 actor에게 보이는 provider가 답할 수 없으면 projection을 반환하지 않으며, 호출자는 호스트 모델이나 공개 범위를 넓히는 이유를 받지 않습니다.

kernel에는 Nexia\Models 네임스페이스나 호스트 모델 facade가 없습니다. 좁은 Identity, Organization, Party, Installed Apps 계약을 사용하세요. 운영 App은 호스트 Eloquent 모델을 조회하거나 받지 않으며, Nexia\Testing\Contracts\HostTestStore는 테스트 전용입니다.

Mutation identity와 발행

MutationMatcher는 App 중립 재확인 조건입니다. Resource Catalog key와 lifecycle operation(Created, Updated, Deleted, Restored)을 지정하거나, semantic action key와 Succeeded만 지정합니다. 두 subject 종류를 섞을 수 없습니다. 한 matcher 안의 key와 operation은 OR 의미이고 선택적 resourceIds는 Resource matcher를 좁힙니다. Resource key, action key, Resource ID는 SDK, host header, Gateway, Shell 경계 전체에서 각각 UTF-8 최대 160 byte입니다.

호스트가 ResourceCatalogContribution으로 model에 연결된 모든 commit된 Eloquent lifecycle event를 자동 관찰합니다. 따라서 일반 생성형 Resource controller에는 save/delete 계측을 추가하지 않습니다. Bulk Query update처럼 model event를 우회하거나 Resource Catalog root가 없는 성공한 semantic action에만 MutationPublisher를 주입합니다.

use Nexia\Mutation\Contracts\MutationPublisher;
use Nexia\Mutation\MutationOperation;

$mutations = app(MutationPublisher::class);
$mutations->resourceChanged(
    'workshop.note',
    MutationOperation::Updated,
    $publicId,
);

$mutations->actionSucceeded('workshop.note.archived');1234567891011

업무 write가 성공한 뒤에만 publisher를 호출하세요. Tenant, actor, initiator, request, surface, correlation context는 호스트가 신뢰하는 runtime에서 파생하며 App 코드는 하나도 제공하지 않습니다. 현재 transaction이 commit된 뒤 발행하고, 활성 transaction이 없으면 즉시 발행합니다.

이 신호는 같은 브라우저의 대기를 깨우는 힌트이지 durable domain event, audit record, cache invalidation, 완료 결과가 아닙니다. Consumer는 항상 authoritative state를 다시 읽습니다. 다른 App이나 runtime이 신뢰성 있게 반응해야 한다면 Nexia\Events를 사용하세요.

App 간 접근

App 간 import와 패키지 의존성은 금지입니다. 예외는 없습니다. 지원되는 대안이 셋입니다.

ResourceRef는 모델을 import하지 않고 다른 App의 레코드를 지칭합니다. Core가 그것을 해석하고 행위자의 자격을 적용해 그가 볼 수 있는 것만 돌려줍니다. 정규 browser selector는 consuming Resource와 field도 요구하며 선언된 target, 목적, permission, owner availability를 검사한 뒤 dispatch합니다.

사람이 만든 Dashboard가 Resource 두 개를 함께 읽어야 할 때 Core는 어느 App도 다른 App을 import하게 하지 않고 기존 Resource 계약을 조합합니다. SDK는 App 중립 CompositionSpec wire DTO와 서로 같은 PHP·TypeScript validator만 게시합니다. Spec에는 의미적 Resource key, source alias, 서버가 발급한 relationship key, field, 제한된 filter, dimension, measure, 결과 shape만 들어갑니다. Table, model, SQL, 임의 expression, planner, executor 표면은 없습니다. Core는 live actor-filtered catalog로 key를 해석하고 query를 계획하고 실행할 때 권한을 다시 확인합니다. 이는 사람이 직접 쓰는 Dashboard 기능이며 App 또는 Agent authoring interface가 아닙니다.

표면이 없을 때

API를 추가하기 전에 설치된 패키지와 호스트 버전부터 확인하세요. 소스 체크아웃은 패키지 자체를 수정할 때만 필요합니다. App 고유 동작은 App에 두고 App 간 연동에는 Resource 계약이나 공개 이벤트를 사용하세요. 기존 API로 표현할 수 없는 플랫폼 작업이라면 기능을 요청하고 SDK와 호스트가 모두 지원한 뒤 소비합니다.

Core 클래스나 다른 App을 import하거나 vendor/를 수정하지 마세요. 기존 로컬 설정에 준비된 SDK 체크아웃을 추가할 때는 task apps:add PACKAGES=app-sdk를 사용합니다.

오늘 App 쪽 계약이 없는 기능

이 두 클래스는 SDK API가 아닙니다. Site Configuration은 실제 App이 공통 설정 화면에 선언형 항목을 기여해야 하는 사용 사례가 확인될 때만 별도 SDK 후보로 검토합니다. App 자체 설정 화면은 설정 페이지 추가를 따르세요. 설치 요구는 먼저 tenant migration과 필수 설치 콘텐츠, 선택적 Copyable Template, 운영자 준비 작업을 위한 Setup 태스크 기여로 해결할 수 있는지 판단합니다.

호스트 전용 표면에 대한 기존 패키지 import가 아직 남아 있다면 .nexia/coupling-baseline.json에 명시적 예외로 기록합니다. 깨끗한 App에는 파일이 없고, ratchet은 기록된 파일·심볼 쌍만 허용하며 그 밖의 참조를 거부합니다.

오류

App에 적용

설치된 SDK 네임스페이스와 호스트 바인딩을 함께 사용하세요. Resource 만들기의 생성 결과에서 모델, 권한, Contribution API가 연결되는 위치를 확인할 수 있습니다.

관련 문서

• HTTP 미들웨어 — App Route stack, 등록된 모든 별칭, 인자, 실행 순서, 거부 코드
• React 컴포넌트와 훅 — @nexia/sdk export 표면 전체
• App SDK 사용하기 — 경계가 이런 모양인 이유
• Contribution 계약 — 모든 contribution 인터페이스와 그 메서드
• 경계 위반 해결 — 거부된 import 고치기

prepare() 후 실제 바이트 출력 함수를 FileDeliveryAttempts::callback(attemptId, producer)으로 감쌉니다. 서버의 시작과 종료 결과를 기록하며, 응답 객체 생성만으로 전송 완료를 판단하지 않습니다. FileLifecycleRecorder는 제한된 식별·상황 메타데이터만 받고 권한은 부여하지 않습니다. 현황 관측과 보존 만료 대기 사건은 과거 다운로드나 바이트 삭제를 의미하지 않습니다.

기존 multipart 입력은 AuthorizedImportFileStore::receiveLocal()로 호스트 검증 절차에 연결합니다. discardUnbound()는 중복 업로드 거절 등으로 App 업무 기록에 연결하지 않은 새 입력에만 사용하며, 채택한 증거에는 호출하지 않습니다. 이 SDK 변경을 적용하는 자체 구현은 두 메서드와 전송 콜백을 제공해야 합니다.