feat(req): 集成 Stitch 原型设计到需求工作流

新建 req-prototype 技能，支持基于 PRD 自动生成 Stitch UI 原型。同步 req-review、req-workflow 技能到仓库，并更新 req、req-prd 中的原型相关引用。 REQ-20260320-0005 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
feat(dev-test): 添加集成测试模板 + TG2 检测规则
2026-03-20 23:42:24 +10:30 · 2026-03-16 14:28:44 +10:30
10 changed files with 671 additions and 296 deletions
--- a/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md
+++ b/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md
@@ -14,6 +14,7 @@ description: 软件测试技能。用于单元测试、集成测试、E2E测试
 | `ios-testing.md` | iOS 测试 (XCTest + Swift Concurrency) |
 | `android-testing.md` | Android 测试 (JUnit + Espresso + Compose) |
 | `e2e-testing.md` | E2E Playwright：API Mock 冒烟测试（无后端）+ 全链路集成测试 |
+| `templates/go-integration-test.md` | Go 集成测试模板（多步骤 API 流程、中间件验证、租户隔离） |

 ---

@@ -141,3 +142,20 @@ ai-proj task append-doc --id <taskId> --content "# 测试报告
 7. **Mock 仅限 Handler 层** - handler 层可以 mock biz 接口 + httptest
 8. **E2E 冒烟测试必须用 API Mock** - E2E 门禁不能依赖后端，否则形同虚设。用 `page.route()` 拦截 API，见 `e2e-testing.md`。质量门禁流程（Gates 1-5）定义在 `req-test-gate` 技能中
 9. **李宁测试用例** - Excel 导出见 `coolbuy-legacy` 技能的 `test-cases-excel.md`
+
+---
+
+## TG2 集成测试检测
+
+### 模板映射
+
+| 变更范围 | 测试输出位置 | 模板 |
+|----------|-------------|------|
+| 单个 handler 或 service | `*_test.go` (同目录) | `go-testing.md` |
+| handlers/ + middleware/ + routes/ (同一功能) | `tests/{feature}_integration_test.go` | `templates/go-integration-test.md` |
+
+### 检测规则
+
+若 git diff 显示同一功能的 `handlers/`、`middleware/`、`routes/` 文件均有变更（通过命名模式识别，如 `impersonation_handler.go` + `impersonation_middleware.go` + `impersonation_routes.go`），则除单元测试外**额外生成** `backend/tests/` 下的集成测试。
+
+识别方式：提取文件名中的功能前缀（如 `impersonation`），若在三个目录中均出现，则触发集成测试生成。
--- a/skills-dev/dev-test-plugin/skills/dev-test/templates/go-integration-test.md
+++ b/skills-dev/dev-test-plugin/skills/dev-test/templates/go-integration-test.md
@@ -0,0 +1,127 @@
+# Go 集成测试模板
+
+## 适用场景
+
+当 git diff 显示同一功能的 **handlers/ + middleware/ + routes/** 文件均有变更时，除单元测试外应额外生成集成测试。
+
+适用于：
+- 多步骤 API 流程（登录→操作→验证→退出）
+- 中间件拦截验证（权限、限流、模拟状态限制）
+- 租户隔离 / 数据隔离验证
+- 跨模块交互（handler ↔ middleware ↔ repository）
+
+## 检测规则
+
+通过命名模式识别同一功能的跨文件变更：
+
+```
+handlers/{feature}_handler.go
+middleware/{feature}_middleware.go
+routes/{feature}_routes.go
+```
+
+例如 `impersonation_handler.go` + `impersonation_middleware.go` + `impersonation_routes.go` 同时变更 → 生成 `tests/impersonation_integration_test.go`。
+
+## 生成规则
+
+1. 测试文件放在 `backend/tests/` 目录（与 `test_helpers.go` 同包）
+2. 使用 `SetupTestApp` + `defer TeardownTestApp` 初始化真实路由和数据库
+3. 每个测试完全自包含：独立创建/清理数据
+4. 异步持久化操作（goroutine 写 DB）需 `time.Sleep(200-500ms)` 后再验证
+
+## 代码骨架
+
+```go
+package tests
+
+import (
+    "encoding/json"
+    "fmt"
+    "net/http"
+    "testing"
+    "time"
+
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+func TestFeature_Scenario(t *testing.T) {
+    testApp := SetupTestApp(t)
+    defer TeardownTestApp(t, testApp)
+
+    // === Setup: 创建测试数据 ===
+    // 使用 test_helpers.go 中的 helper 函数
+    sysAdmin := CreateTestSystemUser(t, testApp, "admin_scenario")
+    // tenantID := CreateTestTenant(t, testApp, "scenario_tenant")
+    // enterprise := CreateTestEnterpriseWithTenant(t, testApp, "Corp", "CODE", tenantID)
+    // tenantAdmin := CreateTestTenantAdmin(t, testApp, "tadmin", enterprise.ID, tenantID)
+
+    // === Cleanup: 按外键约束顺序清理 ===
+    defer CleanupImpersonationTestData(t, testApp,
+        []int{sysAdmin.ID},
+        []int{},    // enterpriseIDs
+        []int64{},  // tenantIDs
+    )
+
+    // === 状态变量：跨步骤传递 ===
+    var token string
+
+    t.Run("Step1_InitialAction", func(t *testing.T) {
+        w := MakeAuthenticatedRequest(t, testApp, http.MethodPost,
+            "/api/v1/...",
+            map[string]string{"key": "value"},
+            sysAdmin,
+        )
+        require.Equal(t, http.StatusOK, w.Code, "Step1 failed: %s", w.Body.String())
+
+        var resp map[string]interface{}
+        require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+        // 提取后续步骤需要的数据
+        token = resp["data"].(map[string]interface{})["token"].(string)
+    })
+
+    t.Run("Step2_VerifyState", func(t *testing.T) {
+        if token == "" {
+            t.Skip("Step1 failed")
+        }
+        // 使用 Step1 产出的 token 继续验证
+    })
+
+    t.Run("StepN_AsyncVerification", func(t *testing.T) {
+        // 异步写入的数据需要等待
+        time.Sleep(300 * time.Millisecond)
+        // 然后验证 DB 数据
+    })
+}
+```
+
+## 4 种必测场景
+
+| 场景类型 | 说明 | 示例 |
+|----------|------|------|
+| **Happy Path** | 完整正常流程 | 开始模拟 → 访问 API → 查状态 → 退出 → 确认恢复 |
+| **权限拒绝** | 无权限用户尝试操作 | 普通用户尝试模拟 → 403 |
+| **隔离验证** | 跨租户/跨企业数据隔离 | tenant2 admin 访问 tenant1 企业 → 403 |
+| **边界条件** | 输入校验、状态冲突 | 原因太短 → 400；已在模拟中再次模拟 → 403 |
+
+## Helper 函数参考
+
+```go
+// 来自 test_helpers.go
+SetupTestApp(t)                              // 初始化完整应用（路由 + DB）
+CreateTestSystemUser(t, app, username)       // 系统管理员 + JWT
+CreateTestTenant(t, app, name)               // 创建租户，返回 int64 ID
+CreateTestEnterpriseWithTenant(t, app, name, code, tenantID)  // 带租户的企业
+CreateTestTenantAdmin(t, app, username, enterpriseID, tenantID...)  // 租户管理员
+CreateTestEnterpriseUser(t, app, username, enterpriseID)   // 普通企业用户
+ExtractImpersonationToken(t, response)       // 从模拟响应提取 token
+MakeAuthenticatedRequest(t, app, method, path, body, user)  // 发送认证请求
+CleanupImpersonationTestData(t, app, userIDs, enterpriseIDs, tenantIDs)  // 按FK顺序清理
+```
+
+## 注意事项
+
+- **Token 链式传递**：模拟 API 返回新 token，后续请求必须用新 token
+- **异步持久化**：handler 用 goroutine 写 session/audit，测试需 Sleep 后再查
+- **数据隔离**：每个测试用唯一的 username/code，避免测试间干扰
+- **清理顺序**：外键约束要求先删子表再删父表
--- a/skills-req/req-plugin/skills/SKILL.md
+++ b/skills-req/req-plugin/skills/SKILL.md
@@ -86,6 +86,7 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD
 1.  /req new         → 创建需求 (draft)
 2.  需求讨论         → 输出结论摘要，用户确认
 3.  req-prd 技能     → 编写 PRD（创建【评审】PRD 任务）
+3.5 /req prototype   → 生成 Stitch 原型（可选，有 UI 时推荐）
 4.  /req submit      → 提交评审 (pending)，含 4 道门禁
 5.  /req review pass → 评审通过 (approved, delivery_stage=analysis)
 6.  /req next        → 推进到 design/dev 阶段
@@ -94,7 +95,7 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD
 9.  /req cr          → 代码评审（创建【代码评审】任务）
 10. /req next        → 推进到 testing 阶段
 11. /req test        → 测试验收（5-Gate 流程）
-12. /req deploy      → 批量部署（DG1-DG6 Deploy Gates）
+12. /req deploy      → 批量部署（build-and-push.sh → Jenkins ai-proj）
 13. /req done        → 归档 (archived) + git commit + push
 ```

@@ -231,6 +232,18 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD

 **`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联

+### 原型设计
+
+**`/req prototype [REQ-ID]`** — 基于 PRD 生成 Stitch 原型：
+1. 读取 PRD 文档，提取 UI 相关描述
+2. 创建 Stitch 项目 + 生成页面（调用 req-prototype 子技能）
+3. 截图回填 PRD「4.2 界面原型」章节
+- 参数：`--device [desktop|mobile|tablet]`，`--model [pro|flash]`
+
+**`/req prototype edit [REQ-ID] --prompt "..."`** — 修改已有原型
+
+**`/req prototype variant [REQ-ID]`** — 生成设计变体供选择
+
 ### 提交评审

 **`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径：
@@ -281,13 +294,15 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD

 **`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程

-**`/req deploy [--project <name>] [--env <env>]`** — 项目级批量部署：
+**`/req deploy [--project <name>] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）：
 1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
 2. AskUserQuestion 确认范围
 3. `ai-proj task create` 创建部署批次任务
-4. Deploy Gates DG1-DG6：staging 部署 → 冒烟测试 → 回归 → 生产部署
-5. `ai-proj task append-doc` 记录部署文档
-6. `ai-proj req advance --id <id> --to released` 批量推进
+4. 部署前检查（变更检测、数据库迁移）
+5. 执行 `./scripts/build-and-push.sh prod --detect --deploy --wait --verify`
+6. 部署后验证（截图 + 定向验证）
+7. `ai-proj task append-doc` 记录部署文档 + 写入需求历史
+8. `ai-proj req advance --id <id> --to released` 批量推进

 **`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
 - **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
@@ -376,185 +391,10 @@ ai-proj req tasks --id <id>               # 查看关联任务

 **linkRole**: `prd`, `design`, `implementation`, `code_review`, `test`, `deploy`, `regression`, `documentation`

-## 详细阶段管理命令
-
-### `/req phase [REQ-ID]`
-查看需求当前开发阶段和任务状态。
-
-**执行逻辑**：
-1. `get_requirement(id)` → 获取 `delivery_stage`
-2. `get_requirement_tasks(id)` → 获取所有关联任务
-3. 按 linkRole 分组展示，标注当前阶段任务完成度
-
-**输出示例**：
-```
-REQ-20260218-0013 | 阶段: dev (开发)
-────────────────────────────────────
-✅ analysis (评审)
-   ✅ #6035 【评审】PRD: 需求全生命周期阶段化管理
-▶ dev (开发) ← 当前阶段
-   🔄 #6042 【开发-后端】实现阶段管理 API [in_progress]
-   ⬜ #6043 【开发-前端】阶段可视化组件 [todo]
-⬜ review (代码评审)
-⬜ testing (测试)
-```
-
-### `/req resume [REQ-ID]`
-从上次中断的位置恢复工作。**会话被截断后的首选命令**。
-
-**执行逻辑**：
-1. 若无 REQ-ID → `list_requirements(status=approved)` 找最近活跃需求
-2. `get_requirement(id)` → 获取 delivery_stage
-3. `get_requirement_tasks(id)` → 获取所有关联任务及状态
-4. 汇总展示恢复上下文
-
-**输出格式**：
-```
-📋 恢复工作上下文
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-需求: REQ-20260218-0016 | 需求标题
-状态: approved | 阶段: dev (开发)
-
-📊 任务进度: 2/4 完成
-  ✅ #6051 【开发-后端】实现 API
-  🔄 #6053 【开发-Skill】xxx [in_progress]
-  ⬜ #6054 【开发-Skill】xxx [todo]
-
-▶ 建议操作:
-  1. 继续任务 #6053（当前 in_progress）
-  2. 执行 /req next 推进阶段
-```
-
-### `/req regression [--module <name>] [--mode <mode>]`
-**运行回归测试**。系统级持续质量活动。
-
- `--module` 指定模块，不指定则按影响域推断
- `--mode`：`impact`（影响域，默认）| `critical`（关键路径）| `full`（全量）
-
-**执行逻辑**：
-1. 确定范围：指定 module → 直接运行；未指定 → `git diff` + `module-deps.json` 推断
-2. 运行 `regression-suite/suites/` 下对应脚本
-3. 对比上次运行结果，标记回归（上次 PASS + 本次 FAIL）
-4. 有回归 → AskUserQuestion「是否创建 bug 需求？」
-
-## 辅助命令
-
-**`/req link [REQ-ID] --task-id [TASK-ID]`** — 关联任务到需求
-
-**`/req decompose [REQ-ID]`** — 分解需求为任务，自动加阶段前缀
-
-**`/req generate-tasks [REQ-ID]`** — 根据 PRD 自动生成开发任务，带【开发】前缀
-
-**`/req priority [REQ-ID] [low|medium|high]`** — 设置需求优先级
-
-**`/req stats [REQ-ID|--all]`** — 查看需求统计信息
-
-## 阶段任务 Checklist 模板
-
-`/req next` 推进到新阶段时，通过 `create_stage_task` 自动创建建议任务：
-
-### analysis（评审）
-```
-☐ 【评审】PRD: {需求标题}          (linkRole: prd)
-☐ 【评审】技术设计: {需求标题}      (linkRole: design) [可选]
-```
-
-### design（设计）
-```
-☐ 【设计】技术方案: {需求标题}      (linkRole: design)
-```
-
-### dev（开发）
-```
-☐ 【开发-后端】{需求标题}           (linkRole: implementation)
-☐ 【开发-前端】{需求标题}           (linkRole: implementation) [可选]
-```
-
-### review（代码评审）
-```
-☐ 【代码评审】{需求标题}            (linkRole: code_review)
-```
-
-### testing（测试）
-```
-☐ 【测试】单元测试: {需求标题}       (linkRole: test)
-☐ 【测试】集成测试: {需求标题}       (linkRole: test) [可选]
-```
-
-### 部署（由 `/req deploy` 批量触发）
-```
-testing 完成 → 进入「待部署池」→ /req deploy 创建批次任务
-```
-
-**按需求类型的最低测试标准**：
-
-| 需求类型 | 最低测试要求 |
-|----------|-------------|
-| **code** | `go test` 或前端测试通过 + API 验证 + 截图验证 |
-| **skill** | 关键词一致性 + 规则无歧义 + 边界情况（至少 3 项） |
-| **ops** | 部署命令可执行 + 健康检查通过 |
-
-## MCP 工具映射
-
-| 命令 | MCP 工具 |
-|------|----------|
-| `/req` | `list_requirements` |
-| `/req new` | `create_requirement` |
-| `/req phase` | `get_requirement` + `get_requirement_tasks` |
-| `/req next` | `advance_delivery_stage` + `create_stage_task` |
-| `/req resume` | `get_requirement` + `get_requirement_tasks` |
-| `/req dev` | `get_requirement` + `get_requirement_tasks` + `start_task_with_timer` |
-| `/req cr` | `get_requirement_tasks` + Git diff |
-| `/req test` | `req-test-gate` 5-Gate 流程 |
-| `/req deploy` | Deploy Gates DG1-DG6 |
-| `/req regression` | `git diff` + 回归套件 |
-| `/req done` | 类型推断 + 检查清单 + `archive_requirement` |
-| `/req review` | `submit_requirement` |
-| `/req review pass` | `approve_requirement` |
-| `/req link` | `link_tasks_to_requirement` |
-
-## 环境选择
-
-> **重要**：正式需求应直接在**生产环境** (`mcp__ai-proj-prod__*`) 创建。
-> 仅在功能测试、流程验证时使用开发环境 (`mcp__ai-proj-dev__*`)。
-> 开发环境同步到生产时，`due_date`、`reviewer_id`、`allow_self_approve` 等字段会丢失，需手动补充。
-
-## Hook 自动同步
-
-需求操作自动触发同步，无需手动执行：
-
-| 事件 | 触发操作 |
-|------|----------|
-| `requirement.created` | 同步到远程 |
-| `requirement.approved` | 同步需求和任务 |
-| `task.completed` | 同步任务状态 |
-| `requirement.archived` | 最终同步 + 思源笔记 |
-
-**手动同步**：
-```typescript
-mcp__ai-proj__sync_requirement_to_remote(requirementId)
-mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)
-```
-
-**同步已知限制**：
-| 字段 | 同步支持 | 说明 |
-|------|----------|------|
-| title, description, status, priority | ✅ | 正常同步 |
-| **due_date** | ❌ | 不会同步，需手动补充 |
-| reviewer_id | ❌ | 不会同步 |
-| allow_self_approve | ❌ | 不会同步 |
-
-## 思源笔记集成
-
-归档时自动同步 5 阶段文档到思源笔记：
- 路径：`需求管理/REQ-XXXX/`
- 文档：01-PRD.md ~ 05-生命周期总结.md
- 手动同步：`/req sync-siyuan [REQ-ID]`
-
 ## 相关技能

 | 技能 | 用途 |
 |------|------|
 | `req-prd` | PRD 文档编写 + 评审方法论 |
-| `req-test-gate` | 测试 5-Gate + Deploy Gates |
-| `req-dev` | PRD 到代码转换、开发计划 |
+| `req-prototype` | Stitch 原型生成 + 迭代 |
+| `dev-test` | 测试 + 质量门禁 |
--- a/skills-req/req-prd-plugin/skills/SKILL.md
+++ b/skills-req/req-prd-plugin/skills/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: req-prd
-description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划、PRD 评审。当用户提到产品设计、PRD、需求文档、功能规划、用户故事、PRD 评审相关任务时自动激活。
+description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划。当用户提到产品设计、PRD、需求文档、功能规划、用户故事相关任务时自动激活。
 ---

 # 产品需求设计 Skill (req-prd)
@@ -304,7 +304,11 @@ CREATE TABLE `prd_product_label` (
 [流程图或步骤描述]

 ### 4.2 界面原型
-[原型链接或描述]
+
+> 使用 `/req prototype [REQ-ID]` 基于 PRD 自动生成 Stitch 原型。
+> 生成后截图将自动回填到此章节。
+
+[执行 `/req prototype` 后自动填充]

 ## 5. 技术要求
 ### 5.1 性能要求
@@ -619,7 +623,8 @@ mcp__ai-proj__export_task_document_to_file
 ## 常用工具

 ### 原型设计
- Figma
+- **Stitch** (Google AI) — 集成在 `/req prototype`，自动从 PRD 生成原型
+- Figma — 手动精细设计
 - Sketch
 - Axure

@@ -657,114 +662,3 @@ mcp__ai-proj__export_task_document_to_file
 - 数据安全分级
 - 敏感操作审计
 - 权限最小化原则
-
---
-
-## PRD 评审方法论
-
-PRD 评审是需求流程的关键质量关卡。
-
-### 评审流程
-
-```
-PRD 提交 → 结构检查 → 清晰度评估 → 技术可行性 → 数据模型 → API 审查 → 结论
-```
-
-### 结构完整性检查
-
-| 检查项 | 必须 | 说明 |
-|--------|:----:|------|
-| 基本信息 | ✓ | 编号、标题、日期、作者 |
-| 需求背景 | ✓ | 为什么需要这个功能 |
-| 目标用户 | ✓ | 面向的用户群体 |
-| 功能描述 | ✓ | 详细功能需求 |
-| 数据模型 | ✓ | 数据库表结构 |
-| API 设计 | ✓ | RESTful 接口 |
-| 验收标准 | ✓ | 验收条件 |
-| 用户故事 | ○ | As a... I want... |
-| 页面原型 | ○ | 界面布局 |
-| 非功能需求 | ○ | 性能、安全 |
-
-### 需求清晰度（SMART 原则）
-
-| 原则 | 检查点 |
-|------|--------|
-| **S**pecific | 描述是否具体明确 |
-| **M**easurable | 是否有量化指标 |
-| **A**chievable | 技术上是否可行 |
-| **R**elevant | 是否与业务目标相关 |
-| **T**ime-bound | 是否有时间范围 |
-
-**示例**：
- ❌ "用户可以搜索需求"
- ✅ "用户可按编号精确搜索、按标题模糊搜索、按状态筛选，结果分页显示"
-
-### 技术可行性
-
-| 维度 | 评估内容 |
-|------|----------|
-| 技术栈兼容 | 现有栈是否支持 |
-| 架构影响 | 是否需修改架构 |
-| 第三方依赖 | 是否引入新依赖 |
-| 性能影响 | 潜在性能问题 |
-| 安全考量 | 安全风险 |
-
-### 数据模型验证
-
-| 检查项 | 说明 |
-|--------|------|
-| 表结构 | 字段类型、约束、索引 |
-| 关联关系 | 外键、多对多 |
-| 命名规范 | 符合项目规范 |
-| 扩展性 | 预留扩展字段 |
-| 查询性能 | 常用查询有索引 |
-
-### API 设计审查
-
-| 检查项 | 标准 |
-|--------|------|
-| RESTful | URL 用名词，HTTP 方法语义正确 |
-| 响应格式 | `{success, data, message}` |
-| 错误处理 | 明确的错误码 |
-| 分页 | `?page=1&page_size=20` |
-| 版本控制 | `/api/v1/...` |
-
-### 评审结论模板
-
-**通过**：
-```
-✅ PRD 评审通过
-
-【结论】文档完整，需求清晰，方案可行，建议批准。
-【肯定】需求背景清晰、数据模型合理、API 规范
-【建议】（非阻塞）补充性能测试用例
-【评审人】xxx  【时间】2026-xx-xx
-```
-
-**驳回**：
-```
-❌ PRD 评审驳回
-
-【原因】
-1. 数据模型缺少索引
-2. API 缺少错误处理
-3. 搜索需求描述模糊
-
-【修改要求】
-□ 补充索引设计
-□ 明确错误码
-□ 细化搜索实现
-
-【驳回人】xxx  【时间】2026-xx-xx
-```
-
-### 常见驳回原因
-
-| 类别 | 问题 | 建议 |
-|------|------|------|
-| 结构缺失 | 缺数据模型或 API | 补充技术设计 |
-| 需求模糊 | 描述不具体 | 按 SMART 重写 |
-| 边界不清 | 缺异常处理 | 补充边界条件 |
-| 设计缺陷 | 模型/API 不合理 | 重新设计 |
-| 范围过大 | 难以实现 | 拆分为多需求 |
-| 验收不明 | 缺验收标准 | 补充验收条件 |
--- a/skills-req/req-prototype-plugin/.claude-plugin/plugin.json
+++ b/skills-req/req-prototype-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "req-prototype-plugin",
+  "description": "Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型。",
+  "version": "1.0.0",
+  "author": {
+    "name": "qiudl"
+  }
+}
--- a/skills-req/req-prototype-plugin/skills/SKILL.md
+++ b/skills-req/req-prototype-plugin/skills/SKILL.md
@@ -0,0 +1,164 @@
+---
+name: req-prototype
+description: Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型，支持编辑和变体生成。当执行 /req prototype 或需要生成界面原型时使用。
+arguments: [REQ-ID] [--device desktop|mobile|tablet] [--model pro|flash] [--prompt "..."]
+---
+
+# Stitch 原型设计 Skill (req-prototype)
+
+## 概述
+
+基于 PRD 文档自动生成 Stitch UI 原型，插入在 PRD 编写完成后、submit 评审前。
+
+**核心流程**：读取 PRD → 提取 UI 描述 → 转英文 prompt → 调用 Stitch API → 截图回填 PRD
+
+## 前置条件
+
+执行前必须检查：
+
+| 检查项 | 方式 | 失败处理 |
+|--------|------|----------|
+| 需求存在 | `ai-proj req get --id <id>` | 报错：需求不存在 |
+| PRD 文档存在 | `ai-proj req tasks --id <id>` 找 linkRole=prd 任务 + 检查文档 | 报错：请先执行 req-prd 编写 PRD |
+| PRD 包含 UI 描述 | 检查 PRD 中「功能需求」「交互设计」「界面原型」章节 | 警告：PRD 未包含 UI 相关描述，建议先补充 |
+
+## 子命令
+
+### 1. `/req prototype [REQ-ID]` — 生成原型
+
+**流程**：
+
+```
+1. 前置条件检查
+2. 读取 PRD 文档（ai-proj task get-doc）
+3. 提取 UI 相关内容（功能需求 + 交互设计章节）
+4. PRD → Stitch Prompt 转换（中文 → 英文设计描述）
+5. 创建 Stitch 项目（mcp__stitch__create_project）
+6. 生成页面（mcp__stitch__generate_screen_from_text）
+7. 获取截图（mcp__stitch__get_screen）
+8. 回填 PRD「4.2 界面原型」章节
+```
+
+**参数**：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--device` | `desktop` | 设备类型：desktop / mobile / tablet |
+| `--model` | `pro` | 模型：pro (GEMINI_3_1_PRO) / flash (GEMINI_3_FLASH) |
+
+### 2. `/req prototype edit [REQ-ID] --prompt "..."` — 编辑原型
+
+**流程**：
+
+```
+1. 从 PRD「4.2 界面原型」元数据获取 stitch_project_id 和 screen_id
+2. 调用 mcp__stitch__edit_screens 编辑指定页面
+3. 获取更新后截图
+4. 更新 PRD「4.2 界面原型」章节
+```
+
+### 3. `/req prototype variant [REQ-ID]` — 生成变体
+
+**流程**：
+
+```
+1. 从 PRD「4.2 界面原型」元数据获取 stitch_project_id 和 screen_id
+2. 调用 mcp__stitch__generate_variants 生成变体
+3. 展示所有变体截图供用户选择
+4. 用户选择后更新 PRD
+```
+
+**变体参数**：
+
+| 参数 | 选项 | 说明 |
+|------|------|------|
+| `creativeRange` | REFINE / EXPLORE / REIMAGINE | 创意程度 |
+| `aspects` | LAYOUT / COLOR_SCHEME / IMAGES / TEXT_FONT / TEXT_CONTENT | 变化维度 |
+
+## PRD → Stitch Prompt 转换策略
+
+从 PRD 提取以下章节内容，转换为英文设计 prompt：
+
+1. **功能需求**（第 3 章）→ 提取功能列表和交互描述
+2. **交互设计**（第 4 章）→ 提取用户流程和界面描述
+3. **目标用户**（第 2 章）→ 确定设计风格和复杂度
+
+**转换模板**：
+
+```
+Design a [device_type] web application for [product_name].
+
+Target users: [user_description]
+
+Key features:
+- [feature_1]: [description]
+- [feature_2]: [description]
+...
+
+User flow:
+1. [step_1]
+2. [step_2]
+...
+
+UI requirements:
+- [layout_requirement]
+- [interaction_requirement]
+...
+
+Style: Clean, modern, professional SaaS interface with clear navigation.
+```
+
+## Stitch API 参数映射
+
+| 用户参数 | Stitch API 参数 | 值映射 |
+|----------|-----------------|--------|
+| `--device desktop` | `deviceType` | `DESKTOP` |
+| `--device mobile` | `deviceType` | `MOBILE` |
+| `--device tablet` | `deviceType` | `TABLET` |
+| `--model pro` | `modelId` | `GEMINI_3_1_PRO` |
+| `--model flash` | `modelId` | `GEMINI_3_FLASH` |
+
+## PRD 回填逻辑
+
+定位 PRD 中 `### 4.2 界面原型` 章节，替换内容为：
+
+```markdown
+### 4.2 界面原型
+
+> Stitch AI 自动生成原型，基于本 PRD 功能需求和交互设计。
+
+**原型预览**：
+
+| 页面 | 截图 | 说明 |
+|------|------|------|
+| [screen_name_1] | ![screenshot](screenshot_url_1) | [描述] |
+| [screen_name_2] | ![screenshot](screenshot_url_2) | [描述] |
+
+**Stitch 项目信息**：
+```yaml
+stitch_project_id: "<project_id>"
+screens:
+  - id: "<screen_id_1>"
+    name: "<screen_name_1>"
+    device: "<device_type>"
+  - id: "<screen_id_2>"
+    name: "<screen_name_2>"
+    device: "<device_type>"
+model: "<model_id>"
+generated_at: "<timestamp>"
+```
+
+**编辑原型**：`/req prototype edit [REQ-ID] --prompt "修改说明"`
+**生成变体**：`/req prototype variant [REQ-ID]`
+```
+
+## 异常处理
+
+| 异常 | 处理 |
+|------|------|
+| 需求无 PRD 文档 | 报错：`请先使用 req-prd 技能编写 PRD 文档` |
+| PRD 无 UI 相关描述 | 警告并询问：`PRD 未包含明确的 UI 描述，是否基于功能需求自动推断？` |
+| Stitch API 超时 | 提示：`Stitch 生成耗时约 1-2 分钟，请稍候...` 超过 3 分钟报错 |
+| Stitch API 返回错误 | 展示错误信息，建议调整 prompt 或更换模型 |
+| PRD 无「4.2 界面原型」章节 | 在「## 4. 交互设计」末尾自动追加该章节 |
+| 已有原型元数据 | 询问：`已存在原型，是否覆盖？` |
--- a/skills-req/req-review-plugin/.claude-plugin/plugin.json
+++ b/skills-req/req-review-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "req-review-plugin",
+  "description": "PRD 评审方法论。用于需求评审、PRD 文档审查、评审意见编写。",
+  "version": "1.0.0",
+  "author": {
+    "name": "qiudl"
+  }
+}
--- a/skills-req/req-review-plugin/skills/SKILL.md
+++ b/skills-req/req-review-plugin/skills/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: req-review
+description: PRD 评审方法论。用于需求评审、PRD 文档审查、评审意见编写。当执行 /req review 或需要评审 PRD 文档时使用。
+---
+
+# PRD 评审方法论
+
+PRD 评审是需求流程的关键质量关卡。
+
+## 评审流程
+
+```
+PRD 提交 → 结构检查 → 清晰度评估 → 技术可行性 → 数据模型 → API 审查 → 结论
+```
+
+## 结构完整性检查
+
+| 检查项 | 必须 | 说明 |
+|--------|:----:|------|
+| 基本信息 | ✓ | 编号、标题、日期、作者 |
+| 需求背景 | ✓ | 为什么需要这个功能 |
+| 目标用户 | ✓ | 面向的用户群体 |
+| 功能描述 | ✓ | 详细功能需求 |
+| 数据模型 | ✓ | 数据库表结构 |
+| API 设计 | ✓ | RESTful 接口 |
+| 验收标准 | ✓ | 验收条件 |
+| 用户故事 | ○ | As a... I want... |
+| 页面原型 | ○ | 如有 Stitch 原型则必审：布局合理性、与 PRD 描述一致性 |
+| 非功能需求 | ○ | 性能、安全 |
+
+## 需求清晰度（SMART 原则）
+
+| 原则 | 检查点 |
+|------|--------|
+| **S**pecific | 描述是否具体明确 |
+| **M**easurable | 是否有量化指标 |
+| **A**chievable | 技术上是否可行 |
+| **R**elevant | 是否与业务目标相关 |
+| **T**ime-bound | 是否有时间范围 |
+
+**示例**：
+- ❌ "用户可以搜索需求"
+- ✅ "用户可按编号精确搜索、按标题模糊搜索、按状态筛选，结果分页显示"
+
+## 技术可行性
+
+| 维度 | 评估内容 |
+|------|----------|
+| 技术栈兼容 | 现有栈是否支持 |
+| 架构影响 | 是否需修改架构 |
+| 第三方依赖 | 是否引入新依赖 |
+| 性能影响 | 潜在性能问题 |
+| 安全考量 | 安全风险 |
+
+## 数据模型验证
+
+| 检查项 | 说明 |
+|--------|------|
+| 表结构 | 字段类型、约束、索引 |
+| 关联关系 | 外键、多对多 |
+| 命名规范 | 符合项目规范 |
+| 扩展性 | 预留扩展字段 |
+| 查询性能 | 常用查询有索引 |
+
+## API 设计审查
+
+| 检查项 | 标准 |
+|--------|------|
+| RESTful | URL 用名词，HTTP 方法语义正确 |
+| 响应格式 | `{success, data, message}` |
+| 错误处理 | 明确的错误码 |
+| 分页 | `?page=1&page_size=20` |
+| 版本控制 | `/api/v1/...` |
+
+## 界面原型检查（如有）
+
+当 PRD 包含 Stitch 生成的原型时，评审人应检查：
+
+| 检查项 | 说明 |
+|--------|------|
+| 页面覆盖 | 原型页面覆盖了 PRD 中描述的主要功能 |
+| 布局一致 | 布局与 PRD 功能描述一致（无遗漏关键元素） |
+| 交互合理 | 导航、表单、操作按钮逻辑合理 |
+| 数据展示 | 列表、详情、表单字段完整 |
+
+## 评审结论模板
+
+**通过**：
+```
+✅ PRD 评审通过
+
+【结论】文档完整，需求清晰，方案可行，建议批准。
+【肯定】需求背景清晰、数据模型合理、API 规范
+【建议】（非阻塞）补充性能测试用例
+【评审人】xxx  【时间】2026-xx-xx
+```
+
+**驳回**：
+```
+❌ PRD 评审驳回
+
+【原因】
+1. 数据模型缺少索引
+2. API 缺少错误处理
+3. 搜索需求描述模糊
+
+【修改要求】
+□ 补充索引设计
+□ 明确错误码
+□ 细化搜索实现
+
+【驳回人】xxx  【时间】2026-xx-xx
+```
+
+## 常见驳回原因
+
+| 类别 | 问题 | 建议 |
+|------|------|------|
+| 结构缺失 | 缺数据模型或 API | 补充技术设计 |
+| 需求模糊 | 描述不具体 | 按 SMART 重写 |
+| 边界不清 | 缺异常处理 | 补充边界条件 |
+| 设计缺陷 | 模型/API 不合理 | 重新设计 |
+| 范围过大 | 难以实现 | 拆分为多需求 |
+| 验收不明 | 缺验收标准 | 补充验收条件 |
--- a/skills-req/req-workflow-plugin/.claude-plugin/plugin.json
+++ b/skills-req/req-workflow-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "req-workflow-plugin",
+  "description": "需求完整工作流。从创建到归档的完整流程、Hook 自动同步、测试环境流程。",
+  "version": "1.0.0",
+  "author": {
+    "name": "qiudl"
+  }
+}
--- a/skills-req/req-workflow-plugin/skills/SKILL.md
+++ b/skills-req/req-workflow-plugin/skills/SKILL.md
@@ -0,0 +1,184 @@
+---
+name: req-workflow
+description: 需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。
+---
+
+# 需求完整工作流
+
+从 PRD 到归档的完整流程。
+
+## 完整流程概览（阶段化）
+
+```
+1. /req new         → 创建需求 (draft)
+2. req-prd 技能     → 编写 PRD（创建【评审】PRD 任务）
+2.5 /req prototype  → 生成 Stitch 原型（可选，有 UI 时推荐）
+3. /req review      → 提交评审 (pending)
+4. /req review pass → 评审通过 (approved, delivery_stage=analysis)
+5. /req next        → 推进到 design/dev 阶段
+6. /req dev         → 启动开发（创建【开发】任务, delivery_stage=dev）
+7. req-dev 技能     → 编写开发文档
+8. /req next        → 推进到 review 阶段
+9. /req cr          → 代码评审（创建【代码评审】任务, delivery_stage=review）
+10. /req next       → 推进到 testing 阶段
+11. /req test       → 测试验收（创建【测试】任务, delivery_stage=testing）
+12. /req next       → 推进到 staging 阶段
+13. /req deploy staging  → 部署 staging（创建【部署】任务, delivery_stage=staging）
+14. /req next       → 推进到 released 阶段
+15. /req deploy prod     → 部署生产（创建【部署】任务, delivery_stage=released）
+16. /req done       → 归档 (archived)
+```
+
+**每个阶段都有明确的任务、检查点和交付物，防止遗漏。**
+
+## 5 阶段文档
+
+| 阶段 | 文档名 | 技能 |
+|------|--------|------|
+| PRD | 01-PRD.md | `req-prd` |
+| 开发 | 02-开发设计.md | `req-dev` |
+| 测试 | 03-测试报告.md | 自动生成 |
+| 发布 | 04-发布记录.md | 自动生成 |
+| 归档 | 05-生命周期总结.md | 自动生成 |
+
+> 注：Stitch 原型不单独编号，嵌入 01-PRD.md 的「4.2 界面原型」章节。
+
+## Hook 自动同步
+
+需求操作自动触发同步，无需手动执行：
+
+| 事件 | 触发操作 |
+|------|----------|
+| `requirement.created` | 同步到远程 |
+| `requirement.approved` | 同步需求和任务 |
+| `task.completed` | 同步任务状态 |
+| `requirement.archived` | 最终同步 + 思源笔记 |
+
+**手动同步**（如需）：
+```typescript
+mcp__ai-proj__sync_requirement_to_remote(requirementId)
+mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)
+```
+
+## 测试环境流程
+
+**必须按顺序执行，任何阶段失败后从本机重新开始**：
+
+```
+[本机] → 通过 → [预发布] → 通过 → [生产]
+   ↑                 │              │
+   └─────────────────┴──── 失败 ────┘
+```
+
+| 环境 | 用途 | 验证方式 |
+|------|------|----------|
+| 本机 | 开发调试 | `go test ./...` |
+| 预发布 | 集成测试 | API 验证 |
+| 生产 | 最终验收 | API + 功能验证 |
+
+## 任务关联规范
+
+创建任务时设置 `link_role` 并加阶段前缀：
+
+| link_role | 阶段前缀 | 所属阶段 | 权重 |
+|-----------|----------|----------|------|
+| prd | 【评审】 | analysis | 10% |
+| design | 【评审】 | design | 5% |
+| implementation | 【开发】 | dev | 50% |
+| code_review | 【代码评审】 | review | 5% |
+| test | 【测试】 | testing | 15% |
+| deploy | 【部署】 | staging/released | 10% |
+| documentation | 【文档】 | any | 5% |
+
+**进度计算**：按 link_role 权重统计已完成任务。
+
+## 标准任务结构（阶段化）
+
+```
+需求 REQ-xxx
+├── 📝 analysis 阶段
+│   └── 【评审】PRD: {需求标题}                    (linkRole: prd)
+├── 📐 design 阶段
+│   └── 【评审】技术设计: {需求标题}                (linkRole: design)
+├── 💻 dev 阶段
+│   ├── 【开发-后端】{描述}                        (linkRole: implementation)
+│   └── 【开发-前端】{描述}                        (linkRole: implementation)
+├── 🔍 review 阶段
+│   └── 【代码评审】CR: {需求标题}                  (linkRole: code_review)
+├── 🧪 testing 阶段
+│   └── 【测试】集成测试: {需求标题}                (linkRole: test)
+├── 🚀 staging 阶段
+│   └── 【部署】部署到 staging (singapore)          (linkRole: deploy)
+└── 🏁 released 阶段
+    ├── 【部署】部署到 prod (tools_ai_proj)         (linkRole: deploy)
+    └── 【验收】功能验收确认                        (linkRole: documentation)
+```
+
+**命名规则**：所有任务标题必须以阶段前缀开头（如【评审】、【开发】、【部署】）。
+
+## 环境配置
+
+**双环境 MCP 配置**：区分开发测试和生产环境
+
+```json
+// ~/.claude/.mcp.json
+{
+  "mcpServers": {
+    "ai-proj-dev": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/mcp-task-bridge/dist/index.js"],
+      "env": {
+        "TASK_API_BASE": "http://localhost:8080/api/v1",
+        "TASK_API_TOKEN": "aiproj_pk_xxx...",
+        "NODE_ENV": "development"
+      }
+    },
+    "ai-proj-prod": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/mcp-task-bridge/dist/index.js"],
+      "env": {
+        "TASK_API_BASE": "https://ai.pipexerp.com/api/v1",
+        "TASK_API_TOKEN": "aiproj_pk_xxx...",
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
+```
+
+**环境使用指南**：
+
+| 环境 | 使用场景 | 工具前缀 |
+|------|----------|----------|
+| `ai-proj-dev` | 功能测试、流程验证、本地调试 | `mcp__ai-proj-dev__*` |
+| `ai-proj-prod` | 正式需求管理、生产数据操作 | `mcp__ai-proj-prod__*` |
+
+**跨机器支持**：
+- `ai-proj-dev` 支持 melbourne 和 adelaide 机器的本地环境（都是 localhost:8080）
+- 无论在哪台开发机器上，都使用 `ai-proj-dev` 连接本地 API
+
+**项目配置**：
+```json
+// .claude/settings.local.json
+{
+  "env": {
+    "REQUIREMENT_PROJECT": "coolbuy-paas"
+  }
+}
+```
+
+## 思源笔记集成
+
+归档时自动同步 5 阶段文档到思源笔记：
+- 路径：`需求管理/REQ-XXXX/`
+- 文档：01-PRD.md ~ 05-生命周期总结.md
+
+手动同步：`/req sync-siyuan [REQ-ID]`
+
+## 邮件通知
+
+发送邮件：`/req notify [REQ-ID] --type <prd|dev|test|deploy|archive>`
+
+默认收件人：项目邮件组（见项目配置）