feat(req): 部署门禁制度 — PDV 验收任务 + Deploy Gate 1-3

在 /req deploy 流程中增加部署后 E2E 验收（Post-Deploy Verification）门禁： - 新增 verification linkRole 和【验收】任务命名规范 - Deploy Gate 1 健康检查 / Gate 2 PDV 任务完成 / Gate 3 证据完整 - PDV Playwright spec 模板（页面可达、菜单可见、API 连通） - 同步更新 req-workflow、dev-test、e2e-testing 相关文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-31 09:34:08 +10:30
parent b9c808cce0
commit 187f5621c9
5 changed files with 270 additions and 16 deletions
--- a/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md
+++ b/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md
@@ -15,6 +15,7 @@ description: 软件测试技能。用于单元测试、集成测试、E2E测试
 | `android-testing.md` | Android 测试 (JUnit + Espresso + Compose) |
 | `e2e-testing.md` | E2E Playwright：API Mock 冒烟测试（无后端）+ 全链路集成测试 |
 | `templates/go-integration-test.md` | Go 集成测试模板（多步骤 API 流程、中间件验证、租户隔离） |
+| `templates/pdv-smoke-spec.md` | PDV 部署后验收 Playwright 模板（页面可达、菜单可见、API 连通） |

 ---

@@ -50,6 +51,7 @@ description: 软件测试技能。用于单元测试、集成测试、E2E测试
 | E2E (Mock 冒烟) | `npm run test:e2e:smoke-mock` | `e2e-testing.md` §API Mock |
 | E2E (全链路) | `npm run test:e2e` | `e2e-testing.md` §全链路 |
 | E2E (Coolbuy PaaS) | `make e2e` | `e2e-testing.md` §Coolbuy |
+| E2E (部署后验收 PDV) | `E2E_BASE_URL=<url> npx playwright test e2e/pdv/` | §PDV |

 ---

@@ -145,6 +147,60 @@ ai-proj task append-doc --id <taskId> --content "# 测试报告

 ---

+## 部署后 E2E 验收 (PDV — Post-Deploy Verification)
+
+部署后验收是独立于 TG4 的 E2E 冒烟模式，在 `/req deploy` 健康检查通过后执行。
+
+### PDV vs TG4 区别
+
+| 维度 | TG4 (开发阶段 E2E 冒烟) | PDV (部署后验收) |
+|------|------------------------|-----------------|
+| **触发时机** | `/req test` Gate 4 | `/req deploy` 步骤 6 |
+| **环境** | 本地开发环境，API Mock | 真实部署环境 (staging/prod) |
+| **目的** | 验证前端逻辑、UI 渲染 | 验证功能入口可达、基本可用 |
+| **API** | `page.route()` 拦截 | 真实后端 API |
+| **范围** | 回归冒烟 | 仅新功能可达性 |
+
+### PDV 检查项
+
+| 检查项 | 说明 | 示例 |
+|--------|------|------|
+| **页面可达** | 需求涉及的前端页面返回 200 | `/okr/my`, `/okr/team` |
+| **菜单可见** | 新增菜单项在侧栏中出现 | OKR 菜单对目标用户角色可见 |
+| **基础渲染** | 页面无白屏/JS 报错 | 页面有预期的标题/组件 |
+| **API 连通** | 关键 API 带 token 调用返回正常 | `GET /api/v1/okr/objectives` 返回 200 |
+
+### PDV 不做什么
+
+- 不做完整回归测试（那是 TG4 的事）
+- 不测试复杂业务流程（如多步骤表单提交）
+- 不替代手动验收
+- 只做「功能入口可达 + 基本可用」的冒烟验证
+
+### PDV 执行方式
+
+```bash
+E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium
+```
+
+### PDV Spec 生成规则
+
+AI 根据需求变更范围动态生成 Playwright spec，模板见 `templates/pdv-smoke-spec.md`。生成流程：
+
+1. 从需求关联任务提取前端变更范围（页面路由、菜单项、API 端点）
+2. 登录测试账号（使用 storageState 或手动登录）
+3. 验证新增菜单项可见（检查 `.ant-menu` 包含目标文本）
+4. 导航到新页面，验证非白屏（title 不含 error/500/404）
+5. 调用关键 API，验证返回状态码 < 500
+6. 每步截图保存为证据
+
+### PDV 结果判定
+
+- **全部 PASS** → 继续推进到 released
+- **任一 FAIL** → 阻断推进，在部署文档记录失败项，通知修复
+
+---
+
 ## TG2 集成测试检测

 ### 模板映射
--- a/skills-dev/dev-test-plugin/skills/dev-test/e2e-testing.md
+++ b/skills-dev/dev-test-plugin/skills/dev-test/e2e-testing.md
@@ -1,14 +1,17 @@
 # E2E 测试 (Playwright)

-## 两种 E2E 测试模式
+## 三种 E2E 测试模式

 | 模式 | 后端依赖 | 速度 | 适用场景 | 门禁阶段 |
 |------|---------|------|---------|---------|
-| **API Mock 冒烟测试** | ❌ 无需后端 | 快（<30s） | UI 布局、路由、菜单、权限隔离 | E2E 冒烟门禁 |
+| **API Mock 冒烟测试** | ❌ 无需后端 | 快（<30s） | UI 布局、路由、菜单、权限隔离 | TG4 E2E 冒烟门禁 |
 | **全链路集成测试** | ✅ 需完整后端+DB | 慢（分钟级） | CRUD 业务流程、数据持久化 | 手动/CI |
+| **部署后验收 (PDV)** | ✅ 真实部署环境 | 中（<2min） | 功能入口可达、菜单可见、API 连通 | `/req deploy` 步骤 6 |

 **⚠️ 关键原则：E2E 冒烟门禁必须使用 API Mock 模式，不依赖后端。** 依赖后端的 E2E 在开发机上经常跑不通（后端没启动、DB 未初始化），导致门禁形同虚设。

+> **PDV 与 TG4 的区别**：TG4 在开发阶段用 API Mock 验证前端逻辑；PDV 在部署后用真实环境验证功能可达性。详见 `SKILL.md` §PDV 章节。
+
 > **与 req-test-gate 的关系**：本文档定义 E2E 测试的**执行技术**（怎么写 mock、怎么跑）。质量门禁流程（Gates 0-5、scope 分级、文档持久化）定义在 `req-test-gate` 技能中。

 ---
--- a/skills-dev/dev-test-plugin/skills/dev-test/templates/pdv-smoke-spec.md
+++ b/skills-dev/dev-test-plugin/skills/dev-test/templates/pdv-smoke-spec.md
@@ -0,0 +1,147 @@
+# PDV Smoke Spec 模板
+
+部署后验收 (Post-Deploy Verification) Playwright 测试模板。AI 根据需求变更范围，基于此模板动态生成验收 spec。
+
+## 使用方式
+
+```bash
+# 指定部署环境 URL 执行
+E2E_BASE_URL=https://staging.example.com npx playwright test e2e/pdv/ --project=chromium
+```
+
+## Spec 模板结构
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:3000';
+
+test.describe('PDV: {需求标题}', () => {
+
+  test.beforeEach(async ({ page }) => {
+    // 方式 1: 使用 storageState（推荐，需预先保存登录状态）
+    // test.use({ storageState: 'e2e/.auth/user.json' });
+
+    // 方式 2: 手动登录
+    await page.goto(`${BASE_URL}/login`);
+    await page.fill('input[name="username"]', '{测试账号}');
+    await page.fill('input[name="password"]', '{测试密码}');
+    await page.click('button[type="submit"]');
+    await page.waitForURL('**/dashboard/**');
+  });
+
+  test('菜单可见性: {菜单名}', async ({ page }) => {
+    await page.goto(`${BASE_URL}/`);
+    await page.waitForSelector('.ant-menu');
+
+    // 检查侧栏包含新菜单项
+    const menu = page.locator('.ant-menu');
+    await expect(menu).toContainText('{菜单名}');
+
+    // 截图证据
+    await page.screenshot({ path: 'e2e-results/pdv-menu-{菜单名}.png', fullPage: false });
+  });
+
+  test('页面可达: {页面路由}', async ({ page }) => {
+    const response = await page.goto(`${BASE_URL}{页面路由}`);
+
+    // 验证 HTTP 状态
+    expect(response?.status()).toBeLessThan(400);
+
+    // 验证非白屏 — title 不含错误关键词
+    await expect(page).not.toHaveTitle(/error|500|404|not found/i);
+
+    // 验证页面有核心内容（非空白）
+    await expect(page.locator('{核心选择器}')).toBeVisible({ timeout: 10000 });
+
+    // 检查无 JS 报错（通过 console error 监听）
+    const errors: string[] = [];
+    page.on('console', msg => {
+      if (msg.type() === 'error') errors.push(msg.text());
+    });
+    await page.waitForTimeout(2000);
+    expect(errors.filter(e => !e.includes('favicon'))).toHaveLength(0);
+
+    // 截图证据
+    await page.screenshot({ path: 'e2e-results/pdv-page-{页面名}.png', fullPage: true });
+  });
+
+  test('API 连通: {接口描述}', async ({ request }) => {
+    // 需要带认证 token 调用
+    const resp = await request.get(`${BASE_URL}/api/v1/{路径}`, {
+      headers: {
+        'Authorization': 'Bearer {token}',
+      },
+    });
+
+    // 验证非 5xx 错误
+    expect(resp.status()).toBeLessThan(500);
+
+    // 可选：验证响应结构
+    // const body = await resp.json();
+    // expect(body).toHaveProperty('data');
+  });
+
+});
+```
+
+## 占位符说明
+
+| 占位符 | 含义 | 来源 |
+|--------|------|------|
+| `{需求标题}` | 需求名称 | `ai-proj req get --id <id>` |
+| `{菜单名}` | 新增的菜单文本 | 从需求关联的前端任务中提取 |
+| `{页面路由}` | 新增/变更的前端路由 | 从前端路由配置或 PRD 提取 |
+| `{核心选择器}` | 页面核心内容的 CSS 选择器 | 如 `h1`, `.page-title`, `[data-testid="xxx"]` |
+| `{测试账号}` / `{测试密码}` | 测试环境登录凭据 | 环境配置 |
+| `{token}` | API 认证 token | 登录后获取 |
+| `{接口描述}` / `{路径}` | 关键 API 端点 | 从后端路由或 PRD 提取 |
+| `{页面名}` | 截图文件名标识 | 自定义 |
+
+## 生成示例（OKR 功能）
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:3000';
+
+test.describe('PDV: OKR 团队/对齐/设置/评分功能', () => {
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto(`${BASE_URL}/login`);
+    await page.fill('input[name="username"]', 'testuser');
+    await page.fill('input[name="password"]', 'TestPass123');
+    await page.click('button[type="submit"]');
+    await page.waitForURL('**/dashboard/**');
+  });
+
+  test('菜单可见性: OKR', async ({ page }) => {
+    await page.goto(`${BASE_URL}/`);
+    await page.waitForSelector('.ant-menu');
+    await expect(page.locator('.ant-menu')).toContainText('OKR');
+    await page.screenshot({ path: 'e2e-results/pdv-menu-okr.png' });
+  });
+
+  test('页面可达: /okr/my', async ({ page }) => {
+    const response = await page.goto(`${BASE_URL}/okr/my`);
+    expect(response?.status()).toBeLessThan(400);
+    await expect(page).not.toHaveTitle(/error|500|404/i);
+    await expect(page.locator('h1, .page-title')).toBeVisible({ timeout: 10000 });
+    await page.screenshot({ path: 'e2e-results/pdv-page-okr-my.png', fullPage: true });
+  });
+
+  test('页面可达: /okr/team', async ({ page }) => {
+    const response = await page.goto(`${BASE_URL}/okr/team`);
+    expect(response?.status()).toBeLessThan(400);
+    await expect(page).not.toHaveTitle(/error|500|404/i);
+    await expect(page.locator('h1, .page-title')).toBeVisible({ timeout: 10000 });
+    await page.screenshot({ path: 'e2e-results/pdv-page-okr-team.png', fullPage: true });
+  });
+
+  test('API 连通: OKR objectives', async ({ request }) => {
+    const resp = await request.get(`${BASE_URL}/api/v1/okr/objectives`);
+    expect(resp.status()).toBeLessThan(500);
+  });
+
+});
+```
--- a/skills-req/req-plugin/skills/SKILL.md
+++ b/skills-req/req-plugin/skills/SKILL.md
@@ -108,9 +108,23 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD
 |------|--------|------|
 | PRD | 01-PRD.md | `req-prd` |
 | 测试 | 02-测试报告.md | 自动生成 |
-| 发布 | 03-发布记录.md | 自动生成 |
+| 发布 | 03-发布记录.md | 自动生成（含 PDV 验收章节） |
 | 归档 | 04-生命周期总结.md | 自动生成 |

+**03-发布记录.md 中 PDV 章节模板**：
+
+```markdown
+### 部署后验收 (PDV)
+| 检查项 | 结果 | 截图 |
+|--------|------|------|
+| 页面可达: /path/to/page | ✅ PASS | [截图] |
+| 菜单可见: {菜单名} | ✅ PASS | [截图] |
+| 基础渲染: 无白屏/JS 报错 | ✅ PASS | [截图] |
+| API: /api/v1/{路径} | ✅ PASS | — |
+
+PDV 结论: ✅ 全部通过 / ❌ {N}项失败，阻断推进
+```
+
 ## 任务命名规范

 | linkRole | 前缀 | 示例 |
@@ -121,6 +135,7 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD
 | code_review | 【代码评审】 | 【代码评审】CR: 代码审查 |
 | test | 【测试】 | 【测试】集成测试验证 |
 | deploy | 【部署】 | 【部署】部署到 staging |
+| verification | 【验收】 | 【验收】PDV: OKR 功能部署验收 |
 | documentation | 【文档】 | 【文档】API 文档更新 |

 ## 阶段内容门禁（防空转）
@@ -135,6 +150,24 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD

 未通过 → AskUserQuestion（补充文档 or 强制跳过+记录原因）

+### 部署门禁（推进到 released 前）
+
+`/req deploy` 推进 `released` 前，必须通过 3 道门禁：
+
+```
+Deploy Gate 1: 健康检查 ── /health 返回 200，服务存活
+Deploy Gate 2: PDV 验收 ── linkRole=verification 的【验收】任务存在且 completed
+Deploy Gate 3: 证据完整 ── 验收任务有文档，含检查项表格 + E2E 截图 + 通过/失败结论
+```
+
+**PDV 验收任务生命周期**：
+1. `/req deploy` 步骤 6 自动创建：`ai-proj task create --title "【验收】PDV: {需求标题}"`
+2. 关联需求：`ai-proj req link --id <req_id> --task-ids <task_id> --link-role verification`
+3. 执行 Playwright PDV 冒烟测试
+4. 附加验收文档（检查项表格 + 截图证据 + 结论）：`ai-proj task append-doc --id <task_id>`
+5. **全部通过** → `ai-proj task complete --id <task_id>` → 门禁放行
+6. **任一失败** → 任务保持 in_progress，阻断推进，报告失败项
+
 ### CR 五视角扫描法

 **核心原则**：实现阶段关注"怎么让它跑通"，评审阶段关注"怎么让它出错"。AI 必须**切换到对抗性思维**，逐一用以下 5 个视角扫描代码。
@@ -309,16 +342,26 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD
 **`/req deploy [--project <name>] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）：
 1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
 2. AskUserQuestion 确认范围
-3. `ai-proj task create` 创建部署批次任务
+3. `ai-proj task create` 创建【部署】批次任务（linkRole=deploy）
 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` 批量推进
+6. **Deploy Gate 1: 健康检查** — `/health` 返回 200
+7. **Deploy Gate 2+3: PDV 验收**（为每个需求创建独立验收任务）：
+   a. `ai-proj task create --title "【验收】PDV: {需求标题}"` 创建验收任务
+   b. `ai-proj req link --id <req_id> --task-ids <task_id> --link-role verification` 关联需求
+   c. 从需求关联任务中提取前端变更范围（页面路由、菜单项、关键 API）
+   d. 生成验收检查清单（页面可达 + 菜单可见 + 基础渲染 + API 连通）
+   e. 用 Playwright 对部署环境执行冒烟测试：`E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium`
+   f. 收集截图证据
+   g. `ai-proj task append-doc --id <task_id>` 附加验收文档（检查项表格 + 截图 + 结论）
+   h. **全部通过** → `ai-proj task complete --id <task_id>` → Gate 2+3 放行
+   i. **任一失败** → 任务保持 in_progress，**阻断推进**，报告失败项
+8. `ai-proj task append-doc` 记录【部署】任务文档（构建日志 + 健康检查 + PDV 结果摘要）
+9. `ai-proj req advance --id <id> --to released` 批量推进（仅 Gate 1-3 全部通过的需求）

 **`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
 - **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
- **code 检查**：delivery_stage=released + deploy 任务完成 + 部署文档 + 所有任务完成
+- **code 检查**：delivery_stage=released + deploy 任务完成 + verification 任务完成（PDV 通过） + 部署文档 + 所有任务完成
 - **skill 检查**：delivery_stage≥testing + 所有任务完成
 - **ops 检查**：deploy 任务完成 + 所有任务完成

@@ -347,6 +390,7 @@ ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
 | review | 【约定】{约定名称}（bug 类需求，convention flow 自动创建） | documentation |
 | testing | 【测试】集成测试: {需求标题} | test |
 | deploy | 由 `/req deploy` 批量创建 | deploy |
+| released | 【验收】PDV: {需求标题}（`/req deploy` 自动创建） | verification |

 ## 测试环境流程

@@ -365,7 +409,8 @@ ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
 | implementation | 【开发】 | dev | 50% |
 | code_review | 【代码评审】 | review | 5% |
 | test | 【测试】 | testing | 15% |
-| deploy | 【部署】 | staging/released | 10% |
+| deploy | 【部署】 | staging/released | 5% |
+| verification | 【验收】 | released | 5% |
 | documentation | 【文档】 | any | 5% |

 ## 标准任务结构
@@ -378,7 +423,9 @@ ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
 ├── 🔍 review    → 【代码评审】CR: {需求标题}                 (linkRole: code_review)
 ├── 🧪 testing   → 【测试】集成测试: {需求标题}               (linkRole: test)
 ├── 🚀 staging   → 【部署】部署到 staging                     (linkRole: deploy)
-└── 🏁 released  → 【部署】部署到 prod                        (linkRole: deploy)
+└── 🏁 released
+    ├── 【部署】部署到 prod                                   (linkRole: deploy)
+    └── 【验收】PDV: {需求标题}                               (linkRole: verification)
 ```

 ## ai-proj CLI 速查
@@ -402,7 +449,7 @@ ai-proj req tasks --id <id>               # 查看关联任务

 **开发阶段**: `backlog`, `analysis`, `design`, `dev`, `review`, `integration`, `testing`, `staging`, `released`

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

 ## 相关技能

--- a/skills-req/req-workflow-plugin/skills/SKILL.md
+++ b/skills-req/req-workflow-plugin/skills/SKILL.md
@@ -25,7 +25,7 @@ description: 需求完整工作流。用于从创建到归档的完整流程、H
 12. /req next       → 推进到 staging 阶段
 13. /req deploy staging  → 部署 staging（创建【部署】任务, delivery_stage=staging）
 14. /req next       → 推进到 released 阶段
-15. /req deploy prod     → 部署生产（创建【部署】任务, delivery_stage=released）
+15. /req deploy prod     → 部署生产 + PDV 验收（健康检查 → E2E 验收 → released）
 16. /req done       → 归档 (archived)
 ```

@@ -38,7 +38,7 @@ description: 需求完整工作流。用于从创建到归档的完整流程、H
 | PRD | 01-PRD.md | `req-prd` |
 | 开发 | 02-开发设计.md | `req-dev` |
 | 测试 | 03-测试报告.md | 自动生成 |
-| 发布 | 04-发布记录.md | 自动生成 |
+| 发布 | 04-发布记录.md | 自动生成（含 PDV 验收章节） |
 | 归档 | 05-生命周期总结.md | 自动生成 |

 > 注：Stitch 原型不单独编号，嵌入 01-PRD.md 的「4.2 界面原型」章节。
@@ -74,7 +74,7 @@ mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)
 |------|------|----------|
 | 本机 | 开发调试 | `go test ./...` |
 | 预发布 | 集成测试 | API 验证 |
-| 生产 | 最终验收 | API + 功能验证 |
+| 生产 | 最终验收 | 健康检查 + PDV E2E 验收（页面可达、菜单可见、API 连通） |

 ## 任务关联规范

@@ -87,7 +87,8 @@ mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)
 | implementation | 【开发】 | dev | 50% |
 | code_review | 【代码评审】 | review | 5% |
 | test | 【测试】 | testing | 15% |
-| deploy | 【部署】 | staging/released | 10% |
+| deploy | 【部署】 | staging/released | 5% |
+| verification | 【验收】 | released | 5% |
 | documentation | 【文档】 | any | 5% |

 **进度计算**：按 link_role 权重统计已完成任务。
@@ -111,7 +112,7 @@ mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)
 │   └── 【部署】部署到 staging (singapore)          (linkRole: deploy)
 └── 🏁 released 阶段
    ├── 【部署】部署到 prod (tools_ai_proj)         (linkRole: deploy)
-    └── 【验收】功能验收确认                        (linkRole: documentation)
+    └── 【验收】PDV: {需求标题}                     (linkRole: verification)
 ```

 **命名规则**：所有任务标题必须以阶段前缀开头（如【评审】、【开发】、【部署】）。