系统设计

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

语言规则

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

触发条件

初始设计模式

用户已完成需求文档，项目无系统设计
用户要求系统/技术设计
用户需要架构或 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 询问用户：

技术栈偏好

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

目标平台

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

部署环境

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

现有系统集成

- 是否需要与现有系统集成？ - 选项：否 / 是（指定系统、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 | 新增 | ✅ | 新表 |

兼容性评估

变更类型	向后兼容判断	处理方式
新增接口	✅ 兼容	直接添加
新增字段（可选）	✅ 兼容	直接添加
新增字段（必填）	❌ 不兼容	需要迁移计划
修改字段类型	❌ 不兼容	需要迁移计划
删除字段/接口	❌ 不兼容	需要废弃周期
修改接口参数	⚠️ 视情况	评估影响范围

破坏性变更处理：

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

设计变更记录

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

---

## 设计变更记录

### 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 图、索引策略

拆分内容分配：

文件	包含章节
02-system-design.md	1-7: 平台、架构、技术选型、模块、接口签名、模式、代码结构
02-system-design-api.md	9-10: 完整 API 设计、状态流转
02-system-design-data.md	8, 11-13: 数据模型、异常处理、扩展性、需求追溯

详细模板参见 [templates/design-template.md](templates/design-template.md)。

设计原则

MTE 原则

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

原则	说明	检查点
Maintainability	可维护性	模块职责单一、依赖清晰、易于理解和修改
Testability	可测试性	核心逻辑可单元测试、依赖可 Mock、边界清晰（参考 `/testing-guide`）
Extensibility	可扩展性	预留扩展点、接口抽象、开闭原则

设计模式选择

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

场景	推荐模式	适用情况
对象创建	Factory / Builder	复杂对象构建、多种类型创建
行为扩展	Strategy / Template	算法可替换、流程固定步骤可变
结构组织	Facade / Adapter	简化复杂接口、适配第三方库
状态管理	State / Observer	状态驱动行为、事件通知
数据访问	Repository / DAO	数据层抽象、查询封装

设计层次

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

文档结构

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

核心接口设计

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

### 核心接口

#### 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 测试场景。

日志级别

级别	用途	示例场景
ERROR	需要立即处理的错误	数据库连接失败、支付失败、关键服务不可用
WARN	潜在问题但不影响核心功能	重试成功、降级处理、资源接近阈值
INFO	关键业务操作	用户登录、订单创建、状态变更
DEBUG	调试信息	函数入参、中间状态、性能指标

关键日志点

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

| 操作 | 日志级别 | 日志内容 | 关联编号 |
|------|----------|----------|----------|
| 用户登录成功 | 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": "[email protected]"}
2024-01-26 10:30:16 ERROR [req-abc123] [EmailService] Failed to send verification email {"userId": "u001", "error": "SMTP timeout"}

追溯 ID (Correlation ID)

属性	说明
生成时机	每个请求入口生成唯一 ID
传递方式	通过 Context/Header 贯穿整个调用链
命名约定	`traceId` 或 `correlationId`
格式	UUID 或 `req-{timestamp}-{random}`

用途：

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

E2E 测试日志策略

场景	日志策略	说明
测试通过	仅保留 ERROR/WARN	减少日志量
测试失败	保留完整日志（含 DEBUG）	便于排查
手动复现	启用 DEBUG 级别	最大化信息

失败分析流程：

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

日志设计约束

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

约束

基础约束

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

MTE 原则约束

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

设计模式约束

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

避免过度设计

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

安全约束

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

增量设计约束

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

Skill 协作

场景	协作 Skill	说明
新功能设计变更	`/devdocs-feature`	新功能触发增量设计
优化建议设计变更	`/devdocs-insights`	洞察确认后触发增量设计
可测试性设计	`/testing-guide`	确保核心逻辑可单元测试
代码质量	`/code-quality`	MTE 原则指导设计
UI 架构	`/ui-skills`	UI 组件设计约束
接口自动提取	`/devdocs-retrofit`	从现有代码逆向提取接口定义并同步到设计文档

下一步

初始设计后

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

增量设计后

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