【AI Native开发-04】“删除要安全”为什么不是一份可执行的 Spec？

flowchart TB
    A["一句愿望<br/>删除要安全"] --> B["角色与目标"]
    B --> C["正常与异常流程"]
    C --> D["业务规则与权限"]
    D --> E["数据约束与非目标"]
    E --> F["REQ 编号的验收标准"]
    F --> G["人可评审 · AI 可执行 · 测试可追踪"]

需求文档的句子：
  “删除功能要安全，不要误删文章。”
  → 人看了能点头，AI 看了只能猜：什么叫安全？什么算误删？

Spec 的句子：
  “当文章 hide 为 false 或缺省（已公开）时调用删除接口，系统返回 409，
   文章文件保持存在，列表中仍然可见。”
  → 条件明确、行为明确、可直接翻译成一个测试用例

反例：“只有管理员能删除。”
正例：
- 管理员：通过服务现有身份系统登录，可删除允许删除的文章
- 普通用户：无删除入口，直接调用删除接口返回 403，且无副作用
- 未登录访客：无删除入口，直接调用删除接口返回 401，且无副作用
- 复用现有身份与角色机制，不另建一套平行权限体系

功能描述：“提供删除按钮和删除接口。”
用户目标：“管理员能把写错、废弃的草稿从系统里清掉，
          同时绝不可能误删已经对外发布的文章。”

1. 管理员在文章列表看到未公开（hide: true）文章旁有「删除」操作
2. 点击「删除」，弹出二次确认，确认文案显示文章标题
3. 管理员确认后，系统删除文章文件
4. 列表刷新，该文章消失
5. 刷新页面 / 重新构建后，文章仍然不存在（删除是持久的）

- 删除时文件已被其他人删掉（并发）：
  返回 404，列表静默移除该项，不报错崩溃
- 二次确认时点取消：不发任何删除请求，文章保持不变
- 删除过程中出错（文件系统/Git 提交失败）：
  文章保持原状，列表提示“删除失败，请重试”，不留下半删除状态
- 已发布文章调用删除：见业务规则，拒绝

- 仅 hide: true 的文章允许删除
- hide 为 false 或缺省（已公开）的文章删除请求一律拒绝，返回 409 Conflict
- 文章是否公开由 frontmatter 的 hide 布尔字段表达，
  系统中不存在 status 字符串字段（架构事实，见 pitfalls）
- 删除为物理删除 Markdown 文件，本功能不做回收站/软删除

- 前端：普通用户与未登录访客看不到删除入口（体验层）
- 服务端：删除接口必须通过现有身份机制独立鉴权
- 未登录请求返回 401；已登录但非管理员返回 403；均不得执行删除
- 拒绝响应的验证不只看状态码，还要直接确认受控存储中的文章仍存在

- 文章 = 受控内容目录中的 <年>/<月>/<slug>.md 文件
- 删除 = 删除该文件，并使后续发布构建不再生成对应页面
- 状态由 frontmatter 的 hide 布尔字段表达，不引入新的 status 字段
- 测试只能操作临时内容目录，不能触碰真实文章

- AC-1：管理员删除 hide: true 文章 → 存储中文件消失，后续构建不再生成页面
- AC-2：普通用户调用删除接口 → 403，且存储中文件仍存在
- AC-3：删除已公开（hide 非 true）文章 → 409，文件仍存在
- AC-4：确认框点取消 → 不发删除请求，文章不变
- AC-5：并发重复删除 → 一次成功，其余请求返回约定的冲突/不存在结果，无额外副作用

本次不做：
- 回收站 / 撤销删除 / 软删除
- 批量删除
- 删除操作审计日志
- 已发布文章的“下线”流程（那是另一个功能）
- 任何全局权限模型改造

REQ-001 管理员可删除 hide: true 文章
REQ-002 未登录请求返回 401；已登录但非管理员返回 403；两者均无副作用
REQ-003 已公开文章删除返回 409
REQ-004 取消确认不发删除请求
REQ-005 删除后重建仍不存在（人工验收：本地构建确认）
REQ-006 删除失败时列表保持原状态并提示错误
REQ-007 目标文章不存在时返回 404；重复删除不产生额外副作用

原始一句话需求：
  “给博客加个删除文章功能。”

第一步 补角色与目标：
  谁删？管理员。为什么删？清理废弃草稿，绝不误删已发布。

第二步 拆正常流程：
  列表 → 二次确认 → 删除文件 → 列表刷新 → 重建后仍消失。

第三步 穷举异常：
  并发已删？取消？删除失败？已发布？
  （每问一个“如果失败/如果不满足条件会怎样”，就补一条）

第四步 写死业务规则和数据事实：
  hide 布尔表达公开状态、物理删除、无 status 字段、无回收站。

第五步 补权限边界：
  未登录 401、已登录但非管理员 403，且副作用为零。

第六步 编号 + 准出检查：
  每条行为规则给 REQ 号；逐条问“这能写成测试吗？”
  写不成测试的行为承诺要改写成可测；背景、理由与非目标不必硬改成测试断言。

[ ] 每条规则都能翻译成至少一个测试用例（可测性）
[ ] 角色、权限、服务端校验明确，前端隐藏 ≠ 安全
[ ] 正常流程 + 每个失败分支都有明确的系统行为
[ ] 状态、数据字段基于真实代码（已核对，不是假设）
[ ] 没有“尽量/适当/友好/流畅”等不可判定词
[ ] 非目标显式列出，且与业务规则不矛盾
[ ] 每条规则有 REQ 编号，可被 Plan 和测试引用
[ ] 两个没参与讨论的人，按这份 Spec 能得出相同验收结论

# Spec: <功能名>

## 背景与用户目标
<!-- 一句话真实意图，不是功能清单 -->

## 用户角色
- <角色 A>：<能做什么>
- <角色 B>：<能做什么>
<!-- 写明项目里真实的身份机制，禁止 AI 自建 -->

## 正常流程
1. 
2. 

## 异常流程
- <失败场景>：<系统行为 / 返回 / 状态>
- 

## 业务规则
- <如果……那么……>
- 

## 权限边界
- 前端：
- 服务端（独立校验）：
- 副作用验证要求：

## 数据约束
- 涉及的数据/文件/字段：
- 数据如何变化：
- 相关架构事实（引用 pitfalls / 决策记录）：

## 验收标准（需求编号）
- REQ-001 
- REQ-002 
<!-- 每条行为承诺都应可验证；关键用例另选能暴露目标错误的变异体，不能指望单一空实现证明全部有效性 -->

## 非目标
- 本次不做：
- 明确不改造的现有模块：

## 待确认问题
- <!-- 写 Spec 时悬而未决的点，进 Plan 前必须清零或转 Spike -->