상세 설계 문서

구현 진행 계획

기획서로프로토타입

구현 진행 계획 v1

1. 현재 기준

  • 작업 폴더: /Users/paul/dev/real-estate-contract-saas
  • 배포 프로젝트: Vercel paulkim7788s-projects/1
  • 현재 앱 상태: Next.js 프로토타입, 본사관리자/사용자관리자 화면 분리, 기획서 HTML 페이지 제공
  • 검증 기준: npm run lint, npm run build, Vercel Preview 배포

2. 진행 순서

로컬 안정화
→ 기획서 확정
→ DB 설계
→ 로그인/권한
→ 계약하기 저장
→ 계약관리/고객관리/매물관리 연결
→ 과금 계산
→ PDF/인쇄

3. 현재 완료

로컬 안정화

  • iCloud placeholder 문제를 피하기 위해 /Users/paul/dev/real-estate-contract-saas로 작업 폴더를 이전했습니다.
  • 새 폴더에는 dataless 파일이 없습니다.
  • 의존성 설치를 완료했습니다.
  • 로컬 빌드와 린트가 통과했습니다.
  • 기존 Vercel 프로젝트와 새 폴더를 다시 연결했습니다.
  • Preview 배포가 성공했습니다.

4. 서브에이전트 분담

에이전트 담당 산출물
DB/권한 멀티테넌트 DB, 로그인/권한 정책 docs/db-schema-v1.md, docs/auth-permission-v1.md
과금 부동산 기본 과금, 인원 과금, 기능 과금 docs/billing-model-v1.md
계약서/PDF 계약 템플릿, 저장 구조, PDF/인쇄 플로우 docs/contract-template-save-pdf-v1.md
프론트 프로토타입 화면에서 저장 흐름과 과금 포인트 강화 src/app/page.tsx

5. MVP 구현 단위

5.1 DB 설계 확정

목표는 실제 DB를 붙이기 전에 테이블, 관계, 권한 범위를 먼저 고정하는 것입니다.

핵심 테이블:

  • offices
  • users
  • customers
  • properties
  • contracts
  • contract_customers
  • contract_properties
  • contract_templates
  • contract_template_versions
  • subscriptions
  • plans
  • company_features
  • usage_events
  • invoices

완료 기준:

  • 사무소별 데이터 격리 기준이 명확합니다.
  • 본사관리자, 부동산 오너, 중개인, 중개보조인의 조회 범위가 명확합니다.
  • 계약, 고객, 매물이 서로 연결되는 구조가 정리됩니다.

5.2 로그인/권한

1차 구현에서는 실제 인증 제공자를 붙이기 전에도 권한 모델을 코드로 먼저 표현합니다.

권장 단계:

  1. 역할 타입 정의
  2. 세션 사용자 타입 정의
  3. officeId 기반 접근 제어 함수 작성
  4. 화면/데이터 샘플에 권한별 조회 범위 반영
  5. 이후 실제 Auth.js, Clerk, Supabase Auth 중 하나로 연결

5.3 계약하기 저장

계약서는 단순 폼 저장이 아니라 다음 구조로 갑니다.

ContractTemplateVersion
  = 계약서 양식 + 필드 위치 + 입력 스키마

Contract.inputJson
  = 실제 계약 데이터

ContractCustomer / ContractProperty
  = 고객/매물 업무 연결

1차 구현은 브라우저 로컬 상태 또는 mock repository로 저장 흐름을 먼저 보여주고, 이후 DB 저장으로 전환합니다.

5.4 관리 화면 연결

계약 저장 후 다음 변화가 화면에 보여야 합니다.

  • 계약관리 목록에 계약이 추가됩니다.
  • 고객관리 목록에 계약 당사자가 누적됩니다.
  • 매물관리 목록에 연결 매물 상태가 변경됩니다.
  • 대시보드의 계약/고객/매물 수치가 바뀝니다.

5.5 과금 계산

과금은 계약 수수료가 아니라 SaaS 이용료 기준으로 먼저 잡습니다.

1차 과금:

  • 부동산 사무소 기본 이용료
  • 초기값 0원, 향후 예: 월 10,000원

2차 과금:

  • 기본 포함 인원 초과 과금
  • 초기값 0원, 향후 예: 추가 1명당 월 5,000원

3차 과금:

  • 기능 추가 과금
  • 기능별 월 정액 또는 사용량 기반
  • 예: PDF 저장, 카카오 알림, 고급 권한, 매물 교환

5.6 PDF/인쇄

초기 구현은 HTML print layout을 우선합니다.

이후 실제 계약서 배경 이미지/PDF 위에 좌표 기반 필드를 올리는 방식으로 확장합니다.

6. 바로 다음 작업

  1. 에이전트 산출물을 검토합니다.
  2. 문서 간 용어를 맞춥니다.
  3. src/lib에 타입과 mock repository를 만듭니다.
  4. 계약 저장 버튼이 실제 상태를 변경하도록 연결합니다.
  5. 로컬 빌드 후 Vercel Preview에 배포합니다.