03 Domain and Workflow

도메인과 Workflow

핵심 도메인

도메인	대표 데이터	책임
Company	사업장 ID·상태	모든 tenant 데이터의 격리 기준
User / RefreshToken	이메일·password hash·Role·token hash	HR·ADMIN·VIEWER 인증
Worker	표시 이름·국적·언어·근무 상태·업무 날짜	최소 HR Context
WorkerDocument	유형·제출 상태·유효/만료일·제출처	문서 준비 상태 추적
StoredFile	storage key·MIME·size·hash·검증 상태	원본과 business metadata 분리
Task	유형·상태·필수정보·현재 version	실제 HR 업무카드
TaskChecklistItem	확인 항목·완료·actor	상태 전이와 완료 조건
AiRun	입력 hash·상태·버전·오류·trace	복구 가능한 비동기 AI 실행
AiCandidate	유형·slot·누락·모호성·선택 상태	확정 전 AI 제안
ApprovalRevision	AI 원본·HR 수정·changed fields·승인 version	HITL 결정 근거
Evidence	유형·file reference·제출 시각	완료 조건 증명
TaskActivity	안전한 사용자 화면 projection	한 업무의 timeline
WorkerLink	token hash·만료·폐기·사용 정책	로그인 없는 최소 접근
WorkerResponse	응답 유형·문서 reference	근로자의 제한된 행동
AuditEvent	Actor·행동·대상·request/trace	변경 불가능한 책임 기록
EventPublication	event ID·상태·시도·오류	재시작 후 후속 처리 복구
ImportJob / Row	mapping·행 오류·확정 상태	M4 선택적 일괄 등록

관계 초안

erDiagram
  COMPANY ||--o{ USER : owns
  COMPANY ||--o{ WORKER : employs
  WORKER ||--o{ WORKER_DOCUMENT : has
  STORED_FILE ||--o{ WORKER_DOCUMENT : referenced_by
  COMPANY ||--o{ TASK : owns
  WORKER ||--o{ TASK : subject_of
  TASK ||--o{ TASK_CHECKLIST_ITEM : contains
  COMPANY ||--o{ AI_RUN : owns
  AI_RUN ||--o{ AI_CANDIDATE : produces
  AI_CANDIDATE o|--o| TASK : confirmed_as
  TASK ||--o{ APPROVAL_REVISION : reviewed_as
  TASK ||--o{ EVIDENCE : proves
  TASK ||--o{ WORKER_LINK : exposes_minimum
  WORKER_LINK ||--o{ WORKER_RESPONSE : receives
  TASK ||--o{ AUDIT_EVENT : records
  COMPANY ||--o{ EVENT_PUBLICATION : recovers

Loading

실제 FK·unique constraint·보존 정책은 migration PR에서 확정합니다. 모든 tenant domain row는 직접 또는 부모를 통해 company_id 범위를 검증합니다.

업무카드 유형

TaskType	설명	예시
EXPIRY_RENEWAL	체류 연장 준비	만료일·필요문서 확인
DOCUMENT_REQUEST	근로자 서류 요청	여권 사본 요청
PAYROLL_EXPLANATION	급여 항목 안내	공제 항목 설명
EMPLOYMENT_CHANGE	고용변동 준비	기준일·사실관계 확인
WORK_NOTICE	업무 공지	교육·안전·일정 안내

Task 상태

상태	쉬운 뜻	다음 행동
DRAFT	작성 중인 초안	정보 보완·검토 요청
NEEDS_INFO	필수정보 부족	추가정보 입력
READY_FOR_REVIEW	사람 검토 가능	승인·반려·취소
APPROVED	현재 version 승인	처리 시작·근로자/외부 대기
IN_PROGRESS	담당자가 처리 중	대기·완료·실패
WAITING_WORKER	근로자 응답/문서 대기	응답 확인·처리 재개
WAITING_EXTERNAL	외부기관 결과 대기	결과 확인·처리 재개
COMPLETED	증빙까지 충족	일반 수정 금지
FAILED	처리 실패·복구 판단 필요	명시적 재개·정보 보완·취소
CANCELLED	사유를 남기고 종료	일반 수정 금지

Task 상태 전이

stateDiagram-v2
  [*] --> DRAFT
  DRAFT --> NEEDS_INFO
  DRAFT --> READY_FOR_REVIEW
  NEEDS_INFO --> READY_FOR_REVIEW
  READY_FOR_REVIEW --> APPROVED
  APPROVED --> IN_PROGRESS
  APPROVED --> WAITING_WORKER
  IN_PROGRESS --> WAITING_WORKER
  IN_PROGRESS --> WAITING_EXTERNAL
  WAITING_WORKER --> IN_PROGRESS
  WAITING_WORKER --> WAITING_EXTERNAL
  WAITING_EXTERNAL --> IN_PROGRESS
  APPROVED --> COMPLETED
  IN_PROGRESS --> COMPLETED
  WAITING_WORKER --> COMPLETED
  WAITING_EXTERNAL --> COMPLETED
  IN_PROGRESS --> FAILED
  WAITING_WORKER --> FAILED
  WAITING_EXTERNAL --> FAILED
  FAILED --> IN_PROGRESS
  FAILED --> NEEDS_INFO
  DRAFT --> CANCELLED
  NEEDS_INFO --> CANCELLED
  READY_FOR_REVIEW --> CANCELLED
  APPROVED --> CANCELLED
  IN_PROGRESS --> CANCELLED
  WAITING_WORKER --> CANCELLED
  WAITING_EXTERNAL --> CANCELLED
  FAILED --> CANCELLED
  COMPLETED --> [*]
  CANCELLED --> [*]

Loading

완료·취소는 terminal 상태입니다. 운영 실수 복구가 필요하면 일반 PATCH가 아닌 별도 정책·권한·감사 기록으로 처리합니다.

명령과 guard

명령	핵심 검사
requestReview	필수정보·허용 TaskType·현재 상태
approve	READY_FOR_REVIEW, 사람 Role, 현재 version snapshot
start	승인 version과 현재 version 일치
waitWorker	승인된 안내/문서 요청, 유효 Link 정책
waitExternal	제출 여부·제출처·시각
complete	checklist·필수 증빙·승인 유효성
fail	안전한 오류 코드·actor·복구 가능성
resume	실패/대기 사유 해소와 명시적 사유
cancel	권한·취소 사유·현재 비terminal 상태

Controller와 JPA setter가 상태를 직접 바꾸지 않습니다. Workflow Service가 상태·Role·company_id·필수정보·증빙·승인 version을 검사하고 @Version으로 동시 수정을 감지합니다.

AI Run 상태

상태	의미
QUEUED	Run과 실행 요청이 DB에 저장됨
RUNNING	Provider 호출 중
VALIDATING	JSON·업무 규칙·핵심값 검사 중
NEEDS_REVIEW	결과는 있으나 사람 확인이 필요함
SUCCEEDED	검증된 후보를 보여줄 수 있음
RETRYING	제한된 정책으로 다시 실행 중
FAILED	가짜 결과 없이 안전하게 실패함

stateDiagram-v2
  [*] --> QUEUED
  QUEUED --> RUNNING
  RUNNING --> VALIDATING
  RUNNING --> RETRYING
  RETRYING --> RUNNING
  VALIDATING --> SUCCEEDED
  VALIDATING --> NEEDS_REVIEW
  QUEUED --> FAILED
  RUNNING --> FAILED
  VALIDATING --> FAILED
  RETRYING --> FAILED
  SUCCEEDED --> [*]
  NEEDS_REVIEW --> [*]
  FAILED --> [*]

Loading

FAILED 뒤 새 실행은 같은 row 상태를 무한히 되돌리기보다 retry attempt와 audit를 명시적으로 남깁니다. 정확한 정책은 #24에서 고정합니다.

AI 후보와 실제 Task

• AI Run은 후보를 만들 뿐 실제 Task를 자동 생성하지 않습니다.
• HR은 POST /ai-runs/{runId}/confirm에서 선택한 후보와 편집값을 확정합니다.
• 같은 confirm 재시도는 unique constraint로 Task를 한 번만 생성합니다.
• 확정 Task도 DRAFT, NEEDS_INFO, READY_FOR_REVIEW 중 하나이며 승인 전입니다.
• 제외 후보는 물리 삭제하지 않고 선택하지 않은 이유와 actor를 감사 기록에 남깁니다.
• 날짜·금액·대상·문서 종류·안내 내용 변경은 승인 fingerprint를 무효화합니다.

복합 요청 예시

입력:

응웬반A 체류연장 준비하고 여권 사본도 요청해줘

후보	유형	보존할 핵심값	초기 Task 상태
1	EXPIRY_RENEWAL	worker ID·체류 만료일	정보에 따라 NEEDS_INFO 또는 READY_FOR_REVIEW
2	DOCUMENT_REQUEST	worker ID·PASSPORT_COPY	READY_FOR_REVIEW

두 후보는 독립적으로 확정·편집·제외할 수 있으며 승인도 각각 수행합니다.

완료와 실패 판단

• 근로자 안내: 확인 또는 허용된 응답 기록
• 문서 요청: 검증된 제출 reference와 HR 확인 정책
• 외부기관 업무: 제출 여부·제출처·접수증 등 증빙
• 단순 공지: 승인된 안내 전달과 확인 정책
• 처리 실패: 오류 코드·실패 시점·복구 가능한 다음 행동

외부기관 자동 제출과 AI의 법적 최종 판단은 MVP 범위가 아닙니다.

관련 이슈

• #6 Workflow
• #11 승인·감사
• #24 AI Run
• #25 Event 재처리
• #7 Worker Link