chat-one-service/docs/project-solution.md

# ChatOne Service 项目方案（NestJS）

本文给出一个主流且简洁、可直接落地的服务端方案，满足以下目标：
- 基于 NestJS 构建；
- 同时提供客户端接口与后台管理接口；
- 支持短信登录、邮箱登录；
- 支持千问、火山引擎、DeepSeek 等多平台 AI Chat 流式输出；
- 对外提供统一调用接口（自动路由）和指定平台调用接口；
- 提供用户管理、平台管理、用量统计。

## 目录

- [1. 技术选型（主流且简洁）](#1-技术选型主流且简洁)
- [2. 项目结构（推荐：按用户端/管理端强隔离）](#2-项目结构推荐按用户端管理端强隔离)
- [3. 模块职责](#3-模块职责)
- [4. API 设计（示例）](#4-api-设计示例)
- [5. 自动路由与统一格式方案](#5-自动路由与统一格式方案)
- [6. 依赖清单（核心）](#6-依赖清单核心)
- [7. 配置文件示例](#7-配置文件示例)
- [8. 数据库设计（PostgreSQL）](#8-数据库设计postgresql)
- [9. 缓存方案（Redis）](#9-缓存方案redis)
- [10. 登录与鉴权方案](#10-登录与鉴权方案)
- [11. 拆分演进路线（低成本）](#11-拆分演进路线低成本)
- [12. 最小可用开发流程（MVP）](#12-最小可用开发流程mvp)
- [13. 非功能建议（上线前）](#13-非功能建议上线前)
- [14. 一句话总结](#14-一句话总结)

---

## 1. 技术选型（主流且简洁）

- **运行时**：Node.js 20 LTS
- **框架**：NestJS 10（Fastify 适配器，性能更优）
- **ORM**：Prisma（类型安全、迁移友好）
- **数据库**：PostgreSQL 15
- **缓存/队列**：Redis 7（缓存、限流、验证码、会话黑名单）
- **鉴权**：JWT（Access + Refresh）+ RBAC
- **文档**：Swagger（`@nestjs/swagger`）
- **校验**：`class-validator` + `class-transformer`
- **日志**：Pino（`nestjs-pino`）
- **任务调度**：`@nestjs/schedule`（统计聚合作业）
- **流式输出**：SSE（标准 EventSource，前端接入简单）

---

## 2. 项目结构（推荐：按用户端/管理端强隔离）

```text
chat-one-service/
├─ src/
│  ├─ main.ts                           # 单体双端统一启动入口（MVP）
│  ├─ app.module.ts                     # 根模块：聚合 client/admin/shared
│  ├─ common/
│  │  ├─ constants/                     # 全局常量（错误码前缀、header key 等）
│  │  ├─ decorators/                    # 自定义装饰器（当前用户、角色、公开路由）
│  │  ├─ filters/                       # 全局异常过滤（统一错误响应格式）
│  │  ├─ guards/                        # 通用 guard（按需被 client/admin 复用）
│  │  ├─ interceptors/                  # 请求日志、traceId、响应耗时统计
│  │  ├─ pipes/                         # DTO 校验与类型转换
│  │  └─ utils/                         # 通用工具函数（时间、脱敏、签名等）
│  ├─ config/
│  │  ├─ configuration.ts               # 读取并组织配置（按模块导出）
│  │  ├─ validation.ts                  # 启动前环境变量校验（fail fast）
│  │  └─ swagger.ts                     # Swagger 初始化与分组（client/admin）
│  ├─ apps/
│  │  ├─ client-app/                   # 用户端边界：面向 C 端业务能力
│  │  │  ├─ client-app.module.ts       # 用户端聚合模块（auth/chat/sessions/profile）
│  │  │  ├─ auth/                      # 用户端认证：短信验证码、登录、refresh
│  │  │  ├─ chat/
│  │  │  │  ├─ chat.module.ts          # chat 子模块聚合入口
│  │  │  │  ├─ controllers/            # 对外接口层（统一/指定平台 SSE 入口）
│  │  │  │  ├─ application/            # 用例编排层（配额检查、路由、日志）
│  │  │  │  ├─ domain/                 # 领域规则层（会话/消息/策略）
│  │  │  │  ├─ infrastructure/         # 基础设施层（Prisma/Redis/SSE/事件）
│  │  │  │  ├─ dto/                    # 请求/响应 DTO（仅用户端可见字段）
│  │  │  │  └─ constants/              # chat 常量（事件类型、错误码、模型别名）
│  │  │  ├─ sessions/                  # 会话与历史查询（可逐步并入 chat）
│  │  │  └─ profile/                   # 用户资料、偏好设置、个人配置
│  │  ├─ admin-app/                    # 管理端边界：面向运营/管理能力
│  │  │  ├─ admin-app.module.ts        # 管理端聚合模块（auth/users/platforms/stats）
│  │  │  ├─ auth/                      # 管理端认证：邮箱登录、RBAC、审计
│  │  │  ├─ users/                     # 用户管理：查询、禁用、角色与额度治理
│  │  │  ├─ platforms/                 # 平台管理：密钥、权重、模型映射、健康检查
│  │  │  ├─ stats/                     # 统计报表：请求量、token、成本、错误率
│  │  │  └─ audits/                    # 审计日志：关键管理操作留痕
│  │  └─ shared-domain/                # 双端共享能力（无业务端特有语义）
│  │     ├─ ai-gateway/
│  │     │  ├─ providers/              # 第三方平台适配实现（qwen/volc/deepseek）
│  │     │  │  ├─ provider.interface.ts# provider 抽象协议，统一调用方式
│  │     │  │  ├─ qwen.provider.ts
│  │     │  │  ├─ volc.provider.ts
│  │     │  │  └─ deepseek.provider.ts
│  │     │  ├─ router/
│  │     │  │  └─ provider-router.service.ts # 自动路由与降级策略
│  │     │  └─ formatter/
│  │     │     └─ stream-normalizer.service.ts # 统一 SSE chunk 输出协议
│  │     ├─ identity/                  # 身份能力：JWT 签发、策略、guard、token 工具
│  │     ├─ sms/                       # 短信能力：验证码发送、频控、模板封装
│  │     ├─ mail/                      # 邮件能力：登录通知、告警通知、模板发送
│  │     └─ stats-core/                # 统计核心：聚合计算、指标定义、通用查询
│  ├─ prisma/
│  │  ├─ prisma.module.ts              # Prisma 注入模块
│  │  └─ prisma.service.ts             # PrismaClient 生命周期与扩展
│  └─ types/                           # 全局类型声明（枚举、共享接口）
├─ prisma/
│  ├─ schema.prisma                    # 数据模型定义
│  └─ migrations/                      # 数据库迁移历史
├─ docs/
│  └─ project-solution.md              # 架构与实现方案文档
├─ .env.example                        # 环境变量示例
├─ package.json                        # 依赖与脚本
└─ tsconfig.json                       # TypeScript 编译配置
```

---

## 3. 模块职责

### 3.1 用户端（`client-app`）

- **client-auth**
  - 仅负责短信验证码发送/校验、客户端 token 签发与刷新
- **chat**
  - 提供统一 chat 接口与指定平台 chat 接口
  - 对外只暴露用户侧可见字段，不暴露平台敏感信息
  - 按 `controller -> application -> domain -> infrastructure` 分层，便于平滑拆分
- **sessions/profile（可选）**
  - 会话记录、消息历史、个人资料

#### chat 子目录建议（简化版）

- **controllers**
  - 仅处理 HTTP/SSE 协议、参数校验、响应头，不写业务逻辑
- **application**
  - 编排用例流程（鉴权通过后，做配额检查、路由 provider、写 usage）
- **domain**
  - 放会话、消息、配额策略等核心业务规则与仓储抽象接口
- **infrastructure**
  - 对接 Prisma、Redis、SSE writer、消息队列等外部依赖实现
- **dto**
  - 负责 API 入参与出参定义，避免直接暴露内部模型
- **constants**
  - 统一维护 chat 错误码、模型别名、事件类型常量

建议保持这个粒度即可，后续按开发规模再向下细分，不必一开始拆到文件级别。

### 3.2 管理端（`admin-app`）

- **admin-auth**
  - 仅负责邮箱密码登录（可选二次验证码）
- **users**
  - 用户管理、封禁/解禁、角色治理
- **platforms**
  - AI 平台开关、密钥、权重、模型映射、健康检查
- **stats/audits**
  - 用量统计、成本分析、审计日志

### 3.3 共享域（`shared-domain`）

- **ai-gateway**
  - 第三方平台适配、自动路由、流式格式统一
- **identity**
  - JWT strategy、通用 guard、token 工具
- **sms/mail/stats-core**
  - 可复用基础设施能力，避免双端重复实现

> 设计原则：控制器和应用服务严格按端隔离，后续拆分时优先迁移 `client-app` 或 `admin-app` 整个目录，shared 部分按需复制或抽公共包。

---

## 4. API 设计（示例）

统一前缀建议：
- 客户端：`/api/client/v1`
- 管理端：`/api/admin/v1`

为避免后期冲突，建议从现在开始执行以下规范：
- DTO 分离：`client-app/dto` 与 `admin-app/dto` 禁止互相引用；
- Guard 分离：`ClientJwtGuard` 与 `AdminJwtGuard` 不混用；
- Swagger 分离：客户端文档与管理端文档分组输出（如 `/docs-client`、`/docs-admin`）；
- 错误码分离：客户端错误码与管理端错误码使用不同前缀（如 `C_` / `A_`）。

### 4.1 客户端认证接口（短信）

- `POST /api/client/v1/auth/sms/send`
  - 入参：`{ phone, scene }`
  - 出参：`{ requestId, expireIn }`

- `POST /api/client/v1/auth/sms/login`
  - 入参：`{ phone, code }`
  - 出参：`{ accessToken, refreshToken, user }`（`user` 与 `users` 表对齐，建议含 `id`、`phone`、`nickname`、`avatarUrl` 等；未落库前可为占位结构）

- `POST /api/client/v1/auth/refresh`
  - 入参：`{ refreshToken }`
  - 出参：`{ accessToken, refreshToken }`

### 4.2 客户端 AI Chat 接口（流式）

- `POST /api/client/v1/chat/completions/stream`
  - 说明：统一接口，后台自动路由平台
  - 入参示例：
    ```json
    {
      "model": "gpt-4o-mini-like",
      "messages": [
        { "role": "system", "content": "你是助手" },
        { "role": "user", "content": "介绍一下NestJS" }
      ],
      "temperature": 0.7,
      "platform": "auto"
    }
    ```
  - 返回：`text/event-stream`（SSE）

- `POST /api/client/v1/chat/completions/stream/:platform`
  - 说明：指定平台（`qwen | volc | deepseek`）
  - 其余参数同上

### 4.3 建议统一 SSE 事件格式

```text
event: meta
data: {"requestId":"xxx","platform":"qwen","model":"qwen-turbo"}

event: delta
data: {"content":"你好"}

event: usage
data: {"promptTokens":120,"completionTokens":80,"totalTokens":200}

event: done
data: {"finishReason":"stop"}

event: error
data: {"code":"PLATFORM_TIMEOUT","message":"upstream timeout"}
```

### 4.4 管理端认证接口（邮箱）

- `POST /api/admin/v1/auth/login`
  - 入参：`{ email, password }`
  - 出参：`{ accessToken, refreshToken, admin }`

- `POST /api/admin/v1/auth/refresh`
- `POST /api/admin/v1/auth/logout`

### 4.5 管理端用户管理

- `GET /api/admin/v1/users`
- `GET /api/admin/v1/users/:id`
- `PATCH /api/admin/v1/users/:id/status`（启用/禁用）
- `PATCH /api/admin/v1/users/:id/role`

### 4.6 管理端平台管理

- `GET /api/admin/v1/platforms`
- `POST /api/admin/v1/platforms`
- `PATCH /api/admin/v1/platforms/:id`
- `PATCH /api/admin/v1/platforms/:id/health-check`

### 4.7 管理端统计

- `GET /api/admin/v1/stats/overview?startDate=&endDate=`
- `GET /api/admin/v1/stats/platforms`
- `GET /api/admin/v1/stats/users/top`

---

## 5. 自动路由与统一格式方案

### 5.1 自动路由策略（简版）

按优先级执行：
1. 过滤禁用平台；
2. 过滤健康检查失败平台；
3. 根据模型支持能力过滤；
4. 根据权重 + 当前错误率 + 当前限流剩余综合打分；
5. 选择得分最高平台；
6. 失败时自动降级重试下一个平台（最多 1~2 次）。

### 5.2 统一消息格式（内部 DTO）

- `ChatMessageDto`: `{ role, content, name?, toolCall? }`
- `ChatRequestDto`: `{ model, messages, temperature, topP, stream, userId }`
- `ChatChunkDto`: `{ type: 'meta'|'delta'|'usage'|'done'|'error', payload }`

第三方差异全部在 provider 内部适配，Controller 对外始终输出统一 SSE 事件。

---

## 6. 依赖清单（核心）

```bash
# Nest 基础
npm i @nestjs/common @nestjs/core @nestjs/platform-fastify @nestjs/config @nestjs/jwt @nestjs/passport @nestjs/swagger
npm i class-validator class-transformer passport passport-jwt

# 数据库/缓存
npm i @prisma/client ioredis
npm i -D prisma

# 日志/安全/限流
npm i nestjs-pino pino-http helmet @nestjs/throttler

# 任务/工具
npm i @nestjs/schedule dayjs

# 第三方请求
npm i undici

# 开发依赖
npm i -D typescript ts-node tsx @types/node eslint prettier
```

可选增强：
- `argon2`：密码哈希
- `zod`：配置或响应结构额外校验
- `@opentelemetry/api`：链路追踪

---

## 7. 配置文件示例

### 7.1 `.env.example`

```env
# App
NODE_ENV=development
PORT=3000
APP_NAME=chat-one-service
APP_BASE_URL=http://localhost:3000

# JWT
JWT_ACCESS_SECRET=replace_me_access
JWT_REFRESH_SECRET=replace_me_refresh
JWT_ACCESS_EXPIRES_IN=2h
JWT_REFRESH_EXPIRES_IN=30d

# PostgreSQL
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/chat_one?schema=public

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# SMS（Spug 推送助手：https://push.spug.cc）
SPUG_PUSH_SMS_TEMPLATE_ID=你的消息模板编号
# SPUG_PUSH_BASE_URL=https://push.spug.cc
# SPUG_SMS_NAME=模板要求的 name 变量（可选）
# SMS_MOCK=true
SMS_CODE_TTL_SECONDS=300

# Mail (admin login / notice)
MAIL_HOST=smtp.qq.com
MAIL_PORT=465
MAIL_SECURE=true
MAIL_USER=xxx@qq.com
MAIL_PASS=app_password
MAIL_FROM=ChatOne <xxx@qq.com>

# AI Providers
QWEN_API_KEY=your_qwen_key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
VOLC_API_KEY=your_volc_key
VOLC_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
DEEPSEEK_API_KEY=your_deepseek_key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

# Route Strategy
AI_ROUTE_RETRY_TIMES=1
AI_ROUTE_TIMEOUT_MS=45000

# Split-ready（拆分预留）
CLIENT_PORT=3000
ADMIN_PORT=3001
CLIENT_JWT_ACCESS_SECRET=replace_me_client_access
ADMIN_JWT_ACCESS_SECRET=replace_me_admin_access
REDIS_KEY_PREFIX_CLIENT=chatone:client
REDIS_KEY_PREFIX_ADMIN=chatone:admin
```

### 7.2 `src/config/validation.ts`（建议）

使用 `class-validator` 或 `zod` 校验环境变量，应用启动即失败（fail fast），避免线上缺配置。

---

## 8. 数据库设计（PostgreSQL）

以下为简化且够用的核心表：

### 8.1 用户与管理员

- `users`
  - `id` (bigserial pk)
  - `phone` (varchar unique)
  - `nickname` (varchar)
  - `avatar_url` (varchar, nullable) — 头像地址（HTTPS 对象存储或 CDN URL）；为空时客户端展示默认头像
  - `status` (smallint, 1正常 0禁用)
  - `created_at`, `updated_at`

- `admins`
  - `id`
  - `email` (varchar unique)
  - `password_hash` (varchar)
  - `role` (varchar: super_admin/admin/ops)
  - `status`
  - `last_login_at`
  - `created_at`, `updated_at`

### 8.2 平台配置与模型映射

- `ai_platforms`
  - `id`
  - `code` (varchar unique: qwen/volc/deepseek)
  - `name`
  - `enabled` (bool)
  - `weight` (int default 100)
  - `priority` (int default 100)
  - `base_url`
  - `api_key_encrypted`
  - `timeout_ms`
  - `rpm_limit`
  - `health_status` (varchar: healthy/unhealthy/unknown)
  - `created_at`, `updated_at`

- `ai_platform_models`
  - `id`
  - `platform_id` (fk)
  - `biz_model` (varchar)          # 业务统一模型名
  - `provider_model` (varchar)     # 平台真实模型名
  - `enabled` (bool)
  - unique(platform_id, biz_model)

### 8.3 会话与消息（可选落库）

- `chat_sessions`
  - `id`
  - `user_id` (fk)
  - `title`
  - `created_at`, `updated_at`

- `chat_messages`
  - `id`
  - `session_id` (fk)
  - `role` (user/assistant/system)
  - `content` (text)
  - `token_count` (int)
  - `provider` (varchar)
  - `created_at`

### 8.4 请求审计与统计

- `ai_request_logs`
  - `id`
  - `request_id` (varchar unique)
  - `user_id` (fk nullable)
  - `platform_code`
  - `biz_model`
  - `provider_model`
  - `status` (success/fail)
  - `error_code`
  - `latency_ms`
  - `prompt_tokens`
  - `completion_tokens`
  - `total_tokens`
  - `estimated_cost`
  - `created_at`

- `usage_daily_stats`
  - `id`
  - `stat_date` (date)
  - `dimension` (platform/user/total)
  - `dimension_key` (varchar)
  - `request_count`
  - `success_count`
  - `fail_count`
  - `total_tokens`
  - `estimated_cost`
  - unique(stat_date, dimension, dimension_key)

---

## 9. 缓存方案（Redis）

建议键设计：

- 短信验证码：`sms:code:{phone}:{scene}`（TTL 5 分钟）
- 短信发送频控：`sms:send:limit:{phone}`（TTL 60 秒）
- 刷新令牌黑名单：`auth:rt:blacklist:{jti}`（TTL 到 token 过期）
- 用户会话缓存：`auth:user:{userId}`（TTL 30 分钟，可选）
- 平台健康状态：`ai:platform:health:{code}`（TTL 30 秒）
- 平台动态权重：`ai:platform:weight:{code}`（TTL 60 秒）
- 统计临时聚合：`stats:daily:{date}:{dimension}`（TTL 1 天）

为便于拆分，建议从第一天就加命名空间前缀：
- 用户端：`chatone:client:*`
- 管理端：`chatone:admin:*`
- 共享：`chatone:shared:*`

同时启用 `@nestjs/throttler` 做接口限流：
- 客户端 chat 接口：按用户 + IP 双维度限流；
- 登录接口：按手机号/邮箱严格限流，防刷。

---

## 10. 登录与鉴权方案

### 10.1 客户端（短信登录）

1. 用户请求发送验证码；
2. 服务端生成验证码写入 Redis（哈希存储，避免明文）；
3. 用户提交验证码登录，校验通过后签发 JWT；
4. AccessToken 短期（2h），RefreshToken 长期（30d）；
5. 刷新时校验 RefreshToken 的 `jti` 与黑名单状态；
6. 注销时将 RefreshToken `jti` 拉黑至过期。

### 10.2 管理端（邮箱登录）

1. 邮箱 + 密码登录（密码 `argon2` 哈希）；
2. 可选开启邮箱二次验证码；
3. JWT + RBAC（`super_admin` / `admin` / `ops`）；
4. 管理端接口统一加 `JwtAuthGuard + RolesGuard`；
5. 关键操作（平台密钥修改、用户封禁）记录审计日志。

### 10.3 Token 建议

- AccessToken：只放必要字段（`sub`, `role`, `type`）
- RefreshToken：包含 `jti`，便于撤销
- 密钥轮转：支持双密钥平滑切换（`kid`）
- 传输：优先 `Authorization: Bearer`；管理端也可改 HttpOnly Cookie
- 强隔离建议：客户端与管理端使用不同 `issuer`、`audience`、`secret`，token 绝不互认

---

## 11. 拆分演进路线（低成本）

### 阶段 A：单体双端（当前推荐）
- 一个 Nest 进程，两个 AppModule（`client-app` / `admin-app`）；
- 共用数据库与 Redis，但 key 前缀、token 体系已隔离；
- 发布快，开发成本最低。

### 阶段 B：双进程同仓
- 启动两个入口：`main.client.ts`、`main.admin.ts`；
- 用户端和管理端可独立扩容、独立发布；
- 共享逻辑仍来自 `shared-domain`。

### 阶段 C：双服务拆仓（可选）
- `client-service`：保留短信、chat、会话；
- `admin-service`：保留邮箱登录、平台管理、统计审计；
- `shared-domain` 抽为内部 npm 包或 Git 子模块。

---

## 12. 最小可用开发流程（MVP）

建议按下面顺序实现，2~3 周可交付可用版本：

1. 初始化 NestJS + Prisma + PostgreSQL + Redis；
2. 完成客户端短信登录与 JWT 刷新；
3. 完成 Qwen 单平台流式 chat；
4. 抽象 provider 接口，接入 Volc、DeepSeek；
5. 实现统一流式格式 + 自动路由；
6. 完成管理端邮箱登录；
7. 完成平台管理、用户管理；
8. 完成请求日志与基础统计报表；
9. 完成 Swagger、限流、异常处理与日志。

---

## 13. 非功能建议（上线前）

- **安全**：API Key 加密存储；生产环境开启 Helmet/CORS 白名单；
- **稳定性**：上游超时、熔断、重试与降级；
- **可观测性**：请求链路 ID、结构化日志、错误告警；
- **成本控制**：平台权重 + 单用户日额度 + 模型白名单；
- **测试**：核心流程至少有 e2e（登录、chat、管理端鉴权）。

---

## 14. 一句话总结

该方案以 NestJS + Prisma + PostgreSQL + Redis 为核心，采用“**用户端/管理端强隔离 + shared-domain 复用**”组织代码，在保持开发效率的同时确保后续可平滑拆分为两个独立服务，并持续支持多平台 AI 路由与统一流式协议。