---
name: req-workflow
description: 需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。
---

# 需求完整工作流

从 PRD 到归档的完整流程。

## 需求创建环境选择

> **重要**：正式需求应直接在**生产环境** (`mcp__ai-proj-prod__*`) 创建。
> 仅在功能测试、流程验证时使用开发环境 (`mcp__ai-proj-dev__*`)。
> 如果在开发环境创建了需求后同步到生产，`due_date`、`reviewer_id`、`allow_self_approve` 等字段会丢失，需手动补充。

## 完整流程概览（阶段化）

```
1. /req new         → 创建需求 (draft)
2. req-prd 技能     → 编写 PRD（创建【评审】PRD 任务）
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 | 自动生成 |

## 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 | ✅ | 正常同步 |
| project_id | ✅ | 正常同步 |
| **due_date** | ❌ | **不会同步**，需手动通过 REST API 在目标环境补充 |
| reviewer_id | ❌ | 不会同步 |
| allow_self_approve | ❌ | 不会同步 |

> **经验教训**（2026-02-20）：`sync_requirement_to_remote` 不同步 `due_date` 字段。同步后务必在目标环境验证并手动补充缺失字段。

## 测试环境流程

**必须按顺序执行，任何阶段失败后从本机重新开始**：

```
[本机] → 通过 → [预发布] → 通过 → [生产]
   ↑                 │              │
   └─────────────────┴──── 失败 ────┘
```

| 环境 | 用途 | 验证方式 |
|------|------|----------|
| 本机 | 开发调试 | `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>`

默认收件人：项目邮件组（见项目配置）