startover/plan.md

# 프로젝트: Startover MVP 구현 plan

## 개요

Startover MVP의 목표는 폐업자 매장 정보를 기반으로 창업자, 철거업체, 인테리어업체를 연결하는 `assisted marketplace`를 베타 수준으로 출시하는 것이다.

이 plan은 `DEVELOPMENT_PLAN.md`를 실제 구현 단위로 쪼갠 작업 문서다. 정책 문서, 구조 작업, 테스트 시나리오, 에러 시나리오, 우선순위, 진행 상태를 한 곳에서 관리한다.

## 범위

- Phase 1 MVP만 다룬다.
- 베타 지역은 `강남권(역삼/선릉/논현)`과 `마포권(홍대/합정/연남)`으로 제한한다.
- 업종은 `F&B`를 우선 지원한다.
- 초기 출시 방식은 `운영자 개입형 assisted marketplace`다.
- 실시간 채팅, B2B 유료화, 직거래 장터, ML 시세 추천은 현재 plan의 구현 범위에서 제외한다.

## 작업 원칙

- 완료 표시는 `[x]`, 진행 중 표시는 `[진행중]`, 미착수는 `[ ]`로 표시한다.
- 구조적 변경과 행위적 변경을 같은 커밋에 섞지 않는다.
- 새로운 행위는 반드시 테스트를 먼저 작성한다.
- 모든 상태 전환은 `AuditLog`와 `EventLog`를 남긴다.
- 외부 연동은 직접 호출하지 않고 어댑터 계층 뒤에 둔다.
- 결제, 정산, 분쟁, 정보 공개는 feature flag와 운영자 승인 흐름을 기본값으로 둔다.
- 하드코딩 대신 `정책 문서`, `마스터 데이터`, `설정 테이블`로 결정한다.

## 핵심 기능

1. 사용자/인증
2. 매장 등록/검토/공개
3. 검색/매칭 요청/운영자 수동 추천
4. 정부 지원금 가이드형 대행
5. 업체 인증
6. 계약/서명/에스크로/검수/분쟁
7. 운영 백오피스
8. 이벤트 계측과 KPI 대시보드

## 선행 고정 작업

다음 항목은 핵심 비즈니스 로직 구현 전에 먼저 확정해야 한다. 단, 구조 작업 `S001~S003`은 병행 가능하다.

- [ ] `D001` `docs/policies/subsidy-policy.md` 작성
  - 목표: 지원금 대행의 범위, 운영자 역할, 반려 사유, 제출 준비 상태를 고정한다.
- [ ] `D002` `docs/policies/data-exposure-policy.md` 작성
  - 목표: 폐업 정보의 공개 등급, 노출 시점, 역할별 열람 범위를 고정한다.
- [ ] `D003` `docs/policies/contract-escrow-policy.md` 작성
  - 목표: 계약, 서명 증적, 정산 해제, 환불, 분쟁 보류 규칙을 고정한다.
- [ ] `D004` `docs/analytics/event-schema.md` 작성
  - 목표: 이벤트명, 속성, 버전, KPI 계산식을 고정한다.
- [x] `D005` 베타 지역/업종 마스터 데이터 초안 작성
  - 목표: `RegionHierarchy`, `IndustryTaxonomy`의 초기 값을 고정한다.
- [x] `D006` `schema.prisma` 설계 초안 문서 작성
  - 목표: 엔티티를 실제 컬럼 수준으로 내리고 필수/선택, 관계, 인덱스를 정리한다.

## 구조 작업 계획

이 단계는 Tidy First의 구조적 변경 단계다. 아직 사용자 행동을 바꾸는 기능 구현은 하지 않는다.

- [ ] `S001` 모노레포 기본 구조 생성
  - `apps/web`, `apps/admin`, `packages/domain`, `packages/application`, `packages/infrastructure`, `packages/database`, `packages/analytics`, `packages/shared`
- [ ] `S002` 테스트 도구 셋업
  - `Vitest 또는 Jest`, `Testing Library`, `Playwright`, 공통 테스트 유틸 구성
- [ ] `S003` 타입/환경/린트 기본 셋업
  - TypeScript strict mode, env 검증, ESLint, import alias, 기본 CI 파이프라인
- [ ] `S004` Prisma 기본 스키마와 마이그레이션 흐름 구성
  - dev DB, migration, seed, test DB 전략 포함
- [ ] `S005` 공통 인프라 프리미티브 생성
  - `AuditLog`, `EventLog`, `Outbox`, `FeatureFlag`, `PolicyVersion`, `IdempotencyKey`

## 테스트 계획

### 1단계: 마스터 데이터와 매장 초안 생성

사용자 여정:
폐업자가 베타 대상 지역과 업종을 선택해 최소 필수 정보만으로 매장 초안을 생성하고, 이후 검토 요청을 보낼 수 있어야 한다.

단위 테스트:

- [ ] `U001` 폐업자 역할 사용자는 필수 필드가 있으면 매장 초안을 생성할 수 있다.
- [ ] `U002` 베타 대상이 아닌 지역 클러스터로는 매장 초안을 생성할 수 없다.
- [ ] `U003` 지원하지 않는 업종 코드로는 매장 초안을 생성할 수 없다.
- [ ] `U004` 임대 정보와 시설 정보는 별도 값 객체로 검증된다.
- [ ] `U005` 필수 필드 누락 시 사용자 친화적인 검증 오류를 반환한다.

통합 테스트:

- [ ] `I001` `POST /api/v1/stores`는 초안을 생성하고 `AuditLog`를 남긴다.
- [ ] `I002` `POST /api/v1/stores/:id/submit`은 상태를 `SUBMITTED`로 전환한다.
- [ ] `I003` `GET /api/v1/master-data`는 베타 지역/업종 마스터를 반환한다.

### 2단계: 매장 검토와 공개

사용자 여정:
운영자가 등록된 매장을 검토하고 승인 또는 반려할 수 있으며, 승인된 매장만 검색 가능 상태로 공개된다.

단위 테스트:

- [ ] `U006` 운영자 승인 전에는 매장을 공개할 수 없다.
- [ ] `U007` 반려 시 사유 코드와 메모가 반드시 기록된다.
- [ ] `U008` 공개 시 권한 없는 사용자에게는 상세 주소와 연락처가 노출되지 않는다.
- [ ] `U009` 공개 상태 전환은 정책 버전을 함께 기록한다.

통합 테스트:

- [ ] `I004` 운영자 검토 API는 승인/반려 결과와 감사 로그를 함께 저장한다.
- [ ] `I005` 공개된 매장 조회 API는 제한 공개 정책을 적용한다.

E2E 테스트:

- [ ] `E2E001` 폐업자가 매장 등록 후 운영자 승인으로 공개되는 흐름이 완료된다.

### 3단계: 검색, 매칭 요청, 운영자 수동 추천

사용자 여정:
창업자와 업체는 공개된 매장을 검색하고 매칭 요청을 보낼 수 있으며, 운영자는 수동 추천으로 성사율을 보완할 수 있어야 한다.

단위 테스트:

- [ ] `U010` 검색 결과는 지역, 업종, 상태 기준으로 필터링된다.
- [ ] `U011` 동일 사용자는 같은 매장에 중복된 열린 매칭 요청을 만들 수 없다.
- [ ] `U012` 운영자는 수동 추천 시 추천 사유를 반드시 남겨야 한다.
- [ ] `U013` 매칭 수락 후 요청 상태는 `CONTRACTING`으로 전이된다.

통합 테스트:

- [ ] `I006` `POST /api/v1/matching/requests`는 요청 생성과 알림 이벤트를 함께 기록한다.
- [ ] `I007` `PATCH /api/v1/matching/requests/:id/accept`는 상태를 전이하고 계약 생성 준비 상태를 만든다.

E2E 테스트:

- [ ] `E2E002` 창업자가 공개 매장을 검색하고 매칭 요청을 보낸다.

### 4단계: 정부 지원금 가이드형 대행

사용자 여정:
폐업자는 자신의 매장을 기반으로 지원금 케이스를 만들고, 체크리스트와 서류를 제출하고, 운영자 피드백을 받으며 상태를 추적할 수 있어야 한다.

단위 테스트:

- [ ] `U014` 공개 또는 검토 가능한 매장만 지원금 케이스를 시작할 수 있다.
- [ ] `U015` 필수 서류가 누락되면 `READY_TO_SUBMIT`으로 전이할 수 없다.
- [ ] `U016` 운영자 반려 시 반려 사유와 보완 요청이 기록된다.
- [ ] `U017` 정책 버전이 달라지면 신규 케이스에는 최신 체크리스트가 적용된다.

통합 테스트:

- [ ] `I008` `POST /api/v1/subsidies/cases`는 케이스와 초기 체크리스트를 생성한다.
- [ ] `I009` `PATCH /api/v1/subsidies/cases/:id/review`는 상태 변경과 감사 로그를 남긴다.

E2E 테스트:

- [ ] `E2E003` 폐업자가 지원금 케이스를 만들고 운영자 피드백을 확인한다.

### 5단계: 업체 인증

사용자 여정:
철거업체와 인테리어업체는 인증 신청을 하고, 운영자 승인을 받은 업체만 서비스 내에서 노출되고 계약 프로세스에 참여할 수 있어야 한다.

단위 테스트:

- [ ] `U018` 필수 인증 서류와 서비스 권역이 없으면 승인할 수 없다.
- [ ] `U019` 인증 중지된 업체는 검색 결과와 계약 후보에서 제외된다.
- [ ] `U020` 업체 인증 상태 변경은 제재 이력과 함께 남는다.

통합 테스트:

- [ ] `I010` `POST /api/v1/vendors/certifications`는 인증 신청과 검토 큐를 생성한다.
- [ ] `I011` `PATCH /api/v1/vendors/certifications/:id/approve`는 인증 승인과 이벤트 기록을 남긴다.

### 6단계: 계약, 서명, 에스크로, 검수

사용자 여정:
승인된 매칭은 계약으로 전환되고, 문서 버전과 서명 증적이 저장되어야 하며, 결제는 검수 전까지 자동 해제되지 않아야 한다.

단위 테스트:

- [ ] `U021` 수락된 매칭만 계약을 생성할 수 있다.
- [ ] `U022` 계약 생성 시 템플릿 버전과 정책 버전이 함께 저장된다.
- [ ] `U023` 검수 승인 전에는 정산 해제를 실행할 수 없다.
- [ ] `U024` 같은 웹훅 이벤트는 `IdempotencyKey` 기준으로 한 번만 처리된다.
- [ ] `U025` 분쟁이 열리면 에스크로는 즉시 `DISPUTED` 또는 보류 상태로 전환된다.

통합 테스트:

- [ ] `I012` `POST /api/v1/contracts`는 계약 초안과 문서 버전을 생성한다.
- [ ] `I013` `POST /api/v1/contracts/:id/sign`은 서명 증적을 저장한다.
- [ ] `I014` 결제 웹훅 처리 API는 성공/중복/실패 케이스를 구분한다.
- [ ] `I015` 검수 승인 API는 정산 해제 검토 상태를 만든다.

E2E 테스트:

- [ ] `E2E004` 업체 인증 이후 계약 생성, 결제, 검수 승인까지 완료된다.

### 7단계: 분쟁과 운영자 개입

사용자 여정:
사용자는 분쟁을 열 수 있고, 운영자는 증빙을 검토해 정산을 보류하거나 종료할 수 있어야 한다.

단위 테스트:

- [ ] `U026` 분쟁이 열리면 정산 해제 요청은 차단된다.
- [ ] `U027` 운영자의 수동 정산 변경은 사유 코드 없이는 실행할 수 없다.
- [ ] `U028` 분쟁 종료 시 최종 판단 결과와 근거 파일 참조가 저장된다.

통합 테스트:

- [ ] `I016` `POST /api/v1/disputes`는 분쟁 케이스를 만들고 정산을 보류한다.
- [ ] `I017` 운영자 수동 정산 변경 API는 감사 로그를 남긴다.

E2E 테스트:

- [ ] `E2E005` 분쟁이 열리면 잔금 정산이 보류된 상태로 유지된다.

### 8단계: 이벤트 계측과 KPI

사용자 여정:
운영자는 대시보드에서 핵심 KPI를 볼 수 있어야 하며, 모든 핵심 흐름은 버전 있는 이벤트로 재현 가능해야 한다.

단위 테스트:

- [ ] `U029` 도메인 이벤트는 분석 이벤트로 변환될 때 버전을 포함한다.
- [ ] `U030` 분석 이벤트에는 PII가 포함되지 않는다.
- [ ] `U031` 월 거래 건수는 완료된 거래만 집계한다.
- [ ] `U032` 시설인수 매칭 성공률은 공개 매장 대비 계약 완료 매장 비율로 계산된다.

통합 테스트:

- [ ] `I018` 매장 공개 시 `store_published` 이벤트가 outbox에 적재된다.
- [ ] `I019` 계약 완료 시 KPI 집계에 필요한 이벤트가 적재된다.
- [ ] `I020` 운영 대시보드 조회 API는 KPI 스냅샷을 반환한다.

## 공통 에러 시나리오

- [ ] `X001` 인증되지 않은 사용자는 보호된 API에 접근할 수 없다.
- [ ] `X002` 잘못된 역할 사용자는 허용되지 않은 행위를 할 수 없다.
- [ ] `X003` 정책상 지원하지 않는 지역/업종은 등록 단계에서 차단된다.
- [ ] `X004` 파일 업로드 실패 시 부분 저장 없이 롤백되거나 재시도 가능 상태로 남는다.
- [ ] `X005` 외부 연동 실패 시 사용자 메시지와 운영자 알림이 동시에 기록된다.
- [ ] `X006` 중복 웹훅/중복 요청은 idempotent 하게 처리된다.
- [ ] `X007` 운영자 수동 보정은 항상 사유 코드와 메모를 남긴다.
- [ ] `X008` 제한 공개 대상 정보는 잘못된 캐시나 API 응답으로 노출되지 않는다.

## 우선순위

### 1순위: 코드 구현 전 고정

- `D001` ~ `D006`

### 2순위: 구조 작업

- `S001` ~ `S005`

### 3순위: 첫 번째 베타 가치 루프

- `U001` ~ `I005`
- 목표: `매장 등록 -> 운영자 검토 -> 공개`

### 4순위: 수요 연결 루프

- `U010` ~ `I007`
- 목표: `검색 -> 매칭 요청 -> 수락`

### 5순위: 정책 신뢰 루프

- `U014` ~ `I017`
- 목표: `지원금 -> 업체 인증 -> 계약 -> 결제 -> 검수 -> 분쟁`

### 6순위: 운영 계측 루프

- `U029` ~ `I020`
- 목표: `이벤트 -> KPI -> 운영 대시보드`

## 완료 기준

- 정책 문서 `D001` ~ `D006`이 모두 작성되고 승인되었다.
- 구조 작업 `S001` ~ `S005`가 완료되었다.
- 각 단계의 단위/통합/E2E 테스트가 모두 통과한다.
- 전체 핵심 도메인 기준 테스트 커버리지가 80% 이상이다.
- 결제/정산/분쟁 관련 기능은 feature flag 뒤에서 동작한다.
- 운영자가 백오피스 없이 수작업 엑셀에 의존하지 않아도 된다.

## 현재 진행 상태

- 선행 고정 작업: `[ ]` 미시작
- 구조 작업: `[ ]` 미시작
- 테스트 작성: `[ ]` 미시작
- 현재 코드 구현 시작 가능 여부: `아직 불가`
- 현재 가장 먼저 해야 할 일: `D001 지원금 대행 정책서 작성`
- 첫 번째 행동 테스트 후보: `U001 폐업자 역할 사용자는 필수 필드가 있으면 매장 초안을 생성할 수 있다`

## 시작 순서

1. `D001` ~ `D006` 완료
2. `S001` ~ `S005` 완료
3. `U001`부터 TDD 사이클 시작
4. 각 테스트 통과 후 즉시 리팩토링 여부 점검
5. 단계 종료 시 전체 테스트 재실행