devdocs-system-design
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese系统设计
System Design
基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。
Create or update system design documents based on requirement documents, supporting both initial design and incremental design modes.
语言规则
Language Rules
- 支持中英文提问
- 统一中文回复
- 使用中文生成文档
- Supports questions in both Chinese and English
- Provide unified English responses
- Generate documents in English
触发条件
Trigger Conditions
初始设计模式
Initial Design Mode
- 用户已完成需求文档，项目无系统设计
- 用户要求系统/技术设计
- 用户需要架构或 API 设计
- User has completed requirement documents, and there is no system design for the project
- User requests system/technical design
- User needs architecture or API design
增量设计模式
Incremental Design Mode
- 新功能加入后需要设计变更（来自 ）
/devdocs-feature - 优化建议确认后需要设计调整（来自 ）
/devdocs-insights - 技术改进需要架构调整
- 用户要求更新/修改现有设计
- Design changes are required after new features are added (from )
/devdocs-feature - Design adjustments are required after optimization suggestions are confirmed (from )
/devdocs-insights - Architecture adjustments are required for technical improvements
- User requests to update/modify existing design
前置条件
Preconditions
- 需求文档：
docs/devdocs/01-requirements.md - 如不存在，建议先运行
/devdocs-requirements
- Requirement document:
docs/devdocs/01-requirements.md - If it does not exist, it is recommended to run first
/devdocs-requirements
设计模式检测
Design Mode Detection
启动时自动检测
│
▼
检查 02-system-design.md 是否存在
│
├── 不存在 → 初始设计模式
│
└── 存在 → 增量设计模式
│
▼
检查是否有新增需求（F-XXX）未覆盖
│
├── 有 → 提示增量设计
│
└── 无 → 询问用户意图Automatic detection on startup
│
▼
Check if 02-system-design.md exists
│
├── Does not exist → Initial Design Mode
│
└── Exists → Incremental Design Mode
│
▼
Check if there are unimplemented new requirements (F-XXX)
│
├── Yes → Prompt for incremental design
│
└── No → Ask user's intention工作流程
Workflow
初始设计流程
Initial Design Workflow
1. 读取需求 → 加载 01-requirements.md
│
▼
2. 询问偏好 → 技术栈、平台、集成需求
│
▼
3. 探索代码 → 了解现有架构
│
▼
4. 创建设计 → 生成系统设计文档
│
▼
5. 验证覆盖 → 检查所有 F-XXX 都有对应模块/接口
│
▼
6. 用户确认 → 获得批准后定稿1. Read Requirements → Load 01-requirements.md
│
▼
2. Ask Preferences → Tech stack, platform, integration requirements
│
▼
3. Explore Code → Understand existing architecture
│
▼
4. Create Design → Generate system design document
│
▼
5. Verify Coverage → Check that all F-XXX have corresponding modules/interfaces
│
▼
6. User Confirmation → Finalize after approval增量设计流程
Incremental Design Workflow
1. 读取现有设计 → 加载 02-system-design*.md
│
▼
2. 识别变更来源
├── 新功能需求（F-XXX）
├── 优化建议（INS-XXX）
└── 技术改进
│
▼
3. 影响分析
├── 识别受影响的模块
├── 识别受影响的接口
└── 识别受影响的数据模型
│
▼
4. 兼容性评估
├── 接口变更是否向后兼容？
├── 数据模型变更是否需要迁移？
└── 是否有破坏性变更？
│
▼
5. 设计变更
├── 新增模块/接口/数据模型
├── 修改现有设计
└── 标注变更版本
│
▼
6. 生成变更记录 → 追加到设计文档
│
▼
7. 用户确认 → 获得批准后更新文档1. Read Existing Design → Load 02-system-design*.md
│
▼
2. Identify Change Sources
├── New feature requirements (F-XXX)
├── Optimization suggestions (INS-XXX)
└── Technical improvements
│
▼
3. Impact Analysis
├── Identify affected modules
├── Identify affected interfaces
└── Identify affected data models
│
▼
4. Compatibility Assessment
├── Are interface changes backward compatible?
├── Do data model changes require migration?
└── Are there breaking changes?
│
▼
5. Design Changes
├── Add new modules/interfaces/data models
├── Modify existing design
└── Mark change version
│
▼
6. Generate Change Record → Append to design document
│
▼
7. User Confirmation → Update document after approval设计前必问
Mandatory Questions Before Design
必须使用 AskUserQuestion 询问用户：
-
技术栈偏好
- 是否有偏好的技术栈？
- 选项：指定技术栈 / 无偏好（将根据需求推荐）
-
目标平台
- 目标平台是什么？
- 选项：Web / Mobile (iOS/Android) / Desktop / Server / 跨平台
-
部署环境
- 部署在哪里？
- 选项：云服务 (AWS/GCP/Azure) / 私有化 / 混合
-
现有系统集成
- 是否需要与现有系统集成？
- 选项：否 / 是（指定系统、API、数据库）
如用户无偏好，则根据需求设计最优方案。
Must use AskUserQuestion to ask the user:
-
Tech Stack Preference
- Do you have a preferred tech stack?
- Options: Specify tech stack / No preference (will recommend based on requirements)
-
Target Platform
- What is the target platform?
- Options: Web / Mobile (iOS/Android) / Desktop / Server / Cross-platform
-
Deployment Environment
- Where will it be deployed?
- Options: Cloud service (AWS/GCP/Azure) / On-premises / Hybrid
-
Existing System Integration
- Is integration with existing systems required?
- Options: No / Yes (specify system, API, database)
If the user has no preference, design the optimal solution based on requirements.
增量设计
Incremental Design
影响分析
Impact Analysis
增量设计前必须进行影响分析：
markdown
undefinedImpact analysis must be performed before incremental design:
markdown
undefined影响分析：<变更名称>
Impact Analysis: <Change Name>
变更来源：F-XXX / INS-XXX / 技术改进
变更日期：YYYY-MM-DD
Change Source: F-XXX / INS-XXX / Technical Improvement
Change Date: YYYY-MM-DD
受影响的模块
Affected Modules
| 模块 | 影响类型 | 说明 |
|---|---|---|
| UserService | 修改 | 新增方法 |
| AuthModule | 新增 | 新增密码重置模块 |
| EmailService | 无变化 | 复用现有邮件服务 |
| Module | Impact Type | Description |
|---|---|---|
| UserService | Modify | Add new method |
| AuthModule | Add | Add password reset module |
| EmailService | No Change | Reuse existing email service |
受影响的接口
Affected Interfaces
| 接口 | 变更类型 | 向后兼容 | 说明 |
|---|---|---|---|
| POST /api/auth/reset-password | 新增 | ✅ | 新接口 |
| GET /api/user/:id | 修改 | ✅ | 返回值新增字段 |
| POST /api/auth/login | 修改 | ❌ | 参数结构变更 |
| Interface | Change Type | Backward Compatible | Description |
|---|---|---|---|
| POST /api/auth/reset-password | Add | ✅ | New interface |
| GET /api/user/:id | Modify | ✅ | Add new field to return value |
| POST /api/auth/login | Modify | ❌ | Parameter structure changed |
受影响的数据模型
Affected Data Models
| 实体 | 变更类型 | 需要迁移 | 说明 |
|---|---|---|---|
| User | 修改 | ✅ | 新增 |
| PasswordResetLog | 新增 | ✅ | 新表 |
undefined| Entity | Change Type | Needs Migration | Description |
|---|---|---|---|
| User | Modify | ✅ | Add |
| PasswordResetLog | Add | ✅ | New table |
undefined兼容性评估
Compatibility Assessment
| 变更类型 | 向后兼容判断 | 处理方式 |
|---|---|---|
| 新增接口 | ✅ 兼容 | 直接添加 |
| 新增字段（可选） | ✅ 兼容 | 直接添加 |
| 新增字段（必填） | ❌ 不兼容 | 需要迁移计划 |
| 修改字段类型 | ❌ 不兼容 | 需要迁移计划 |
| 删除字段/接口 | ❌ 不兼容 | 需要废弃周期 |
| 修改接口参数 | ⚠️ 视情况 | 评估影响范围 |
破坏性变更处理：
- 标注废弃（Deprecated）
- 设置废弃周期（如 2 个版本）
- 提供迁移指南
- 在变更记录中说明
| Change Type | Backward Compatibility Judgment | Handling Method |
|---|---|---|
| New interface | ✅ Compatible | Add directly |
| Add optional field | ✅ Compatible | Add directly |
| Add required field | ❌ Incompatible | Need migration plan |
| Modify field type | ❌ Incompatible | Need migration plan |
| Delete field/interface | ❌ Incompatible | Need deprecation period |
| Modify interface parameters | ⚠️ Depends | Evaluate impact scope |
Breaking Change Handling:
- Mark as Deprecated
- Set deprecation period (e.g., 2 versions)
- Provide migration guide
- Explain in change records
设计变更记录
Design Change Records
增量设计完成后，在设计文档末尾追加变更记录：
markdown
---After completing incremental design, append change records at the end of the design document:
markdown
---设计变更记录
Design Change Records
v1.2.0 (2024-01-20)
v1.2.0 (2024-01-20)
变更来源：F-005 密码重置功能, INS-003 登录安全优化
新增模块：
- - 密码重置模块（关联 F-005）
PasswordResetModule
修改模块：
- - 新增密码重置入口
AuthModule
新增接口：
- - 发送重置邮件
IPasswordResetService.sendResetEmail() - - 执行密码重置
IPasswordResetService.resetPassword()
新增 API：
- - 请求密码重置
POST /api/auth/forgot-password - - 执行密码重置
POST /api/auth/reset-password
数据模型变更：
- 新增字段：
User,resetTokenresetTokenExpiry - 新增实体：
PasswordResetLog
破坏性变更：无
迁移说明：
- 执行数据库迁移脚本
migrations/001-add-reset-token.sql
Change Source: F-005 Password Reset Feature, INS-003 Login Security Optimization
Added Modules:
- - Password reset module (associated with F-005)
PasswordResetModule
Modified Modules:
- - Added password reset entry
AuthModule
Added Interfaces:
- - Send reset email
IPasswordResetService.sendResetEmail() - - Execute password reset
IPasswordResetService.resetPassword()
Added APIs:
- - Request password reset
POST /api/auth/forgot-password - - Execute password reset
POST /api/auth/reset-password
Data Model Changes:
- added fields:
User,resetTokenresetTokenExpiry - Added entity:
PasswordResetLog
Breaking Changes: None
Migration Instructions:
- Execute database migration script
migrations/001-add-reset-token.sql
v1.1.0 (2024-01-10)
v1.1.0 (2024-01-10)
...
undefined...
undefined增量设计检查清单
Incremental Design Checklist
- 已识别所有受影响的模块
- 已识别所有受影响的接口
- 已识别所有受影响的数据模型
- 已评估向后兼容性
- 破坏性变更已标注处理方式
- 已生成变更记录
- 新增内容已标注关联需求（F-XXX / INS-XXX）
- Identified all affected modules
- Identified all affected interfaces
- Identified all affected data models
- Assessed backward compatibility
- Marked handling methods for breaking changes
- Generated change records
- Marked associated requirements (F-XXX / INS-XXX) for new content
输出文件
Output Files
主文件：
docs/devdocs/02-system-design.mdMain File:
docs/devdocs/02-system-design.md文档拆分规则
Document Splitting Rules
当满足以下条件时，应拆分文档：
- 文档超过 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。
Split the document when any of the following conditions are met:
- Document exceeds 300 lines
- Number of modules exceeds 5
- Number of API interfaces exceeds 10
Splitting Method:
docs/devdocs/
├── 02-system-design.md # Main document: Architecture overview, tech selection, module division
├── 02-system-design-api.md # API Design: Interface definitions, request/response examples
└── 02-system-design-data.md # Data Model: Entity definitions, ER diagrams, indexing strategiesSplitting Content Allocation:
| File | Included Chapters |
|---|---|
| 02-system-design.md | 1-7: Platform, architecture, tech selection, modules, interface signatures, patterns, code structure |
| 02-system-design-api.md | 9-10: Complete API design, state transitions |
| 02-system-design-data.md | 8, 11-13: Data models, exception handling, extensibility, requirement traceability |
Refer to templates/design-template.md for detailed templates.
设计原则
Design Principles
MTE 原则
MTE Principles
系统设计必须遵循 MTE 原则：
| 原则 | 说明 | 检查点 |
|---|---|---|
| Maintainability | 可维护性 | 模块职责单一、依赖清晰、易于理解和修改 |
| Testability | 可测试性 | 核心逻辑可单元测试、依赖可 Mock、边界清晰（参考 |
| Extensibility | 可扩展性 | 预留扩展点、接口抽象、开闭原则 |
System design must follow the MTE Principles:
| Principle | Description | Checkpoint |
|---|---|---|
| Maintainability | Maintainability | Single responsibility for modules, clear dependencies, easy to understand and modify |
| Testability | Testability | Core logic can be unit tested, dependencies can be Mocked, clear boundaries (refer to |
| Extensibility | Extensibility | Reserved extension points, interface abstraction, open/closed principle |
设计模式选择
Design Pattern Selection
根据场景选择合适的设计模式，只在必要时使用：
| 场景 | 推荐模式 | 适用情况 |
|---|---|---|
| 对象创建 | Factory / Builder | 复杂对象构建、多种类型创建 |
| 行为扩展 | Strategy / Template | 算法可替换、流程固定步骤可变 |
| 结构组织 | Facade / Adapter | 简化复杂接口、适配第三方库 |
| 状态管理 | State / Observer | 状态驱动行为、事件通知 |
| 数据访问 | Repository / DAO | 数据层抽象、查询封装 |
Select appropriate design patterns based on scenarios, only use when necessary:
| Scenario | Recommended Pattern | Applicable Situation |
|---|---|---|
| Object Creation | Factory / Builder | Complex object construction, multiple type creation |
| Behavior Extension | Strategy / Template | Replaceable algorithms, fixed process with variable steps |
| Structure Organization | Facade / Adapter | Simplify complex interfaces, adapt third-party libraries |
| State Management | State / Observer | State-driven behavior, event notification |
| Data Access | Repository / DAO | Data layer abstraction, query encapsulation |
设计层次
Design Layers
┌─────────────────────────────────────┐
│ 接口层 │ ← API/Controller（薄层，无业务逻辑）
├─────────────────────────────────────┤
│ 服务层 │ ← 业务逻辑（核心，可测试）
├─────────────────────────────────────┤
│ 领域层 │ ← 领域模型（实体、值对象）
├─────────────────────────────────────┤
│ 基础设施层 │ ← 数据访问、外部服务（可替换）
└─────────────────────────────────────┘┌─────────────────────────────────────┐
│ Interface Layer │ ← API/Controller (thin layer, no business logic)
├─────────────────────────────────────┤
│ Service Layer │ ← Business logic (core, testable)
├─────────────────────────────────────┤
│ Domain Layer │ ← Domain models (entities, value objects)
├─────────────────────────────────────┤
│ Infrastructure Layer │ ← Data access, external services (replaceable)
└─────────────────────────────────────┘文档结构
Document Structure
- 目标平台 - 平台、版本要求、部署环境
- 架构概览 - 高层架构图（Mermaid）
- 技术选型 - 技术选择及理由
- 模块设计 - 模块职责与依赖，标注关联功能点 (F-XXX)
- 核心接口 - 面向接口 (仅签名): 关键接口和方法签名（严禁包含具体实现逻辑），标注关联 F-XXX
- 设计模式 - 应用的模式及理由
- 代码结构 - 目录结构设计
- 数据模型 - 实体定义与关系
- API 设计 - 接口端点及请求/响应示例，标注关联 F-XXX, AC-XXX
- 状态流转 - 关键业务流程的状态机
- 异常处理 - 错误码与处理策略
- 日志设计 - 日志级别、关键日志点、追溯 ID
- 扩展性 - 扩展点与未来考量
- 需求追溯 - 功能点与模块/接口的映射关系，覆盖检查清单
- Target Platform - Platform, version requirements, deployment environment
- Architecture Overview - High-level architecture diagram (Mermaid)
- Tech Selection - Tech choices and reasons
- Module Design - Module responsibilities and dependencies, mark associated feature points (F-XXX)
- Core Interfaces - Interface-oriented (only signatures): Key interfaces and method signatures (strictly no implementation logic), mark associated F-XXX
- Design Patterns - Applied patterns and reasons
- Code Structure - Directory structure design
- Data Model - Entity definitions and relationships
- API Design - Interface endpoints and request/response examples, mark associated F-XXX, AC-XXX
- State Transitions - State machines for key business processes
- Exception Handling - Error codes and handling strategies
- Log Design - Log levels, key log points, trace ID
- Extensibility - Extension points and future considerations
- Requirement Traceability - Mapping between feature points and modules/interfaces, coverage checklist
核心接口设计
Core Interface Design
设计文档中应体现核心接口定义（只定义签名，不写实现），并标注关联功能点：
markdown
undefinedCore interface definitions should be reflected in the design document (only define signatures, no implementation), and mark associated feature points:
markdown
undefined核心接口
Core Interfaces
IUserService（关联：F-001 用户注册, F-002 用户登录）
IUserService (Associated: F-001 User Registration, F-002 User Login)
| 方法 | 参数 | 返回值 | 关联 | 说明 |
|---|---|---|---|---|
| | | F-001, AC-001 | 创建用户 |
| | | F-001, AC-002 | 验证邮箱 |
| | | F-002, AC-006 | 用户登录 |
| Method | Parameter | Return Value | Associated | Description |
|---|---|---|---|---|
| | | F-001, AC-001 | Create user |
| | | F-001, AC-002 | Validate email |
| | | F-002, AC-006 | User login |
IUserRepository
IUserRepository
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| | | 保存用户 |
| | | 根据ID查询 |
| | | 根据邮箱查询 |
undefined| Method | Parameter | Return Value | Description |
|---|---|---|---|
| | | Save user |
| | | Query by ID |
| | | Query by email |
undefined代码结构设计
Code Structure Design
markdown
undefinedmarkdown
undefined目录结构
Directory Structure
src/
├── api/ # 接口层
│ ├── controllers/ # 控制器（路由处理）
│ ├── middlewares/ # 中间件（认证、日志等）
│ └── validators/ # 请求验证
├── services/ # 服务层
│ ├── interfaces/ # 服务接口定义
│ └── impl/ # 服务实现
├── domain/ # 领域层
│ ├── entities/ # 实体
│ ├── value-objects/ # 值对象
│ └── events/ # 领域事件
├── infrastructure/ # 基础设施层
│ ├── repositories/ # 数据仓储实现
│ ├── external/ # 外部服务适配
│ └── config/ # 配置
└── shared/ # 共享
├── types/ # 类型定义
├── utils/ # 工具函数
└── constants/ # 常量
undefinedsrc/
├── api/ # Interface layer
│ ├── controllers/ # Controllers (route handling)
│ ├── middlewares/ # Middlewares (authentication, logging, etc.)
│ └── validators/ # Request validation
├── services/ # Service layer
│ ├── interfaces/ # Service interface definitions
│ └── impl/ # Service implementations
├── domain/ # Domain layer
│ ├── entities/ # Entities
│ ├── value-objects/ # Value objects
│ └── events/ # Domain events
├── infrastructure/ # Infrastructure layer
│ ├── repositories/ # Data repository implementations
│ ├── external/ # External service adapters
│ └── config/ # Configuration
└── shared/ # Shared
├── types/ # Type definitions
├── utils/ # Utility functions
└── constants/ # Constants
undefined日志设计
Log Design
日志是调试和问题排查的关键工具，特别是对于手动测试和 E2E 测试场景。
Logs are critical tools for debugging and troubleshooting, especially for manual testing and E2E testing scenarios.
日志级别
Log Levels
| 级别 | 用途 | 示例场景 |
|---|---|---|
| ERROR | 需要立即处理的错误 | 数据库连接失败、支付失败、关键服务不可用 |
| WARN | 潜在问题但不影响核心功能 | 重试成功、降级处理、资源接近阈值 |
| INFO | 关键业务操作 | 用户登录、订单创建、状态变更 |
| DEBUG | 调试信息 | 函数入参、中间状态、性能指标 |
| Level | Purpose | Example Scenario |
|---|---|---|
| ERROR | Errors requiring immediate handling | Database connection failure, payment failure, critical service unavailability |
| WARN | Potential issues that do not affect core functions | Retry success, degradation handling, resource approaching threshold |
| INFO | Key business operations | User login, order creation, state change |
| DEBUG | Debug information | Function input parameters, intermediate states, performance metrics |
关键日志点
Key Log Points
设计文档中应列出关键操作的日志点：
markdown
| 操作 | 日志级别 | 日志内容 | 关联编号 |
|------|----------|----------|----------|
| 用户登录成功 | 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 |Key operation log points should be listed in the design document:
markdown
| Operation | Log Level | Log Content | Associated ID |
|------|----------|----------|----------|
| User login success | INFO | `[F-002] User login: userId={}, ip={}` | F-002, AC-006 |
| User login failure | WARN | `[F-002] Login failed: userId={}, reason={}` | F-002, AC-007 |
| Password verification failure | WARN | `[F-002] Password mismatch: userId={}` | AC-007 |
| Database exception | ERROR | `[INFRA] DB error: {}, query={}` | - |
| Order creation | INFO | `[F-003] Order created: orderId={}, userId={}` | F-003 |日志格式
Log Format
[时间] [级别] [追溯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"}[Timestamp] [Level] [Trace ID] [Module] Message {Structured Data}Example:
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)
Trace ID (Correlation ID)
| 属性 | 说明 |
|---|---|
| 生成时机 | 每个请求入口生成唯一 ID |
| 传递方式 | 通过 Context/Header 贯穿整个调用链 |
| 命名约定 | |
| 格式 | UUID 或 |
用途：
- E2E 测试失败时，通过 查询完整日志链
traceId - 分布式系统中跨服务追踪
- 问题排查时关联所有相关日志
| Attribute | Description |
|---|---|
| Generation Timing | Generate a unique ID at each request entry |
| Transmission Method | Pass through the entire call chain via Context/Header |
| Naming Convention | |
| Format | UUID or |
Purposes:
- Query the complete log chain via when E2E tests fail
traceId - Cross-service tracing in distributed systems
- Correlate all relevant logs during troubleshooting
E2E 测试日志策略
E2E Test Log Strategy
| 场景 | 日志策略 | 说明 |
|---|---|---|
| 测试通过 | 仅保留 ERROR/WARN | 减少日志量 |
| 测试失败 | 保留完整日志（含 DEBUG） | 便于排查 |
| 手动复现 | 启用 DEBUG 级别 | 最大化信息 |
失败分析流程：
1. 获取失败测试的 traceId
│
▼
2. 查询该 traceId 的完整日志链
│
▼
3. 定位首个 ERROR/异常点
│
▼
4. 分析上下文日志| Scenario | Log Strategy | Description |
|---|---|---|
| Test passed | Only retain ERROR/WARN logs | Reduce log volume |
| Test failed | Retain complete logs (including DEBUG) | Facilitate troubleshooting |
| Manual reproduction | Enable DEBUG level | Maximize information |
Failure Analysis Process:
1. Obtain the traceId of the failed test
│
▼
2. Query the complete log chain for this traceId
│
▼
3. Locate the first ERROR/exception point
│
▼
4. Analyze contextual logs日志设计约束
Log Design Constraints
- 关键业务操作必须有 INFO 级别日志
- 错误必须有 ERROR 级别日志，包含上下文
- 日志必须包含追溯 ID
- 日志必须标注关联的功能点编号
- 敏感信息（密码、Token）不得出现在日志中
- 日志格式必须支持结构化解析
- Key business operations must have INFO-level logs
- Errors must have ERROR-level logs with context
- Logs must include trace ID
- Logs must mark associated feature point IDs
- Sensitive information (passwords, tokens) must not appear in logs
- Log format must support structured parsing
约束
Constraints
基础约束
Basic Constraints
- 必须先询问用户技术栈偏好和目标平台
- 技术选型必须说明理由
- 如用户无偏好，根据需求选择最优方案
- 必须指定目标平台和最低版本要求
- API 设计必须包含请求/响应示例
- 数据模型必须考虑索引和查询模式
- 必须识别与现有系统的集成点
- 优先使用项目现有技术栈
- Must first ask the user about tech stack preferences and target platform
- Tech selection must explain reasons
- If the user has no preference, select the optimal solution based on requirements
- Must specify target platform and minimum version requirements
- API design must include request/response examples
- Data models must consider indexing and query patterns
- Must identify integration points with existing systems
- Prioritize using the project's existing tech stack
MTE 原则约束
MTE Principle Constraints
- 每个模块职责单一，不超过一个变化原因
- 核心业务逻辑必须可单元测试（无外部依赖或依赖可 Mock，详见 ）
/testing-guide - 预留合理扩展点，但不为假设需求设计
- 依赖方向：外层依赖内层，内层不依赖外层
- 接口优于实现：依赖抽象，不依赖具体实现
- Each module has a single responsibility, no more than one reason for change
- Core business logic must be unit testable (no external dependencies or dependencies can be Mocked, see for details)
/testing-guide - Reserve reasonable extension points, but do not design for hypothetical requirements
- Dependency direction: Outer layers depend on inner layers, inner layers do not depend on outer layers
- Interfaces are preferred over implementations: Depend on abstractions, not concrete implementations
设计模式约束
Design Pattern Constraints
- 只在解决实际问题时使用设计模式，不为使用而使用
- 使用的设计模式必须说明解决什么问题
- 优先选择简单方案，复杂方案需要说明理由
- 相同问题在项目中使用一致的模式
- Only use design patterns to solve actual problems, not for the sake of using them
- Design patterns used must explain the problem they solve
- Prioritize simple solutions, complex solutions need to explain reasons
- Use consistent patterns for the same problem in the project
避免过度设计
Avoid Over-Design
- 不为"未来可能"的需求设计，只为当前需求设计
- 不创建只有一个实现的接口（除非为了可测试性）
- 不过早抽象，等到有 3 个以上相似场景再抽象
- 配置优于硬编码，但不为所有内容添加配置
- Do not design for "possible future" requirements, only for current requirements
- Do not create interfaces with only one implementation (unless for testability)
- Do not abstract too early, wait until there are 3 or more similar scenarios before abstracting
- Configuration is preferred over hardcoding, but do not add configuration for everything
安全约束
Security Constraints
- 敏感数据（密码、Token）不明文存储
- 需要认证的 API 已标注
- 用户输入有验证（防注入）
- 敏感操作有日志记录
- Sensitive data (passwords, tokens) must not be stored in plaintext
- APIs requiring authentication must be marked
- User input must be validated (injection prevention)
- Sensitive operations must have log records
增量设计约束
Incremental Design Constraints
- 增量设计前必须进行影响分析
- 必须评估向后兼容性
- 破坏性变更必须标注处理方式
- 必须生成设计变更记录
- 新增内容必须标注关联需求（F-XXX / INS-XXX）
- 修改现有接口必须说明兼容性
- 数据模型变更必须说明迁移方案
- Impact analysis must be performed before incremental design
- Backward compatibility must be evaluated
- Breaking changes must be marked with handling methods
- Design change records must be generated
- New content must mark associated requirements (F-XXX / INS-XXX)
- Modifications to existing interfaces must explain compatibility
- Data model changes must explain migration plans
Skill 协作
Skill Collaboration
| 场景 | 协作 Skill | 说明 |
|---|---|---|
| 新功能设计变更 | | 新功能触发增量设计 |
| 优化建议设计变更 | | 洞察确认后触发增量设计 |
| 可测试性设计 | | 确保核心逻辑可单元测试 |
| 代码质量 | | MTE 原则指导设计 |
| UI 架构 | | 路由到专业的外部 UI/UX Skill |
| 接口自动提取 | | 从现有代码逆向提取接口定义并同步到设计文档 |
| Scenario | Collaboration Skill | Description |
|---|---|---|
| New feature design change | | New features trigger incremental design |
| Optimization suggestion design change | | Incremental design is triggered after insights are confirmed |
| Testability design | | Ensure core logic is unit testable |
| Code quality | | Guide design with MTE principles |
| UI architecture | | Route to professional external UI/UX Skill |
| Automatic interface extraction | | Reverse extract interface definitions from existing code and sync to design documents |
下一步
Next Steps
初始设计后
After Initial Design
用户确认系统设计后，建议运行 进入测试用例设计阶段。
/devdocs-test-casesAfter the user confirms the system design, it is recommended to run to enter the test case design phase.
/devdocs-test-cases增量设计后
After Incremental Design
- 如有新增功能点 → 运行 补充测试用例
/devdocs-test-cases - 如有数据模型变更 → 准备数据库迁移脚本
- 如有破坏性变更 → 通知相关依赖方
- If there are new feature points → Run to supplement test cases
/devdocs-test-cases - If there are data model changes → Prepare database migration scripts
- If there are breaking changes → Notify relevant dependent parties