앱 업무를 전자결재에 연결하기
binding·문서·폼을 연결하고 확정된 증거 제출과 결과 반영을 구현합니다.
앱 업무를 전자결재에 연결하기
보호된 API 추가하기의 법인 소유 Workshop Note와 status 필드를 준비합니다. 같은 조직의 업무 양식과 사용 가능한 결재선도 관리자가 게시해야 합니다. descriptor만으로 설정이나 사용자 권한이 생기지 않습니다.
binding·증거·폼 선언
src/Descriptors/WorkshopApprovalDescriptors.php를 만듭니다:
<?php
declare(strict_types=1);
namespace Nexia\Apps\Acme\Workshop\Descriptors;
use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\ApprovalDocumentSchema;
use Nexia\AppDescriptors\ApprovalFormBindingDescriptor;
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
final class WorkshopApprovalDescriptors implements AppDescriptorContribution
{
public static function appDescriptors(): AppDescriptorSet
{
return AppDescriptorSet::of(
new ApprovalFormBindingDescriptor(
appKey: 'workshop',
resourceKey: 'note',
actionKey: 'submit',
labelKey: 'workshop.approval.note.submit.label',
entryModes: ['link'],
formWidgetKey: 'workshop.note.submit',
documentSchemaKey: 'workshop.note',
descriptionKey: 'workshop.approval.note.submit.description',
submitPermissionKey: 'workshop.note.publish',
),
new ApprovalDocumentSchema(
appKey: 'workshop',
resourceKey: 'note',
titleKey: 'workshop.approval.note.document.title',
sections: [[
'title_key' => 'workshop.approval.note.document.summary',
'fields' => [
[
'key' => 'name',
'label_key' => 'workshop.note.name.label',
'type' => 'string',
],
[
'key' => 'status',
'label_key' => 'workshop.note.status.label',
'type' => 'string',
],
],
]],
),
);
}
}PermissionContribution에서 PermissionDefinition::many(appKey: 'workshop', resource: 'note', actions: ['publish'], assignmentScope: AssignmentScope::LegalEntity)로 workshop.note.publish를 선언하세요. archive Policy와 같은 방식으로 publish Policy를 추가하되 이 권한과 레코드 소유자를 검사합니다. descriptor·권한의 모든 라벨 키를 App locale에 넣습니다. 기본 생성 Note에는 이 업무 권한이 없습니다.
src/Descriptors/WorkshopApprovalSlotWidgets.php를 만듭니다:
<?php
declare(strict_types=1);
namespace Nexia\Apps\Acme\Workshop\Descriptors;
use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
use Nexia\AppDescriptors\DescriptorStatus;
use Nexia\AppDescriptors\SlotWidgetDescriptor;
final class WorkshopApprovalSlotWidgets implements AppDescriptorContribution
{
public static function appDescriptors(): AppDescriptorSet
{
return AppDescriptorSet::of(
new SlotWidgetDescriptor(
key: 'workshop.note.submit',
version: '1.0',
slot: 'approval.composer.business_form',
component: 'workshop.note.submit',
slotApiVersion: 2,
status: DescriptorStatus::Active,
permission: 'workshop.note.publish',
labelKey: 'workshop.approval.note.submit.label',
),
);
}
}프런트엔드 controller 연결
ApprovalBusinessFormSlotPropsV2를 받는 default 컴포넌트를 resources/js/approval/WorkshopNoteApprovalWidget.tsx에 만들고 기존 진입점에서 등록합니다:
import { approvalComposerBusinessFormRegistry } from '@nexia/sdk/host';
approvalComposerBusinessFormRegistry.register(
'workshop.note.submit',
() => import('./approval/WorkshopNoteApprovalWidget'),
);폼은 legalEntityPublicId 범위에서 허용된 Note를 조회·선택합니다. 생성된 App API client·query hook으로 아래 controller를 구현하세요. 다음은 컴포넌트 내부의 수명주기 코드이며 공용 제출 endpoint를 임의로 가정하지 않습니다:
import { useEffect } from 'react';
import type { ApprovalBusinessFormController, ApprovalBusinessFormSlotPropsV2 } from '@nexia/sdk';
// Inside your form component, after its authorized Note query and mutation hooks.
// controller must be memoized and null until the required inputs are ready.
const controller: ApprovalBusinessFormController | null = readyController;
useEffect(() => {
props.registerController(controller);
return () => props.registerController(null);
}, [props.registerController, controller]);| Controller 멤버 | 앱 구현 |
|---|---|
canSubmit | 허용된 Note·유효한 입력·필요한 조직이 준비됐을 때만 true |
saveDraft() | 앱 초안을 저장하고 { appDraftRef } 반환 |
buildPreview() | 허용된 값의 ApprovalDocumentView 반환, 준비 전에는 null |
submit(envelope) | 보호된 App POST 호출 후 { caseId } 반환, 실패는 화면에 표시 |
envelope에는 양식 키·버전, 결재선과 출처, 임시 첨부 ID, 보충 본문, 참조·회람 사용자 ID가 들어옵니다. 수동 제출 흐름에서는 사용자가 편집한 값을 보존해야 하며 무시하면 안 됩니다. 정확한 controller·제출 타입은 전자결재 계약에 있습니다. unmount·권한 거절·대상 변경 때 controller를 해제하고, 권한 실패 시 보호된 캐시도 지우세요.
인가된 업무 제출
기존 보호 API 그룹에 전용 POST를 추가합니다. 사용자·Note 소유자·publish Policy·허용 상태·예상 revision을 검사하세요. 앱에는 변경되지 않는 제출 의도를 저장합니다: 작업 UUID, 대상, 버전, 문서 값, 선택 양식·결재선, 처리 상태. 동시 편집으로 심사 증거가 바뀌지 않도록 하고 브라우저의 최종 승인 결과를 믿지 않습니다.
제출 방식은 다음 중 하나를 선택합니다:
| 방식 | 호스트 계약 |
|---|---|
| 수동 composer의 정확한 양식·선택 결재선 | submitBound(BoundApprovalSubmission, attachments); 검증된 단계로 ApprovalLineDefinition을 만들고 결재선 출처 유지 |
| 현재 관리자 설정·지정 경로 | submitCurrentBound(CurrentBoundApprovalSubmission, attachments); 호스트가 현재 설정을 해석하고 고정 |
다음은 저장한 intent와 복원된 사용자·법인을 사용하는 현재 설정 제출 예제입니다. 빈 첨부 목록은 UI에서도 첨부를 받지 않는 업무에만 사용합니다. intent의 경로·양식은 설정돼 있어야 하며 이 원격 호출이 앱 DB 트랜잭션과 함께 커밋된다는 뜻이 아닙니다:
use Nexia\Approval\Contracts\ApprovalHost;
use Nexia\Approval\CurrentBoundApprovalSubmission;
use Nexia\ResourceReference\ResourceRef;
// App operation after Policy, owner, state and expected-version checks.
// These values come from its persisted, immutable submission intent.
$result = app(ApprovalHost::class)->submitCurrentBound(
new CurrentBoundApprovalSubmission(
legalEntity: $legalEntity,
drafter: $actor,
templateKey: $intent->template_key,
routePolicyKey: $intent->route_policy_key,
bindingKey: 'workshop.note.submit',
resourceRef: new ResourceRef('workshop', 'workshop.note', $intent->note_public_id, $intent->note_name),
resourceVersion: $intent->resource_version,
documentValues: ['name' => $intent->note_name, 'status' => $intent->note_status],
title: $intent->note_name,
idempotencyKey: $intent->operation_id,
),
[],
);
// Persist $result->case->publicId and the returned template/binding versions.첨부를 받으면 prepareSupportingAttachments()를 사용하세요. 호스트 응답 유실은 승인 실패가 아니라 결과 불명입니다. 같은 intent와 멱등 키로 확인·재시도하고 새로운 intent 생성이나 업무 실행으로 우회하지 않습니다. 앱과 호스트의 커밋은 별개입니다. 재시도 보장 기간·fingerprint는 계약 문서에서 확인하세요.
호스트가 확정한 결과는 이벤트와 비동기 작업으로 소비합니다. 고정된 App·resource·action·대상·버전·case ID를 저장된 intent와 비교하고 현재 업무 상태를 재검사한 뒤 한 번만 반영하세요. ApprovalHost::caseSummary()로 정규 case 증거를 조회할 수 있습니다. 결재 완료 자체가 Note를 수정하지는 않습니다. 반려·회수·취소를 승인 경로로 처리하지 마세요.
전체 인계 확인
nexia dev로 동기화하고 제출 사용자에게 조회·publish 권한을 부여합니다.- 결재 양식 관리에서 Workshop Submit Note 업무 양식을 만들고 조직·결재선을 설정해 게시합니다.
- 게시된 양식에서 Note 선택·미리보기·초안 복원·제출을 확인합니다. 빈 폼은 binding·widget·registry 식별자 불일치부터 점검합니다.
- 결재 권한자로 완료한 뒤 연결된 앱 상태가 한 번만 바뀌는지 확인합니다. 결과 이벤트·기존 제출을 반복해도 중복되지 않아야 합니다.
- 다른 조직·권한 없음·revision 변경·결재선 없음·응답 유실·반려를 확인합니다. 인가나 정식 승인을 우회하면 안 됩니다.
직접 실행에도 결재가 필요할 수 있다면 supportsRequirementPolicy를 켜기 전에 직접·정식 제출 양쪽에서 ApprovalRequirements를 적용합니다. 양식 선택과 결재 필수 여부는 별도입니다. 설정·우선순위는 전자결재 계약을 따릅니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.