업무 프로세스로 노트 작업 실행하기
앱 소유 프로세스 작업을 선언·인가·시작하고 업무 결과까지 확인합니다.
업무 프로세스로 노트 작업 실행하기
Workshop Note를 앱 소유 자동 작업으로 보관합니다. 먼저 보호된 API 추가하기의 법인 소유 Note·status migration·archive Policy와 권한을 준비하세요. 생성기만 실행하면 생기는 항목이 아닙니다. 샌드박스에 프로세스 편집·실행 기능이 있어야 하며 작성 권한은 관리자에게 요청합니다.
작업 선언과 구현
src/Descriptors/WorkshopProcessActions.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'],
],
],
),
);
}
}src/Process/ArchiveNoteProcessWorkActionHandler.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',
]);
});
}
}복원된 사용자·법인으로 정확한 대상에 잠금을 걸고 인가합니다. 같은 상태 대입을 반복해도 결과는 같습니다. 화면 API는 중복 보관에 409를 반환하지만 worker 재시도에서는 이미 보관된 상태를 완료로 처리합니다. 수량 변경·결제·외부 효과는 이 단순 대입을 복사하지 말고 invocation의 멱등 키를 업무 효과와 함께 저장하세요.
기존 provider에 handler를 등록합니다:
use Nexia\Apps\Acme\Workshop\Process\ArchiveNoteProcessWorkActionHandler;
use Nexia\Process\Contracts\ProcessWorkActionRegistrar;
// Inside WorkshopServiceProvider::boot(), retain existing registrations.
$this->app->make(ProcessWorkActionRegistrar::class)->register(
'workshop',
'note.archive',
fn () => $this->app->make(ArchiveNoteProcessWorkActionHandler::class),
);descriptor set에 시작 binding을 추가합니다:
use Nexia\AppDescriptors\ProcessStartBindingDescriptor;
// Add this value to WorkshopProcessActions::appDescriptors() alongside the action.
new ProcessStartBindingDescriptor(
appKey: 'workshop',
bindingKey: 'note.archive',
documentKey: 'workshop.note_archive',
processId: 'WorkshopNoteArchive',
resourceKey: 'workshop.note',
startPermissionKey: 'workshop.note.archive',
labelKey: 'workshop.process_actions.note.archive.label',
),App locale에 workshop.process_actions.note.archive.label을 추가합니다(Archive Note / 노트 보관). 프로젝트에서 nexia dev를 실행하고 catalog·handler 준비를 기다립니다.
정의 게시와 대상 시작
프로세스 정의 화면에서 Note와 같은 법인에 키가 workshop.note_archive인 정의를 만듭니다. process ID는 WorkshopNoteArchive, 시작 리소스는 workshop.note로 설정하고 시작 → 자동 작업 → 종료를 연결합니다. 자동 작업에서 Workshop의 노트 보관을 선택해 저장·게시하세요. 선택 목록에 나타나거나 초안을 저장한 것만으로 실행 가능해지지 않습니다. 구현 없는 작업 이름만 연결해 게시하지 마세요.
NoteController에 아래 import·메서드를 추가합니다. 기존 인증 API 그룹에 POST /notes/{note}/archive-process를 연결하고 whereUuid('note')를 지정하세요. 호출 화면은 결과가 확정될 때까지 하나의 UUID 작업 ID를 보관하고 재시도에 재사용합니다:
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Nexia\Organization\Contracts\OrganizationDirectory;
use Nexia\Process\BoundProcessStart;
use Nexia\Process\Contracts\ProcessStarter;
use Nexia\ResourceReference\ResourceRef;
// Inside NoteController. Bind a POST route in the existing guarded App API group.
public function startArchiveProcess(Request $request, string $note): JsonResponse
{
$record = $this->resolveNote($request, $note, 'workshop.note.archive');
$this->authorize('archive', $record);
$data = $request->validate(['operation_id' => ['required', 'uuid']]);
$entity = app(OrganizationDirectory::class)->requireLegalEntityByKey($record->legal_entity_id);
$instance = app(ProcessStarter::class)->start(new BoundProcessStart(
bindingKey: 'workshop.note.archive',
legalEntity: $entity,
actor: $request->user(),
resourceRef: new ResourceRef('workshop', 'workshop.note', (string) $record->public_id, $record->name),
variables: [],
idempotencyKey: 'workshop.note.archive:'.$data['operation_id'],
));
return response()->json(['process_public_id' => $instance->publicId], 202);
}반환된 값은 시작된 프로세스의 식별자이며 보관 완료가 아닙니다. 화면에는 대기 상태를 표시하고 프로세스 진행을 확인한 뒤 허용된 Note를 다시 조회하세요. 정의 없음·권한 거절·handler 사용 불가를 직접 실행으로 우회하지 않습니다.
업무 결과 확인
- 같은 법인에서 Note 보관·조회 권한과 프로세스 접근 권한을 부여합니다.
- draft Note로 시작해 프로세스 완료 후 다시 엽니다.
status가archived여야 합니다. - 같은 작업 ID로 재시도합니다. 접수된 시작 식별자와 업무 효과가 중복되지 않아야 합니다. 응답 유실만으로 새 키를 만들지 않습니다.
- 권한 없는 사용자·다른 법인·없는 레코드를 확인합니다. 격리 테스트에서 handler 등록을 일부러 누락하면 정합성 검사가 실패해야 합니다.
- descriptor 발견과 실제 실행을 구분합니다. 생성자·catalog 검사는 워크플로우 실행 검증이 아닙니다.
사람 입력 폼·결재 대기·대상 리소스·버전 고정은 업무 프로세스 계약에서 확인합니다. 실행 문제는 프로세스·결재 오류 해결을 따르고, 끝나지 않은 작업을 DB에서 완료로 변경하지 않습니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.