seclusion/docs/design.md

# Seclusion 项目设计文档

## 1. 项目概述

**Seclusion** 是一个基于 Next.js + NestJS 的全栈 Monorepo 项目模板，旨在为后续项目开发提供统一的脚手架。

## 2. 技术选型

| 层级     | 技术栈                       | 版本          |
| -------- | ---------------------------- | ------------- |
| 前端     | Next.js + React + TypeScript | 15 / 19 / 5.7 |
| 后端     | NestJS + Prisma + Swagger    | 10 / 6 / 8    |
| 认证     | Passport + JWT               | -             |
| 数据库   | SQLite (可替换)              | -             |
| 包管理   | pnpm workspace               | 9.x           |
| 构建工具 | Turborepo                    | 2.x           |
| 代码规范 | ESLint + Prettier            | -             |

## 3. 项目结构

```
seclusion/
├── apps/
│   ├── web/                    # Next.js 前端应用
│   │   ├── src/
│   │   │   ├── app/            # App Router 页面
│   │   │   ├── components/     # React 组件
│   │   │   └── lib/            # 工具库（API 客户端等）
│   │   └── public/             # 静态资源
│   │
│   └── api/                    # NestJS 后端应用
│       ├── src/
│       │   ├── auth/           # 认证模块
│       │   ├── user/           # 用户模块
│       │   ├── prisma/         # 数据库服务
│       │   └── common/         # 公共装饰器/守卫
│       └── prisma/             # Prisma schema 和迁移
│
├── packages/
│   ├── shared/                 # 共享代码
│   │   └── src/
│   │       ├── types/          # 类型定义
│   │       └── utils/          # 工具函数
│   ├── eslint-config/          # ESLint 配置包
│   └── typescript-config/      # TypeScript 配置包
│
├── package.json                # 根配置
├── pnpm-workspace.yaml         # 工作区定义
└── turbo.json                  # Turborepo 任务配置
```

## 4. 架构设计

### 4.1 Monorepo 架构

```
┌─────────────────────────────────────────────────────────┐
│                      Turborepo                          │
│  ┌─────────────────┐         ┌─────────────────┐       │
│  │    apps/web     │ ◄─────► │    apps/api     │       │
│  │   (Next.js)     │  HTTP   │   (NestJS)      │       │
│  └────────┬────────┘         └────────┬────────┘       │
│           │                           │                 │
│           └───────────┬───────────────┘                 │
│                       ▼                                 │
│           ┌─────────────────────┐                       │
│           │  packages/shared    │                       │
│           │  (类型 + 工具函数)   │                       │
│           └─────────────────────┘                       │
└─────────────────────────────────────────────────────────┘
```

### 4.2 后端模块架构

```
AppModule
    │
    ├── ConfigModule (全局)     # 环境变量管理
    ├── PrismaModule (全局)     # 数据库连接
    ├── AuthModule              # 认证模块
    │   ├── AuthController
    │   ├── AuthService
    │   ├── JwtStrategy
    │   └── JwtAuthGuard
    └── UserModule              # 用户模块
        ├── UserController
        └── UserService
```

### 4.3 认证流程

```
┌──────────┐    POST /auth/login     ┌──────────────┐
│  Client  │ ──────────────────────► │ AuthModule   │
└──────────┘                         └──────┬───────┘
     ▲                                      │
     │         { accessToken }              ▼
     └───────────────────────────── 验证密码，生成 JWT

┌──────────┐    GET /users (Bearer)  ┌──────────────┐
│  Client  │ ──────────────────────► │ JwtAuthGuard │
└──────────┘                         └──────┬───────┘
     ▲                                      │
     │              { users }               ▼
     └───────────────────────────── 验证 Token，放行请求
```

## 5. 数据模型

### 5.1 User 模型

```prisma
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  password  String
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("users")
}
```

## 6. API 接口设计

| 方法   | 路径           | 描述         | 认证 |
| ------ | -------------- | ------------ | ---- |
| POST   | /auth/register | 用户注册     | 否   |
| POST   | /auth/login    | 用户登录     | 否   |
| GET    | /auth/me       | 获取当前用户 | 是   |
| GET    | /users         | 获取所有用户 | 是   |
| GET    | /users/:id     | 获取指定用户 | 是   |
| PATCH  | /users/:id     | 更新用户信息 | 是   |
| DELETE | /users/:id     | 删除用户     | 是   |
| GET    | /health        | 健康检查     | 否   |

## 7. 共享包设计

### 7.1 类型定义 (@seclusion/shared/types)

- `ApiResponse<T>` - 通用 API 响应
- `PaginationParams` - 分页请求参数
- `PaginatedResponse<T>` - 分页响应
- `User` - 用户类型
- `LoginDto` / `CreateUserDto` - 请求 DTO
- `AuthResponse` / `TokenPayload` - 认证相关类型

### 7.2 工具函数 (@seclusion/shared/utils)

- `formatDate()` - 日期格式化
- `generateId()` - 随机 ID 生成
- `deepClone()` - 深拷贝
- `isEmpty()` - 空值判断
- `safeJsonParse()` - 安全 JSON 解析

## 8. 开发规范

### 8.1 端口分配

- 前端: 3000
- 后端: 4000
- Swagger 文档: 4000/api/docs

### 8.2 环境变量

**后端 (apps/api/.env)**

```env
DATABASE_URL="file:./dev.db"
JWT_SECRET="your-secret-key"
JWT_EXPIRES_IN="7d"
PORT=4000
```

**前端 (apps/web/.env.local)**

```env
NEXT_PUBLIC_API_URL=http://localhost:4000
```

## 9. 构建依赖关系

```
build
  ├── packages/shared (先构建)
  ├── apps/web (依赖 shared)
  └── apps/api (依赖 shared)
```

Turborepo 通过 `^build` 依赖确保构建顺序正确。