@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-design/skills/workflow-integration-verify/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: workflow-integration-verify
+description: "Use after both Track A (api-call-guide) and Track B (frontend-tech-spec) complete. Performs Merge Gate verification: cross-check backend API implementation against the API contract and frontend's API calling patterns. Outputs an integration report."
+---
+
+# 联调验证（Merge Gate）
+
+## 定位
+
+| 维度 | 说明 |
+|------|------|
+| **消费者** | QA / 技术负责人 |
+| **角色** | **合并门禁** — 双轨汇合前的最后一道验证。确保前后端对 API 的理解一致 |
+| **前置条件** | Track A（`api-call-guide`）和 Track B（`前端技术方案`）均已完成 |
+
+## 跳过条件
+
+满足以下任一条件时，本 skill 不产生有意义产出，应跳过：
+
+1. 单轨道执行（`active_track == "A"` 或 `active_track == "B"`），没有双轨汇合需求
+2. `api-contract.md` 不存在（本功能无 API 变更）
+3. `api-call-guide.md` 不存在（被跳过）
+
+在完整 workflow 中不要直接跳过文件产出；应生成 no-op `integration-report.md` 和 `integration-report.meta.json`，其中 `api_required: false`、`merge_gate_status: "skipped"`、所有 mismatch / supplement / blocking 计数为 0，并写明跳过原因。单轨模式仍然不能进入 `change-plan / execute`。
+
+## 产出位置
+
+- `.planning/features/{功能名}/integration-report.md`
+- `.planning/features/{功能名}/integration-report.meta.json`
+
+`integration-report.meta.json` 必须包含：
+
+```json
+{
+  "api_required": true,
+  "merge_gate_status": "passed",
+  "contract_backend_mismatch_count": 0,
+  "contract_frontend_mismatch_count": 0,
+  "unhandled_api_supplement_count": 0,
+  "blocking_issue_count": 0,
+  "skip_reason": ""
+}
+```
+
+## 输入
+
+- `.planning/features/{功能名}/api-contract.md` — **API 签名唯一权威源**
+- `.planning/features/{功能名}/api-call-guide.md` — Track A 产出的调用指南
+- `.planning/features/{功能名}/前端技术方案.md` — Track B 产出的前端方案
+- `.planning/features/{功能名}/后端技术方案.md` — Track A 产出的后端方案
+- `.planning/features/{功能名}/api-supplement-requests.md` —（可选）Track B 提交的 API 补充需求
+- `.planning/code-index/`（如存在）— 用于抽查 API route/handler、frontend API calls、imports/calls 关系，并回读源码 evidence
+
+## 核心原则
+
+1. **只对比，不实现** — 验证接口契约 vs 前后端实现的一致性，不写代码、不改方案
+2. **逐 API 验证** — 每个 API 检验：后端方案中的实现 ↔ API 契约 ↔ 前端调用方式
+3. **不匹配分级** — 标记不匹配项的严重级别（阻塞 / 非阻塞）
+4. **以 api-contract.md 为准** — 前后端方案与契约不一致时，以契约为准
+5. **源码事实必须有 evidence** — 当 `.planning/code-index/` 存在且验证涉及已实现代码时，先查 Symbol/Relation，再回读 `evidence_path:evidence_line`；不得只凭 Markdown navigation 或 relation 摘要判断实现一致性
+
+## 验证流程
+
+### Step 1：收集契约证据
+
+从 `api-contract.md` 提取每个接口的：
+- Method + Endpoint
+- 请求参数
+- 响应结构
+- 所属 FP
+
+### Step 2：检查 Track A 实现
+
+从 `后端技术方案.md` 提取：
+- 每个接口的后端实现方案
+- 数据表模型
+- API 参数和响应签名
+- 与 API 契约的差异
+
+若 `.planning/code-index/` 存在，按 endpoint、handler、controller/service 名称查询后端 symbols 和 `routes_to` / `calls` / reads/writes 关系，读取源码 evidence 后抽查实现位置是否与方案和契约一致。
+
+逐项对比：后端方案中的 API 描述是否与契约一致？
+
+### Step 3：检查 Track B 调用
+
+从 `前端技术方案.md` 提取：
+- 前端调用的 API 列表
+- 参数使用方式
+- 响应处理逻辑
+
+从 `api-call-guide.md` 提取：
+- 调用步骤中的请求示例
+- 预期的响应结构
+
+若 `.planning/code-index/` 存在，按 endpoint、API client 方法、页面/组件名查询前端 symbols 和 `imports` / `calls` 关系，读取源码 evidence 后抽查调用方式是否与契约一致。
+
+逐项对比：前端调用的 API 是否与契约一致？
+
+### Step 4：检查 API 补充需求（如果有）
+
+从 `api-supplement-requests.md` 提取：
+- 缺失的 API 列表
+- 每个缺失 API 的预期签名和理由
+
+评估：
+- 是否真的缺失？
+- 可以用已有接口拼吗？
+- 必须新增的对 Track A 影响多大？
+
+## 产出模板
+
+```
+# 联调验证报告：{功能名}
+
+## 验证摘要
+
+| 指标 | 值 |
+|------|----|
+| API 总数 | {count} |
+| 实现与契约一致 | {count} |
+| 不匹配项 | {count} |
+| API 补充需求 | {count} |
+| 验证结论 | 通过 / 有条件通过 / 不通过 |
+
+## 逐 API 验证
+
+### POST /api/v1/orders — ✅ 一致
+
+| 维度 | 契约要求 | 后端实现 | 前端调用 | 结论 |
+|------|---------|---------|---------|:----:|
+| Method | POST | POST | POST | ✅ |
+| Endpoint | /api/v1/orders | /api/v1/orders | /api/v1/orders | ✅ |
+| 请求体 | {user_id, items, remark} | {user_id, items, remark} | {user_id, items, remark} | ✅ |
+| 成功响应 | {order_id, status, ...} | {order_id, status, ...} | {order_id, status} | ✅ |
+| 错误码 | 400/422 | 400/422 | 400/422 | ✅ |
+
+### GET /api/v1/orders/{id} — ⚠️ 不匹配
+
+| 维度 | 契约要求 | 后端实现 | 前端调用 | 结论 |
+|------|---------|---------|---------|:----:|
+| 响应字段 status | string enum | string enum | ✅ | ✅ |
+| 响应字段 items | array | array | ✅ | ✅ |
+| 响应字段 total_amount | number (分) | number (元) | ⚠️ | ❌ 前后端单位不一致 |
+
+### API 补充需求（来自 Track B）
+
+| # | 缺失接口 | 理由 | 评估 | 处理 |
+|---|---------|------|------|------|
+| 1 | PATCH /api/v1/orders/{id}/cancel | 前端需要取消订单功能 | 契约未定义，取消属于另一 FP | 暂缓，进入下一轮开发 |
+
+## 不匹配项处理
+
+| # | 接口 | 问题 | 严重级别 | 归属 | 修复建议 |
+|---|------|------|---------|------|---------|
+| 1 | GET /api/v1/orders/{id} | total_amount 单位不一致 | 阻塞 | 后端 | 统一为分（整数） |
+
+## 验证结论
+
+- [ ] 通过：所有 API 一致，无不匹配
+- [ ] 有条件通过：存在非阻塞不匹配项，已记录修复计划
+- [ ] 不通过：存在阻塞不匹配项，需要修复后重新验证
+```
+
+## 完成门禁
+
+- [ ] 每个 API 契约中的接口都完成了三方验证（契约 vs 后端实现 vs 前端调用）
+- [ ] 不匹配项标注了严重级别和归属
+- [ ] API 补充需求（如有）已评估处理方案
+- [ ] 验证结论已写入报告
+- [ ] meta.json 中 `merge_gate_status` 为 `passed`
+- [ ] meta.json 中所有 mismatch / supplement / blocking 计数均为 0
+- [ ] 无 API 变更时生成 no-op meta，`api_required` 为 false，`merge_gate_status` 为 `skipped`

package/plugins/devflow-design/skills/workflow-ui-spec/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: workflow-ui-spec
+description: "Use when UI designs, screenshots, Figma exports, Lanhu notes, or manual UI descriptions need a structured UI specification."
+---
+
+## Legacy Command Metadata
+
+Original slash-command metadata retained only as workflow invocation guidance.
+
+```yaml
+argument-hint: <功能名> [@设计稿路径] [--auto]
+user-invocable: true
+pattern: generator+reviewer
+inputs:
+- .planning/requirements/baseline.md
+- .planning/PROJECT.md
+- .planning/navigation/INDEX.md
+- .planning/rules/INDEX.md
+- .context/spec/frontend/index.md
+- .context/spec/frontend/
+- .context/spec/design/
+- references/affected-module-exploration.md
+output: .planning/features/{功能名}/UI-SPEC.md
+allowed-tools:
+- Read
+- Write
+- Edit
+- Bash
+- Grep
+- Glob
+- ask
+```
+
+# UI 设计解析与规范化
+
+将 UI 设计稿解析为结构化的 UI 规范文档（UI-SPEC.md），生成与需求基线同级的**设计契约**。
+
+## 定位
+
+UI 稿和 PRD 是研发流程的两个**同级原始输入**：
+
+```
+PRD ──→ 需求基线(2) ──→ 功能点梳理(3.1) ──→ 前端技术方案(3.2)
+         ↑                ↑                    ↑
+UI稿 ──→ UI-SPEC(2.5) ───┘                    │
+         └─────────────────────────────────────┘
+```
+
+- **需求基线** 回答"做什么"（功能、逻辑、数据）
+- **UI-SPEC** 回答"长什么样"（布局、组件、Token、交互）
+- 两者**共同**作为功能点梳理（样式/功能/逻辑三维）和前端技术方案的输入源
+
+UI-SPEC 不写代码细节（那是前端技术方案的事），但必须把 UI 层面的所有决策提前拍板完成。
+
+## 核心原则
+
+1. **视觉事实优先**：UI 稿中的事实（布局、颜色、间距、组件排列）直接提取，不猜测
+2. **不确定就问**：UI 稿中不清晰的部分必须向用户确认，不做假设
+3. **与代码对齐**：提取的组件必须与现有前端代码中的组件做复用匹配
+4. **完整覆盖状态**：每个页面/组件必须覆盖所有用户可见状态
+5. **服务下游**：产出是功能点梳理"样式维度"和前端技术方案"组件拆分/设计 Token"的确定性输入
+
+## 工作流程
+
+### 第一阶段：获取设计输入
+
+1. 解析 `$ARGUMENTS`：
+   - `<功能名>`：功能名称
+   - `@设计稿路径`：设计稿文件路径（图片、PDF）或 Figma/蓝湖链接
+   - `--auto`：非交互模式，缺失信息标记为待确认
+
+2. 确定设计输入来源（按优先级）：
+   - **A. 用户直接提供的截图/图片** → 直接读取分析
+   - **B. Figma/蓝湖链接** → 要求用户导出截图后提供，不直接访问
+   - **C. 需求基线中的 UI 描述** → 从 baseline.md 提取文字描述
+   - **D. 无设计稿** → 标记为待确认，UI-SPEC.md 不生成，下游功能点梳理和前端方案直接使用基线描述
+
+3. 如果设计稿路径为图片（.png/.jpg/.webp），使用 Read 工具读取图片内容进行视觉分析。
+
+### 第二阶段：理解产品上下文
+
+1. 读取 `.planning/requirements/baseline.md`，提取：
+   - 涉及的页面/弹窗/区域列表
+   - 与 UI 相关的用户拍板决策（布局偏好、交互方式、组件选择）
+   - `反向审视与用户拍板` 中影响 UI 的决策
+2. 读取 `.planning/PROJECT.md` 了解前端代码库位置
+3. 按 `.planning/rules/INDEX.md` 加载前端规范（`.context/spec/frontend/`、`.context/spec/design/`）
+4. 若 `.context/spec/design/index.md` 不存在，先通过 OMP 运行时安装共享设计规则包：
+   ```text
+   devflow_design_rule(args=[])
+   ```
+   安装后重新检查 `.context/spec/design/index.md`。如果仍不存在，记录“未发现设计规则包”，继续使用设计稿和现有代码保守分析。
+5. 若存在 `.context/spec/design/index.md`，必须读取该入口，并按入口说明加载：
+   - 项目已确认 token：`.context/spec/design/tokens/project-tokens.md`
+   - 通用设计推荐：`.context/spec/design/recommendations/`
+   - 动态推荐工具：`.context/spec/design/tools/ui-ux-pro-max/scripts/search.py`
+6. 在以下情况调用 `ui-ux-pro-max` 动态推荐工具补充设计参考：
+   - 无设计稿，但需求需要页面风格、配色、字体、布局建议
+   - 设计稿未覆盖颜色、字体、间距、圆角、阴影、响应式、可访问性或状态细节
+   - 需要按产品类型/行业/风格生成候选设计系统
+   推荐命令示例：
+   ```bash
+   python3 .context/spec/design/tools/ui-ux-pro-max/scripts/search.py "<产品类型> <行业> <风格关键词>" --design-system -p "<功能名>" --format markdown
+   python3 .context/spec/design/tools/ui-ux-pro-max/scripts/search.py "loading error accessibility responsive" --domain ux
+   ```
+7. 设计结论合并优先级必须为：用户拍板/设计稿事实/需求基线 > 现有代码与项目 token > `.context/spec/design/tokens/project-tokens.md` > `ui-ux-pro-max` 推荐。推荐结果只能作为“推荐 - 待拍板”，不得覆盖设计稿事实或现有项目规范。
+
+### 第三阶段：设计解析
+
+对每个页面/弹窗/区域，从设计稿中提取以下结构化信息：
+
+#### 3.1 页面布局结构
+
+```
+页面: {页面名称}
+├── 顶部导航区: {描述、是否固定、包含元素}
+├── 主内容区: {描述、滚动行为}
+│   ├── 区域1: {名称、功能}
+│   ├── 区域2: {名称、功能}
+│   └── ...
+├── 底部操作区: {描述、是否固定}
+└── 弹窗/浮层: {触发条件、内容}
+```
+
+#### 3.2 组件树
+
+对每个区域，逐层拆解组件嵌套关系（至少3层）：
+
+```
+页面 → 区域 → 子组件 → 基础组件
+```
+
+每个组件标注：
+- **类型**：页面 / 区域容器 / 业务组件 / 基础组件 / 第三方组件
+- **复用决策**：已有可复用 / 需新建 / 需修改现有 / 来自第三方库
+- **状态列表**：默认 / loading / empty / error / disabled / 权限受限 / 重复提交
+
+#### 3.3 设计 Token 提取
+
+从设计稿中提取视觉变量，优先与现有代码中的设计变量对齐：
+
+| 类别 | Token 名 | 值 | 用途 | 对应代码变量 |
+|------|---------|----|----|------------|
+| 颜色 | `--color-primary` | `#FF6B35` | 主色调 | `$primary-color` |
+| 字号 | `--font-size-title` | `18px` | 页面标题 | `$font-size-lg` |
+| 间距 | `--spacing-card` | `12px` | 卡片内边距 | `$padding-card` |
+| 圆角 | `--radius-button` | `8px` | 按钮圆角 | `$border-radius-base` |
+| 阴影 | `--shadow-card` | `0 2px 8px rgba(0,0,0,0.1)` | 卡片投影 | 待确认 |
+
+设计 Token 必须分来源输出：
+
+- **设计稿事实**：来自截图/Figma/蓝湖/用户已确认设计描述，可作为下游实现依据。
+- **现有项目规范**：来自现有代码、组件库或 `.context/spec/design/tokens/project-tokens.md`，可作为下游实现依据。
+- **推荐 - 待拍板**：来自 `.context/spec/design/recommendations/` 或 `ui-ux-pro-max` 动态查询，只能进入待确认事项，用户确认前不得被前端技术方案当作已确认实现值。
+
+#### 3.4 交互流程
+
+描述关键交互的完整链路（用户操作 → 视觉反馈 → 状态变化 → 接口调用）：
+
+```
+流程: {流程名称}
+触发: {用户操作}
+步骤1: {视觉变化/动画} → {状态变化}
+步骤2: {视觉变化/动画} → {状态变化}
+步骤3: {接口调用（标注需求基线中的接口）} → {结果处理}
+终态: {成功/失败/空数据的 UI 表现}
+```
+
+#### 3.5 响应式/多端适配
+
+- 如果目标平台包含多端（小程序 + H5 + App），标注各端差异
+- 标注断点和布局变化
+
+### 第四阶段：与现有代码对齐
+
+1. 读取 `references/affected-module-exploration.md`，对每个涉及的现有前端页面/组件进行探索
+2. 对每个设计组件，在现有前端代码中查找可复用的组件：
+   ```
+   设计组件: {名称}
+   → 候选复用: {现有组件路径} / {npm 包名}
+   → 匹配度: 完全匹配 / 需加 Props 不改内部 / 需改内部 / 无可复用
+   → 修改点: {如果需修改，列出具体差异}
+   ```
+3. **复用深度检查**（新增）：对标记为"复用"的现有组件，检查接口是否够用：
+   ```
+   现有组件: Table
+   现有接口: props=[columns, dataSource, loading], events=[rowClick]
+   当前需求需要: 多级表头、行拖拽排序
+   → 多级表头: Table 已支持（columns.children 语法）→ ✅ 完全匹配
+   → 行拖拽排序: Table 不支持，需额外加 props=[dragSortable] 和 events=[sortChange]
+   → 判断: 可复用，需扩展接口（加 1 prop + 1 event → 接口从 4 增到 6，仍可接受）
+   → 结论: 复用-轻微扩展
+   ```
+   判断标准：
+   - 新增 Props+Events ≤ 2 → ✅ 可接受，标记为"复用-轻微扩展"
+   - 新增 Props+Events ≥ 3 → ⚠️ 接口膨胀风险，考虑是否新建组件
+   - 同时需改内部逻辑 → 🔴 可能是 seam 选错了，考虑是否应新建
+4. 检查设计 Token 是否与现有设计变量冲突
+5. 与需求基线中已确认的组件复用决策交叉验证，有冲突时反馈到需求基线
+
+### 第五阶段：生成 UI-SPEC.md
+
+1. 创建/确认 `.planning/features/{功能名}/` 目录
+2. 读取 `assets/ui-spec-template.md` 模板
+3. 按模板结构填充所有章节，并在设计 Token 与交互章节中标明来源：设计稿事实 / 现有项目规范 / 推荐 - 待拍板
+4. 将所有来自推荐源且影响实现的候选值写入“待确认事项”
+5. 写入 `审查结论` 章节
+
+## 输出文档结构（UI-SPEC.md）
+
+```markdown
+# UI 设计规范 — {功能名}
+
+## 1. 设计来源
+- 设计稿路径/截图说明
+- 设计工具/版本
+- 解析日期
+
+## 2. 页面清单与布局
+### 2.1 {页面1名称}
+- 路由路径
+- 布局结构（ASCII 图）
+- 区域划分
+### 2.2 {页面2名称}
+...
+
+## 3. 组件树与复用分析
+### 3.1 新增组件
+### 3.2 修改现有组件
+### 3.3 复用现有组件
+
+## 4. 设计 Token
+### 4.0 来源分层
+- 设计稿事实
+- 现有项目规范
+- 推荐 - 待拍板
+### 4.1 颜色
+### 4.2 字体与字号
+### 4.3 间距
+### 4.4 圆角与阴影
+### 4.5 动画/过渡
+
+## 5. 交互流程
+### 5.1 {流程1}
+### 5.2 {流程2}
+...
+
+## 6. 状态覆盖矩阵
+| 页面/组件 | Loading | Empty | Error | Disabled | 权限限制 | 重复提交 |
+|----------|---------|-------|-------|----------|---------|---------|
+| 页面A     | ✓       | ✓     | ✓     | -        | ✓       | ✓       |
+
+## 7. 多端差异（如适用）
+
+## 8. 待确认事项
+
+## 9. 下游输入契约
+本 UI-SPEC 为以下文档提供 UI 层面的确定输入：
+- **功能点梳理**（Step 3.1）：样式维度的页面/区域/组件/字段/按钮/弹窗等可验证节点
+- **前端技术方案**（Step 3.2）：组件树、设计 Token、交互流程、复用决策
+
+## 10. 审查结论
+```
+
+## 强制审查门禁
+
+### 设计完整性
+
+- [ ] 所有涉及页面/弹窗的布局结构已从设计稿提取（无凭感觉推测）
+- [ ] 每个页面至少拆到区域→组件→子组件三层
+- [ ] 每个组件标注了完整状态列表
+- [ ] 设计 Token 不少于 5 类（颜色、字号、间距、圆角、阴影）
+
+### 代码对齐
+
+- [ ] 每个新增/修改组件已与现有前端代码做了复用匹配
+- [ ] 设计 Token 已与现有设计变量做了对齐检查
+- [ ] 与需求基线中已确认的组件/交互决策无冲突
+
+### 用户体验
+
+- [ ] 关键交互流程已描述完整链路（触发→反馈→状态→结果）
+- [ ] 状态覆盖矩阵覆盖了所有组件/页面的所有状态
+- [ ] loading/empty/error 三个状态每个页面至少有一个处理方案
+
+### 下游可用性
+
+- [ ] 页面清单和组件树可直接映射为功能点梳理的"样式"维度节点
+- [ ] 设计 Token 可直接被前端技术方案引用为样式变量
+- [ ] 交互流程中的接口已与需求基线中的 API 列表对齐
+
+### 反向对照
+
+| 嗅探 | 检查 |
+|------|------|
+| 布局嗅探 | 设计稿中是否有多端差异未标注？ |
+| 复用嗅探 | 是否有设计稿中的组件与现有组件高度相似但被标记为"新建"？ |
+| 遗漏嗅探 | 需求基线中的所有页面/弹窗是否都有对应的 UI 设计？ |
+| 冲突嗅探 | 设计 Token 是否与现有变量命名/值冲突？ |
+| 需求对齐 | 设计稿中的交互是否与需求基线的用户拍板决策一致？ |
+
+**审查结论不通过时，不得进入功能点梳理阶段。**