Codebase WIKI Documentation Skill

현재 세션은 읽기 전용이며 대상 경로를 조회할 수 있는 터미널/LSP 도구가 없어 WIKI.md 파일을 직접 생성하지 못했습니다. 아래 내용을 /Users/jihoon/dev/reservation-api/WIKI.md로 저장하면 됩니다. 실제 컨트롤러·DTO 이름은 코드 확인 전제의 추정값입니다.

# Reservation API Wiki

## 1. 프로젝트 개요

예약, 결제, 알림을 제공하는 NestJS 기반 백엔드 API입니다.

### 기술 스택

| 영역 | 기술 |
|---|---|
| Runtime | Node.js 20 |
| Language | TypeScript |
| Framework | NestJS |
| ORM | Prisma |
| Database | PostgreSQL |
| Cache | Redis |
| Async Queue | BullMQ |
| Architecture | Modular Monolith |
| API 문서 | Swagger/OpenAPI 추정 |

### 주요 도메인

- `reservation`: 예약 생성, 조회, 상태 변경
- `payment`: 결제 준비 및 승인
- `notification`: 예약·결제 결과 알림
- `common`: 공통 예외, 가드, 인터셉터, 응답 형식
- `config`: 환경 변수 및 애플리케이션 설정

---

## 2. 아키텍처

```mermaid
flowchart LR
    Client[Client] --> API[NestJS API]

    API --> Reservation[Reservation Module]
    API --> Payment[Payment Module]
    API --> Notification[Notification Module]

    Reservation --> Prisma[Prisma ORM]
    Payment --> Prisma
    Notification --> Prisma

    Prisma --> PostgreSQL[(PostgreSQL)]

    Reservation --> Redis[(Redis)]
    Payment --> Redis

    Reservation --> Queue[BullMQ Queue]
    Payment --> Queue
    Queue --> Worker[Background Worker]
    Worker --> Notification

    Payment --> PG[External Payment Provider]
    Notification --> NS[Notification Provider]

애플리케이션은 NestJS 모듈 단위로 도메인을 분리합니다. 동기적인 예약·결제 처리는 API 요청 안에서 수행하고, 알림 및 후처리 작업은 BullMQ를 통해 비동기로 처리합니다.

---

3. 프로젝트 구조

reservation-api/
├── src/
│   ├── main.ts
│   ├── app.module.ts
│   ├── modules/
│   │   ├── reservation/
│   │   │   ├── reservation.module.ts
│   │   │   ├── reservation.controller.ts
│   │   │   ├── reservation.service.ts
│   │   │   ├── dto/
│   │   │   └── entities/
│   │   ├── payment/
│   │   │   ├── payment.module.ts
│   │   │   ├── payment.controller.ts
│   │   │   ├── payment.service.ts
│   │   │   ├── dto/
│   │   │   └── entities/
│   │   └── notification/
│   │       ├── notification.module.ts
│   │       ├── notification.service.ts
│   │       ├── processors/
│   │       └── consumers/
│   ├── common/
│   │   ├── filters/
│   │   ├── guards/
│   │   ├── interceptors/
│   │   ├── decorators/
│   │   └── pipes/
│   └── config/
│       ├── database.config.ts
│       ├── redis.config.ts
│       └── app.config.ts
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── test/
├── package.json
├── tsconfig.json
└── .env.example

실제 세부 파일명은 저장소의 구현에 맞춰 갱신해야 합니다.

---

4. 핵심 컴포넌트

Reservation Module

예약 도메인의 진입점입니다.

주요 책임:

• 예약 가능 여부 확인
• 예약 생성
• 예약 상태 관리
• 중복 예약 방지
• 결제 대상 예약 생성
• 예약 취소 및 만료 처리

권장 상태:

PENDING_PAYMENT
PAYMENT_COMPLETED
CONFIRMED
CANCELLED
EXPIRED

Payment Module

결제 제공자와 통신하고 결제 상태를 관리합니다.

주요 책임:

• 결제 준비
• 결제 승인 요청
• 결제 승인 결과 검증
• 결제 실패 처리
• 예약 상태와 결제 상태 동기화
• 결제 멱등성 보장

권장 상태:

READY
PENDING
COMPLETED
FAILED
CANCELLED
REFUNDED

Notification Module

예약과 결제 이벤트를 사용자에게 전달합니다.

예시:

• 예약 생성 알림
• 결제 성공 알림
• 결제 실패 알림
• 예약 만료 알림
• 취소 및 환불 알림

알림 발송은 BullMQ 작업으로 분리하여 API 응답 시간을 줄이고 재시도를 지원할 수 있습니다.

Common

공통 기능을 제공합니다.

• 인증 및 권한 검사
• 요청 유효성 검증
• 예외 응답 표준화
• 로깅 및 추적 ID
• 응답 포맷 통일
• 환경 설정 로딩

---

5. 예약 생성부터 결제 승인까지의 데이터 흐름

sequenceDiagram
    autonumber
    participant C as Client
    participant R as ReservationController
    participant RS as ReservationService
    participant DB as PostgreSQL
    participant Cache as Redis
    participant P as PaymentController
    participant PS as PaymentService
    participant PG as Payment Provider
    participant Q as BullMQ
    participant N as Notification Worker

    C->>R: 예약 생성 요청
    R->>RS: DTO 검증 후 예약 생성 위임

    RS->>Cache: 예약 가능 여부/분산 잠금 확인
    Cache-->>RS: 사용 가능 또는 잠금 결과

    RS->>DB: 예약 및 결제 대기 정보 저장
    DB-->>RS: reservationId 반환

    RS->>Cache: 예약 관련 캐시 저장 또는 무효화
    RS->>Q: 예약 생성 알림 작업 등록
    RS-->>R: PENDING_PAYMENT 예약 반환
    R-->>C: 예약 생성 응답

    C->>P: 결제 승인 요청(reservationId, paymentKey)
    P->>PS: 결제 승인 위임

    PS->>DB: 예약 조회 및 결제 상태 확인
    DB-->>PS: 예약/결제 정보 반환

    PS->>PS: 금액·주문 ID·예약 상태 검증
    PS->>PG: 결제 승인 API 호출
    PG-->>PS: 승인 성공 또는 실패

    alt 결제 승인 성공
        PS->>DB: 트랜잭션으로 결제 COMPLETED 저장
        PS->>DB: 예약 PAYMENT_COMPLETED/CONFIRMED 변경
        PS->>Cache: 예약 캐시 무효화
        PS->>Q: 결제 성공 알림 작업 등록
        PS-->>P: 승인 결과 반환
        P-->>C: 결제 성공 응답
        Q->>N: 알림 작업 전달
        N-->>C: 결제 성공 알림
    else 결제 승인 실패
        PS->>DB: 결제 FAILED 저장
        PS->>Q: 결제 실패 알림 작업 등록
        PS-->>P: 실패 정보 반환
        P-->>C: 결제 실패 응답
        Q->>N: 실패 알림 작업 전달
    end

트랜잭션 경계

결제 승인 성공 시 다음 작업은 하나의 데이터베이스 트랜잭션으로 처리하는 것이 안전합니다.

1. 결제 레코드 생성 또는 상태 갱신
2. 예약 상태 변경
3. 외부 결제 승인 식별자 저장

외부 결제사 호출 자체는 PostgreSQL 트랜잭션 안에 장시간 포함하지 않는 것이 좋습니다. 외부 승인 결과를 받은 후 짧은 트랜잭션으로 내부 상태를 확정합니다.

멱등성

동일한 결제 승인 요청이 재전송되어도 중복 결제가 발생하지 않아야 합니다.

권장 키:

• paymentKey
• orderId
• reservationId
• 외부 결제 승인 ID

이미 COMPLETED 상태인 결제에 대해 같은 요청이 오면 기존 성공 결과를 반환합니다.

---

6. 데이터 모델

erDiagram
    USER ||--o{ RESERVATION : creates
    RESERVATION ||--|| PAYMENT : has
    RESERVATION ||--o{ NOTIFICATION : triggers

    USER {
        string id PK
        string email
        datetime createdAt
    }

    RESERVATION {
        string id PK
        string userId FK
        string resourceId
        decimal amount
        string status
        datetime reservedAt
        datetime expiresAt
        datetime createdAt
        datetime updatedAt
    }

    PAYMENT {
        string id PK
        string reservationId FK
        string paymentKey
        string orderId
        decimal amount
        string status
        string providerTransactionId
        datetime approvedAt
        datetime createdAt
        datetime updatedAt
    }

    NOTIFICATION {
        string id PK
        string reservationId FK
        string type
        string status
        string payload
        datetime sentAt
        datetime createdAt
    }

실제 모델명과 컬럼은 prisma/schema.prisma를 기준으로 갱신해야 합니다.

---

7. API Reference

아래 엔드포인트는 일반적인 도메인 구조를 기준으로 한 예상 인터페이스입니다. 실제 경로는 Controller 선언을 기준으로 확인해야 합니다.

예약

예약 생성

POST /reservations
Content-Type: application/json
Authorization: Bearer <token>

요청 예시:

{
  "resourceId": "resource-123",
  "startAt": "2026-09-24T10:00:00Z",
  "endAt": "2026-09-24T12:00:00Z"
}

응답 예시:

{
  "id": "reservation-123",
  "status": "PENDING_PAYMENT",
  "amount": 30000,
  "expiresAt": "2026-09-24T10:15:00Z"
}

예약 조회

GET /reservations/:reservationId
Authorization: Bearer <token>

예약 취소

POST /reservations/:reservationId/cancel
Authorization: Bearer <token>

결제

결제 승인

POST /payments/confirm
Content-Type: application/json
Authorization: Bearer <token>

요청 예시:

{
  "reservationId": "reservation-123",
  "paymentKey": "payment-key",
  "orderId": "order-123",
  "amount": 30000
}

응답 예시:

{
  "paymentId": "payment-123",
  "reservationId": "reservation-123",
  "status": "COMPLETED",
  "approvedAt": "2026-09-24T10:05:00Z"
}

공통 오류

HTTP 상태	의미
400	요청 형식 또는 비즈니스 규칙 오류
401	인증 실패
403	접근 권한 부족
404	예약 또는 결제 정보 없음
409	중복 예약, 상태 충돌, 멱등성 충돌
422	결제 금액 등 도메인 검증 실패
500	서버 내부 오류
502	외부 결제 제공자 오류

---

8. 설정

주요 환경 변수 예시:

NODE_ENV=development
PORT=3000

DATABASE_URL=postgresql://user:password@localhost:5432/reservation

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

PAYMENT_PROVIDER_URL=
PAYMENT_PROVIDER_SECRET=

QUEUE_PREFIX=reservation

설정 원칙:

• 비밀 값은 소스 코드에 저장하지 않습니다.
• 시작 시 필수 환경 변수의 유효성을 검증합니다.
• 개발·테스트·운영 환경의 데이터베이스와 Redis를 분리합니다.
• 결제 제공자 키는 로그에 출력하지 않습니다.

---

9. 시작하기

사전 요구사항

• Node.js 20+
• PostgreSQL
• Redis
• npm, pnpm 또는 yarn
• 결제 제공자 테스트 계정

설치

npm install

환경 변수

cp .env.example .env

.env에 PostgreSQL, Redis, 결제 제공자 설정을 입력합니다.

Prisma

npx prisma generate
npx prisma migrate dev

실행

npm run start:dev

빌드 및 운영 실행

npm run build
npm run start:prod

---

10. 개발 가이드

모듈 개발 순서

1. 도메인 요구사항과 상태 전이를 정의합니다.
2. Prisma 모델과 마이그레이션을 작성합니다.
3. DTO에 입력 검증을 추가합니다.
4. Service에 비즈니스 로직을 구현합니다.
5. Controller에 HTTP 인터페이스를 연결합니다.
6. 외부 연동은 별도 Provider/Adapter로 분리합니다.
7. 비동기 작업은 BullMQ Job과 Processor로 분리합니다.
8. 성공·실패·재시도 시나리오를 테스트합니다.

예약 처리 시 주의사항

• 동시 요청에 의한 중복 예약을 방지해야 합니다.
• Redis 잠금만으로 최종 정합성을 보장하지 말고 DB 제약 조건을 함께 사용합니다.
• 예약 만료 작업은 BullMQ delayed job 또는 주기적 작업으로 처리합니다.
• 예약과 결제의 상태 전이는 명시적으로 관리합니다.

결제 처리 시 주의사항

• 클라이언트가 전달한 금액을 신뢰하지 않고 서버의 예약 금액과 비교합니다.
• 결제 승인 요청은 멱등적으로 처리합니다.
• 외부 결제 성공 후 내부 저장에 실패할 경우 보정 작업이 필요합니다.
• 결제 제공자 웹훅을 사용하는 경우 승인 API와 중복 처리할 수 있도록 설계합니다.
• 결제 키와 인증 정보는 로그·예외 메시지에서 마스킹합니다.

테스트

권장 테스트 범위:

• 예약 가능 여부 및 중복 예약
• 예약 만료
• 결제 승인 성공
• 결제 금액 불일치
• 결제 제공자 오류
• 중복 결제 승인 요청
• 결제 성공 후 알림 큐 등록
• Redis 또는 PostgreSQL 장애

예상 명령:

npm run lint
npm run test
npm run test:e2e

운영 관찰 지표

• 예약 생성 성공률
• 결제 승인 성공률
• 결제 승인 지연 시간
• 중복 예약 충돌 수
• BullMQ 대기 작업 수
• 실패 작업 및 재시도 횟수
• Redis 캐시 적중률
• 결제 성공 후 예약 상태 불일치 수