03 Domain and Workflow

도메인과 Workflow

핵심 도메인

도메인	대표 데이터	책임
Company	사업장 ID, 이름, 상태	데이터 격리의 기준
User	이메일, 비밀번호 해시, 역할	HR·관리자·조회자 인증
Worker	표시 이름, 국적, 언어, 근무 상태, 날짜	HR 업무 Context
WorkerDocument	서류 유형, 상태, 제출처, 만료일	서류 준비 상태 추적
StoredFile	저장 키, MIME, 크기, 해시, 보존 상태	파일 원본과 메타데이터 분리
Task	유형, 상태, 필수정보, 승인·완료 조건	실제 HR 업무카드
TaskAnalysis	HR 원문 참조, 버전, 전체 분석 상태	AI 분석 단위
TaskAnalysisCandidate	후보 유형, 대상, 누락정보, 선택 여부	확정 전 AI 제안
TaskChecklistItem	확인 항목, 완료 여부, 담당자	Workflow 진행 조건
ApprovalRequest	요청자, 대상 버전, 검토 상태	승인 절차 시작점
Evidence	증빙 유형, 파일 참조, 제출 시각	완료 조건 증명
TaskActivity	사용자 화면용 행동 이력	업무 타임라인 조회
WorkerLink	토큰 해시, 만료·폐기	로그인 없는 제한 접근
WorkerResponse	응답 유형, 제출 참조	근로자의 제한된 행동
ImportJob / ImportRow	열 매핑, 행 오류, 확정 상태	선택적 일괄 등록
CompanySettings	링크 만료·임박 기준 등	사업장 운영 정책
AuditLog	Actor, 행동, 대상, 시각	책임과 변경 이력
AiInvocation	Provider·버전·지연·오류	AI 호출 재현과 품질 분석

업무카드 유형

MVP 시작 유형은 다음과 같습니다.

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

상태 정의

상태	뜻	다음 행동
DRAFT	사람이 검토하기 전 초안	정보 검사 또는 편집
NEEDS_INFO	필수정보 부족	HR에게 추가정보 요청
READY_FOR_REVIEW	검토 가능한 후보	HR 승인 또는 폐기
APPROVED	HR 승인 완료	링크 발급·외부 대기·완료
WAITING_WORKER	근로자 확인·응답 대기	응답 확인
WAITING_EXTERNAL	외부기관 처리 대기	접수·결과 확인
COMPLETED	완료 조건과 증빙 충족	수정 금지, 조회만 허용
CANCELLED	폐기·취소	사유 보존, 재사용 금지

기본 상태 전이

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

Loading

상태는 Controller나 JPA Entity setter로 직접 바꾸지 않고 TaskWorkflowService가 다음을 검사한 후 변경합니다.

1. 현재 상태에서 목표 상태가 허용되는가?
2. 필수정보가 채워졌는가?
3. 현재 사용자가 필요한 역할을 가졌는가?
4. 승인자가 기록됐는가?
5. 완료증빙 또는 외부 제출 결과가 필요한가?
6. 같은 사업장의 업무인가?

AI 후보와 실제 업무

• AI 분석 결과는 먼저 TaskAnalysisCandidate로 저장합니다.
• HR이 POST /task-analyses/{analysisId}/confirm에서 선택한 후보만 실제 Task가 됩니다.
• 실제 Task도 승인 전에는 DRAFT, NEEDS_INFO, READY_FOR_REVIEW 중 하나입니다.
• HR 승인 전에는 Worker Link를 발급할 수 없습니다.
• HR이 삭제한 후보도 물리 삭제하지 않고 CANCELLED와 사유를 남깁니다.
• 승인 후 제목·대상자·날짜·서류 같은 핵심값이 바뀌면 재승인합니다.
• AI는 외부기관 제출 여부나 법률적 결론을 자동 확정하지 않습니다.

복합 요청 예시

입력:

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

후보 1:

• 유형: EXPIRY_RENEWAL
• 대상: 응웬반A의 worker_id
• 필수정보: 체류 만료일, 필요한 절차 Context
• 초기 상태: 정보에 따라 NEEDS_INFO 또는 READY_FOR_REVIEW

후보 2:

• 유형: DOCUMENT_REQUEST
• 요청 서류: 여권 사본
• 초기 상태: READY_FOR_REVIEW

두 후보는 독립적으로 승인하거나 폐기할 수 있습니다.

완료 판단

업무 유형별로 완료 조건을 분리합니다.

• 근로자 안내: 확인 또는 허용된 응답 기록
• 서류 요청: 제출 상태 또는 파일 참조 기록
• 외부기관 업무: 제출 여부와 접수증 등 완료증빙 기록
• 단순 공지: 승인된 안내 전달과 확인 정책 충족

MVP의 서버는 외부기관에 자동 제출하지 않습니다. 제출 사실과 증빙만 기록합니다.

관련 이슈

• #5 근로자·서류
• #6 업무카드·Workflow
• #7 Worker Link
• #11 승인·감사
• #13 문서 준비도
• #14 파일 가져오기