전자 결재에 기여하기 예제

이 예제는 지금까지 만든 Workshop Note를 실제 전자결재 작성 흐름에 연결합니다. 앞의 Descriptor 예제가 관리 화면에 노트 제출 선택지를 게시했다면, 여기서는 Slot Widget, frontend controller, App 소유 제출 endpoint를 같은 identity로 묶습니다.

이 작업이 끝나면

위 캡처는 Descriptor catalog에서 노트 제출을 골라 업무 양식에 연결한 실제 화면입니다. 선택하면 기존 노트를 전자결재에 연결합니다.라는 App 설명이 표시됩니다. 이 양식을 생성·게시한 뒤에만 사용자용 전자결재 작성 목록에 나타납니다.

세 계약이 Core의 작성 흐름에 연결되는 방식

이 예제는 하나의 클래스를 상속해 완성되는 기능이 아니라, 다음 세 경계를 같은 workshop.note.submit identity로 연결합니다.

게시된 Legal Entity 양식
  → Core 작성기가 binding의 formWidgetKey를 읽음
  → SlotWidgetCompositionResolver가 허용된 Slot descriptor를 선택
  → frontend registry에서 같은 key의 Workshop Widget을 로드
  → Widget이 App 제출 endpoint를 호출
  → App이 Note·Policy·revision을 재검사
  → ApprovalHost::submitBound()
  → CoreApprovalHost가 Core 결재 case를 생성12345678

App endpoint는 CoreApprovalHost를 직접 import하거나 상속하지 않습니다. 생성자에서 SDK의 ApprovalHost 인터페이스를 주입받고, Core host가 그 인터페이스를 CoreApprovalHost 구현에 bind합니다. 이 경계 덕분에 Core는 Workshop 모델을 모르고, Workshop도 Core Eloquent 모델을 사용하지 않습니다.

1. Slot Widget Descriptor 추가

예제 파일을 Workshop의 descriptor discovery root에 복사합니다.

cp docs/developers/examples/approval-contribution/WorkshopApprovalSlotWidgets.php \
  packages/workshop/src/Descriptors/WorkshopApprovalSlotWidgets.php12

핵심 identity는 네 곳에서 완전히 같아야 합니다.

Approval binding formWidgetKey
        = Slot descriptor key
        = Slot descriptor component
        = frontend registry key
        = workshop.note.submit12345

Slot descriptor는 Core가 소유한 approval.composer.business_form slot을 사용하고, 앞에서 만든 workshop.note.publish 권한으로 가시성을 제한합니다.

2. frontend Widget 등록

packages/workshop/resources/js/index.ts에 공개 App SDK registry 등록을 추가합니다.

import { approvalComposerBusinessFormRegistry } from '@nexia/sdk/host';

approvalComposerBusinessFormRegistry.register(
    'workshop.note.submit',
    () => import('./approval/WorkshopNoteApprovalWidget'),
);123456

WorkshopNoteApprovalWidget은 ApprovalBusinessFormSlotPropsV2를 받고 Note를 읽은 뒤 composer controller를 등록합니다.

registerController({
    canSubmit: note !== null && note.status === 'active',
    saveDraft: async () => ({ appDraftRef: note.public_id }),
    buildPreview: () => ({
        title: note.name,
        sections: [{
            title: t('workshop.approval.note.document.summary'),
            fields: [
                { key: 'name', label: t('workshop.note.name.label'), value: note.name },
                { key: 'status', label: t('workshop.note.status.label'), value: note.status },
            ],
        }],
    }),
    submit: async (envelope) => {
        const response = await api.post(
            `/legal-entities/${legalEntityPublicId}/workshop/notes/${note.public_id}/submit-approval`,
            {
                template_key: envelope.templateKey,
                template_version: envelope.templateVersion,
                line: envelope.line,
                reference_user_ids: envelope.referenceUserIds,
                circulation_user_ids: envelope.circulationUserIds,
            },
        );
        return { caseId: response.data.approval_case.public_id };
    },
});123456789101112131415161718192021222324252627

위 코드는 controller 연결 구조를 보여주는 축약본입니다. 실제 Widget은 loading, not-found, 권한 거부, idempotency key, 첨부 staging, 오류 상태까지 처리해야 합니다. 브라우저는 Core endpoint가 아니라 App endpoint를 호출합니다.

3. App에서 재인가하고 제출

App endpoint는 요청의 Note를 Legal Entity 범위에서 다시 찾고 workshop.note.publish Policy를 검사합니다. 현재 상태와 revision도 잠근 상태에서 확인한 뒤 App SDK의 ApprovalHost를 호출합니다.

$case = $this->approvals->submitBound(
    new BoundApprovalSubmission(
        legalEntity: $legalEntity,
        drafter: $actor,
        templateKey: $input['template_key'],
        templateVersion: (int) $input['template_version'],
        bindingKey: 'workshop.note.submit',
        bindingVersion: '1.0',
        resourceRef: new ResourceRef(
            appKey: 'workshop',
            resourceKey: 'workshop.note',
            resourceId: (string) $note->public_id,
            display: $note->name,
            href: '/apps/workshop/notes/'.$note->public_id,
        ),
        resourceVersion: (string) $note->updated_at->getTimestamp(),
        documentValues: [
            'name' => $note->name,
            'status' => $note->status->value,
        ],
        lineDefinition: $line,
        title: $note->name,
    ),
);123456789101112131415161718192021222324

App은 Note와 Policy를 소유하고, Core는 결재선·case·감사 증거를 소유합니다. App이 Core Eloquent model을 import하거나 Core가 Workshop model을 알아서는 안 됩니다.

4. 양식을 게시하고 화면 확인

1. 전자결재 → 양식 관리 → 새 전자결재 양식에서 업무 양식을 고릅니다.
2. 도메인 양식 → Workshop → 노트 제출을 선택합니다.
3. 이름, Legal Entity 범위, 결재 규칙을 입력해 양식을 생성하고 게시합니다.
4. 전자결재 → 전자결재 작성에서 게시한 Workshop 양식을 엽니다.
5. 기존 Note를 연결했을 때 이름·상태와 공용 결재선이 함께 보이는지 확인합니다.
6. 제출 뒤 생성된 결재 case로 이동하는지 확인합니다.

binding만 추가했을 때 전자결재 작성에 보이지 않는 것은 정상입니다. 그 목록은 active descriptor 전체가 아니라 게시된 Legal Entity 양식을 보여줍니다.

5. 발견 확인

sh docs/developers/examples/approval-contribution/verify.sh1

스크립트가 Workshop Approval contribution discovered and validated.를 출력하면 정적 contribution 검증이 끝난 것입니다.

자주 발생하는 오류

설정별 동작까지 확인하기

이 Workshop 예제는 최소 기여 연결을 검증합니다. 결재 필수 정책이나 기본 절차 설치를 자동으로 추가하지는 않습니다. 전자 결재에서 개발자의 정책 적용 조건과 관리자의 양식·결재선·필수 설정 순서를 확인한 뒤, 업무 프로세스의 실제 구매 흐름을 따라가세요. 자동 입력과 사람 검토, 결재 필수·불필요, 결재선 준비, 결과 분기, 기본안 업데이트를 하나의 흐름에서 비교할 수 있습니다.