sdd-full 1.0.0 → 1.2.0

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: test-driven-development
+description: 在编写实现代码之前，实现任何功能或错误修复时使用
+---
+
+# 测试驱动开发 (TDD)
+
+## 概述
+
+先写测试。看着它失败。编写最小代码使其通过。
+
+**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 何时使用
+
+**始终：**
+- 新功能
+- 错误修复
+- 重构
+- 行为变更
+
+**例外（询问你的人类伙伴）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想“就这一次跳过 TDD”？停止。那是合理化。
+
+## 铁律
+
+```
+没有先失败的测试，就没有生产代码
+```
+
+在测试之前写代码？删除它。重新开始。
+
+**没有例外：**
+- 不要将其作为“参考”保留
+- 不要在编写测试时“适应”它
+- 不要看它
+- 删除意味着删除
+
+从测试中重新实现。就这样。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="验证失败\n正确", shape=diamond];
+    green [label="GREEN\n最小代码", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="验证通过\n全部绿色", shape=diamond];
+    refactor [label="REFACTOR\n清理", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="下一个", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="是"];
+    verify_red -> red [label="错误\n失败"];
+    green -> verify_green;
+    verify_green -> refactor [label="是"];
+    verify_green -> green [label="否"];
+    refactor -> verify_green [label="保持\n绿色"];
+    verify_green -> next;
+    next -> red;
+}
+```
+
+### 红 - 编写失败的测试
+
+编写一个最小测试，显示应该发生什么。
+
+<Good>
+```typescript
+test('重试失败操作 3 次', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+```
+名称清晰，测试真实行为，一个测试一个行为
+</Good>
+
+<Bad>
+```typescript
+test('重试有效', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+名称模糊，测试模拟而非代码
+</Bad>
+
+**要求：**
+- 一个行为
+- 清晰的名称
+- 真实代码（除非不可避免，否则不要使用模拟）
+
+### 验证红 - 看着它失败
+
+**必须执行。永远不要跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试失败（不是错误）
+- 失败消息符合预期
+- 失败是因为功能缺失（不是拼写错误）
+
+**测试通过？** 你在测试现有行为。修复测试。
+
+**测试错误？** 修复错误，重新运行直到正确失败。
+
+### 绿 - 最小代码
+
+编写最简单的代码以通过测试。
+
+<Good>
+```typescript
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+刚好足够通过
+</Good>
+
+<Bad>
+```typescript
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI
+}
+```
+过度设计
+</Bad>
+
+不要添加功能、重构其他代码或超出测试范围的“改进”。
+
+### 验证绿 - 看着它通过
+
+**必须执行。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出纯净（无错误、警告）
+
+**测试失败？** 修复代码，不是测试。
+
+**其他测试失败？** 立即修复。
+
+### 重构 - 清理
+
+仅在绿色之后：
+- 移除重复
+- 改进名称
+- 提取辅助函数
+
+保持测试绿色。不要添加行为。
+
+### 重复
+
+下一个失败的测试用于下一个功能。
+
+## 好的测试
+
+| 质量 | 好 | 坏 |
+|------|----|----|
+| **最小** | 一个行为。名称中有 "and"？拆分它。 | `test('validates email and domain and whitespace')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 演示期望的 API | 掩盖代码应该做什么 |
+
+## 为什么顺序很重要
+
+**"我会在之后写测试来验证它有效"**
+
+在代码之后写的测试立即通过。立即通过证明不了什么：
+- 可能测试错误的东西
+- 可能测试实现，而不是行为
+- 可能遗漏你忘记的边缘情况
+- 你从未看到它捕获错误
+
+测试优先迫使你看到测试失败，证明它实际上测试了某些东西。
+
+**"我已经手动测试了所有边缘情况"**
+
+手动测试是临时的。你认为你测试了一切，但：
+- 没有记录你测试了什么
+- 代码更改时无法重新运行
+- 在压力下容易忘记情况
+- "我尝试时它有效" ≠ 全面
+
+自动化测试是系统的。它们每次都以相同的方式运行。
+
+**"删除 X 小时的工作是浪费的"**
+
+沉没成本谬误。时间已经过去了。你现在的选择：
+- 删除并重写 TDD（再 X 小时，高信心）
+- 保留它并在之后添加测试（30 分钟，低信心，可能有错误）
+
+"浪费"是保留你不能信任的代码。没有真实测试的工作代码是技术债务。
+
+**"TDD 是教条的，务实意味着适应"**
+
+TDD 就是务实：
+- 在提交前发现错误（比之后调试更快）
+- 防止回归（测试立即捕获中断）
+- 记录行为（测试展示如何使用代码）
+- 启用重构（自由更改，测试捕获中断）
+
+"务实"的捷径 = 在生产中调试 = 更慢。
+
+**"测试之后达到相同的目标 - 这是精神不是仪式"**
+
+不。测试之后回答"这做什么？"。测试之前回答"这应该做什么？"。
+
+测试之后被你的实现所偏见。你测试你构建的东西，而不是需要的东西。你验证记住的边缘情况，而不是发现的边缘情况。
+
+测试之前迫使在实现之前发现边缘情况。测试之后验证你记住了一切（你没有）。
+
+30 分钟的测试之后 ≠ TDD。你获得覆盖率，失去测试工作的证明。
+
+## 常见的合理化
+
+| 借口 | 现实 |
+|------|------|
+| "太简单了，不需要测试" | 简单代码会中断。测试需要 30 秒。 |
+| "我会之后测试" | 立即通过的测试证明不了什么。 |
+| "测试之后达到相同的目标" | 测试之后 = "这做什么？" 测试之前 = "这应该做什么？" |
+| "已经手动测试过了" | 临时 ≠ 系统。无记录，无法重新运行。 |
+| "删除 X 小时是浪费的" | 沉没成本谬误。保留未验证的代码是技术债务。 |
+| "保留作为参考，先写测试" | 你会适应它。那是测试之后。删除意味着删除。 |
+| "需要先探索" | 很好。扔掉探索，从 TDD 开始。 |
+| "测试难 = 设计不清" | 听测试的。难测试 = 难使用。 |
+| "TDD 会减慢我" | TDD 比调试快。务实 = 测试优先。 |
+| "手动测试更快" | 手动不能证明边缘情况。你会重新测试每个更改。 |
+| "现有代码没有测试" | 你正在改进它。为现有代码添加测试。 |
+
+## 红旗 - 停止并重新开始
+
+- 测试之前的代码
+- 实现之后的测试
+- 测试立即通过
+- 无法解释测试为什么失败
+- "稍后"添加的测试
+- 合理化"就这一次"
+- "我已经手动测试过了"
+- "测试之后达到相同的目的"
+- "这是精神不是仪式"
+- "保留作为参考"或"适应现有代码"
+- "已经花了 X 小时，删除是浪费的"
+- "TDD 是教条的，我在务实"
+- "这不同因为..."
+
+**所有这些都意味着：删除代码。用 TDD 重新开始。**
+
+## 示例：错误修复
+
+**错误：** 接受空电子邮件
+
+**红**
+```typescript
+test('拒绝空电子邮件', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**验证红**
+```bash
+$ npm test
+失败：期望 'Email required'，得到 undefined
+```
+
+**绿**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**验证绿**
+```bash
+$ npm test
+通过
+```
+
+**重构**
+如果需要，提取多个字段的验证。
+
+## 验证清单
+
+在标记工作完成之前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 每个测试在实现前都看到失败
+- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
+- [ ] 为每个测试编写最小代码以通过
+- [ ] 所有测试通过
+- [ ] 输出纯净（无错误、警告）
+- [ ] 测试使用真实代码（仅在不可避免时使用模拟）
+- [ ] 覆盖边缘情况和错误
+
+无法检查所有框？你跳过了 TDD。重新开始。
+
+## 卡住时
+
+| 问题 | 解决方案 |
+|------|----------|
+| 不知道如何测试 | 编写期望的 API。先编写断言。询问你的人类伙伴。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须模拟一切 | 代码耦合度太高。使用依赖注入。 |
+| 测试设置庞大 | 提取辅助函数。仍然复杂？简化设计。 |
+
+## 调试集成
+
+发现错误？编写重现错误的失败测试。遵循 TDD 循环。测试证明修复并防止回归。
+
+永远不要没有测试就修复错误。
+
+## 测试反模式
+
+添加模拟或测试实用程序时，阅读 @testing-anti-patterns.md 以避免常见陷阱：
+- 测试模拟行为而不是真实行为
+- 向生产类添加仅测试方法
+- 在不理解依赖关系的情况下模拟
+
+## 最终规则
+
+```
+生产代码 → 测试存在且首先失败
+否则 → 不是 TDD
+```
+
+未经你的人类伙伴许可，无例外。

package/skills/ui-sdd/SKILL.md

@@ -0,0 +1,290 @@
+
+# UI-SDD 完整整合版：App全域全景骨架 + 标准模板
+
+---
+
+## 第一部分：App全域全景骨架（项目启动第一步）
+
+### 核心定义
+**App全域全景骨架**：在写任何SDD、写任何代码前，先把整个App所有页面、弹窗、公共组件、全局隐性规则，梳理成一棵完整结构树。作用：定结构、定拆分、防遗漏。
+
+---
+
+### 具体5步流程（照着做！）
+
+#### 第1步：模拟用户完整走一遍App全流程
+从头到尾模拟真实用户操作，不思考设计、不写细节，只记录出现了哪些页面、哪些弹窗。
+
+**示例（地图导航App）**：
+```
+打开App → 启动页 → 首页（Tab）→ 搜索页 → 详情页 → 设置 → 退出
+            ↓
+         真实地图页
+            ↓
+         语音测试页
+```
+
+#### 第2步：逐一把看到的「页面、弹窗」全部罗列出来
+边走边记，看到什么写什么，不脑补、不省略。
+
+**示例（地图导航App）**：
+| 类型 | 名称 |
+|------|------|
+| 独立页面 | 启动页、首页、真实地图页、搜索页、语音测试页 |
+| 弹窗 | 确认弹窗、权限申请弹窗、语音识别中浮层 |
+| 反复出现组件 | 顶部导航栏、语音按钮、加载指示器、错误提示 |
+
+#### 第3步：分类归为三大类（固定分类）
+把罗列好的内容，强制分成3类：
+
+| 分类 | 说明 | 示例 |
+|------|------|------|
+| **业务页面（pages）** | 全屏独立页面，一页一个入口 | 启动页、首页、搜索页 |
+| **弹窗/浮层（dialog）** | 非全屏、弹出覆盖式 | 确认弹窗、权限弹窗 |
+| **全局公共组件（common）** | 多个页面复用的UI控件 | 导航栏、按钮、输入框 |
+
+#### 第4步：梳理「全局隐性规则」（最容易漏！）
+单独拉出一类，不属于页面也不属于组件，但是整个App都要遵守：
+
+| 规则分类 | 说明 | 示例 |
+|----------|------|------|
+| 全局配色/圆角/字体规范 | UI样式统一 | 主色调深海蓝、圆角统一8dp |
+| 平台适配 | iOS/Android差异 | iOS刘海安全区、Android物理返回 |
+| 页面路由/栈/返回逻辑 | 导航行为 | 返回保留页面栈、某些页面替换路由 |
+| 未登录拦截/登录态管理 | 用户状态 | 首次使用请求权限 |
+| 全局弱网/报错兜底 | 异常处理 | 网络不可用提示、加载失败重试 |
+| 全局键盘适配/防抖/权限流程 | 交互细节 | 键盘弹出布局调整、点击防抖 |
+
+#### 第5步：整理成「树形全景骨架结构」
+把上面三类，整理成树状层级：
+
+```
+App全域全景骨架
+├─ 启动流程页面
+│  ├─ 启动页（闪屏）
+│  └─ 隐私协议页（可选）
+├─ 主业务页面
+│  ├─ 首页
+│  ├─ 真实地图页
+│  ├─ 搜索页
+│  └─ 语音测试页
+├─ 全局弹窗/浮层
+│  ├─ 通用确认弹窗
+│  ├─ 权限申请弹窗
+│  └─ 语音识别浮层
+├─ 全局公共组件
+│  ├─ 顶部导航栏
+│  ├─ 语音按钮
+│  ├─ 加载指示器
+│  ├─ 错误提示
+│  └─ 确认弹窗
+└─ 全局隐性规则
+   ├─ 样式规范（颜色/字体/间距）
+   ├─ 平台适配（iOS/Android）
+   ├─ 路由逻辑（栈/返回）
+   ├─ 权限流程（定位/麦克风）
+   └─ 网络/键盘/防抖
+```
+
+---
+
+### 极简口诀（记住就会！）
+1. **模拟用户走全程**
+2. **所见全部罗列**
+3. **分成页面/弹窗/组件三类**
+4. **补上全局隐性规则**
+5. **整理成树形骨架**
+
+---
+
+### 画完骨架后马上能做什么？
+1. 直接按这个树，**建立SDD目录文件夹**
+2. 每个页面/弹窗/组件，对应新建SDD文档
+3. 对照骨架做「UI交互盘点清单」逐项打勾
+4. 保证后面所有SDD **100%全覆盖无遗漏**
+
+---
+
+## 第二部分：UI交互专用SDD标准模板
+
+### 何时使用
+- 需要为新页面、弹窗、复杂组件编写设计文档
+- 需要确保UI布局、交互、状态能1:1还原
+- 适用于Web、原生iOS、原生Android、Flutter项目
+- 需要替代原型设计，直接通过文档驱动开发
+
+---
+
+### 模板结构（完整11部分）
+
+#### 1. 基础信息
+| 字段 | 说明 |
+|------|------|
+| **归属平台** | Web / 原生iOS / 原生Android / Flutter |
+| **页面名称** | 页面的正式名称 |
+| **页面路由** | 路由地址（Web/Flutter）或页面标识 |
+| **关联用户故事** | 对应的用户故事ID或描述 |
+| **依赖接口/本地缓存** | 所需的数据接口或本地存储 |
+| **适配机型/系统版本** | 适配范围 |
+
+#### 2. 整体页面结构布局
+- 整体布局方式：固定布局 / 流式 / 弹性 / 卡片式
+- 页面整体分区（从上到下/从左到右）
+- 全局样式基准（统一约束）
+
+#### 3. 页面所有状态定义（必写！）
+必须逐条定义，不能只写正常状态：
+1. 默认初始态
+2. 加载中态（全局/局部）
+3. 空数据态
+4. 网络异常/接口报错态
+5. 表单禁用/按钮置灰态
+6. 操作成功反馈态
+7. 键盘弹出适配态（移动端必写）
+
+#### 4. 组件清单 & 静态UI描述
+逐个列出页面所有控件，每项写清楚：
+- 位置
+- 文案/占位符
+- 默认样式
+- 显隐条件
+
+#### 5. 逐组件交互逻辑（核心！）
+| 组件类型 | 需定义内容 |
+|----------|------------|
+| 输入类 | 输入规则、实时校验、清空按钮、键盘类型 |
+| 点击类 | 触发动作、防抖间隔、禁用条件、重复点击、点击反馈 |
+| 手势类 | 滑动、下拉刷新、长按、iOS右滑返回、Android物理返回 |
+
+#### 6. 弹窗、浮层、Toast交互规则
+- 触发条件
+- 弹出动画
+- 遮罩是否可点击关闭
+- 按钮确认/取消行为
+- 自动消失时长
+- 弹窗关闭后页面状态保留规则
+
+#### 7. 页面跳转 & 返回逻辑
+| 场景 | 路由 | 返回逻辑 | 保留页面栈 | 替换路由 |
+|------|------|----------|------------|----------|
+| 正向跳转 | | | | |
+| 返回上一页 | | | | |
+
+#### 8. 动画 & 过渡效果
+- 页面进入/退出过渡动画
+- 加载动画样式
+- 按钮点击动效
+- 列表加载骨架屏动效
+
+#### 9. 边界&异常场景处理
+1. 弱网/无网络时表现
+2. 接口报错文案展示
+3. 输入超限、特殊字符拦截
+4. 无权限访问处理
+5. 首次进入/非首次进入差异化
+
+#### 10. 平台差异化专属规则
+分别说明iOS、Android、Flutter、Web的差异。
+
+#### 11. 验收标准（UI视觉 + 交互行为逐条可测！）
+- 视觉验收
+- 状态验收
+- 交互验收
+- 异常验收
+- 平台适配验收
+
+---
+
+## 第三部分：完整工作流程
+
+### 项目从零启动（需求→UI→实现）
+```
+1. 用 sdd 技能：拆 Epic→Feature→Story，写验收标准，做估算
+2. 用 ui-sdd 的「App全域全景骨架」：梳理完整结构，建目录
+3. 用 ui-sdd 的「标准模板」：逐个页面写SDD
+4. 交付开发（或用 sdd-add 做快速实现）
+```
+
+### 正常迭代开发（日常新功能）
+```
+1. 用 sdd：把新功能拆成 Story，写验收标准
+2. 用 ui-sdd：回「全景骨架」补勾，补建/更新SDD
+3. 用 sdd-add：做快速实现，需求文档必须引用 sdd 的 Story 和 ui-sdd 的 SDD
+```
+
+### 临时需求/紧急修复
+```
+1. 直接用 sdd-add：快速澄清、优先级、实现
+2. 如果涉及UI/新增页面：必须同步回 ui-sdd 补勾、补建SDD
+3. 如果涉及Story拆分：必须同步回 sdd 补Story
+```
+
+---
+
+## 第四部分：文档关联引用规范
+
+### sdd Story 中引用 ui-sdd
+在 sdd 产出的 Story 文档中加入：
+```markdown
+## 关联文档
+- 对应UI交互SDD：spec/ui/pages/xxx-page.sdd.md
+- 复用组件SDD：spec/ui/common/ui-yyy.sdd.md
+- 相关弹窗SDD：spec/ui/dialog/zzz-dialog.sdd.md
+```
+
+### ui-sdd SDD 中引用 sdd Story
+在 ui-sdd 产出的页面/组件SDD中加入：
+```markdown
+## 关联用户故事
+- 主故事：US-001（在 docs/stories/user_stories.md）
+- 相关故事：US-002、US-003
+```
+
+### sdd-add 临时需求中引用前两者
+在 sdd-add 产出的临时需求文档中加入：
+```markdown
+## 关联文档
+- 关联Story：docs/stories/user_stories.md 中的 US-xxx
+- 关联UI-SDD：spec/ui/pages/yyy-page.sdd.md
+```
+
+---
+
+## 第五部分：一句话原则
+
+**「sdd 定方向（做什么），ui-sdd 定样子（怎么做），sdd-add 填细节（快速补）；从上往下拆，从下往上补，互相引用不遗漏」**
+
+---
+
+## 附录：快速检查表
+
+### 「App全域全景骨架」完成检查
+- [ ] 第1步：模拟用户走完全程
+- [ ] 第2步：所见全部罗列（页面/弹窗/组件）
+- [ ] 第3步：分成三大类（pages/dialog/common）
+- [ ] 第4步：补上全局隐性规则
+- [ ] 第5步：整理成树形结构
+
+### 单个UI-SDD文档完成检查
+- [ ] 基础信息完整
+- [ ] 页面结构清晰
+- [ ] 所有状态定义（至少7种）
+- [ ] 组件清单及静态UI
+- [ ] 交互逻辑详细（包括防抖、点击反馈）
+- [ ] 平台适配规则
+- [ ] 验收标准明确（逐条可测）
+
+---
+
+## 最佳实践总结
+
+1. **骨架先行**：先画App全域全景骨架，再写单个SDD
+2. **状态优先**：定义所有状态，再写组件和交互
+3. **交互细化**：每个交互都要考虑边缘情况（防抖、反馈等）
+4. **平台适配**：明确列出各平台的差异
+5. **验收标准**：每条标准都要可测试
+6. **互相引用**：sdd、ui-sdd、sdd-add 三者文档互相关联
+
+---
+
+*文档版本：v1.0 | 最后更新：2026-05-04*