Devdocs System Design

系统设计

基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。

语言规则

• 支持中英文提问
• 统一中文回复
• 使用中文生成文档

触发条件

初始设计模式

• 用户已完成需求文档，项目无系统设计
• 用户要求系统/技术设计
• 用户需要架构或 API 设计

增量设计模式

• 新功能加入后需要设计变更（来自 /devdocs-feature）
• 优化建议确认后需要设计调整（来自 /devdocs-insights）
• 技术改进需要架构调整
• 用户要求更新/修改现有设计

前置条件

• 需求文档：docs/devdocs/01-requirements.md
• 如不存在，建议先运行 /devdocs-requirements

设计模式检测

启动时自动检测
      │
      ▼
检查 02-system-design.md 是否存在
      │
      ├── 不存在 → 初始设计模式
      │
      └── 存在 → 增量设计模式
            │
            ▼
      检查是否有新增需求（F-XXX）未覆盖
            │
            ├── 有 → 提示增量设计
            │
            └── 无 → 询问用户意图

工作流程

初始设计流程

1. 读取需求 → 加载 01-requirements.md
      │
      ▼
2. 询问偏好 → 技术栈、平台、集成需求
      │
      ▼
3. 探索代码 → 了解现有架构
      │
      ▼
4. 创建设计 → 生成系统设计文档
      │
      ▼
5. 验证覆盖 → 检查所有 F-XXX 都有对应模块/接口
      │
      ▼
6. 用户确认 → 获得批准后定稿

增量设计流程

1. 读取现有设计 → 加载 02-system-design*.md
      │
      ▼
2. 识别变更来源
      ├── 新功能需求（F-XXX）
      ├── 优化建议（INS-XXX）
      └── 技术改进
      │
      ▼
3. 影响分析
      ├── 识别受影响的模块
      ├── 识别受影响的接口
      └── 识别受影响的数据模型
      │
      ▼
4. 兼容性评估
      ├── 接口变更是否向后兼容？
      ├── 数据模型变更是否需要迁移？
      └── 是否有破坏性变更？
      │
      ▼
5. 设计变更
      ├── 新增模块/接口/数据模型
      ├── 修改现有设计
      └── 标注变更版本
      │
      ▼
6. 生成变更记录 → 追加到设计文档
      │
      ▼
7. 用户确认 → 获得批准后更新文档

设计前必问

必须使用 AskUserQuestion 询问用户：

1. 技术栈偏好

   • 是否有偏好的技术栈？
   • 选项：指定技术栈 / 无偏好（将根据需求推荐）

2. 目标平台

   • 目标平台是什么？
   • 选项：Web / Mobile (iOS/Android) / Desktop / Server / 跨平台

3. 部署环境

   • 部署在哪里？
   • 选项：云服务 (AWS/GCP/Azure) / 私有化 / 混合

4. 现有系统集成

   • 是否需要与现有系统集成？
   • 选项：否 / 是（指定系统、API、数据库）

如用户无偏好，则根据需求设计最优方案。

增量设计

影响分析

增量设计前必须进行影响分析：

## 影响分析：<变更名称>

**变更来源**：F-XXX / INS-XXX / 技术改进
**变更日期**：YYYY-MM-DD

### 受影响的模块

| 模块 | 影响类型 | 说明 |
|------|----------|------|
| UserService | 修改 | 新增方法 `resetPassword()` |
| AuthModule | 新增 | 新增密码重置模块 |
| EmailService | 无变化 | 复用现有邮件服务 |

### 受影响的接口

| 接口 | 变更类型 | 向后兼容 | 说明 |
|------|----------|----------|------|
| POST /api/auth/reset-password | 新增 | ✅ | 新接口 |
| GET /api/user/:id | 修改 | ✅ | 返回值新增字段 |
| POST /api/auth/login | 修改 | ❌ | 参数结构变更 |

### 受影响的数据模型

| 实体 | 变更类型 | 需要迁移 | 说明 |
|------|----------|----------|------|
| User | 修改 | ✅ | 新增 `resetToken` 字段 |
| PasswordResetLog | 新增 | ✅ | 新表 |

兼容性评估

破坏性变更处理：

1. 标注废弃（Deprecated）
2. 设置废弃周期（如 2 个版本）
3. 提供迁移指南
4. 在变更记录中说明

设计变更记录

增量设计完成后，在设计文档末尾追加变更记录：

---

## 设计变更记录

### v1.2.0 (2024-01-20)

**变更来源**：F-005 密码重置功能, INS-003 登录安全优化

**新增模块**：
- `PasswordResetModule` - 密码重置模块（关联 F-005）

**修改模块**：
- `AuthModule` - 新增密码重置入口

**新增接口**：
- `IPasswordResetService.sendResetEmail()` - 发送重置邮件
- `IPasswordResetService.resetPassword()` - 执行密码重置

**新增 API**：
- `POST /api/auth/forgot-password` - 请求密码重置
- `POST /api/auth/reset-password` - 执行密码重置

**数据模型变更**：
- `User` 新增字段：`resetToken`, `resetTokenExpiry`
- 新增实体：`PasswordResetLog`

**破坏性变更**：无

**迁移说明**：
- 执行数据库迁移脚本 `migrations/001-add-reset-token.sql`

---

### v1.1.0 (2024-01-10)

...

增量设计检查清单

• 已识别所有受影响的模块
• 已识别所有受影响的接口
• 已识别所有受影响的数据模型
• 已评估向后兼容性
• 破坏性变更已标注处理方式
• 已生成变更记录
• 新增内容已标注关联需求（F-XXX / INS-XXX）

输出文件

主文件：docs/devdocs/02-system-design.md

文档拆分规则

当满足以下条件时，应拆分文档：

• 文档超过 300 行
• 模块数量超过 5 个
• API 接口超过 10 个

拆分方式：

docs/devdocs/
├── 02-system-design.md          # 主文档：架构概览、技术选型、模块划分
├── 02-system-design-api.md      # API 设计：接口定义、请求响应示例
└── 02-system-design-data.md     # 数据模型：实体定义、ER 图、索引策略

拆分内容分配：

详细模板参见 templates/design-template.md。

设计原则

MTE 原则

系统设计必须遵循 MTE 原则：

设计模式选择

根据场景选择合适的设计模式，只在必要时使用：

设计层次

┌─────────────────────────────────────┐
│             接口层                   │  ← API/Controller（薄层，无业务逻辑）
├─────────────────────────────────────┤
│             服务层                   │  ← 业务逻辑（核心，可测试）
├─────────────────────────────────────┤
│             领域层                   │  ← 领域模型（实体、值对象）
├─────────────────────────────────────┤
│           基础设施层                 │  ← 数据访问、外部服务（可替换）
└─────────────────────────────────────┘

文档结构

1. 目标平台 - 平台、版本要求、部署环境
2. 架构概览 - 高层架构图（Mermaid）
3. 技术选型 - 技术选择及理由
4. 模块设计 - 模块职责与依赖，标注关联功能点 (F-XXX)
5. 核心接口 - 面向接口 (仅签名): 关键接口和方法签名（严禁包含具体实现逻辑），标注关联 F-XXX
6. 设计模式 - 应用的模式及理由
7. 代码结构 - 目录结构设计
8. 数据模型 - 实体定义与关系
9. API 设计 - 接口端点及请求/响应示例，标注关联 F-XXX, AC-XXX
10. 状态流转 - 关键业务流程的状态机
11. 异常处理 - 错误码与处理策略
12. 日志设计 - 日志级别、关键日志点、追溯 ID
13. 扩展性 - 扩展点与未来考量
14. 需求追溯 - 功能点与模块/接口的映射关系，覆盖检查清单

核心接口设计

设计文档中应体现核心接口定义（只定义签名，不写实现），并标注关联功能点：

### 核心接口

#### IUserService（关联：F-001 用户注册, F-002 用户登录）

| 方法 | 参数 | 返回值 | 关联 | 说明 |
|------|------|--------|------|------|
| `createUser` | `CreateUserDTO` | `User` | F-001, AC-001 | 创建用户 |
| `validateEmail` | `string` | `boolean` | F-001, AC-002 | 验证邮箱 |
| `login` | `LoginDTO` | `AuthToken` | F-002, AC-006 | 用户登录 |

#### IUserRepository

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `save` | `User` | `User` | 保存用户 |
| `findById` | `string` | `User \| null` | 根据ID查询 |
| `findByEmail` | `string` | `User \| null` | 根据邮箱查询 |

代码结构设计

### 目录结构

src/
├── api/                    # 接口层
│   ├── controllers/        # 控制器（路由处理）
│   ├── middlewares/        # 中间件（认证、日志等）
│   └── validators/         # 请求验证
├── services/               # 服务层
│   ├── interfaces/         # 服务接口定义
│   └── impl/               # 服务实现
├── domain/                 # 领域层
│   ├── entities/           # 实体
│   ├── value-objects/      # 值对象
│   └── events/             # 领域事件
├── infrastructure/         # 基础设施层
│   ├── repositories/       # 数据仓储实现
│   ├── external/           # 外部服务适配
│   └── config/             # 配置
└── shared/                 # 共享
    ├── types/              # 类型定义
    ├── utils/              # 工具函数
    └── constants/          # 常量

日志设计

日志是调试和问题排查的关键工具，特别是对于手动测试和 E2E 测试场景。

日志级别

关键日志点

设计文档中应列出关键操作的日志点：

| 操作 | 日志级别 | 日志内容 | 关联编号 |
|------|----------|----------|----------|
| 用户登录成功 | INFO | `[F-002] User login: userId={}, ip={}` | F-002, AC-006 |
| 用户登录失败 | WARN | `[F-002] Login failed: userId={}, reason={}` | F-002, AC-007 |
| 密码验证失败 | WARN | `[F-002] Password mismatch: userId={}` | AC-007 |
| 数据库异常 | ERROR | `[INFRA] DB error: {}, query={}` | - |
| 订单创建 | INFO | `[F-003] Order created: orderId={}, userId={}` | F-003 |

日志格式

[时间] [级别] [追溯ID] [模块] 消息 {结构化数据}

示例：

2024-01-26 10:30:15 INFO [req-abc123] [UserService] User created {"userId": "u001", "email": "user@example.com"}
2024-01-26 10:30:16 ERROR [req-abc123] [EmailService] Failed to send verification email {"userId": "u001", "error": "SMTP timeout"}

追溯 ID (Correlation ID)

用途：

• E2E 测试失败时，通过 traceId 查询完整日志链
• 分布式系统中跨服务追踪
• 问题排查时关联所有相关日志

E2E 测试日志策略

失败分析流程：

1. 获取失败测试的 traceId
   │
   ▼
2. 查询该 traceId 的完整日志链
   │
   ▼
3. 定位首个 ERROR/异常点
   │
   ▼
4. 分析上下文日志

日志设计约束

• 关键业务操作必须有 INFO 级别日志
• 错误必须有 ERROR 级别日志，包含上下文
• 日志必须包含追溯 ID
• 日志必须标注关联的功能点编号
• 敏感信息（密码、Token）不得出现在日志中
• 日志格式必须支持结构化解析

约束

基础约束

• 必须先询问用户技术栈偏好和目标平台
• 技术选型必须说明理由
• 如用户无偏好，根据需求选择最优方案
• 必须指定目标平台和最低版本要求
• API 设计必须包含请求/响应示例
• 数据模型必须考虑索引和查询模式
• 必须识别与现有系统的集成点
• 优先使用项目现有技术栈

MTE 原则约束

• 每个模块职责单一，不超过一个变化原因
• 核心业务逻辑必须可单元测试（无外部依赖或依赖可 Mock，详见 /testing-guide）
• 预留合理扩展点，但不为假设需求设计
• 依赖方向：外层依赖内层，内层不依赖外层
• 接口优于实现：依赖抽象，不依赖具体实现

设计模式约束

• 只在解决实际问题时使用设计模式，不为使用而使用
• 使用的设计模式必须说明解决什么问题
• 优先选择简单方案，复杂方案需要说明理由
• 相同问题在项目中使用一致的模式

避免过度设计

• 不为"未来可能"的需求设计，只为当前需求设计
• 不创建只有一个实现的接口（除非为了可测试性）
• 不过早抽象，等到有 3 个以上相似场景再抽象
• 配置优于硬编码，但不为所有内容添加配置

安全约束

• 敏感数据（密码、Token）不明文存储
• 需要认证的 API 已标注
• 用户输入有验证（防注入）
• 敏感操作有日志记录

增量设计约束

• 增量设计前必须进行影响分析
• 必须评估向后兼容性
• 破坏性变更必须标注处理方式
• 必须生成设计变更记录
• 新增内容必须标注关联需求（F-XXX / INS-XXX）
• 修改现有接口必须说明兼容性
• 数据模型变更必须说明迁移方案

Skill 协作

下一步

初始设计后

用户确认系统设计后，建议运行 /devdocs-test-cases 进入测试用例设计阶段。

增量设计后

1. 如有新增功能点 → 运行 /devdocs-test-cases 补充测试用例
2. 如有数据模型变更 → 准备数据库迁移脚本
3. 如有破坏性变更 → 通知相关依赖方