전자 결재 계약
전자 결재 업무 양식으로 나타나기 위해 App이 함께 배포해야 하는 바인딩과 문서 스키마, Slot Widget입니다.
전자 결재 계약
App 동작을 결재 작성기에 표시하려면 바인딩과 문서 스키마를 게시하고 formWidgetKey에 해당하는 widget을 등록하세요. 바인딩·스키마·widget의 식별자가 맞아야 합니다. 아래 선언부터 적용하고 제출 권한과 고정 증빙 계약을 이어서 확인하세요.
결재 조회
기존 결재 메서드와의 차이는 SDK 조회 API 전환표에서 확인하세요.
인증된 App 요청에서 Nexia\Approval\Approval::query($legalEntity)를
사용합니다. Core는 선택한 법인에서 사용자가 열람할 수 있는 문서에
필터와 정렬을 적용하고, 페이지 또는 단건을 반환합니다.
같은 테넌트에서 조회한 법인 디렉터리 모델이나 법인 공개 ID도 전달할 수
있습니다.
use Nexia\Approval\Approval;
$page = Approval::query($legalEntity)->where('source', 'native')
->orderByDesc('submitted_at')->paginate(25);
$approval = Approval::query($legalEntity)->find($approvalPublicId);first()와 find()는 한 건 또는 null을 반환합니다. 원본 App이
공개한 필터는 throughResource($key, $conditions)로 적용합니다.
일반 결재 필터에 지원하지 않는 필드를 지정하면 HTTP 422가 반환됩니다.
기존 결재 요약 계약이 필요한 업무 흐름에서는 ApprovalHost::caseSummary()를
계속 사용합니다.
시그니처
Descriptor contribution 하나이고, 보통 클래스 하나에 둡니다.
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\ApprovalDocumentSchema;
use Nexia\AppDescriptors\ApprovalFormBindingDescriptor;바인딩의 정체성은 넘기는 것이 아니라 파생됩니다.
{appKey}.{resourceKey}.{actionKey} → quality.inspection_decision.submit
최소 예시
설명용 Quality key를 사용하는 생성자 유효 선언 예시입니다. 해당 Quality 업무 Resource가 체크아웃에 있다는 전제는 아닙니다. 실제로 등록한 Resource와 아래 런타임 연동 계약을 함께 사용하세요.
<?php
declare(strict_types=1);
namespace Nexia\Apps\Amuz\Quality\Descriptors;
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\ApprovalDocumentSchema;
use Nexia\AppDescriptors\ApprovalFormBindingDescriptor;
final class QualityApprovalDescriptors implements AppDescriptorContribution
{
public static function appDescriptors(): AppDescriptorSet
{
return AppDescriptorSet::of(
new ApprovalFormBindingDescriptor(
appKey: 'quality',
resourceKey: 'inspection_decision',
actionKey: 'submit',
labelKey: 'quality.approval.inspection_decision.submit.label',
entryModes: ['link'],
formWidgetKey: 'quality.inspection_decision.submit',
documentSchemaKey: 'quality.inspection_decision',
submitPermissionKey: 'quality.inspection_decision.submit',
),
new ApprovalDocumentSchema(
appKey: 'quality',
resourceKey: 'inspection_decision',
titleKey: 'quality.approval.inspection_decision.document.title',
sections: [[
'title_key' => 'quality.approval.inspection_decision.document.summary',
'fields' => [
['key' => 'proposed_decision', 'label_key' => 'quality.inspection_decision.proposed_decision.label'],
['key' => 'reason_text', 'label_key' => 'quality.inspection_decision.reason_text.label'],
],
]],
),
);
}
}typed 바인딩과 스키마는 별도 값으로 유지되고, 발견만 공통 set으로 옮겼습니다. Approval business-template과 route-policy preset도 같은 게시 경계를 씁니다.
인자: ApprovalFormBindingDescriptor
| 인자 | 타입 | 기본값 | 동작 |
|---|---|---|---|
appKey | string | — | 소유 App, 비어 있으면 안 됨 |
resourceKey | string | — | App 안의 Resource, 비어 있으면 안 됨 |
actionKey | string | — | 승인 대상 동작, 비어 있으면 안 됨 |
labelKey | string | — | composer의 라벨, 비어 있으면 안 됨 |
entryModes | string 목록 | — | create, link 중 최소 하나 |
formWidgetKey | string | — | 폼을 렌더링하는 Slot Widget 키, 비어 있으면 안 됨 |
documentSchemaKey | string | — | 제출되는 문서 스키마, 비어 있으면 안 됨 |
version | string | 1.0 | Descriptor 개정 |
status | DescriptorStatus | Active | Active, Deprecated, Removed |
descriptionKey | string, null | null | 더 긴 설명 |
approvedLabelKey | string, null | null | 승인됐을 때 결과 라벨 |
rejectedLabelKey | string, null | null | 반려됐을 때 결과 라벨 |
recalledLabelKey | string, null | null | 회수됐을 때 결과 라벨 |
cancelledLabelKey | string, null | null | 취소됐을 때 결과 라벨 |
submitPermissionKey | string, null | null | 제출에 필요한 권한 |
ApprovalFormBindingDescriptor::ENTRY_MODES는 ['create', 'link']입니다.
| 모드 | 레코드가 | 쓰는 경우 |
|---|---|---|
create | 제출의 일부로 생성됨 | 승인이 레코드가 존재하게 되는 방식일 때 |
link | 이미 존재하고 건에 붙음 | 레코드를 먼저 작성한 뒤 제출할 때 |
두 흐름을 모두 지원한다면 둘 다 선언하세요. 제출 전에 작성하는 레코드는 ['link']를 사용합니다.
검증
필수 필드마다 생성자에서 검증하고, 메시지에 파생된 id가 담깁니다.
ApprovalFormBindingDescriptor app_key must be a non-empty string.
ApprovalFormBindingDescriptor [quality] resource_key must be a non-empty string.
ApprovalFormBindingDescriptor [quality.inspection_decision] action_key must be a non-empty string.
ApprovalFormBindingDescriptor [quality.inspection_decision.submit] label_key must be a non-empty string.
ApprovalFormBindingDescriptor [quality.inspection_decision.submit] must declare at least one entry mode.
ApprovalFormBindingDescriptor [quality.inspection_decision.submit] entry mode [attach] must be one of: create, link
ApprovalFormBindingDescriptor [quality.inspection_decision.submit] form_widget_key must be a non-empty string.
ApprovalFormBindingDescriptor [quality.inspection_decision.submit] document_schema_key must be a non-empty string.
ApprovalDocumentSchema
| 인자 | 타입 | 기본값 | 동작 |
|---|---|---|---|
appKey | string | — | 소유 App |
resourceKey | string | — | 문서가 서술하는 Resource |
sections | array | — | 순서 있는 문서 섹션 |
version | string | 1.0 | 스키마 개정 |
status | DescriptorStatus | Active | 라이프사이클 |
titleKey | string, null | null | 문서 제목 키 |
각 섹션은 제목 키와 필드 목록을 담은 배열입니다.
[
'title_key' => 'quality.approval.inspection_decision.document.summary',
'fields' => [
['key' => 'decision_revision', 'label_key' => 'quality.inspection_decision.decision_revision.label'],
],
]스키마는 App이 저장하는 것이 아니라 승인자가 읽는 것을 선언합니다. 판단에 필요한 필드를 넣고 내부 장부는 빼세요.
세 조각이 맞아야 한다
바인딩은 자기완결적이지 않습니다. 산출물 셋이 키로 이어지고, 하나만 어긋나도 composer가 제시할 수는 있지만 렌더링하지 못하는 바인딩이 됩니다.
| 산출물 | 키 | 일치해야 할 대상 |
|---|---|---|
ApprovalFormBindingDescriptor | formWidgetKey | 어떤 SlotWidgetDescriptor.key |
SlotWidgetDescriptor | slot | approval.composer.business_form |
SlotWidgetDescriptor | component | 등록된 프런트엔드 컴포넌트 |
ApprovalFormBindingDescriptor | documentSchemaKey | 어떤 스키마의 {appKey}.{resourceKey} |
바인딩과 widget key를 동일한 Resource·동작 식별자에서 만드세요.
같은 AppDescriptorSet에 아래 값을 추가하세요. SlotWidgetDescriptor import는 contributor 파일 상단에 둡니다.
use Nexia\AppDescriptors\SlotWidgetDescriptor;
new SlotWidgetDescriptor(
key: 'quality.inspection_decision.submit',
version: '1.0',
slot: 'approval.composer.business_form',
component: 'quality.inspection_decision.submit',
slotApiVersion: 2,
permission: 'quality.inspection_decision.submit',
);slotApiVersion: 2는 컴포넌트가 @nexia/sdk의 ApprovalBusinessFormSlotPropsV2를 소비한다는 뜻입니다.
권한
바인딩은 요청을 라우팅합니다. 쓰기를 승인하지 않습니다.
| 플랫폼의 Approval이 하는 일 | 여러분 App이 해야 하는 일 |
|---|---|
| 건을 결재선에 따라 라우팅 | 제출된 페이로드 검증 |
| 결과와 감사 흔적 기록 | 최종 레코드 동작에서 Policy 강제 |
| 여러분 위젯과 문서 렌더링 | 행위자가 수행할 수 없는 동작 거부 |
승인된 건은 App 판단의 입력이지 판단의 대체물이 아닙니다. submitPermissionKey는 제출을 통제하고 이후의 쓰기는 통제하지 않습니다.
App 안에 병행 승인 장치를 만들지 마세요. 전자결재를 거치는 Resource는 플랫폼 Approval에 업무 양식으로 이어집니다.
결과 또는 반환: 고정된 바인딩 증거
BoundApprovalSubmission을 만들어 ApprovalHost::submitBound()로 제출합니다. 어긋나면 안 되는 증거가 명시됩니다.
지원 파일은 전체 흐름에서 하나의 list 계약을 사용합니다.
prepareSupportingAttachments()를 호출해
list<ApprovalAttachmentEvidence>를 얻고 그 list를 submitBound()의 두 번째
인자로 바로 넘기세요. ApprovalAttachmentEvidence는 Media UUID, checksum,
scan verdict, 선택 scan 시각을 담습니다. prepared attachments wrapper는
없습니다.
| 필드 묶음 | 고정되는 증거 |
|---|---|
| Template | templateKey, templateVersion |
| Binding | bindingKey, bindingVersion |
| Resource | 정규 ResourceRef, resourceVersion |
| 판단 | documentValues, 해석된 lineDefinition, 제목과 선택 라벨 |
| 재생 | 선택 idempotencyKey, idempotencyFingerprint |
호스트는 case를 만들기 전에 선택된 template과 binding 버전, 정규 Resource 정체성, 해석된 결재선을 검증합니다. 이후 ApprovalHost::caseSummary()는 고정된 binding App·Resource·동작 필드와 Resource 버전이 든 ApprovalCaseSummary를 반환합니다. Case가 없거나 예전 비정규 Resource reference라면 null을 반환하므로, 그 부재에서 부분 reference를 만들어내지 마세요.
테넌트 작성 Process가 현재 실제 설정을 선택하는 경우에는
submitCurrentBound(CurrentBoundApprovalSubmission, $attachments)를 사용하세요.
호스트가 현재 게시된 template, 활성 route policy, 설치된 binding을 해석해
원자적으로 snapshot합니다. CurrentBoundApprovalResult는 case, route, 고정된
정확한 template·binding 버전을 반환합니다.
이 경로가 자동 승인 정책을 opt-in하는 제출 경로입니다. submitBound()는 기존의
사람 전자 결재 의미를 유지하며 자동 승인 정책 사실을 평가하지 않습니다.
선택적 정책 자동승인 사실
자동승인은 바인딩 하나에 적용하는 선택적 Core 정책입니다. App은 approved boolean을 보내거나 사용자 결재 동작·서명을 만들지 않습니다. 바인딩이 이를 지원할 때만 provider를 등록하세요.
use Nexia\Approval\Contracts\AutomaticApprovalFactProviderRegistrar;
/** @var AutomaticApprovalFactProviderRegistrar $registrar */
$registrar->register('quality.inspection_decision.submit', fn () => new QualityApprovalFacts($records));evaluate()는 Core가 제출 transaction을 유지하는 동안 실행됩니다. ResourceRef가 가리키는 현재 App 레코드를 잠그고 다시 읽은 뒤 AutomaticApprovalEvaluation(resourceRef, resourceVersion, documentFingerprint, facts)를 반환해야 합니다. fingerprint는 원시 값이나 정규화하지 않은 JSON이 아니라 렌더된 snapshot으로 계산합니다.
use Nexia\Support\CanonicalPayloadFingerprint;
$snapshot = $approvalHost->renderDocument('quality.inspection_decision', $documentValues)?->toArray();
$documentFingerprint = CanonicalPayloadFingerprint::sha256($snapshot);facts에는 저장된 scalar bool, int, string만 넣고 금액은 정수 최소 단위 또는 canonical decimal string을 사용합니다. ResourceRef·resource version·정규화한 렌더 문서 fingerprint가 달라지면 Core가 거절하고, 활성 정책만 평가해 정책·버전·사실·시각·결과의 불변 증거를 남깁니다. 법인에 활성 정책이 있으면 같은 바인딩의 법인 정책이 우선이며, 법인 정책이 없을 때만 tenant catalog 정책을 사용합니다. approval.automatic_policy.*는 법인 정책을, approval.automatic_policy_catalog.*는 tenant catalog 정책을 관리하는 별도 권한입니다.
같은 bound 요청을 재시도할 때는 안정적인 idempotency key를 사용하세요. Host는 키를 기안자와 첨부 파일을 포함한 불변 요청 payload에 묶습니다. 24시간 idempotency 보존 기간 안의 일치하는 재시도는 정책이 retire된 뒤에도 처음 고정한 case·route·template·binding 결과를 반환합니다. 무기한 재실행을 보장하지는 않습니다. payload가 달라지거나 다른 기안자가 같은 키를 쓰면 거절됩니다. 사실이 없거나 일치하지 않거나 provider를 쓸 수 없거나 강한 서명 template이면 기존 사람 결재 경로가 유지됩니다. 소비자는 outcome_source (human 또는 policy), policy_key, policy_version, document_fingerprint를 구분해 검증할 수 있으며 정책 결과를 사람 서명으로 다루면 안 됩니다.
바인딩과 Template
자주 혼동되지만 서로 바꿔 쓸 수 없습니다.
| Approval 바인딩 | Approval Form Template | |
|---|---|---|
| 사는 곳 | 여러분 패키지 소스 | 테넌트 데이터 |
| 소유자 | 여러분 App | 관리자 |
| 목적 | App과 Approval 런타임의 연결 | 저장되고 선택 가능한 업무 양식 |
| 바뀌는 시점 | 릴리스를 배포할 때 | 관리자가 편집할 때 |
Template은 게시될 때 바인딩을 선택할 수 있습니다. 바인딩은 플랫폼이 제출 시점에 해석하는, 설치된 App 기능으로 남습니다.
오류
| 증상 | 원인 | 해결 |
|---|---|---|
바인딩 id가 담긴 부팅 시 InvalidArgumentException | 생성자 검증 | 메시지를 읽으세요. 누락된 필드를 알려줍니다 |
| composer에서 바인딩이 제시되지 않음 | 발견, 설치, status 관문 | 샌드박스 Catalog 확인 후 테넌트 설치와 status 확인 |
| 바인딩은 제시되는데 composer가 아무것도 렌더링하지 않음 | formWidgetKey에 맞는 Slot Widget이 없거나 컴포넌트가 등록되지 않음 | 키를 맞춘 뒤 composer를 직접 열어 확인. doctor는 pageElements()만 순회하고 위젯 component는 검사하지 않습니다 |
| 문서가 비었거나 라벨이 잘못됨 | documentSchemaKey가 기여된 스키마와 안 맞음 | {appKey}.{resourceKey} 맞추기 |
| 승인자에게 i18n 키 원문이 보임 | 로케일 항목 누락 | resources/lang/{locale}.json에 키 추가 |
App에 적용
App에서는 바인딩과 문서 스키마를 게시하고 동일한 key의 composer widget을 등록한 뒤 호스트 기능으로 제출합니다. 위 Quality resource/action 이름은 이 식별자 연결을 보여 주는 예시입니다. 과거 Quality Descriptor 파일을 전제로 작업하지 마세요.
업무별 결재 설정
직접 처리와 결재 상신 경로가 모두 ApprovalRequirements::required(bindingKey, legalEntityKey, default, contextKey)를 적용한 바인딩만 supportsRequirementPolicy를 선언합니다. Core의 전자결재 → 관리 → 업무별 결재 설정에서 해당 업무를 설정합니다. App 설정은 /workbench/approvals/operation-requirements?app=<app-key>로 연결하고, 별도의 결재 필수 입력란을 만들지 않습니다.
기존 contributor에 ApprovalRequirementContextProvider를 구현하면 조건별로 안정적인 키·표시명·기존 App 기본값을 담은 ApprovalRequirementContext를 제공할 수 있습니다. Core가 바인딩의 contribution에서 발견합니다. App은 신뢰할 수 있는 업무 데이터로 조건을 판단하고 상신 시 requirementContextKey로 전달합니다. 우선순위는 법인 조건 → 법인 공통 → 기업 조건 → 기업 공통 → App 기본값입니다. 실행 시 결정한 값을 증빙에 저장하고, 설정 변경으로 진행 중인 업무를 바꾸지 않습니다.
submitPermissionKey는 양식 목록의 사용 가능 여부를 판단합니다. 위임된 업무 권한은 additionalSubmitPermissionKeys로 추가할 수 있습니다. 선택한 범위에서 하나 이상의 권한이 있어야 하며, 실제 App endpoint는 대상 레코드와 동작의 권한을 다시 검사합니다. 양식이 보인다는 사실만으로 리소스 수정 권한이 생기지 않습니다.
게시된 양식은 route_policy_key를 가질 수 있으며 변경하려면 새 양식 버전이 필요합니다. 기업 공통 양식은 법인 전용 결재선을 선택할 수 없고, 같은 키의 법인 결재선이 공통 결재선을 대신하지 않습니다. CurrentBoundApprovalSubmission에 경로 없이 수동 lineDefinition을 전달할 수 있어 결과의 route는 null일 수 있습니다. 명시적으로 선택한 경로가 사라진 경우에는 오류로 처리합니다.
Process에서 사람이 결재선을 선택해야 하면 액션에 supportsLinePreparation을 선언하고 ProcessWorkActionInvocation.approvalLine을 사용합니다. Core는 대기 중인 동일 token에 준비 User Task를 만듭니다. 준비 완료는 결재선을 검증하고 같은 업무를 재시도하며, 승인이나 다음 단계 진행을 의미하지 않습니다. App은 기존 업무 명령과 내구성 있는 callback으로 상신과 결과 반영을 처리합니다.
공통 데이터의 업무는 requirementPolicyLegalEntityScoped: false를 선언하고 결재 필요 여부 조회에 법인 키를 null로 전달합니다. 설정은 기업 공통 범위에만 표시됩니다. 특정 조건만 변경할 수 있는 업무는 requirementPolicyContextsOnly: true를 사용합니다. Core는 선언된 조건만 제공하고 업무 전체의 일괄 우회를 거부합니다. 이 속성들은 기존 업무 범위를 보존하기 위한 것이며 모든 업무의 결재를 선택 사항으로 만들지 않습니다.
업무 생성이나 Process 실행 결과를 일반 HTTP 재시도 기간인 24시간 이후에도 유지하려면 ApprovalIdempotencyKey(durable: true)를 사용합니다. 재시도에서는 동일한 실행자·대상·입력의 불변 지문을 전달합니다. 일반 키의 만료 정책은 유지되고, 영구 키는 중복 실행을 막는 업무 증거로 보관됩니다.
네이티브 승인 결과 이벤트의 증거 조회
사용자 권한을 위임하지 않는 AppEventListeners::listen() 핸들러도 검증된 approval.case.completed, rejected, recalled, cancelled 이벤트에 명시된 case를 ApprovalHost::caseSummary()로 조회할 수 있습니다. Core는 tenant, 소비 App, case, 법인, Resource reference, 기안자와 최종 상태를 저장된 case와 대조합니다. 같은 이벤트 처리에서 ActorDirectory::findByKey()로 해당 case의 기안자를 조회할 수 있으며, 승인한 사용자와 기안자가 달라도 됩니다. 이 조회는 사용자 세션이나 쓰기 권한을 만들지 않습니다. 대화형 조회에는 기존 권한과 관여자 검사가 유지됩니다.
유실된 상신 연결을 복구하기 전에는 App의 intent, Resource revision과 문서 증거 검사를 유지하세요. Case ID만으로 복구하면 안 됩니다. 보관 처리된 case도 정규 증거를 유지합니다. 이 이벤트 조회를 사용하려면 Core 수정이 먼저 적용되어야 합니다. 기존 실패 이벤트는 정상 재처리·복구 절차가 별도로 필요하며, 배포만으로 App 자료가 복구됐다고 판단하지 마세요.
관련 문서
- 업무 프로세스 — 끝에서 끝까지의 흐름
- Slot Widget 추가 — 짝의 위젯 쪽 절반
- React 컴포넌트와 훅 —
ApprovalBusinessFormSlotPropsV2와 composer 레지스트리 - 업무 프로세스·전자 결재 문제 해결 — 위 오류 각각 진단
Host는 Process 결재선 준비에 사용할 실제 바인딩 대상을 ApprovalException.preparationResourceRef에 보존합니다. 이 내부 참조는 공개 오류 응답에 포함하지 않으며, 하위 문서를 상신해도 Process의 최초 대상은 유지됩니다.
백그라운드 상신
공통 App 요청 큐 (미출시)
업무 양식 컨트롤러에서 @nexia/sdk의 queueApprovalRequest로 기존 App POST 처리기를 접수합니다. 이 헬퍼에는 대응하는 Core 호스트가 필요합니다. 아래 버전 정보는 기존 명시적 확정 작업 계약의 버전이며 새 헬퍼의 최소 버전이 아닙니다. 헬퍼가 포함된 React SDK와 대응 Core가 릴리스되기 전에 이를 사용하는 App을 배포하지 마세요.
return queueApprovalRequest(api, legalEntityPublicId,
`/example/requests/${savedId}/submit`, {
template_key: envelope.templateKey,
template_version: envelope.templateVersion,
line: envelope.line,
reference_user_ids: envelope.referenceUserIds,
circulation_user_ids: envelope.circulationUserIds,
supplemental_body: envelope.supplementalBody,
supporting_attachment_stage_ids: envelope.supportingAttachmentStageIds,
}, { headers: { 'Idempotency-Key': requestKey } }, savedId);App 초안을 먼저 저장하세요. 응답 유실 시 같은 UUID 요청 키를 유지합니다. 마지막 인수는 초안을 다시 여는 App 발급 참조입니다. 헬퍼는 접수 시 { submissionId }를 반환합니다. Core는 원래 본문과 쿼리를 보존하고 작업 실행 시 경로 및 업무 권한을 다시 확인한 뒤 기존 처리기를 한 번 실행합니다. 업무 검증·버전 검사·트랜잭션은 App이 계속 담당합니다. 처리기 내부의 PHP ApprovalHost는 계속 결재 참조를 반환하며, 이 경로에는 기능별 Job이나 확정 처리기를 추가하지 않습니다.
호스트는 App 처리 중 결재를 준비하고, 원래 App 쓰기 영수증에서 저장 성공을 확인한 뒤 결재를 시작합니다. 불확실한 쓰기는 원래 결과만 조회하며 임의로 재실행하지 않습니다. 상신 중·실패 접수는 기안자의 내 결재함에 표시하며 통합관리의 결재 건으로 노출하지 않습니다. 실행 전에는 접수를 취소할 수 있습니다. 호스트 접수 차단 설정을 끄면 새 요청을 거부하며 동기 실행으로 우회하지 않습니다.
대상은 상신 화면의 요청입니다. 임의의 PHP 호출, 프로세스 작업, 승인·반려 결정까지 바꾸지는 않습니다. 이미 백그라운드에서 실행 중인 App 작업은 ApprovalHost를 직접 사용할 수 있습니다. 이전에 접수한 건이 끝날 때까지 기존 확정 처리기는 유지하세요.
기존 명시적 App 확정 작업 계약
이 선택적 계약은 호환되는 Core·SDK·네이티브 런타임을 함께 적용해야 합니다. SDK 설치만으로 활성화되지 않습니다. 기존 ApprovalHost::submitBound 호출은 동기 동작을 유지합니다. PHP SDK 0.10.15·React SDK 0.8.15 이상과 호환 호스트·런타임이 필요하며, Core 0.8.173·Manager 0.1.0-alpha.104에서 이 경로를 지원합니다.
ApprovalSubmissionHost::enqueueBound($submission, $attachmentStageIds, $finalizeWorkKey, $appDraftRef, $subjectRevision)는 결재 문서가 아닌 ApprovalSubmissionReceipt를 반환합니다. 앱 트랜잭션에서 검증한 초안을 고정하고 접수 ID를 보관하세요. 업무 폼의 상신 콜백은 { submissionId: receipt.publicId }를 반환합니다. 기존 동기 폼의 { caseId }도 유지됩니다. 호스트는 접수 상태와 상신 완료를 구분해 표시합니다.
앱은 approval.submission_delivery 콜백을 사용하는 관리형 작업 핸들러를 선언해야 합니다. 입력은 submission_id뿐입니다. 앱 DB 잠금을 잡기 전에 ApprovalSubmissionHost::delivery()로 결과를 조회합니다. 트랜잭션과 행 잠금 안에서 고정한 레코드 버전을 확인한 뒤, commit이면 전달된 결재 문서를 연결하고 release이면 보관한 초안을 복원합니다. 변경과 처리 결과를 원자적으로 저장하세요. 동일 결과의 재전달은 추가 변경 없이 성공해야 하며, 결과나 문서가 달라지면 거부해야 합니다. 이 확정 핸들러에서 알림을 보내거나 관련 없는 외부 서비스를 호출하지 마세요.
레코드 버전은 고정한 편집 버전이며 문서 내용 해시와 다릅니다. 초안 참조는 원래 작성 화면에서 사용하는 앱 발급 참조여야 합니다. 종료 결과가 확인될 때까지 원문과 첨부파일을 유지하세요. Core 접수는 앱 트랜잭션의 커밋 증거가 아니며 HTTP 시간 초과도 상신 실패의 증거가 아닙니다.
Core는 앱 확정 작업의 완료를 확인한 뒤 결재 문서를 활성화합니다. 처리를 시작하기 전에 취소할 수 있지만, 취소 요청만으로 앱 초안 잠금을 해제하면 안 됩니다. 결과가 불확실하면 조회 가능한 상태로 보존하고 확인해야 하며 새 키로 다시 상신하면 안 됩니다. 활성화 전 샌드박스에서 새로고침, 중복 클릭, 지연 완료, 접수 취소, 레코드 버전 충돌, 응답 유실을 검증하세요. 전용 확정 작업의 응답이 유실되면 동일한 불변 결과가 최대 세 번까지 전달될 수 있습니다. 원래 상신 작업을 다시 실행하지는 않습니다. 이 계약이 모든 불확실한 앱 작업 결과를 자동으로 복구하지는 않습니다.
업무 양식 결재자 권한 제한
ApprovalFormBindingDescriptor::requiredActorPermissionKeys에 결재자에게
필요한 추가 권한 키 목록을 선언합니다. 기본값은 빈 목록입니다. 예를 들어
requiredActorPermissionKeys: ['quality.inspection.authorize']를 선언하면
결재·합의 담당자는 해당 법인에서 모든 선언 권한과 approval.case.act를
함께 보유해야 합니다. 참조·회람 대상에는 추가 조건을 적용하지 않습니다.
업무 권한은 App이 선언하며 Core에 특정 App의 권한을 하드코딩하지 않습니다.
호스트는 후보를 필터링하고 직접 구성·저장·정책 결재선을 상신 시 검증합니다. 요구 권한을 결재 건에 보존하며 활성화·결재 처리·담당자 재지정 시 저장된 조건과 현재 조건을 모두 확인합니다. 현재 조건은 기존 진행 중 결재에도 적용됩니다. App에서 이 필드를 선언하기 전에 대응하는 PHP SDK와 호스트를 함께 반영해야 합니다. 이전 디코더는 지원하지 않는 선언을 거부하며 권한 조건을 무시하지 않습니다.