[Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현

[hywznn]

한 줄 목표

AI가 만든 업무가 사람 승인 없이 전달되지 않게 하고, AI 원본·HR 수정·승인 버전·상태 변경을 개인정보 없이 추적 가능한 감사 기록으로 남깁니다.

HITL 승인에서 저장할 것

• AI가 제안한 원본 snapshot
• HR이 수정한 최종 snapshot
• 변경된 field 목록과 안전한 before/after 요약
• 승인자, 승인 시각, 승인 대상 Task version
• 승인/반려 사유와 request_id, trace_id
• 사용한 agent/model/prompt/context/workflow version reference

날짜, 금액, 대상 근로자, 문서 종류, 안내 내용처럼 업무 결과에 영향을 주는 핵심 field가 승인 뒤 바뀌면 기존 승인을 무효화하고 READY_FOR_REVIEW로 돌려 재승인을 요구합니다.

UserRole과 ActorType 구분

• ADMIN, HR, VIEWER는 로그인 사용자의 UserRole입니다.
• HR_USER는 로그인 사용자의 감사 ActorType이며 Audit에 실제 Role snapshot을 함께 남깁니다.
• WORKER_LINK는 보안 링크를 사용한 근로자 행동입니다.
• AI_AGENT는 AI Run이 만든 제안의 출처일 뿐 로그인·승인 Role이 아닙니다.
• SYSTEM_RULE은 만료·재시도·복구 같은 정해진 Server command입니다.

Actor ID가 없거나 공개 token actor인 경우에도 원본 token 대신 안전한 reference만 기록합니다.

소유 API 8개

• POST /api/v1/tasks/{taskId}/approval-requests
• POST /api/v1/tasks/{taskId}/approve
• POST /api/v1/tasks/{taskId}/reject
• POST /api/v1/tasks/{taskId}/external-submissions
• POST /api/v1/tasks/{taskId}/evidence
• POST /api/v1/tasks/{taskId}/complete
• GET /api/v1/tasks/{taskId}/activities — 한 업무의 화면용 timeline
• GET /api/v1/audit-events — ADMIN용 사업장 감사 검색

approval-requests는 필수정보가 충족된 Task를 READY_FOR_REVIEW로 옮깁니다. 반려는 현재 승인 요청을 종료하고 사유를 남긴 뒤 READY_FOR_REVIEW → DRAFT로 되돌립니다. 외부 제출은 제출처·시각·안전한 reference를 저장하고 허용 상태에서 WAITING_EXTERNAL로 전이합니다.

activities가 timeline의 canonical API이므로 별도 /timeline을 만들지 않습니다. Audit API는 actor/event/resource/trace/date cursor filter를 제공하되 원문 내부 payload를 그대로 노출하지 않습니다.

감사 이벤트 최소 필드

• id, company_id, actor_type, 안전한 actor_id, 당시 user_role
• action, target_type, target_id
• request_id, trace_id, event_version
• 마스킹된 change_summary 또는 안전한 snapshot reference
• created_at
• IP·User-Agent는 기본 미저장. 필요 시 ADR에서 목적, 접근 역할, 마스킹/hash, 보존기간, 삭제 책임을 함께 확정

JWT, Worker Link 원본 token, 외국인등록번호, 여권번호, 계좌번호, 전화번호, 외부 API Key, 전체 Prompt는 저장하지 않습니다.

구현 범위

• Approval snapshot/revision, ExternalSubmission, Evidence, AuditEvent 모델과 migration
• 승인 요청·승인·반려·외부 제출·완료 command와 Workflow guard
• optimistic lock으로 동시 승인/수정 충돌 차단
• 중요 field fingerprint와 승인 version 비교
• 승인 후 중요 변경 시 승인 무효화·재검토 전환 core와 연동 Port ([Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6 PATCH에서 호출)
• 완료증빙 유형·파일 reference·제출 시각·actor 검증
• domain 변경과 감사 event를 같은 transaction으로 기록
• #25의 내구성 있는 publication과 연결
• activities는 내부 감사 event를 사용자용 안전 DTO로 projection
• /api/v1/audit-events tenant scope, ADMIN 권한, cursor pagination
• 감사 기록의 일반 수정·삭제 경로 금지

반드시 기록할 행동

• Task/AiRun 후보 생성·확정·폐기
• Task 수정과 핵심값 변경
• 승인 요청·승인·반려·승인 무효화
• Worker Link 발급·회전·폐기·조회·응답·문서 제출
• 외부기관 제출·대기, 증빙 연결, 완료·실패·취소
• 필요한 인증 실패와 권한 거부

완료 조건

• 승인 전·승인 무효화 후 완료가 차단됩니다.
• Worker Link 발급 차단 연동은 #7에서 ApprovalControlPort를 사용해 검증합니다.
• AI 원본과 HR 수정본, changed fields, 승인 version/reason을 보존합니다.
• 반려 후 Task가 DRAFT로 돌아가고 이전 승인 요청을 재사용할 수 없습니다.
• 외부 제출 reference 없이 WAITING_EXTERNAL로 전이할 수 없습니다.
• 중요 field 변경 뒤 기존 승인을 재사용할 수 없습니다.
• Task activities로 전체 주요 흐름을 시간순 재구성할 수 있습니다.
• ADMIN이 사업장 범위의 감사 event를 filter해 조회할 수 있습니다.
• 타 사업장 감사 기록과 민감 원문을 조회할 수 없습니다.
• 감사 기록 실패 시 핵심 상태 변경도 함께 실패합니다.
• 동시 승인 경쟁·stale 수정·완료 guard와 개인정보 차단 테스트가 있습니다.

이번 이슈에서 하지 않는 것

• 규제기관 제출용 장기 보존 정책 확정
• 외부 SIEM 연동과 모든 HTTP 전문 저장
• AI 결과 자동 승인
• Event publication 재처리 구현: [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25

선행/후속 관계

• 선행: [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23
• 연결: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25
• 후속: [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7, [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

구현 PR

• feat: 승인·감사 워크플로우 구현 #37 — 코드·H2 통합 테스트 완료, PostgreSQL 17 CI와 팀원 리뷰 대기
• [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25 durable publication 연결과 [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7 Worker Link guard는 각 소유 이슈에서 후속 통합

용어 도움말

• HITL: Human-in-the-loop. 중요한 AI 결과를 사람이 검토·승인하는 구조입니다.
• Snapshot: 승인 시점의 내용을 나중 변경과 구분해 보존한 값입니다.
• Projection: 내부 기록에서 화면에 필요한 안전한 field만 골라 만든 조회 모델입니다.