【AI Native开发-02】从一句需求到一次交付：SDD 四道闸门如何拦住错误

功能：删除文章

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

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

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

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 } 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")

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

    expect(res.status).toBe(403)

    // 关键：不能只断言状态码，必须验证副作用没有发生
    const stillThere = await fetch(`/api/articles/${article.id}`)
    expect(stillThere.status).toBe(200)
  })

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

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

    expect(res.status).toBe(409)
    const stillThere = await fetch(`/api/articles/${article.id}`)
    expect(stillThere.status).toBe(200)
  })
})

// 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
根因：内容文件里控制公开与否的字段是 hide 布尔，
      并没有 status 字段，article.status 为 undefined，
      undefined 不等于 "published"，校验被绕过

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

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

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

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

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

测试失败
  │
  ├─ 1. 这条测试断言的行为，Spec 里写了吗？
  │      没写 → Spec 缺口，回到 Gate 1（不要改代码）
  │      写了但自相矛盾 → Spec 冲突，回到 Gate 1
  │
  ├─ 2. Spec 的描述与真实数据模型一致吗？
  │      不一致 → Spec 前提错误，回到 Gate 1
  │              （本文 TC-004 属于这一类）
  │
  ├─ 3. Plan 的方案能实现这条 Spec 吗？
  │      不能 → 方案缺陷，回到 Gate 2
  │      影响范围判断错 → 回到 Gate 2
  │
  ├─ 4. 代码行为与已批准的 Plan 一致吗？
  │      不一致 → 实现缺陷，回到 Gate 3
  │
  ├─ 5. 测试本身写对了吗？
  │      选择器、fixture、断言、等待条件错 → 回到测试设计
  │      断言弱于 Spec 原意 → 回到测试设计
  │
  └─ 6. 环境、数据、登录态稳定吗？
         不稳定 → 回到测试执行，按 flaky 处理

specs/article-delete/verify.md
  → 记录本次失败、根因、归因层级、修复顺序

docs/pitfalls.md
  → 记录可复用的教训，供后续所有功能引用

## 内容模型的状态表达

本项目文章公开状态用 frontmatter 的 hide 布尔字段表达，
不存在 status 字符串字段。

编写涉及文章状态的 Spec 时，必须使用 hide: true/false 表述，
不得引入 status 概念。

历史事故：曾因 Spec 写「已发布不可删除」而实现读取
article.status，值为 undefined 导致校验被绕过。

# Verify 报告：删除文章

## 结论
通过，可交付。含 1 项人工验收、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 | 通过（修 Spec 后） |
| 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 假设存在 status 字段，实际为 hide 布尔标记
归因层级：Spec（非 Implement）
修复顺序：补 Spec 状态定义 → 更新 Plan 判断依据 → 修改实现
已沉淀至 docs/pitfalls.md

## 有效性自检
空实现测试：替换为空实现后 5 条用例全部失败（预期）
计划外文件修改：0

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