SDK 조회 API 전환표
기존 디렉터리·결재 메서드의 대체 코드와 기존 계약을 계속 써야 하는 조건을 확인합니다.
SDK 조회 API 전환표
| 필요한 작업 | 사용할 API |
|---|---|
| 디렉터리 조회·필터·조인 | Party::query(), User::query(), LegalEntity::query(), OperatingUnit::query(), Site::query() |
| 현재 사용자가 볼 수 있는 결재 조회 | Approval::query($legalEntity)의 paginate(), first(), find() |
| 권한이나 현재 자격 확인, 결재 상신, 업무 결과 정산 | 해당 기존 호스트 계약 |
모델은 Nexia\Laravel\Directory에 있습니다. 호환되는 PHP SDK와 Core가 연결된 관리 App DB 또는 대응 CLI가 준비한 개발자 로컬 스냅샷에서 디렉터리 모델을 사용합니다. App 레코드를 조인할 때는 기존 레코드 정책을 적용합니다. 호출자별 가시성 판정이나 최신 정보가 필요하면 해당 호스트 계약을 사용합니다. 고객 관리 App DB에서는 호스트 계약을 사용합니다. 모델 조회는 Eloquent 모델, 스칼라, 컬렉션을 반환하며 필수 조회의 미존재는 새 모델의 Eloquent 예외로 처리합니다. 기존 플랫폼 객체가 필요한 호출은 기존 호스트 조회를 사용합니다.
기존 API가 필요한 행에는 이유를 적었습니다. 호출을 옮기기 전에 필요한 권한 범위와 반환 타입을 확인하세요. 메서드 제거는 남은 호출과 지원 런타임을 확인한 뒤 결정합니다.
IdentityQueries 호환성 안내에는 신규 사용 중단 표시와 기존 배치 호출 설명이 있습니다.
DB 준비와 조인은 Core 식별자를 외래키로 참조하기, 결재 필드·가시성·원본 App 조건은 전자 결재 계약을 참고하세요.
Party
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 공개 ID로 Party 찾기 | PartyDirectory::findByPublicId($id) | Party::where('public_id', $id)->first() |
| 공개 ID로 필수 Party 조회 | PartyDirectory::requireByPublicId($id) | Party::where('public_id', $id)->firstOrFail() |
| 공개 ID 존재 확인 | PartyDirectory::exists($id) | Party::where('public_id', $id)->exists() 접근 판단은 PartyAccess::allows()를 사용합니다. |
| 공개 ID 여러 개 조회 | PartyDirectory::findByPublicIds($ids) | Party::whereIn('public_id', $ids)->get()->keyBy('public_id')->all() 공개 ID 맵을 유지하며 값은 Eloquent 모델입니다. |
| 키로 Party 한 건 조회 | PartyDirectory::findByKey($key) | Party::find($key) |
| 키 여러 개로 Party 조회 | PartyDirectory::findByKeys($keys) | Party::whereKey($keys)->get()->all() |
| 키로 필수 Party 조회 | PartyDirectory::requireByKey($key) | Party::findOrFail($key) |
| 키의 공개 ID 조회 | PartyDirectory::publicIdByKey($key) | Party::whereKey($key)->value('public_id') |
| 키별 공개 ID 조회 | PartyDirectory::publicIdsByKeys($keys) | Party::whereKey($keys)->pluck('public_id', 'key')->all() |
| 병합 후 최종 Party 찾기 | PartyDirectory::findCanonicalByPublicId($id) | Party::canonical($id) 호스트에서 병합을 추적합니다. 기본 속성을 담은 모델을 반환합니다. |
| 활성 Party 이름 검색 | PartyDirectory::activeSearch($search, $limit) | Party::active()->when($search !== '', fn ($q) => $q->matchingName($search))->orderBy('display_name')->limit($limit)->get()->all() |
| 호출자가 볼 수 있는 활성 Party 검색 | PartyDirectory::activeSearch($search, $limit) | 기존 메서드 |
| 이메일로 활성 개인 찾기 | PartyDirectory::activePeopleByEmail($email, $limit) | Party::peopleByEmail($email, $limit) 같은 호스트 조회를 사용하며 모델 컬렉션을 반환합니다. |
| 이메일을 포함해 개인 검색 | PartyDirectory::searchActivePeople($search, $limit, $excludedKeys) | Party::searchPeople($search, $limit, $excludedKeys) 이메일 검색과 제외 조건을 유지합니다. PersonDirectoryEntry 대신 contact_email이 있는 모델 컬렉션입니다. |
| Party 이름으로 App 레코드 정렬 | PartyDirectory::orderByDisplayLabel($builder, $partyKeyColumn, $direction) | leftJoinSub() Party를 조인해 display_name으로 정렬합니다. |
| 호출자 가시성을 유지하거나 DB 연결이 다른 App 레코드 정렬 | PartyDirectory::orderByDisplayLabel($builder, $partyKeyColumn, $direction) | 기존 메서드 |
| Party 이름으로 App 레코드 검색 | PartyDirectory::whereDisplayLabelMatches($builder, $partyKeyColumn, $search) | whereIn($partyKeyColumn, Party::matchingName($search)->select('key')) |
| 호출자 가시성을 유지하거나 DB 연결이 다른 App 레코드 검색 | PartyDirectory::whereDisplayLabelMatches($builder, $partyKeyColumn, $search) | 기존 메서드 |
| Party 병합 결과 일괄 조회 | BatchCanonicalPartyDirectory::findCanonicalByPublicIds($ids) | Party::canonicalMany($ids) 호스트의 일괄 조회를 우선 사용하고, 지원하지 않으면 단건으로 조회합니다. 모델 컬렉션을 반환합니다. |
| 이메일 여러 개로 개인 조회 | BatchPartyDirectory::activePeopleByEmails($emails, $limitPerEmail) | Party::peopleByEmails($emails, $limitPerEmail) 정규화한 이메일별 모델 컬렉션입니다. 호스트의 일괄 조회 계약이 필요합니다. |
| Party별 역할 조회 | PartyBusinessDirectory::activeRoles($actor, $ids) | Party::roles($actor, $ids) 공개 ID별 역할 맵을 컬렉션으로 받습니다. |
| 역할·유형으로 Party 검색 | PartyBusinessDirectory::search($actor, $search, $roles, $types, $page, $perPage) | Party::searchByRoles($actor, $roles, $search, $types, $perPage, $page) 인수 순서가 바뀌며 Paginator를 반환합니다. SQL 조건을 조합할 때는 Party::withRoles($actor, $roles)를 사용합니다. 10,000건까지 지원합니다. |
| Party별 관계 조회 | PartyBusinessDirectory::activeRelationships($actor, $ids) | Party::relationships($actor, $ids) 공개 ID별 관계 맵을 컬렉션으로 받습니다. |
| 조회 가능한 관계 한 건 보기 | PartyRelationshipDirectory::findVisibleByPublicId($actor, $id) | Party::relationship($actor, $id) 같은 호스트 조회를 사용하고 동일한 DTO 또는 null을 반환합니다. |
| 호출자가 Party에 접근할 수 있는지 판정 | PartyAccess::allows($actor, $partyKey) | 기존 메서드 유지 호출자별 접근 권한 판정에 사용합니다. |
이 기능에서 계속 쓰는 계약
| 계약 | 기존 메서드 |
|---|---|
PartyWritePreconditions | register() |
PersonPartyProvisioner | ensureForDirectorySubject() |
사용자 계정
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 키로 사용자 조회하고 필요시 삭제 계정 포함 | ActorDirectory::findByKey($key, $includeDeleted) | $key === null ? null : User::withTrashed($includeDeleted)->find($key) |
| 키 여러 개로 사용자 조회 | ActorDirectory::findByKeys($keys, $includeDeleted) | User::withTrashed($includeDeleted)->whereKey($keys)->get()->all() |
| 키로 필수 사용자 조회 | ActorDirectory::requireByKey($key, $includeDeleted) | User::withTrashed($includeDeleted)->findOrFail($key) |
| 공개 ID로 사용자 조회 | ActorDirectory::findByPublicId($id) | User::where('public_id', $id)->first() |
| 공개 ID로 필수 사용자 조회 | ActorDirectory::requireByPublicId($id) | User::where('public_id', $id)->firstOrFail() |
| Party의 첫 사용자 계정 조회 | ActorDirectory::findByPartyKey($partyKey) | User::where('party_key', $partyKey)->orderBy('key')->first() 첫 계정 선택 기준을 유지하도록 키 오름차순을 지정합니다. |
| 공개 ID의 사용자 키 조회 | ActorDirectory::keyByPublicId($id) | User::where('public_id', $id)->value('key') |
| 키의 사용자 공개 ID 조회 | ActorDirectory::publicIdByKey($key) | User::whereKey($key)->value('public_id') |
| 키별 사용자 공개 ID 조회 | ActorDirectory::publicIdsByKeys($keys) | User::whereKey($keys)->pluck('public_id', 'key')->all() |
| 사용자 표시명 조회 | ActorDirectory::displayLabelByKey($key) | User::whereKey($key)->value('display_label') Party 표시명과 사용자 이름이 없으면 새 모델은 공개 ID를 사용합니다. 기존 호스트는 이메일을 반환할 수 있습니다. |
| 사용자 키 존재 확인 | ActorDirectory::existsByKey($key, $includeDeleted) | User::withTrashed($includeDeleted)->whereKey($key)->exists() |
| 공개 ID 여러 개로 사용자 조회 | BatchActorDirectory::findByPublicIds($ids) | User::whereIn('public_id', $ids)->get()->all() Actor[]가 필요하면 기존 호스트 일괄 조회를 사용합니다. |
| 법인의 활성 사용자 한 명 표시 | ActorDirectory::activeByPublicIdForLegalEntity($id, $entityKey) | User::activeForLegalEntity($entityKey)->where('public_id', $id)->first() |
| 서명자 등 특정 사용자의 현재 법인 자격 확인 | ActorDirectory::activeByPublicIdForLegalEntity($id, $entityKey) | 기존 메서드. 호스트의 단건 판정과 Actor가 필요합니다. |
| 법인의 활성 사용자 목록 조회 | ActorDirectory::activeForLegalEntity($entityKey) | User::activeForLegalEntity($entityKey)->orderBy('display_label')->orderBy('key')->get()->all() User 모델을 반환합니다. SQL 정렬은 기존 호스트의 자연 정렬과 다를 수 있습니다. |
이 기능에서 계속 쓰는 계약
| 계약 | 기존 메서드 |
|---|---|
PersonLoginAccounts | ensure() |
PersonLoginInvitations | status(), invite() |
BatchPersonLoginInvitations | statuses() |
법인
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 공개 ID로 법인 조회 | OrganizationDirectory::findLegalEntity($id) | LegalEntity::where('public_id', $id)->first() |
| 공개 ID로 필수 법인 조회 | OrganizationDirectory::legalEntity($id) | LegalEntity::where('public_id', $id)->firstOrFail() |
| 공개 ID로 활성 법인 조회 | OrganizationDirectory::findActiveLegalEntity($id) | LegalEntity::active()->where('public_id', $id)->first() 모델의 active()는 법인에 연결된 조직 Party도 확인합니다. Core의 기존 활성 조건은 법인 상태를 확인합니다. |
| 키로 활성 법인 조회 | OrganizationDirectory::findActiveLegalEntityByKey($key) | LegalEntity::active()->find($key) 모델의 active()는 법인에 연결된 조직 Party도 확인합니다. Core의 기존 활성 조건은 법인 상태를 확인합니다. |
| 키로 법인 조회 | OrganizationDirectory::findLegalEntityByKey($key) | LegalEntity::find($key) |
| 키 여러 개로 법인 조회 | OrganizationDirectory::findLegalEntitiesByKeys($keys) | LegalEntity::whereKey($keys)->get()->all() |
| 키로 필수 법인 조회 | OrganizationDirectory::requireLegalEntityByKey($key) | LegalEntity::findOrFail($key) |
| 키의 법인 공개 ID 조회 | OrganizationDirectory::legalEntityPublicIdByKey($key) | LegalEntity::whereKey($key)->value('public_id') |
| 공개 ID의 법인 키 조회 | OrganizationDirectory::legalEntityKeyByPublicId($id, $activeOnly) | LegalEntity::where('public_id', $id)->when($activeOnly, fn ($q) => $q->active())->value('key') 모델의 active()는 법인에 연결된 조직 Party도 확인합니다. Core의 기존 활성 조건은 법인 상태를 확인합니다. |
| 키별 법인 공개 ID 조회 | OrganizationDirectory::legalEntityPublicIdsByKeys($keys) | LegalEntity::whereKey($keys)->pluck('public_id', 'key')->all() |
| 법인 계층 리비전 조회 | OrganizationDirectory::legalEntityHierarchyRevisionByKey($key) | $entity->hierarchyRevision() 이미 읽은 모델에서 기존 호스트 메서드를 호출합니다. 현재 Core와 Manager는 null을 반환합니다. |
| 법인 목록 조회 | OrganizationDirectory::legalEntities() | LegalEntity::orderBy('code')->get()->all() 선택 권한이 있는 법인 목록에는 기존 대상 해석기를 사용합니다. |
이 기능에서 계속 쓰는 계약
| 계약 | 기존 메서드 |
|---|---|
HasLegalEntityProfile | legalProfile() |
HasFunctionalCurrency | functionalCurrencyCode(), functionalCurrencyMinorUnit() |
OrganizationMemberships | actorParticipatesInLegalEntity() |
OrganizationTargetResolver | resolveListTargets(), resolveCreateTarget() |
PersonLegalEntityAccess | end() |
운영조직
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 공개 ID로 운영조직 조회 | OrganizationDirectory::findOperatingUnit($id) | OperatingUnit::where('public_id', $id)->first() |
| 법인에 소속된 운영조직 필수 조회 | OrganizationDirectory::operatingUnit($id, $entityKey) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->where('public_id', $id)->firstOrFail() |
| 법인에 소속된 운영조직 키 조회 | OrganizationDirectory::operatingUnitKeyForLegalEntityPublicId($entityKey, $id) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->where('public_id', $id)->value('key') |
| 키의 운영조직 공개 ID 조회 | OrganizationDirectory::operatingUnitPublicIdByKey($key) | OperatingUnit::whereKey($key)->value('public_id') |
| 공개 ID의 운영조직 키 조회 | OrganizationDirectory::operatingUnitKeyByPublicId($id) | OperatingUnit::where('public_id', $id)->value('key') |
| 키별 운영조직 공개 ID 조회 | OrganizationDirectory::operatingUnitPublicIdsByKeys($keys) | OperatingUnit::whereKey($keys)->pluck('public_id', 'key')->all() |
| 키로 운영조직 조회 | OrganizationDirectory::findOperatingUnitByKey($key) | OperatingUnit::find($key) |
| 키 여러 개로 운영조직 조회 | OrganizationDirectory::findOperatingUnitsByKeys($keys) | OperatingUnit::whereKey($keys)->get()->all() |
| 키로 필수 운영조직 조회 | OrganizationDirectory::requireOperatingUnitByKey($key) | OperatingUnit::findOrFail($key) |
| 운영조직의 법인 소속 표시 | OrganizationDirectory::isOperatingUnitAffiliatedWithLegalEntity($key, $entityKey) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->whereKey($key)->exists() |
| 저장 전 현재 운영조직 소속 확인 | OrganizationDirectory::isOperatingUnitAffiliatedWithLegalEntity($key, $entityKey) | 기존 메서드. 해당 운영조직·법인에 대한 호스트 판정을 사용합니다. |
| 디렉터리에서 법인에 소속된 운영조직 키 조회 | OrganizationDirectory::operatingUnitKeysForLegalEntity($entityKey) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->pluck('key')->all() |
| 현재 법인 소속 키 전체 조회 | OrganizationDirectory::operatingUnitKeysForLegalEntity($entityKey) | 기존 메서드. 로컬 스냅샷과 무관하게 호스트 키를 읽습니다. |
| 기준일에 유효한 운영조직 목록 조회 | OrganizationDirectory::effectiveOperatingUnitsForLegalEntity($entityKey, $asOf) | OperatingUnit::forLegalEntity($entityKey, $asOf)->orderBy('display_label')->get()->all() 기준일에 유효한 조직을 조회합니다. 단순 소속을 보려면 affiliatedWithLegalEntity()를 사용합니다. |
이 기능에서 계속 쓰는 계약
| 계약 | 기존 메서드 |
|---|---|
OperatingUnitEvidenceDirectory | findByKey(), effectiveForLegalEntity(), lockForLegalEntity() |
OrganizationWritePreconditions | register() |
PersonOperatingUnitMemberships | move() |
사업장
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 키로 사업장 이름·코드 표시 | SiteDirectory::findForLegalEntity($siteKey, $entityKey, $asOf) | Site::forLegalEntity($entityKey, $asOf)->find($siteKey) |
| 키로 주소나 SiteView 조회 | SiteDirectory::findForLegalEntity($siteKey, $entityKey, $asOf) | 기존 메서드. 디렉터리 모델의 주소는 null입니다. |
| 공개 ID로 사업장 이름·코드 표시 | SiteDirectory::findByPublicIdForLegalEntity($id, $entityKey, $asOf) | Site::forLegalEntity($entityKey, $asOf)->where('public_id', $id)->first() |
| 공개 ID로 저장 전 사업장 확인 또는 주소 조회 | SiteDirectory::findByPublicIdForLegalEntity($id, $entityKey, $asOf) | 기존 메서드. 호스트에서 현재 사업장을 단건 확인합니다. |
| 사업장 선택 목록에 이름·코드 표시 | SiteDirectory::optionsForLegalEntity($entityKey, $asOf, $search, $limit) | Site::forLegalEntity($entityKey, $asOf) 아래 검색 예제 참고. |
| 주소나 SiteView가 필요한 사업장 선택 목록 | SiteDirectory::optionsForLegalEntity($entityKey, $asOf, $search, $limit) | 기존 메서드. 호스트가 전체 선택 객체를 반환합니다. |
입력값 $search로 이름과 코드를 검색하고 기존 선택 목록의 1~100건 제한을 적용합니다.
use Nexia\Laravel\Directory\Site;
$search = trim($search);
$term = '%'.addcslashes($search, '\\%_').'%';
$sites = Site::forLegalEntity($entityKey, $asOf)
->when($search !== '', fn ($query) => $query->where(
fn ($fields) => $fields->where('label', 'ilike', $term)
->orWhere('code', 'ilike', $term),
))
->orderBy('label')
->limit(max(1, min($limit, 100)))
->get();Site 모델의 address는 null입니다. 로컬의 Site 스코프는 Core에서 현재 소속 조건을 확인한 뒤 스냅샷을 읽습니다. 신규 사업장과 표시명 변경은 스냅샷 갱신 후 반영됩니다. 이미 조회한 모델에서 플랫폼 객체가 필요하면 $user->actor(), $entity->context(), $unit->context()를 사용합니다. 결과는 null일 수 있습니다.
결재
결재 목록과 단건 조회
인증된 App 요청에서 선택한 법인을 SDK 쿼리에 전달합니다.
use Nexia\Approval\Approval;
$page = Approval::query($legalEntity)->orderByDesc('submitted_at')->paginate(25);
$first = Approval::query($legalEntity)->orderByDesc('submitted_at')->first();
$approval = Approval::query($legalEntity)->find($approvalPublicId);연결된 레코드를 소유한 App이 공개한 필터는 throughResource()로 지정합니다. 결재 결과를 대조해 App 레코드의 업무 상태를 확정하는 코드에는 caseSummary()를 계속 사용합니다. 이 계약은 삭제된 케이스의 결과 증거가 필요한 정산과 검증된 이벤트 처리에도 사용됩니다.
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 화면에 결재 목록 표시 | SDK 전용 목록 조회 없음 | Approval::query($legalEntity)->paginate(25) |
| 조건에 맞는 첫 결재 표시 | SDK 전용 조건 조회 없음 | Approval::query($legalEntity)->first() |
| 화면에 결재 한 건 표시 | ApprovalHost::caseSummary($caseId) | Approval::query($legalEntity)->where('source', 'native')->find($caseId) |
| 결재 결과 정산 또는 검증된 결재 이벤트 처리 | ApprovalHost::caseSummary($caseId) | 기존 메서드. 바인딩·리소스 버전과 자동결재 증거를 호스트 요약에서 받습니다. |
| 적용할 결재 경로 해석 | ApprovalHost::resolveRoute($routePolicyKey, $entity) | 기존 메서드 유지 적용되는 결재 경로를 해석합니다. |
| 적용할 활성 경로가 있는지 확인 | ApprovalHost::routeExists($routePolicyKey, $legalEntityId) | 기존 메서드 유지 적용 가능한 활성 경로 확인에 사용합니다. |
| 결재 문서 미리보기 | ApprovalHost::renderDocument($resourceKey, $values) | 기존 메서드 유지 문서 미리보기 렌더링에 사용합니다. |
| 상신용 첨부 증거 준비 | ApprovalHost::prepareSupportingAttachments($entity, $drafter, $stageIds) | 기존 메서드 유지 상신용 첨부 증거 준비에 사용합니다. |
| 상신 결재선 계산 | ApprovalHost::resolveRouteLine($routeId, $routeKey, $routeVersion, $entity, $submitter, $resourceRef, $payload) | 기존 메서드 유지 상신 요청의 결재선 계산에 사용합니다. |
| 지정된 바인딩으로 상신 | ApprovalHost::submitBound($submission, $attachments) | 기존 메서드 유지 지정된 바인딩으로 상신합니다. |
| 현재 게시 버전을 확정해 상신 | ApprovalHost::submitCurrentBound($submission, $attachments) | 기존 메서드 유지 현재 게시 버전을 확정해 상신합니다. |
| 결재 회수 | ApprovalHost::recall($caseId, $actor) | 기존 메서드 유지 결재 회수에 사용합니다. |
이 기능에서 계속 쓰는 계약
| 계약 | 기존 메서드 |
|---|---|
ApprovalBindingDirectory | availabilityFor() |
ApprovalRequirements | required() |
ApprovalSubmissionHost | enqueueBound(), delivery() |
ApprovalIdempotency | execute() |
ApprovalLineResolver | resolve() |
ApprovalRequirementContextProvider | approvalRequirementContexts() |
ApprovalResolverRegistrar | register(), registered() |
AutomaticApprovalFactProvider | evaluate() |
AutomaticApprovalFactProviderRegistrar | register(), registered() |
ResourceSubjectActor | subjectActorKey() |
ResourceSubjectActorRegistrar | register(), registered() |
ApprovalTestHost | createCase(), caseCount(), case(), resetContributions(), registerBinding(), registerDocumentSchema(), createFixedUserRoute(), publishBusinessTemplate(), approve() |
개인 프로필
| 하려는 일 | 기존 API | 지금 쓸 API |
|---|---|---|
| 개인 프로필 한 건 조회 | PersonProfileDirectory::findByPartyKey() | 기존 메서드 |
| 개인 프로필 일괄 조회 | BatchPersonProfileDirectory::findByPartyKeys() | 호스트가 일괄 조회를 지원하면 기존 메서드 |
이 기능에서 계속 쓰는 계약
| 계약 | 기존 메서드 |
|---|---|
PersonProfileEditor | updateForAuthorizedHr(), updateOwnContact() |
PersonProfileHistory | pageForAuthorizedHr() |
모델 속성 대응
디렉터리 표시에서는 key(), publicId(), displayLabel()에 대응하는 getKey(), public_id, display_label을 사용합니다.
Actor—partyKey()→party_key,isVerified()→verifiedParty—isPerson()→person,isOrganization()→organization,isArchived()→archivedLegalEntity—code()→code,partyPublicId()→party_public_id,isActiveOrganization()→activeOperatingUnit—code()→code,parentKey()→parent_key,classification()→classification,accentColor()→accent_color