Core 식별자를 외래키로 참조하기
허용된 Core FK 대상과 마이그레이션 작성, 저장 전 권한 검사를 확인합니다.
Core 식별자를 외래키로 참조하기
앱 테이블에서 일부 Core 식별자를 외래키로 참조할 수 있습니다. 외래키는 대상의 존재를 보장할 뿐 Core 테이블 조회나 해당 레코드 사용 권한을 부여하지 않습니다. 빠른 시작으로 앱 실행을 마친 상태에서 진행하세요. 파일 경로는 앱 루트 기준입니다.
참조 대상 선택
| 대상 테이블 | 참조 컬럼 | PostgreSQL 타입 | 의미 |
|---|---|---|---|
public.legal_entities | id | bigint | 법인 |
public.operating_units | id | bigint | 운영조직 |
public.parties | id | bigint | 사람·조직의 공통 식별자 |
public.sites | id | bigint | 사업장 |
public.users | id | bigint | 테넌트 사용자 |
현재 허용 목록은 위 컬럼뿐입니다. 각 테이블의 public_id UUID는 외부 식별자이며 FK 허용 대상이 아닙니다. Party는 직원 레코드가 아니고, 모든 사람이 User인 것도 아닙니다. 다른 앱 테이블이나 목록에 없는 Core 테이블까지 참조할 수 있다고 가정하지 마세요.
| 필요한 관계 | 저장·사용 방식 |
|---|---|
| 같은 앱이 소유한 테이블 | 앱 내부 FK와 인덱스 |
| 위 목록의 Core 식별자 | Backend에서 해당 SDK 계약으로 해석한 숫자 키 |
| 다른 앱의 업무 레코드 | 고정 App 키·Resource 키·공개 레코드 식별자와 인가된 Resource Reference. 테이블을 직접 join하지 않음 |
플랫폼은 앱 migration 실행 계정에 REFERENCES를 부여합니다. Core 테이블의 SELECT·INSERT·UPDATE·DELETE 권한은 부여하지 않습니다. 앱 런타임은 이 목록을 사용합니다. 호스트가 선택적 Nexia\Identity\Contracts\BatchActorDirectory를 구현하면 findByPublicIds()에 사용자 공개 ID를 전달해 표시 가능한 삭제되지 않은 사용자를 조회할 수 있습니다. 조회한 ActorDirectory에서 이 인터페이스를 확인하고, 이전 호스트에서는 findByPublicId()를 사용하세요. 결과 순서는 입력 순서와 다를 수 있으며, 단건 조회와 같은 디렉터리 권한 검사를 유지해야 합니다. 이 계약을 사용하기 전에 호환되는 SDK·Core·런타임을 반영하세요. ActorDirectory 소스
Nexia 제공 DB에서는 개발자가 직접 GRANT를 실행하지 않습니다. 개발자 로컬 DB에서는 nexia db local이 전용 DB에 ID 전용 참조 테이블과 앱 계정을 만듭니다. nexia db references 명령은 없습니다. 로컬 DB에서는 db reset과 db fresh를 사용할 수 없습니다.
SDK로 기본 정보 조회하기
User·Party·법인·운영조직·사업장의 기본 정보는 ActorDirectory, PartyDirectory, OrganizationDirectory, SiteDirectory로 조회합니다. 선택된 테넌트 안에서 공통 기본 정보를 읽을 수 있으며, 사용자 없이 실행되는 예약 작업에서도 사용할 수 있습니다. 기존 앱의 호출 코드를 바꿀 필요는 없습니다.
선택적 Nexia\Identity\Contracts\BatchCanonicalPartyDirectory를 사용할 수 있으면 findCanonicalByPublicIds()로 Party 공개 ID의 병합 이력을 단건 조회와 동일한 가시성으로 확인할 수 있습니다. 없거나 볼 수 없는 Party는 결과에서 빠지며 결과 순서는 입력과 다를 수 있습니다. 조회한 PartyDirectory가 해당 인터페이스를 구현하는지 확인하고 이전 호스트에서는 findCanonicalByPublicId()를 사용하세요. 사용 전에 호환 SDK와 앱 런타임을 반영해야 합니다. PartyDirectory 소스
Nexia 제공 DB에서는 격리 런타임이 제한된 읽기 전용 DB 뷰를 조회합니다. 개발자 로컬 DB에서는 인가된 Core 콜백으로 기본 정보를 조회합니다. 앱에서는 내부 뷰 이름이나 Core 모델에 의존하지 말고 SDK 계약을 계속 사용하세요.
기본 정보 조회는 업무 권한이나 다른 테넌트 접근 권한을 부여하지 않습니다. 비밀번호·토큰·원본 비공개 연락처 컬럼은 공개하지 않습니다. 이메일·개인 상세 검색과 소속 기반 사용자 선택은 기존 Core 인가 경로를 유지합니다. 업무 데이터 조회·수정에는 Resource Policy와 조직 대상 검사가 여전히 필요하며, 식별자가 조회된다는 이유로 해당 주체의 권한을 가진 것으로 판단하면 안 됩니다.
법인은 선택적으로 Nexia\Organization\Contracts\HasFunctionalCurrency를 구현할 수 있습니다. 구현된 경우 functionalCurrencyCode()와 functionalCurrencyMinorUnit()으로 설정된 기준통화와 소수 자릿수를 조회합니다. 설정이 없으면 두 값 모두 null일 수 있습니다. 선택적 인터페이스 여부와 값의 유무를 확인하고, 값이 없을 때 원화로 가정하지 마세요. 사용 전에 호환되는 SDK, Core, 앱 런타임을 함께 적용해야 합니다. 통화 설정은 환율 조회나 환전 기능을 제공하지 않습니다.
권한별 조직 대상 응답에서도 법인의 functional_currency_code와 functional_currency_minor_unit을 제공합니다. 이전 호스트와의 호환을 위해 두 필드는 없거나 null일 수 있습니다. 선택한 대상의 값을 화면 표시에 사용하고 저장 전에는 서버에서 통화를 다시 확인하세요.
디렉터리 모델 조회
기존 메서드별 대체 코드는 SDK 조회 API 전환표에서 확인하세요.
Nexia\Laravel\Directory의 Party, User, LegalEntity,
OperatingUnit, Site를 기본 Eloquent 조회와 조인에 사용합니다.
관리 DB의 뷰 또는 nexia db local이 준비한
디렉터리 스냅샷을 읽습니다. App 레코드를 조인할 때는 App의 레코드 정책을
먼저 적용합니다.
use Nexia\Laravel\Directory\Party;
$page = Party::query()
->where('organization', true)
->where('status', 'active')
->orderBy('display_name')
->orderBy('key')
->paginate(25);숫자 key는 App 외래 키에, public_id는 공개 참조에 사용합니다.
User::party(), LegalEntity::party(), OperatingUnit::parent()는
Eloquent 관계입니다. 조인할 때 모델 쿼리를 서브쿼리로 쓰거나 모델의
key를 기준으로 App 관계를 선언할 수 있습니다.
기존 플랫폼 조건을 적용하려면 User::activeForLegalEntity($entity),
OperatingUnit::forLegalEntity($entityKey, $asOf), Site::forLegalEntity($entityKey, $asOf),
Party::withRoles($actor, $roles)를 사용하고 일반 필터와 정렬을 이어서
추가합니다. 관련 권한 판단, Party 병합·연락처·관계 조회는 기존 호스트
계약을 사용합니다. 호환되는 Core·SDK·CLI를 사용하세요. 고객 관리 App DB는
위 디렉터리 계약으로 조회합니다.
User 모델의 display_label은 Party 표시명, 사용자 이름, 공개 ID 순으로
정합니다. Site 모델의 address는 관리 DB와 개발자 로컬 DB에서
모두 null입니다. 조회 권한이 있는 주소는 호스트 SiteDirectory 계약으로
가져옵니다. 로컬의 Site::forLegalEntity()는 Core에서 현재 소속 조건을
확인한 뒤 스냅샷을 조회합니다. 신규 사업장과 표시명 변경은 스냅샷을 갱신하면
반영됩니다.
마이그레이션 작성
Workshop Note에 선택 입력인 사업장 참조를 추가하는 예제입니다. 생성된 앱의 실제 테이블 접두사를 사용하고 이미 있는 소유자 컬럼을 중복 추가하지 마세요. Note 생성 마이그레이션보다 뒤의 새 파일 database/migrations/tenant/2026_10_04_120000_add_site_to_wsp_notes.php를 만듭니다.
<?php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::table('wsp_notes', function (Blueprint $table): void {
$table->unsignedBigInteger('site_id')->nullable();
$table->index('site_id');
$table->foreign('site_id')->references('id')
->on('public.sites')->restrictOnDelete();
});
}
public function down(): void
{
Schema::table('wsp_notes', function (Blueprint $table): void {
$table->dropForeign(['site_id']);
$table->dropIndex(['site_id']);
$table->dropColumn('site_id');
});
}
};앱 테이블은 할당된 스키마를 사용하고 Core 참조 대상에만 public을 붙입니다. 앱 테이블을 public에 생성하거나 할당 스키마 이름을 코드에 고정하지 마세요. 참조가 허용돼도 FK와 참조 컬럼의 인덱스는 자동 생성되지 않습니다. 삭제 규칙은 업무에 맞춰 정하며, 위 예제는 참조 중인 사업장의 삭제를 차단합니다. down()은 컬럼 데이터를 지우므로 일반 오류 복구용으로 실행하지 않습니다.
저장 전 식별자 해석과 권한 검사
API에서는 공개 식별자를 받습니다. 생성된 Resource Policy와 조직 대상 검사를 유지한 뒤, 허용된 법인의 사업장인지 해석하세요. 다음은 인가를 마친 Controller 내부 발췌입니다. $legalEntityKey는 검증된 저장 소유자에서 가져오며 요청의 숫자 ID를 그대로 쓰지 않습니다.
use Nexia\Organization\Contracts\SiteDirectory;
$data = $request->validate(['site_public_id' => ['required', 'uuid']]);
$site = app(SiteDirectory::class)->findByPublicIdForLegalEntity(
$data['site_public_id'],
$legalEntityKey,
);
abort_if($site === null, 422);
$record->site_id = $site->key;
$record->save();이 발췌는 값이 있는 경우의 지정만 보여 줍니다. 선택 입력에서는 필드 생략은 기존 값 유지, 명시적 null은 비우기로 따로 처리하세요. 모델 응답에서 site_id를 숨기고 허용된 공개 식별자를 반환합니다. 폼·응답 타입 연결은 데이터 모델과 마이그레이션을 따릅니다.
법인·운영조직은 OrganizationDirectory, 사업장은 SiteDirectory, Party는 Nexia\Laravel\Identity\Contracts\PartyDirectory를 사용합니다. 식별자 해석만으로 권한이나 업무상 사용 가능 여부가 검증되지는 않습니다. public.sites 직접 조회, Core Eloquent 모델 import, exists:sites,id 검증으로 권한 처리를 대체하지 마세요. FK만으로는 법인 소속·활성 상태·soft delete·사용자 권한까지 보장하지 않습니다.
적용하고 확인하기
DB 연결을 유지하도록 nexia dev를 켜 둡니다. 두 번째 터미널의 앱 폴더에서 실행하세요.
nexia db migrate
nexia db statuscompleted를 확인합니다. 허용된 사업장을 저장하고 새로고침해 유지되는지, 사용 불가·범위 밖 대상은 거부되는지, 사업장이 없는 기존 Note도 수정 가능한지 확인하세요. 제약 위반 확인에는 별도 테스트 데이터를 사용합니다.
| 증상 | 다음 조치 |
|---|---|
| Core FK 대상에 권한 오류 | 위의 정확한 테이블·컬럼과 앱 migration 실행 여부 확인. 계속 실패하면 작업 ID로 지원 요청. 직접 권한을 넓히지 않음 |
| 타입 불일치 | Core id는 bigint. FK 컬럼에 UUID를 저장하지 않음 |
| FK 위반 | 같은 테넌트의 식별자인지 해석하고 삭제·동시 변경을 처리. 잘못된 값을 저장하려고 제약을 제거하지 않음 |
queued·running·needs_review | 데이터 모델과 마이그레이션의 복구 절차 확인. 접수는 완료가 아니며 초기화로 복구하지 않음 |
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
Party의 업무 역할과 관계
PartyBusinessDirectory로 Party ID별 활성 역할을 일괄 조회하고, 역할과
개인·조직 유형을 조합해 검색하거나 조회 권한이 있는 방향성 관계를 확인할
수 있습니다. 예를 들어 core.customer는 Party 역할이며, 상대 Party와의
관계나 앱의 고객 프로필을 뜻하지 않습니다. 결과에는 디렉터리 권한과 Party
조회 범위가 적용됩니다. 관계 조회와 관계 조건 등록에는 directory.relationship.read도 필요합니다. 표시명이 정의되지 않은 관계 유형은 표시명이 없습니다.
앱 저장이 이 조건에 의존하면 PartyWritePreconditions에 roles 또는
relationships를 등록하세요. 관계 조건에는 코드, 방향과 상대 Party 공개
ID를 지정합니다. Core는 저장 완료 시 조건을 다시 확인합니다. 등록은 저장
성공을 뜻하지 않으며, 격리된 앱 커밋 후 조건이 바뀌면 앱 데이터가 남은 채
검토가 필요할 수 있습니다. 과거 참조 조회와 새 선택의 사용 가능 여부는
구분하세요. 대응하는 SDK·Core·런타임 릴리스가 필요합니다.
use Nexia\Identity\Contracts\PartyBusinessDirectory;
use Nexia\Identity\Contracts\PartyWritePreconditions;
$directory = app(PartyBusinessDirectory::class);
$page = $directory->search($actor, $query, ['core.customer'], ['person', 'organization'], 1, 25);
$roles = $directory->activeRoles($actor, [$partyPublicId]);
$relationships = $directory->activeRelationships($actor, [$partyPublicId]);
app(PartyWritePreconditions::class)->register($actor, $partyPublicId, [
'roles' => ['core.customer'],
]);