Smithery is now a part of Arcade.dev! Read more in our announcement here
Create or update system design documents. Supports initial design and incremental design modes. Use when users need technical architecture, API design, data models, design changes, or impact analysis...
基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。
/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 询问用户：
技术栈偏好
目标平台
部署环境
现有系统集成
如用户无偏好，则根据需求设计最优方案。
增量设计前必须进行影响分析：
## 影响分析：<变更名称>
**变更来源**：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 | 新增 | ✅ | 新表 |
| 变更类型 | 向后兼容判断 | 处理方式 |
|---|---|---|
| 新增接口 | ✅ 兼容 | 直接添加 |
| 新增字段（可选） | ✅ 兼容 | 直接添加 |
| 新增字段（必填） | ❌ 不兼容 | 需要迁移计划 |
| 修改字段类型 | ❌ 不兼容 | 需要迁移计划 |
| 删除字段/接口 | ❌ 不兼容 | 需要废弃周期 |
| 修改接口参数 | ⚠️ 视情况 | 评估影响范围 |
破坏性变更处理：
增量设计完成后，在设计文档末尾追加变更记录：
---
## 设计变更记录
### 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)
...
主文件：docs/devdocs/02-system-design.md
当满足以下条件时，应拆分文档：
拆分方式：
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 原则：
| 原则 | 说明 | 检查点 |
|---|---|---|
| Maintainability | 可维护性 | 模块职责单一、依赖清晰、易于理解和修改 |
| Testability | 可测试性 | 核心逻辑可单元测试、依赖可 Mock、边界清晰（参考 /testing-guide） |
| Extensibility | 可扩展性 | 预留扩展点、接口抽象、开闭原则 |
根据场景选择合适的设计模式，只在必要时使用：
| 场景 | 推荐模式 | 适用情况 |
|---|---|---|
| 对象创建 | Factory / Builder | 复杂对象构建、多种类型创建 |
| 行为扩展 | Strategy / Template | 算法可替换、流程固定步骤可变 |
| 结构组织 | Facade / Adapter | 简化复杂接口、适配第三方库 |
| 状态管理 | State / Observer | 状态驱动行为、事件通知 |
| 数据访问 | Repository / DAO | 数据层抽象、查询封装 |
┌─────────────────────────────────────┐
│ 接口层 │ ← API/Controller（薄层，无业务逻辑）
├─────────────────────────────────────┤
│ 服务层 │ ← 业务逻辑（核心，可测试）
├─────────────────────────────────────┤
│ 领域层 │ ← 领域模型（实体、值对象）
├─────────────────────────────────────┤
│ 基础设施层 │ ← 数据访问、外部服务（可替换）
└─────────────────────────────────────┘
设计文档中应体现核心接口定义（只定义签名，不写实现），并标注关联功能点：
### 核心接口
#### 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 |
| 传递方式 | 通过 Context/Header 贯穿整个调用链 |
| 命名约定 | traceId 或 correlationId |
| 格式 | UUID 或 req-{timestamp}-{random} |
用途：
traceId 查询完整日志链| 场景 | 日志策略 | 说明 |
|---|---|---|
| 测试通过 | 仅保留 ERROR/WARN | 减少日志量 |
| 测试失败 | 保留完整日志（含 DEBUG） | 便于排查 |
| 手动复现 | 启用 DEBUG 级别 | 最大化信息 |
失败分析流程：
1. 获取失败测试的 traceId
│
▼
2. 查询该 traceId 的完整日志链
│
▼
3. 定位首个 ERROR/异常点
│
▼
4. 分析上下文日志
/testing-guide）| 场景 | 协作 Skill | 说明 |
|---|---|---|
| 新功能设计变更 | /devdocs-feature |
新功能触发增量设计 |
| 优化建议设计变更 | /devdocs-insights |
洞察确认后触发增量设计 |
| 可测试性设计 | /testing-guide |
确保核心逻辑可单元测试 |
| 代码质量 | /code-quality |
MTE 原则指导设计 |
| UI 架构 | /ui-skills |
UI 组件设计约束 |
| 接口自动提取 | /devdocs-retrofit |
从现有代码逆向提取接口定义并同步到设计文档 |
用户确认系统设计后，建议运行 /devdocs-test-cases 进入测试用例设计阶段。
/devdocs-test-cases 补充测试用例