# FreeFlow 백엔드 작업 내역서

> 마지막 업데이트: 2026-02-20

## 프로젝트 개요
- **프로젝트명**: FreeFlow (한국 프리랜서/소규모 사업자 재무 관리 SaaS)
- **기술 스택**: NestJS + Prisma ORM + TypeScript + MySQL
- **DB**: officialsite.kr:23306 / freeflow 스키마
- **포트**: 7801
- **API 프리픽스**: /api

---

## Phase 1: 프로젝트 초기화 & DB 스키마 [완료]

- [x] NestJS 프로젝트 초기화 (freeflow.back)
- [x] Prisma 설정 (prisma@5.22.0 - Node 18 호환)
- [x] .env / .env.example / .gitignore 설정
- [x] ecosystem.config.js (PM2 설정)
- [x] CLAUDE.md 작성 (프론트 + 백엔드 양쪽)
- [x] Python DB 스크립트 생성
  - [x] scripts/create_schema.py - freeflow 스키마 생성
  - [x] scripts/check_db.py - DB 상태 확인
  - [x] scripts/seed_plans.py - 4개 플랜 + 4개 부가서비스 시드
  - [x] scripts/seed_categories.py - 기본 경비 카테고리 시드
  - [x] scripts/reset_db.py - DB 리셋 (개발용)
- [x] Prisma 스키마 정의 (31개 모델/테이블)
- [x] prisma db push → MySQL 테이블 생성 완료
- [x] seed_plans.py 실행 → 플랜/부가서비스 시드 완료

### DB 테이블 (31개)
| # | 테이블 | 설명 | 상태 |
|---|--------|------|------|
| 1 | users | 사용자 계정 | 완료 |
| 2 | notification_settings | 알림 설정 | 완료 |
| 3 | businesses | 사업자 정보 | 완료 |
| 4 | clients | 거래처 | 완료 |
| 5 | projects | 프로젝트 | 완료 |
| 6 | estimates | 견적서 | 완료 |
| 7 | estimate_items | 견적서 품목 | 완료 |
| 8 | contracts | 계약서 | 완료 |
| 9 | contract_milestones | 계약 마일스톤 | 완료 |
| 10 | tax_invoices | 전자세금계산서 | 완료 |
| 11 | tax_invoice_items | 세금계산서 품목 | 완료 |
| 12 | cash_receipts | 현금영수증 | 완료 |
| 13 | cash_receipt_items | 현금영수증 품목 | 완료 |
| 14 | settlements | 정산 | 완료 |
| 15 | settlement_payments | 정산 결제 | 완료 |
| 16 | purchase_sale_records | 매입매출 기록 | 완료 |
| 17 | expense_categories | 경비 카테고리 | 완료 |
| 18 | expenses | 경비 | 완료 |
| 19 | fixed_expenses | 고정 경비 | 완료 |
| 20 | templates | 문서 템플릿 | 완료 |
| 21 | ai_conversations | AI 대화 | 완료 |
| 22 | ai_messages | AI 메시지 | 완료 |
| 23 | plans | 구독 플랜 | 완료 |
| 24 | subscriptions | 사용자 구독 | 완료 |
| 25 | addons | 부가서비스 | 완료 |
| 26 | addon_subscriptions | 부가서비스 구독 | 완료 |
| 27 | credit_settings | 크레딧 설정 | 완료 |
| 28 | credit_transactions | 크레딧 거래 | 완료 |
| 29 | payment_methods | 결제 수단 | 완료 |
| 30 | linked_accounts | 연동 계좌 | 완료 |
| 31 | notifications | 알림 | 완료 |

---

## Phase 2: 인증 & 사용자 모듈 [완료]

### Auth 모듈 (8 엔드포인트) [완료]
- [x] POST /api/auth/signup - 회원가입 (유저+사업자+크레딧+구독+카테고리 일괄 생성)
- [x] POST /api/auth/login - 로그인
- [x] POST /api/auth/logout - 로그아웃
- [x] POST /api/auth/refresh - 토큰 갱신
- [x] POST /api/auth/forgot-password - 비밀번호 찾기
- [x] POST /api/auth/reset-password - 비밀번호 재설정
- [x] POST /api/auth/verify-email - 이메일 인증
- [x] GET /api/auth/me - 내 정보

**파일**: auth.module.ts, auth.service.ts, auth.controller.ts, strategies/jwt.strategy.ts, strategies/local.strategy.ts, dto/signup.dto.ts, dto/login.dto.ts, dto/refresh-token.dto.ts, dto/reset-password.dto.ts

### Users 모듈 (6 엔드포인트) [완료]
- [x] GET /api/users/profile - 프로필 조회
- [x] PUT /api/users/profile - 프로필 수정
- [x] POST /api/users/change-password - 비밀번호 변경
- [x] GET /api/users/notification-settings - 알림 설정 조회
- [x] PUT /api/users/notification-settings - 알림 설정 수정
- [x] DELETE /api/users/account - 계정 삭제 (soft delete)

**파일**: users.module.ts, users.service.ts, users.controller.ts, dto/update-user.dto.ts, dto/change-password.dto.ts, dto/update-notification-settings.dto.ts

### Businesses 모듈 (6 엔드포인트) [완료]
- [x] GET /api/businesses - 사업자 정보 조회
- [x] PUT /api/businesses - 사업자 정보 수정
- [x] POST /api/businesses/upload-cert - 사업자 등록증 업로드
- [x] POST /api/businesses/digital-cert - 공동인증서 등록
- [x] POST /api/businesses/hometax - 홈택스 연동 (mock)
- [x] DELETE /api/businesses/hometax - 홈택스 연동 해제

**파일**: businesses.module.ts, businesses.service.ts, businesses.controller.ts, dto/update-business.dto.ts, dto/register-hometax.dto.ts, dto/register-digital-cert.dto.ts

---

## Phase 3: 핵심 비즈니스 로직 모듈 [완료]

### Clients 모듈 (6 엔드포인트) [완료]
- [x] GET /api/clients - 거래처 목록 (페이징/검색)
- [x] GET /api/clients/:id - 거래처 상세
- [x] POST /api/clients - 거래처 생성
- [x] PUT /api/clients/:id - 거래처 수정
- [x] DELETE /api/clients/:id - 거래처 삭제
- [x] GET /api/clients/:id/summary - 거래처 요약

**파일**: clients.module.ts, clients.service.ts, clients.controller.ts, dto/create-client.dto.ts, dto/update-client.dto.ts

### Projects 모듈 (7+ 엔드포인트) [완료]
- [x] GET /api/projects - 프로젝트 목록 (페이징/검색/상태필터)
- [x] GET /api/projects/:id - 프로젝트 상세
- [x] POST /api/projects - 프로젝트 생성
- [x] PUT /api/projects/:id - 프로젝트 수정
- [x] DELETE /api/projects/:id - 프로젝트 삭제
- [x] PATCH /api/projects/:id/status - 상태 변경
- [x] GET /api/projects/summary - 프로젝트 요약

**파일**: projects.module.ts, projects.service.ts, projects.controller.ts, dto/create-project.dto.ts, dto/update-project.dto.ts, dto/update-project-status.dto.ts

### Estimates 모듈 (8 엔드포인트) [완료]
- [x] GET /api/estimates - 견적서 목록
- [x] GET /api/estimates/:id - 견적서 상세
- [x] POST /api/estimates - 견적서 생성 (자동 번호: EST-YYYY-NNN)
- [x] PUT /api/estimates/:id - 견적서 수정
- [x] DELETE /api/estimates/:id - 견적서 삭제
- [x] POST /api/estimates/:id/issue - 견적서 발행
- [x] POST /api/estimates/:id/duplicate - 견적서 복제
- [x] POST /api/estimates/:id/convert-to-contract - 계약서 전환

**파일**: estimates.module.ts, estimates.service.ts, estimates.controller.ts, dto/create-estimate.dto.ts, dto/update-estimate.dto.ts

### Contracts 모듈 (7 엔드포인트) [완료]
- [x] GET /api/contracts - 계약서 목록
- [x] GET /api/contracts/:id - 계약서 상세
- [x] POST /api/contracts - 계약서 생성 (자동 번호: CTR-YYYY-NNN)
- [x] PUT /api/contracts/:id - 계약서 수정
- [x] DELETE /api/contracts/:id - 계약서 삭제
- [x] POST /api/contracts/:id/sign - 계약서 서명
- [x] POST /api/contracts/:id/cancel - 계약서 취소

**파일**: contracts.module.ts, contracts.service.ts, contracts.controller.ts, dto/create-contract.dto.ts, dto/update-contract.dto.ts

### Tax Invoices 모듈 (7 엔드포인트) [완료]
- [x] GET /api/tax-invoices - 세금계산서 목록
- [x] GET /api/tax-invoices/:id - 세금계산서 상세
- [x] POST /api/tax-invoices - 세금계산서 생성 (자동 번호: TI-YYYY-NNN)
- [x] PUT /api/tax-invoices/:id - 세금계산서 수정
- [x] DELETE /api/tax-invoices/:id - 세금계산서 삭제
- [x] POST /api/tax-invoices/:id/issue - 세금계산서 발행
- [x] POST /api/tax-invoices/:id/correction - 수정세금계산서 생성

**파일**: tax-invoices.module.ts, tax-invoices.service.ts, tax-invoices.controller.ts, dto/create-tax-invoice.dto.ts, dto/update-tax-invoice.dto.ts

### Cash Receipts 모듈 (6 엔드포인트) [완료]
- [x] GET /api/cash-receipts - 현금영수증 목록
- [x] GET /api/cash-receipts/:id - 현금영수증 상세
- [x] POST /api/cash-receipts - 현금영수증 생성 (자동 번호: CR-YYYY-NNN)
- [x] PUT /api/cash-receipts/:id - 현금영수증 수정
- [x] DELETE /api/cash-receipts/:id - 현금영수증 삭제
- [x] POST /api/cash-receipts/:id/issue - 현금영수증 발행

**파일**: cash-receipts.module.ts, cash-receipts.service.ts, cash-receipts.controller.ts, dto/create-cash-receipt.dto.ts, dto/update-cash-receipt.dto.ts

---

## Phase 4: 재무 추적 모듈 [완료]

### Settlements 모듈 (10 엔드포인트) [완료]
- [x] GET /api/settlements - 정산 목록 (?status= 필터)
- [x] GET /api/settlements/calendar - 캘린더 (?year=&month=)
- [x] GET /api/settlements/summary - 요약
- [x] GET /api/settlements/:id - 정산 상세
- [x] POST /api/settlements - 정산 생성 (자동 번호: STL-YYYY-NNN)
- [x] PUT /api/settlements/:id - 정산 수정
- [x] DELETE /api/settlements/:id - 정산 삭제
- [x] POST /api/settlements/:id/payments - 결제 추가
- [x] DELETE /api/settlements/:id/payments/:paymentId - 결제 삭제
- [x] 결제 상태 자동 계산 (waiting/partial/paid)

**파일**: settlements.module.ts, settlements.service.ts, settlements.controller.ts, dto/create-settlement.dto.ts, dto/update-settlement.dto.ts, dto/add-payment.dto.ts

### Purchase/Sales 모듈 (6 엔드포인트) [완료]
- [x] GET /api/purchase-sales - 매입매출 목록 (?tradeType= 필터)
- [x] GET /api/purchase-sales/summary - 요약 (?year=&month=)
- [x] GET /api/purchase-sales/:id - 매입매출 상세
- [x] POST /api/purchase-sales - 매입매출 생성 (자동 번호: PS-YYYY-NNN)
- [x] PUT /api/purchase-sales/:id - 매입매출 수정
- [x] DELETE /api/purchase-sales/:id - 매입매출 삭제

**파일**: purchase-sales.module.ts, purchase-sales.service.ts, purchase-sales.controller.ts, dto/create-purchase-sale.dto.ts, dto/update-purchase-sale.dto.ts

### Expenses 모듈 (13 엔드포인트) [완료]
- [x] GET /api/expenses - 경비 목록 (?categoryId=&startDate=&endDate=)
- [x] GET /api/expenses/:id - 경비 상세
- [x] POST /api/expenses - 경비 생성
- [x] PUT /api/expenses/:id - 경비 수정
- [x] DELETE /api/expenses/:id - 경비 삭제
- [x] GET /api/expenses/categories - 카테고리 목록
- [x] POST /api/expenses/categories - 카테고리 생성
- [x] DELETE /api/expenses/categories/:id - 카테고리 삭제
- [x] GET /api/expenses/fixed - 고정경비 목록
- [x] POST /api/expenses/fixed - 고정경비 생성
- [x] PUT /api/expenses/fixed/:id - 고정경비 수정
- [x] DELETE /api/expenses/fixed/:id - 고정경비 삭제
- [x] GET /api/expenses/summary - 월별 요약 (?year=&month=)

**파일**: expenses.module.ts, expenses.service.ts, expenses.controller.ts, dto/create-expense.dto.ts, dto/update-expense.dto.ts, dto/create-fixed-expense.dto.ts, dto/update-fixed-expense.dto.ts, dto/create-category.dto.ts

### Reports 모듈 (5 엔드포인트) [완료]
- [x] GET /api/reports/revenue - 매출 요약 (?year=)
- [x] GET /api/reports/expenses - 비용 요약 (?year=)
- [x] GET /api/reports/profit-loss - 손익 (?year=)
- [x] GET /api/reports/tax - 세금 요약 (?year=)
- [x] GET /api/reports/annual - 연간 보고서 (?year=)

**파일**: reports.module.ts, reports.service.ts, reports.controller.ts

### Dashboard 모듈 (3 엔드포인트) [완료]
- [x] GET /api/dashboard/overview - 대시보드 개요
- [x] GET /api/dashboard/activity - 최근 활동
- [x] GET /api/dashboard/chart - 월별 차트 (?year=)

**파일**: dashboard.module.ts, dashboard.service.ts, dashboard.controller.ts

---

## Phase 5: 고급 기능 모듈 [완료]

### Templates 모듈 (5 엔드포인트) [완료]
- [x] GET /api/templates - 템플릿 목록 (?type=)
- [x] GET /api/templates/:id - 템플릿 상세
- [x] POST /api/templates - 템플릿 생성
- [x] PUT /api/templates/:id - 템플릿 수정
- [x] DELETE /api/templates/:id - 템플릿 삭제

**파일**: templates.module.ts, templates.service.ts, templates.controller.ts, dto/create-template.dto.ts, dto/update-template.dto.ts

### AI Chat 모듈 (4 엔드포인트) [완료]
- [x] GET /api/ai-chat/conversations - 대화 목록
- [x] GET /api/ai-chat/conversations/:id - 대화 상세
- [x] POST /api/ai-chat/send - 메시지 전송 (룰 기반 응답)
- [x] DELETE /api/ai-chat/conversations/:id - 대화 삭제

**파일**: ai-chat.module.ts, ai-chat.service.ts, ai-chat.controller.ts, dto/send-message.dto.ts

### Notifications 모듈 (4 엔드포인트) [완료]
- [x] GET /api/notifications - 알림 목록 (?unreadOnly=)
- [x] PUT /api/notifications/:id/read - 읽음 처리
- [x] PUT /api/notifications/read-all - 전체 읽음
- [x] DELETE /api/notifications/:id - 알림 삭제

**파일**: notifications.module.ts, notifications.service.ts, notifications.controller.ts

### Integrations 모듈 (5 엔드포인트) [완료]
- [x] GET /api/integrations/accounts - 연동 계좌 목록
- [x] POST /api/integrations/accounts - 계좌 연동 (mock)
- [x] DELETE /api/integrations/accounts/:id - 연동 해제
- [x] POST /api/integrations/accounts/:id/sync - 동기화 (mock)
- [x] PUT /api/integrations/accounts/:id/auto-import - 자동 가져오기 토글

**파일**: integrations.module.ts, integrations.service.ts, integrations.controller.ts, dto/connect-account.dto.ts

---

## Phase 6: 빌링 & 결제 (TossPayments) [완료]

### Subscriptions 모듈 (9 엔드포인트) [완료]
- [x] GET /api/subscriptions/current - 현재 플랜
- [x] GET /api/subscriptions/plans - 플랜 목록
- [x] GET /api/subscriptions/addons - 부가서비스 목록
- [x] POST /api/subscriptions/change-plan - 플랜 변경
- [x] POST /api/subscriptions/cancel - 구독 취소
- [x] POST /api/subscriptions/reactivate - 구독 재활성화
- [x] POST /api/subscriptions/addons - 부가서비스 구독
- [x] DELETE /api/subscriptions/addons/:addonId - 부가서비스 해지
- [x] GET /api/subscriptions/my-addons - 내 부가서비스

**파일**: subscriptions.module.ts, subscriptions.service.ts, subscriptions.controller.ts, dto/change-plan.dto.ts, dto/subscribe-addon.dto.ts

### Credits 모듈 (5 엔드포인트) [완료]
- [x] GET /api/credits/balance - 잔액 조회
- [x] GET /api/credits/transactions - 거래 내역
- [x] POST /api/credits/charge - 크레딧 충전
- [x] GET /api/credits/settings - 설정 조회
- [x] PUT /api/credits/settings - 설정 변경

**파일**: credits.module.ts, credits.service.ts, credits.controller.ts, dto/charge-credits.dto.ts, dto/update-settings.dto.ts

### Payments 모듈 (5 엔드포인트) [완료]
- [x] GET /api/payments/methods - 결제 수단 목록
- [x] POST /api/payments/methods - 카드 등록
- [x] DELETE /api/payments/methods/:id - 카드 삭제
- [x] PUT /api/payments/methods/:id/default - 기본 카드 설정
- [x] POST /api/payments/confirm - 토스 결제 확인

**파일**: payments.module.ts, payments.service.ts, payments.controller.ts, toss-payments.service.ts, dto/register-card.dto.ts, dto/toss-confirm.dto.ts

---

## Phase 7: 배포, 프론트 API 연동, QA [완료]

- [x] app.module.ts 에 전체 21개 모듈 등록
- [x] npm run build 컴파일 테스트 (0 errors)
- [x] 백엔드 GitHub Actions deploy.yml (PM2, port 7801)
- [x] 프론트엔드 GitHub Actions deploy.yml (static build)
- [x] 프론트엔드 API 서비스 레이어 (axios) - src/services/api.ts
- [x] 프론트엔드 .env.example (VITE_API_URL)
- [x] 전체 QA 체크 - 빌드 통과
- [x] 커밋 & 푸시

---

## 공통 인프라 파일

- [x] src/main.ts - 부트스트랩 (CORS, ValidationPipe, /api 프리픽스, 포트 7801)
- [x] src/app.module.ts - 전체 21개 모듈 등록
- [x] src/prisma/prisma.service.ts - PrismaClient 래퍼
- [x] src/prisma/prisma.module.ts - @Global 모듈
- [x] src/common/guards/jwt-auth.guard.ts - JWT 인증 가드
- [x] src/common/decorators/current-user.decorator.ts - 현재 사용자 데코레이터
- [x] src/common/filters/http-exception.filter.ts - 전역 예외 필터
- [x] src/common/interceptors/transform.interceptor.ts - 응답 래핑 인터셉터
- [x] src/common/dto/pagination.dto.ts - 페이지네이션 DTO
- [x] src/common/utils/document-number.util.ts - 문서 번호 자동 생성

---

## 총 통계

| 항목 | 수량 |
|------|------|
| DB 테이블 | 31개 |
| NestJS 모듈 | 21개 |
| API 엔드포인트 | ~120개 |
| TypeScript 파일 | 99+ 개 |
| Python 스크립트 | 5개 |
| 시드 데이터 | 4 플랜 + 4 부가서비스 |

## 시드 데이터

### 플랜
| planId | 이름 | 가격 | 크레딧 |
|--------|------|------|--------|
| free | Free | 0원 | 100 |
| starter | Starter | 29,000원 | 300 |
| basic | Basic | 59,000원 | 700 |
| pro | Pro | 99,000원 | 1,500 |

### 부가서비스
| addonId | 이름 | 가격 |
|---------|------|------|
| extra-credits-100 | 크레딧 100건 | 5,000원 |
| extra-credits-500 | 크레딧 500건 | 20,000원 |
| ai-chat-addon | AI 상담 | 9,900원/월 |
| priority-support | 우선 지원 | 19,900원/월 |