startover/plan.md

프로젝트: Re:Link MVP 구현 plan

개요

Re:Link 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 계산식을 고정한다.
• D005 베타 지역/업종 마스터 데이터 초안 작성
  • 목표: RegionHierarchy, IndustryTaxonomy의 초기 값을 고정한다.
• 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. 단계 종료 시 전체 테스트 재실행