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 模型

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)

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

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

NEXT_PUBLIC_API_URL=http://localhost:4000

9. 构建依赖关系

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

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