[Task Workflow] 업무카드·체크리스트·상태 전이 구현

[hywznn]

한 줄 목표

수동 입력으로 실제 Task를 만들고, Server의 명시적 command와 guard를 통과할 때만 업무 상태가 바뀌도록 구현합니다.

초보자용 구분

• Knowledge Workflow Catalog: 업무에 필요한 slot, checklist template, 공식 근거, evidence requirement를 정의한 버전 고정 설명서입니다.
• AI Agent Pipeline: Catalog를 읽어 workflow_id와 후보를 제안합니다.
• Server Task Workflow: 실제 Task의 상태, 권한, 승인 revision과 업무 기록을 실행합니다.

GET /api/v1/workflow-catalogs는 Server가 제공하지만 정의 원본은 fowoco/knowledge release입니다. Server는 Catalog YAML을 독자적으로 수정하지 않고 검증된 read-only projection만 읽습니다.

Task 상태

상태	의미
DRAFT	작성 중인 초안
NEEDS_INFO	필수정보가 부족함
READY_FOR_REVIEW	필수조건과 승인 요청 snapshot을 갖춰 검토 가능
APPROVED	현재 Task revision을 HR이 승인함
WAITING_WORKER	근로자 응답·문서를 기다림
WAITING_EXTERNAL	외부기관 처리 결과를 기다림
COMPLETED	완료 조건과 증빙을 충족함
CANCELLED	사유와 actor를 남기고 종료함

기술 장애는 Task FAILED로 섞지 않고 AiRun/Event 오류와 Audit로 관리합니다. COMPLETED, CANCELLED는 terminal입니다.

소유 API

• GET /api/v1/workflow-catalogs
• GET /api/v1/tasks
• POST /api/v1/tasks
• GET /api/v1/tasks/{taskId}
• PATCH /api/v1/tasks/{taskId}
• PATCH /api/v1/tasks/{taskId}/checklist-items/{itemId}
• POST /api/v1/tasks/{taskId}/cancel

승인·반려·외부 제출·증빙·완료·활동 이력은 #11, Worker Link 전이는 #7, AI candidate 채택은 #24가 소유합니다.

구현 체크리스트

• Task, checklist, transition history와 Flyway schema
• TaskType, TaskStatus, TaskSource, 기능별 Error Code
• TaskWorkflowService command/guard와 transaction
• 수동 생성, 내용 수정, checklist 재평가, 취소 전이
• company_id, role, required slot, 승인 무효화 guard
• Entity setter/Controller의 임의 상태 변경 차단
• @Version과 request expected_version 충돌 처리
• Knowledge bundle의 workflow_catalog_version, workflow_id, checklist snapshot 저장
• #25가 이어받을 PostgreSQL durable publication 경계를 ADR-0003에 정의
• AI candidate ACCEPT/DISCARD와 Task 중복 방지 — #24에서 구현
• 승인된 Task의 Worker Link 발급·폐기 전이 — #7에서 구현
• Domain Event의 실제 durable publication adapter — #25에서 구현

완료 기준

• 허용·금지 상태 전이를 parameterized test로 검증
• required slot·필수 checklist 없이 승인 요청 불가
• 중요값 변경 시 기존 승인 재사용 불가
• 조건이 충분한 승인 후 수정은 기존 승인 무효화 + 새 snapshot + READY_FOR_REVIEW
• 조건이 부족한 승인 후 수정은 기존 승인 무효화 + NEEDS_INFO
• 필수 evidence 없이 COMPLETED 불가 — [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11 통합 test
• 동시 수정 중 하나만 성공하고 타 사업장 접근은 404
• OpenAPI에 상태, expected_version, 409/422, snake_case 계약 반영
• ./gradlew clean test 통과

#5와의 경계

PR #37의 V3 Worker core와 #39의 WorkerTaskContextReader는 Task FK와 업무 가능 여부 확인에 필요한 최소 기반입니다. Worker CRUD·상세 DTO·Document metadata는 #5 담당 범위이며 이 Issue에서 대신 구현하지 않습니다.

배포 주의

• local/test: 저장소의 Knowledge 0.2.0 DRAFT 개발 projection 사용
• prod: WORKFLOW_CATALOG_LOCATION에 RELEASED projection 필수
• 운영에서 DRAFT bundle이면 Server 시작 거부

검증·PR

• 선행 승인·감사: PR feat: 승인·감사 워크플로우 구현 #37
• Task Workflow 구현: PR feat: 업무카드·체크리스트 Workflow 구현 #39 (PR feat: 승인·감사 워크플로우 구현 #37 위의 stacked PR)
• 로컬 전체 test: 통과
• Wiki·README·OpenAPI: 갱신 완료

경계 밖

• Prompt·Agent·Provider 구현: fowoco/ai
• Workflow Catalog 원본·공식 근거 수정: fowoco/knowledge
• 승인·감사 API: [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11
• Worker Link: [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7
• AI candidate/AiRun: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• Event publication 복구: [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25

관계

• Native blocked by: [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11
• 완료된 기반: [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23
• 최소 연동 경계: [Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5
• 후속 통합: [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7, [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10, [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2