본문으로 건너뛰기

예제

프로세스 작업·handler 등록하기

앱 폴더에 예제를 적용하고 연결된 구현·확인 절차를 따릅니다.

예제 유형 레시피

개요

프로세스 작업·handler 등록하기

공개 CLI로 만든 Workshop 앱에서 시작합니다. 네임스페이스는 Nexia\Apps\Acme\Workshop이며 실제 등록한 App 식별자에 맞게 변경하세요. Core 저장소가 아닌 앱 폴더에서 작업합니다.

예제 적용

표시된 WorkshopProcessActions.php 코드를 src/Descriptors/WorkshopProcessActions.php에 적용합니다. 생성된 Manifest의 발견 경로와 기존 등록을 보존하세요. 선행 조건·나머지 파일은 전체 가이드를 따릅니다.

프로세스 예제는 ArchiveNoteProcessWorkActionHandler.php도 src/Process/에 넣고 기존 provider에서 factory를 등록합니다. 가이드에 시작 binding·보호된 시작 API·정의 게시 절차가 있습니다.

앱 폴더의 nexia check로 소스를 확인합니다. 프로젝트 nexia dev에서 소스·catalog·프런트엔드 준비 완료를 기다리고 워크스페이스 자격 증명 및 접근에서 필요한 권한을 부여하세요.

확인

가이드의 허용·거절·재시도·실제 화면 확인을 수행합니다. 문법·descriptor 생성 성공만으로 DB 쓰기·전달·전체 업무 성공을 증명하지 않습니다. 호스트 캐시 명령이나 폐기된 검증 스크립트는 필요하지 않으며 삭제된 스크립트의 성공 문구를 기다리지 않습니다.

포함된 파일

BPMN Work Action Descriptor

docs/developers/examples/business-process-contribution/WorkshopProcessActions.php
코드 예시
PHP
<?php

declare(strict_types=1);

namespace Nexia\Apps\Acme\Workshop\Descriptors;

use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
use Nexia\AppDescriptors\ProcessWorkActionDescriptor;

final class WorkshopProcessActions implements AppDescriptorContribution
{
    public const ARCHIVE_NOTE = 'note.archive';

    public static function appDescriptors(): AppDescriptorSet
    {
        return AppDescriptorSet::of(
            new ProcessWorkActionDescriptor(
                kind: 'serviceTask',
                appKey: 'workshop',
                actionKey: self::ARCHIVE_NOTE,
                labelKey: 'workshop.process_actions.note.archive.label',
                topic: 'workshop.note.archive',
                outputContract: [
                    'note_public_id' => ['type' => 'string'],
                    'status' => [
                        'type' => 'string',
                        'enum' => ['draft', 'archived'],
                    ],
                ],
            ),
        );
    }
}

App 소유 Work Action Handler

docs/developers/examples/business-process-contribution/ArchiveNoteProcessWorkActionHandler.php
코드 예시
PHP
<?php

declare(strict_types=1);

namespace Nexia\Apps\Acme\Workshop\Process;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Gate;
use Nexia\Apps\Acme\Workshop\Models\Note;
use Nexia\Process\Contracts\ProcessWorkActionHandler;
use Nexia\Process\Domain\ProcessWorkActionException;
use Nexia\Process\ProcessWorkActionInvocation;
use Nexia\Process\ProcessWorkActionResult;

final readonly class ArchiveNoteProcessWorkActionHandler implements ProcessWorkActionHandler
{
    public function handle(ProcessWorkActionInvocation $invocation): ProcessWorkActionResult
    {
        if ($invocation->resourceRef->appKey !== 'workshop'
            || $invocation->resourceRef->resourceKey !== 'workshop.note') {
            throw new ProcessWorkActionException(
                'The Process instance is not anchored to a Workshop note.',
                'workshop_note_resource_mismatch',
            );
        }

        return DB::transaction(function () use ($invocation): ProcessWorkActionResult {
            $note = Note::query()
                ->where('public_id', $invocation->resourceRef->resourceId)
                ->where('legal_entity_id', $invocation->legalEntity->key())
                ->lockForUpdate()
                ->first();

            if (! $note instanceof Note) {
                throw new ProcessWorkActionException(
                    'The Workshop note is not available in this Legal Entity.',
                    'workshop_note_unavailable',
                );
            }

            Gate::forUser($invocation->actor)->authorize('archive', $note);

            if ($note->status !== 'archived') {
                $note->forceFill(['status' => 'archived'])->save();
            }

            return new ProcessWorkActionResult(output: [
                'note_public_id' => (string) $note->public_id,
                'status' => 'archived',
            ]);
        });
    }
}

앱 단독 대상 거절 테스트

docs/developers/examples/business-process-contribution/WorkshopProcessWorkActionTest.php
코드 예시
PHP
<?php

declare(strict_types=1);

use Nexia\Apps\Acme\Workshop\Process\ArchiveNoteProcessWorkActionHandler;
use Nexia\Identity\Contracts\Actor;
use Nexia\Organization\Contracts\LegalEntity;
use Nexia\Process\Domain\ProcessWorkActionException;
use Nexia\Process\ProcessWorkActionInvocation;
use Nexia\ResourceReference\ResourceRef;

test('archive rejects a different resource before accessing the database', function (): void {
    $invocation = new ProcessWorkActionInvocation(
        appKey: 'workshop',
        actionKey: 'note.archive',
        descriptorVersion: '1.0',
        processInstancePublicId: 'ac0588d8-8d86-4f4e-9ddf-202a9dafcb06',
        externalTaskKey: 'task-1',
        idempotencyKey: 'archive-task-1',
        legalEntity: $this->createMock(LegalEntity::class),
        actor: $this->createMock(Actor::class),
        resourceRef: new ResourceRef(
            'workshop', 'workshop.example',
            'd7c1c7c4-f1a5-4886-afaa-e3eaa687e91d', 'Different record',
        ),
        input: [],
    );

    try {
        (new ArchiveNoteProcessWorkActionHandler)->handle($invocation);
        $this->fail('Expected a resource mismatch.');
    } catch (ProcessWorkActionException $exception) {
        expect($exception->errorCode)->toBe('workshop_note_resource_mismatch');
    }
});
예제 원본: docs/developers/examples/business-process-contribution/README.ko.md