【AI Native开发-04】如何写一份 AI 能执行的 Spec

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

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

反例：“只有管理员能删除。”
正例：
- 管理员：通过 CMS 登录（Keystatic / Decap，均为 Git 身份），可删除文章
- 访客/未登录：没有任何删除入口，直接调用删除接口返回 403
- 本项目不存在自建用户表和角色系统，不要新建 user/role 模型

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

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

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

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

- 前端：访客看不到删除入口（体验层）
- 服务端：删除接口必须独立校验 CMS 身份，
  未登录/无身份请求返回 403，且不执行任何删除（副作用为零）
- 403 的验证不只看状态码，还要确认文章文件仍然存在

- 文章 = src/content/blog/<年>/<月>/<slug>.md 文件
- 删除 = 删除该文件（以及构建产物中对应页面在下次构建时消失）
- 不涉及数据库；frontmatter schema 定义在 src/content.config.ts
- 删除操作不产生新的字段或状态

- AC-1：管理员删除 hide: true 文章 → 文件消失，重建后仍不存在
- AC-2：访客调用删除接口 → 403，且文件仍存在（副作用验证）
- AC-3：删除已公开（hide 非 true）文章 → 409，文件仍存在
- AC-4：确认框点取消 → 不发删除请求，文章不变
- AC-5：并发重复删除 → 第二次返回 404，不报错（对应第 1 篇 F4 幂等性缺失）

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

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

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

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

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

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

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

第五步 补权限边界：
  服务端独立校验 403 + 副作用为零。

第六步 编号 + 准出检查：
  每条规则给 REQ 号；逐条问“这能写成测试吗？”
  写不成测试的，要么改写成可测，要么移到非目标。

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

# Spec: <功能名>

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

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

## 正常流程
1. 
2. 

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

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

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

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

## 验收标准（需求编号）
- REQ-001 
- REQ-002 
<!-- 每条都应可设计成“空实现会失败”的测试 -->

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

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