01 MVP Roadmap

M3 백엔드 MVP 로드맵

목표

2026년 8월 14일까지 다음 흐름을 PostgreSQL과 외부 LLM을 사용하는 실제 데모 환경에서 끝까지 동작시킵니다.

HR 로그인 → 근로자 등록 → 비동기 AI Run → 검증된 후보 → HR 확정·승인 → 근로자 링크 → 응답·문서 → 증빙·완료 → 감사·복구

• MVP Epic #2
• M3 Milestone
• M4 Milestone
• Server Roadmap · 팀원 전용
• 46개 API 카탈로그

현재와 목표

구분	2026-07-21 현재	M3 목표
서버 기반	Java 17·Spring Boot 4.1·Security·Swagger·Flyway·공통 오류·CI 완료	기반 유지, package-by-feature 모듈 확장
기능 API	GET /health 1개	P0 대표 Workflow API와 Swagger 계약
DB	local H2, dev/prod PostgreSQL profile, 기술 baseline migration	PostgreSQL domain migration·낙관적 잠금·복구 기록
AI	미연동	202 + runId 비동기 실행, Adapter, 외부 LLM, 엄격한 검증
보안	공개 경로 외 기본 차단	JWT·역할·사업장 격리·Token hash·HITL
신뢰성	request_id 기반만 존재	멱등성·제한적 retry·circuit/bulkhead·event 재처리
테스트	H2/PostgreSQL 기반 검증	상태 전이·보안·중복·재시작·Golden E2E
배포	없음	HTTPS·외부 LLM·readiness·복구 runbook

목표 API는 46개입니다. M3/P0는 32개, M4/P1은 14개이며, Import 7개 API는 대표 시나리오의 선행 조건이 아니므로 M4로 이동했습니다.

구현 순서

flowchart LR
  F["#3 개발 기반 ✅"] --> ADR["#23 Architecture ADR"]
  ADR --> A["#4 인증·사업장"]
  A --> W["#5 근로자·문서 메타"]
  W --> WF["#6 Workflow 상태 머신"]
  WF --> EVT["#25 Event 유실 방지"]
  WF --> AUD["#11 HITL 승인·감사"]
  W --> AIR["#24 비동기 AI Run"]
  WF --> AIR
  ADR --> AIA["#8 AI Adapter·검증"]
  AIR --> AIA
  EVT --> AIR
  AUD --> LINK["#7 Worker Link"]
  W --> DOC["#13 파일·문서 준비도"]
  DOC --> LINK
  AIA --> DEP["#9 데모 배포"]
  LINK --> DEP
  EVT --> DEP
  DEP --> E2E["#10 E2E·복구 Runbook"]
  E2E --> M4["M4: #14·#15·#16·#26"]

Loading

화살표는 통합 완료의 선행 관계입니다. Port, DTO, migration 초안, 단위 테스트처럼 충돌하지 않는 작업은 병렬로 준비할 수 있습니다.

단계별 설명

0단계: 완료된 기반

• #3 Spring Boot 개발·검증 기반 — PR #22 병합 완료

새 기능은 기존 Security·오류 envelope·request_id·Flyway·테스트 기반을 교체하지 않고 확장합니다.

1단계: 계약과 데이터 경계

• #23 모듈러 모놀리스·API·Event ADR
• #4 JWT·Actor·사업장 격리
• #5 근로자·문서 메타데이터

중복 API와 모듈 의존성을 먼저 정하고 모든 조회·수정에 company_id를 강제합니다.

2단계: 통제되는 Workflow

• #6 Task 상태 머신
• #25 Event 유실 방지·재처리
• #11 AI 원본·HR 수정·승인·감사

상태 변경은 명령과 guard를 통과하며, 승인 버전과 감사 event를 같은 transaction 경계에 저장합니다.

3단계: 비동기 AI와 근로자 연결

• #24 AI Run 상태·재시도·멱등성
• #8 Provider·Structured Output·장애 격리
• #13 파일·문서 준비도
• #7 Worker Link·응답·문서 제출

AI 분석은 긴 동기 요청이 아니라 저장된 Run입니다. HR이 후보를 확정하고 승인한 뒤에만 제한된 Worker Link를 만듭니다.

4단계: 배포와 실패 증명

• #9 PostgreSQL·외부 LLM 데모 배포
• #10 Golden/장애 E2E와 runbook

LM Studio 없이 배포하고 Timeout·잘못된 JSON·중복 요청·서버 재시작·event handler 실패를 자동 테스트합니다.

M4: 사용성·운영 고도화

• #14 Excel/CSV Import
• #15 오늘 업무 대시보드
• #16 사업장 설정
• #26 분산 추적·운영 지표

M3에서도 request_id, trace_id, 버전, 오류 코드는 저장합니다. #26은 OpenTelemetry·Micrometer dashboard와 운영 alert를 고도화합니다.

이슈 상태 읽는 법

Project Status	Issue label	의미	해야 할 일
Todo	status:ready	지금 시작 가능	담당자 지정·branch 생성
Todo	status:backlog	순서가 아직 아님	우선순위와 일정 확인
Todo	status:blocked	선행 작업 미완료	차단 Issue부터 해결
In Progress	status:in-progress	구현 중	연결 PR 확인
In Progress	status:in-review	리뷰 중	완료 조건·테스트 검토
Done	진행 label 없음	병합·문서·검증 완료	회귀 테스트 유지

M3 완료 조건

• 비동기 AI Run이 202와 조회 가능한 runId를 반환합니다.
• 복합 요청이 체류연장과 여권 사본 요청 후보 2개로 분리됩니다.
• JSON Schema·핵심값·민감정보 검증 실패가 자동 승인·발송으로 이어지지 않습니다.
• IN_PROGRESS, WAITING_*, FAILED를 포함한 상태 전이와 낙관적 잠금이 검증됩니다.
• AI 원본·HR 수정·changed fields·승인 version을 기록하고 중요 변경 뒤 재승인합니다.
• 승인 전 Worker Link 발급이 불가능하고 링크 만료·회전·폐기가 동작합니다.
• 근로자 응답·문서 제출과 완료증빙이 감사 이력에 연결됩니다.
• 중복 요청과 서버 재시작 뒤 Run·event를 유실·중복 없이 복구합니다.
• PostgreSQL·외부 LLM·HTTPS 환경에서 Golden/실패 E2E가 통과합니다.
• 처음 참여한 팀원이 README·Wiki·Issue로 실행과 복구를 재현합니다.

M3 범위 밖

• 외부기관 자동 제출과 AI의 법률·노무 최종 판단
• 자체 학습 모델의 필수 서비스 탑재
• Kafka·Kubernetes·범용 Workflow DSL
• 실제 Blue/Green Agent traffic 전환
• OCR·대용량 파일 처리 전체 구현