# NestJS Template

生產就緒的 NestJS 起始模板，內建常用基礎設施與規範，開新專案時直接 fork 使用。

## 技術棧

| 分類 | 套件 |
|---|---|
| 框架 | NestJS 11 |
| 語言 | TypeScript 5（ESM + NodeNext） |
| 資料庫 | PostgreSQL + TypeORM |
| 快取 | Redis（ioredis） |
| 設定管理 | @nestjs/config |
| 驗證 | class-validator + class-transformer |
| 日誌 | nestjs-pino + pino-roll |
| 認證 | @nestjs/jwt |
| API 文件 | @nestjs/swagger |
| 流量控制 | @nestjs/throttler |
| 資安 | helmet + CORS |

## 內建功能

- **統一回傳格式** — 所有端點自動包裝為 `{ code, message, data }`
- **全域 JWT 驗證** — 預設所有路由需要 Bearer token，公開路由加 `@Public()`
- **全域 Rate Limiting** — 透過環境變數設定 TTL 與上限次數
- **全域 ValidationPipe** — 自動過濾多餘欄位、型別轉換，自訂錯誤訊息
- **統一例外處理** — 所有例外回傳一致的錯誤格式
- **結構化日誌** — 開發環境 pretty print，production 寫檔並自動輪替
- **Swagger UI** — 非 production 環境自動啟用，路徑 `/api/docs`
- **Graceful Shutdown** — 服務停止時正常關閉 DB / Redis 連線

## 快速開始

### 前置需求

- Node.js 22+
- pnpm
- PostgreSQL
- Redis

### 安裝

```bash
pnpm install
cp .env.example .env
```

編輯 `.env`，填入資料庫、Redis、JWT 等設定值。

### 啟動

```bash
# 開發模式
pnpm start:dev

# 生產模式（需先 build）
pnpm build
pnpm start:prod
```

## 環境變數

| 變數 | 說明 | 預設值 |
|---|---|---|
| `NODE_ENV` | 環境 | `development` |
| `PORT` | 監聽埠 | `3000` |
| `CORS_ORIGINS` | 允許的 CORS 來源，逗號分隔 | 空（全封） |
| `DB_HOST` | PostgreSQL 主機 | — |
| `DB_PORT` | PostgreSQL 埠 | `5432` |
| `DB_USER` | 使用者名稱 | — |
| `DB_PASSWORD` | 密碼 | — |
| `DB_NAME` | 資料庫名稱 | — |
| `REDIS_HOST` | Redis 主機 | — |
| `REDIS_PORT` | Redis 埠 | `6379` |
| `REDIS_USER` | Redis 使用者（選填） | — |
| `REDIS_PASSWORD` | Redis 密碼（選填） | — |
| `JWT_SECRET` | JWT 簽名金鑰 | — |
| `JWT_EXPIRES_IN` | Token 有效期 | `7d` |
| `THROTTLE_TTL` | Rate limit 時間窗口（毫秒） | — |
| `THROTTLE_LIMIT` | 時間窗口內最大請求數 | — |

## 目錄結構

```
src/
├── core/               # 生命週期類別 + 基礎設施模組
│   ├── db/             # TypeORM 設定
│   ├── redis/          # Redis 設定
│   ├── logger/         # Pino 日誌設定
│   ├── throttler/      # Rate limiting 設定
│   ├── filter/         # 全域例外 filter
│   ├── interceptor/    # 回應包裝 interceptor
│   ├── guard/          # JWT guard
│   └── pipe/           # Validation exception factory
├── common/             # 跨模組共用（不掛生命週期）
│   ├── decorator/      # @Public() 等自訂裝飾器
│   ├── token/          # 注入 token 常數
│   └── type/           # 共用型別（ApiResponse、JwtPayload）
└── module/             # 業務功能模組（每個領域一個子目錄）
```

新業務模組放在 `src/module/<模組名>/`，結構參考 `CLAUDE.md`。

## 常用指令

```bash
pnpm start:dev       # 開發模式（watch）
pnpm start:debug     # 除錯模式
pnpm build           # 編譯
pnpm typecheck       # 型別檢查
pnpm lint            # Lint 檢查
pnpm format          # 格式化
pnpm test            # 單元測試
pnpm test:cov        # 測試覆蓋率
pnpm test:e2e        # E2E 測試
```

## 開發規範

詳見 [CLAUDE.md](./CLAUDE.md)。