【AI Native开发-02】一句需求到可靠交付，中间要过哪四道闸门？

flowchart TB
    A["一句需求"] --> B{"Gate 1 · Spec<br/>正确行为定义了吗？"}
    B -->|通过| C{"Gate 2 · Plan<br/>现状与影响面核清了吗？"}
    C -->|通过| D{"Gate 3 · Implement<br/>改动守在边界内吗？"}
    D -->|通过| E{"Gate 4 · Verify<br/>每条需求有证据吗？"}
    E -->|通过| F["可交付变更"]
    B -. "规则缺口" .-> B
    C -. "架构误判" .-> C
    D -. "越界修改" .-> D
    E -. "证据缺口" .-> E

功能：删除文章

角色：管理员可以删除未公开（hide: true）文章；普通用户和访客不能删除。
状态：已公开（hide 为 false 或缺省）文章不能直接删除。
交互：删除前必须二次确认；用户取消时不发起请求。
安全：服务端再次校验登录状态和管理员权限。
失败：删除失败时保留列表状态，并提供重试提示。
非目标：本次不做回收站、恢复、批量删除和审计日志。

[ ] 角色和目标明确
[ ] 正常、异常和边界流程明确
[ ] 权限和数据规则明确
[ ] 每条规则可转换成测试
[ ] 非目标明确
[ ] 重要规则有 REQ 编号
[ ] 两个人可以得出相同验收结论

REQ-001 管理员可以删除未公开（hide: true）文章
REQ-002 未登录请求返回 401；已登录但非管理员返回 403；两者均无副作用
REQ-003 已公开（hide 为 false 或缺省）文章不能直接删除，返回 409
REQ-004 取消确认不发请求
REQ-005 删除后重新构建仍不存在
REQ-006 删除失败保留页面状态
REQ-007 目标不存在返回 404，重复删除无额外副作用

specs/
  article-delete/
    spec.md          # 上面这份，含 REQ 编号
    plan.md          # 下一节产出
    tests.md          # 文本用例
    verify.md         # 验证证据与结论

1. 读取内容集合 schema 和文章状态字段
2. 找到文章列表页及其数据来源
3. 找到当前鉴权入口和管理员判断方式
4. 设计删除接口，只允许未公开/已归档文章
5. 服务端校验权限和文章状态
6. 设计失败响应：401/403/404/409
7. 先生成接口文本用例，再生成自动化测试
8. 实现接口并运行接口测试
9. 增加删除按钮和二次确认
10. 增加端到端测试并运行受影响测试
11. 检查构建、Diff 和文章索引

Spike 目标：确认删除内容文件后，构建能否正常生成文章列表
时间盒：不超过半天
产物：一段结论，不是一份可合并的实现
结束条件：能回答“删除后构建是否报错、索引是否残留”

任务 1：实现服务端状态和权限判断
任务 2：生成并补齐接口自动化测试
任务 3：实现前端按钮与二次确认
任务 4：生成并调试端到端测试
任务 5：运行受影响测试并检查 Diff

REQ-001
→ 文本用例 TC-001
→ 自动化用例 e2e/article-delete.spec.ts
→ 执行命令和测试环境
→ 日志、截图、响应和结果
→ 人工验收
→ Verify 结论

TC-001 管理员删除未公开文章
Given 当前用户是管理员，目标文章为未公开状态（hide: true）
When 管理员确认删除
Then 删除请求成功，文章从列表消失

TC-002 普通用户越权删除
Given 当前用户不是管理员
When 调用删除接口
Then 返回 403，文章仍然存在

TC-003 取消删除
Given 删除确认弹窗已打开
When 用户点击取消
Then 不发起删除请求，文章仍然存在

TC-004 删除已发布文章
Given 目标文章为已公开状态（hide 为 false 或缺省）
When 管理员确认删除
Then 返回 409，文章仍可访问

// api/article-delete.test.ts
import { describe, it, expect, beforeEach } from "vitest"
import { createArticle, loginAs, cleanup, api, readArticleFromStore } from "./helpers"

describe("DELETE /api/articles/:id", () => {
  beforeEach(async () => {
    await cleanup()
  })

  it("TC-002 普通用户越权删除返回 403，文章仍存在", async () => {
    const article = await createArticle({ hide: true })
    const token = await loginAs("normal_user")

    // api 是已配置 baseURL 的测试客户端，不依赖原生 fetch 猜测相对地址
    const res = await api.delete(`/api/articles/${article.id}`, {
      headers: { Authorization: `Bearer ${token}` },
    })

    expect(res.status).toBe(403)

    // 直接检查受控测试存储，不用公开 GET 是否存在来推断文件状态
    await expect(readArticleFromStore(article.id)).resolves.toMatchObject({
      id: article.id,
      hide: true,
    })
  })

  it("TC-004 已公开文章不可删除，返回 409", async () => {
    const article = await createArticle({ hide: false })
    const token = await loginAs("admin")

    const res = await api.delete(`/api/articles/${article.id}`, {
      headers: { Authorization: `Bearer ${token}` },
    })

    expect(res.status).toBe(409)
    await expect(readArticleFromStore(article.id)).resolves.toMatchObject({
      id: article.id,
      hide: false,
    })
  })
})

// e2e/article-delete.spec.ts
import { test, expect } from "@playwright/test"

test("TC-003 取消确认不发起删除请求", async ({ page }) => {
  await page.goto("/admin/articles")

  let deleteCalled = false
  page.on("request", (req) => {
    if (req.method() === "DELETE") deleteCalled = true
  })

  await page.getByTestId("article-row-unpublished-1").getByTestId("delete-btn").click()
  await expect(page.getByTestId("confirm-dialog")).toBeVisible()
  await page.getByTestId("confirm-cancel").click()

  // 断言「什么都没发生」，比断言「弹窗关了」更接近 Spec 原意
  expect(deleteCalled).toBe(false)
  await expect(page.getByTestId("article-row-unpublished-1")).toBeVisible()
})

写代码时      → 只跑当前改动相关的单元与接口测试（秒级）
提交前        → 跑受影响模块的完整测试 + 类型与静态检查（分钟级）
合并前        → 跑完整回归，包含 E2E（可以接受十几分钟）
发布前        → 冒烟用例 + 人工验收关键路径

现象：已公开文章被成功删除，返回 204
排查：实现读取的是 article.status
根因：Plan/Implement 把 Spec 中的 hide 状态错误映射成了不存在的
      article.status；其值为 undefined，状态校验因此被绕过

flaky 测试的处理顺序：
1. 定位根因并修复（默认动作）
2. 无法立即修复时，标记 skip 并建缺陷单，
   同时在 Verify 报告中显式列为「未覆盖项」
3. 禁止的做法：加重试次数掩盖、删掉断言、直接删测试

[ ] 每条 REQ 都有文本用例和自动化或人工证据
[ ] 类型、静态、单元、接口和关键 E2E 通过
[ ] 权限、状态、失败和边界场景通过
[ ] 失败、跳过和未执行项有明确解释
[ ] 人工验收通过
[ ] 验证命令、环境和版本可复现
[ ] 已知限制已记录

需求模糊 → AI 猜测 → 改十几个文件 → 测试只测 happy path → 线上误删

Spec Gate：发现删除规则未定义
Plan Gate：发现存储方式被误判
Implement Gate：发现越界修改或缺少权限测试
Verify Gate：发现自动化只测返回码

业务规则矛盾或漏写 → 回到 Spec
技术方案不可行或影响范围错误 → 回到 Plan
代码行为不符合已批准方案 → 回到 Implement
选择器、fixture 或断言错误 → 回到测试设计
环境、数据或登录态不稳定 → 回到测试执行
证据不足 → 不能准出 Verify

# Verify 报告：删除文章

## 结论
通过，可交付。含 2 项人工验收、0 项未覆盖。

## 需求追踪矩阵
| REQ | 用例 | 自动化 | 结论 |
| REQ-001 | TC-001 | e2e/article-delete.spec.ts | 通过 |
| REQ-002 | TC-002 | api/article-delete.test.ts | 通过 |
| REQ-003 | TC-004 | api/article-delete.test.ts | 通过（修 Plan / 实现后） |
| REQ-004 | TC-003 | e2e/article-delete.spec.ts | 通过 |
| REQ-005 | TC-005 | — | 人工验收通过 |
| REQ-006 | TC-006 | — | 人工验收通过 |
| REQ-007 | TC-007 | api/article-delete.test.ts | 通过 |

## 执行环境（假想全栈项目示例）
提交：<commit sha>
Node 22.x / pnpm 9.x / Playwright 1.4x
命令：pnpm test:api && pnpm test:e2e && pnpm build
构建结果：构建成功（示意）

## 失败与归因记录
TC-004 首次失败：已公开文章返回 204 而非 409
根因：Spec 已定义 hide，Plan/Implement 却错误映射为不存在的 status 字段
归因层级：Plan / Implement（非 Spec）
修复顺序：修正 Plan 字段映射 → 修改实现 → 保留回归用例
已沉淀至 docs/pitfalls.md

## 有效性自检
变异检查：换成“对所有删除都返回成功”的错误实现后，5 条关键用例全部失败（预期）
计划外文件修改：0

## 已知限制
- 未实现回收站与恢复（Spec 非目标）
- 未实现批量删除（Spec 非目标）
- 无审计日志，删除操作不可追溯操作人（建议下一迭代）