Imported from majiayu000/claude-skill-registry-data (
data/devdocs-system-design/SKILL.md). Install upstream withnpx skills add majiayu000/claude-skill-registry-data --skill devdocs-system-design. Copyright stays with the author.
系统设计
基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。
语言规则
- 支持中英文提问
- 统一中文回复
- 使用中文生成文档
触发条件
初始设计模式
- 用户已完成需求文档，项目无系统设计
- 用户要求系统/技术设计
- 用户需要架构或 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。
设计原则
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": "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)
| 属性 | 说明 |
|---|---|
| 生成时机 | 每个请求入口生成唯一 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补充测试用例 - 如有数据模型变更 → 准备数据库迁移脚本
- 如有破坏性变更 → 通知相关依赖方