sdd-full 4.2.0 → 4.3.0

package/skills/design-planning/sdd-code/SKILL.md

@@ -0,0 +1,347 @@
+【claude code调用标识：sdd-code】【trae调用标识：sdd-code+功能实现SDD拆分】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目、3.小型功能迭代、4.Bug处理】
+
+---
+name: "sdd-code"
+description: "功能实现逻辑SDD拆分，将用户故事拆分为独立可交付的功能实现SDD，按语言架构特性适配。Invoke when needing to split user stories into implementation-level SDDs after basic SDD split."
+---
+
+# 功能实现逻辑SDD拆分技能
+
+本技能定义「功能实现逻辑SDD拆分」为独立技能，核心解决「功能实现逻辑如何拆分、拆分多少个SDD、不同场景下如何适配」的核心问题，可直接嵌入原有开发流程。
+
+## 核心原则
+
+**1个最小可独立实现的功能逻辑单元 = 1个SDD**，拆分数量由「功能复杂度、代码耦合度、语言架构特性、项目用途」四大维度决定。
+
+---
+
+# 一、通用基础拆分规则
+
+## 1.1 核心拆分原则
+
+- **独立可交付**：每个SDD对应1个最小可独立实现的功能逻辑单元，可单独开发、测试、交付。
+- **低耦合高内聚**：SDD内部逻辑闭环，仅聚焦自身核心功能。
+- **粒度适配场景**：拆分粒度需贴合项目语言、架构、用途。
+- **逻辑闭环完整**：每个SDD需覆盖「正常流程+关键异常流程」。
+- **衔接原有流程**：需严格关联基础SDD拆分产出的用户故事、UI设计、接口契约。
+
+## 1.2 拆分数量判定核心公式
+
+```
+拆分数量 = 核心功能逻辑单元数 + 异常处理逻辑单元数（可选） - 可合并逻辑单元数
+```
+
+## 1.3 禁止拆分与必须拆分场景
+
+### 1.3.1 禁止拆分场景
+- 单一简单操作（如按钮点击事件）
+- 高度耦合的逻辑（如「数据查询+数据渲染」）
+- 重复逻辑（如多个SDD共用的工具函数）
+
+### 1.3.2 必须拆分场景
+- 多分支业务逻辑（如订单支付的多种支付方式）
+- 跨模块依赖逻辑（如「用户登录验证」）
+- 复杂异常处理（如数据入库的多类异常）
+- 前后端分离场景中，前端渲染、前端交互、后端接口实现、后端业务逻辑
+
+---
+
+# 二、按项目语言架构拆分细则
+
+## 2.1 纯前端项目（Vue/React/Angular等）
+
+核心拆分维度：页面渲染 → 交互逻辑 → 数据请求/处理 → 公共逻辑
+
+- **简单页面**：拆分2-3个SDD
+  - 页面渲染逻辑SDD
+  - 核心交互逻辑SDD
+  - 数据请求逻辑SDD（可选）
+
+- **复杂页面**：拆分3-5个SDD
+  - 在简单页面基础上，新增表单校验逻辑SDD、异常提示逻辑SDD
+  - 若有独立组件，可新增组件渲染与交互SDD
+
+## 2.2 纯后端项目（Java/Node.js/Go等）
+
+核心拆分维度：接口实现 → 业务逻辑 → 数据访问 → 公共逻辑
+
+- **简单接口**：拆分2个SDD
+  - 接口实现逻辑SDD
+  - 数据访问逻辑SDD
+
+- **复杂接口**：拆分3-4个SDD
+  - 接口实现逻辑SDD
+  - 业务逻辑SDD
+  - 数据访问逻辑SDD
+  - 异常处理逻辑SDD
+
+## 2.3 Flutter项目（MVVM架构为主）
+
+核心拆分维度：UI渲染（Widget）→ 交互逻辑 → 状态管理 → 数据请求/处理 → 公共逻辑
+
+- **简单页面/组件**：拆分2-3个SDD
+  - UI渲染逻辑SDD
+  - 核心交互逻辑SDD
+  - 数据请求逻辑SDD（可选）
+
+- **复杂页面/组件**：拆分3-5个SDD
+  - 在简单页面基础上，新增状态管理逻辑SDD、异常处理逻辑SDD
+  - 涉及元素渲染特殊处理的场景，可新增渲染辅助逻辑SDD
+
+---
+
+# 三、代码规范与技术债务管理
+
+## 3.1 代码规范要求
+
+### 3.1.1 通用编码规范
+- **命名规范**
+  - 类名：大驼峰（PascalCase），如 `UserService`
+  - 函数名：小驼峰（camelCase），如 `getUserInfo`
+  - 变量名：小驼峰（camelCase），如 `userName`
+  - 常量名：全大写下划线分隔（UPPER_SNAKE_CASE），如 `MAX_RETRY_COUNT`
+  - 文件名：语义化命名，如 `user_service.dart`
+
+- **注释规范**
+  - 公共API必须有文档注释
+  - 复杂逻辑必须有注释说明思路
+  - 注释不要重复代码本身的意思
+  - TODO/FIXME必须有注释说明原因和计划
+
+- **代码风格**
+  - 统一使用项目约定的格式化工具
+  - 缩进统一（2空格或4空格，保持一致）
+  - 避免过长的函数（建议不超过50行）
+  - 单一职责原则，一个函数只做一件事
+
+### 3.1.2 语言特定规范
+- **Flutter/Dart**
+  - 遵循官方Dart风格指南
+  - 优先使用const常量
+  - 合理使用async/await
+  - Widget拆分合理，避免过于庞大
+
+- **Web前端**
+  - 组件化设计
+  - 状态管理合理
+  - 组件Props类型定义完整
+
+- **后端**
+  - 分层架构清晰
+  - 接口设计RESTful
+  - 错误处理统一
+
+## 3.2 技术债务管理
+
+### 3.2.1 技术债务识别
+技术债务主要来源：
+- 快速迭代时的临时方案
+- 技术栈演进，旧代码未及时更新
+- 性能瓶颈暂时未优化
+- 安全隐患暂时未修复
+- 代码可读性较差的部分
+
+### 3.2.2 技术债务记录模板
+
+```markdown
+# 技术债务记录
+
+## 基本信息
+- **债务ID**：TD-001
+- **模块**：用户认证模块
+- **优先级**：P1
+- **识别日期**：2024-05-04
+
+## 问题描述
+- **问题类型**：代码质量/性能/安全/可维护性
+- **具体问题**：密码使用MD5加密，不安全
+- **影响范围**：用户账户安全
+- **当前状态**：未修复/修复中/已修复
+
+## 技术细节
+- **问题代码位置**：lib/auth/password.dart:23-28
+- **当前实现**：使用MD5加密密码
+- **建议方案**：升级为bcrypt或Argon2加密
+
+## 修复计划
+- **预计工作量**：1天
+- **计划修复时间**：2024-05-15前
+- **风险评估**：低/中/高
+- **回滚方案**：如有问题，可回滚到MD5（临时方案）
+
+## 关联信息
+- **关联SDD**：skill-sdd-story1-login-backend-api.md
+- **关联测试**：test/password_encryption_test.dart
+- **备注**：安全审计建议修复
+
+## 更新记录
+| 日期 | 更新内容 | 更新人 |
+|------|---------|-------|
+|      |         |       |
+```
+
+### 3.2.3 技术债务管理规范
+- **优先级定义**
+  - P0：严重问题，必须立即修复
+  - P1：重要问题，近期修复
+  - P2：一般问题，计划修复
+  - P3：轻微问题，有空修复
+
+- **管理流程**
+  - 识别技术债务 → 记录到技术债务清单 → 评估优先级 → 计划修复 → 修复验证 → 关闭债务
+  - 每个迭代预留10-20%时间偿还技术债务
+  - 定期回顾技术债务清单，调整优先级
+
+## 3.3 重构计划
+
+### 3.3.1 重构触发条件
+- 代码难以理解和维护
+- 频繁出现bug
+- 性能不满足要求
+- 技术栈更新需要适配
+- 功能扩展困难
+
+### 3.3.2 重构计划模板
+
+```markdown
+# 重构计划
+
+## 基本信息
+- **重构ID**：REF-001
+- **模块**：订单处理模块
+- **发起日期**：2024-05-04
+- **优先级**：P1
+
+## 重构原因
+- **现状问题**：当前代码耦合度高，难以维护和测试
+- **业务影响**：新功能开发效率低，bug修复周期长
+- **重构目标**：提高代码可维护性，降低耦合度
+
+## 重构范围
+- **涉及文件**：lib/order/order_service.dart, lib/order/order_repository.dart
+- **涉及功能**：订单创建、订单状态更新、订单查询
+- **不涉及内容**：支付模块、用户模块
+
+## 重构方案
+- **重构策略**：增量重构/完全重写
+- **技术方案**：
+  1. 拆分OrderService为多个职责单一的类
+  2. 引入Repository模式，分离数据访问逻辑
+  3. 添加单元测试，提高测试覆盖率
+
+- **依赖关系**：
+  - 前置依赖：无
+  - 后置影响：需同步更新相关测试
+
+## 时间计划
+- **准备阶段**：2024-05-06 分析现有代码
+- **重构阶段**：2024-05-07 到 2024-05-10
+- **测试阶段**：2024-05-11 到 2024-05-12
+- **上线阶段**：2024-05-13
+
+## 风险评估
+- **技术风险**：中/高
+- **风险预案**：准备回滚方案，灰度发布
+- **测试重点**：功能完整性、性能不下降
+
+## 验收标准
+- 代码可维护性提升
+- 测试覆盖率达到80%以上
+- 功能保持完整，无新增bug
+- 性能不低于重构前
+
+## 回滚方案
+- **回滚条件**：出现严重bug，性能明显下降
+- **回滚步骤**：
+  1. 停止新功能的开发
+  2. 从Git回滚代码
+  3. 验证回滚后的功能
+  4. 重新发布
+
+## 备注
+- 重构过程中，保持小步提交，便于回滚
+- 每完成一个小重构，立即验证功能
+```
+
+### 3.3.3 重构最佳实践
+- **增量重构**：尽量避免大规模重写，采用小步迭代方式
+- **测试先行**：重构前确保有充分的测试覆盖
+- **保持功能**：重构过程中保持功能不变
+- **频繁验证**：每一步重构后立即验证
+- **记录过程**：记录重构的原因、过程、结果
+
+---
+
+# 四、SDD拆分落地流程
+
+## 4.1 拆分前置条件
+
+1. 已完成基础SDD拆分（Epic→Feature→用户故事）
+2. 已完成UI设计、前后端架构拆分、数据库+接口拆分
+3. 明确项目语言、架构、用途
+
+## 4.2 拆分步骤（6步落地）
+
+1. **梳理逻辑单元**：拆解每个用户故事对应的核心功能逻辑单元
+2. **判定拆分数量**：结合项目语言、架构、用途，判定需拆分的SDD数量
+3. **拆分SDD**：为每个功能逻辑单元分配独立SDD，明确核心范围、验收标准
+4. **补充技术债务**：识别当前实现中的技术债务，记录到债务清单
+5. **规划重构计划**：如需要重构，制定重构计划
+6. **规范命名与存放**：按命名、目录规范，为每个SDD命名并放入对应目录
+7. **自检优化**：按校验标准，自检SDD拆分合理性
+
+---
+
+# 五、输出文件结构
+
+## 5.1 SDD目录结构
+
+```
+项目根/
+├── docs/
+│   └── tech-debt/       # 技术债务记录
+│       ├── td-001.md
+│       └── td-list.md
+└── specs/
+    ├── function-implementation-sdd/
+    │   ├── story1-login/
+    │   │   ├── skill-sdd-story1-login-frontend-render.md
+    │   │   ├── skill-sdd-story1-login-frontend-interact.md
+    │   │   └── skill-sdd-story1-login-backend-api.md
+    │   └── common/
+    └── refactor-plans/  # 重构计划
+        └── ref-001.md
+```
+
+---
+
+# 六、拆分合理性校验标准
+
+## 6.1 核心校验项（必过项）
+
+- 独立可交付：每个SDD可单独开发、测试、交付
+- 逻辑闭环：每个SDD覆盖正常流程+关键异常流程
+- 粒度适配：无过度拆分、无拆分不足
+- 技能衔接：与基础SDD拆分产出的用户故事、接口契约严格衔接
+- 规范适配：SDD命名、目录符合规范要求
+- 代码规范：SDD中明确代码规范要求
+- 债务管理：技术债务已识别并记录
+- 重构计划：如需重构，计划已制定
+
+---
+
+# 七、与其他技能的衔接
+
+## 7.1 前置技能
+- **sdd**：基础SDD拆分，输出用户故事、UI设计、接口契约
+- **ui-sdd**：UI交互SDD，如需要
+
+## 7.2 后置技能
+- **sdd-test**：测试SDD拆分
+- **sdd-add**：快速迭代补充（如需要）
+- **子代理开发**：执行SDD开发
+
+## 7.3 流程关系
+```
+sdd → ui-sdd → sdd-code → sdd-test → 开发
+```