---

案例一：用户注册功能

❌ 1. 传统开发模式（给人看的）

用户故事： “作为一个新用户，我希望通过邮箱和密码注册账号，以便使用系统。”

• 人类程序员看到后： 脑子里会自动补全很多潜规则（比如密码要加密、邮箱要校验格式、不能重复注册）。
• AI 看到后： 它会给你写一个最简单的实现，可能连密码哈希（Hash）都没有，或者字段名极其随意。

✅ 2. 面向文档驱动开发（给 AI 看的）

在文档驱动模式下，这个用户故事需要包含验收标准（Acceptance Criteria）和数据约束：

User Story: 用户邮箱注册

描述： 新用户通过提交邮箱和密码创建账户。

1. 数据模型 (Schema Constraints):

• email: String, 必须是有效的邮箱格式，最大长度 255，数据库唯一索引 (Unique Index)。
• password: String, 必须包含至少 8 位字符，含大小写字母和数字。

2. 业务流程 (Flow):

1. 接收 API POST 请求 /api/v1/register。
2. 校验： 检查 email 是否已存在于 users 表。如果存在，返回 409 Conflict 错误。
3. 安全： 使用 bcrypt 算法对密码进行哈希处理（Salt rounds = 12）。
4. 持久化： 将用户信息写入数据库，created_at 设为当前 UTC 时间。
5. 响应： 成功则返回 201 Created，不返回密码字段，仅返回 id 和 email。

💡 差异点： 当你把右边这段文字喂给 AI，它写出的代码几乎不需要修改：它会自动引入 bcrypt 库，会自动写正则校验邮箱，会自动处理 409 错误。

---

案例二：购物车结算逻辑

❌ 1. 传统开发模式

用户故事： “作为一个顾客，我希望在购物车结算时看到总价，满 100 元可以减 10 元。”

• 潜在坑点： AI 可能会用浮点数（Float）直接相减导致精度丢失（0.1 + 0.2 = 0.3000004），或者没搞清楚“满 100”是含运费还是不含。

✅ 2. 面向文档驱动开发

User Story: 购物车金额计算

描述： 计算购物车内商品的总价、折扣和最终支付金额。

1. 计算逻辑 (Calculation Rules):

• 基础总价 (Subtotal): 所有 item.price * item.quantity 的总和。
• 折扣规则 (Discount):
  • 条件：如果 Subtotal >= 100.00 (CNY)。
  • 动作：DiscountAmount = 10.00。
  • 注意：折扣仅针对商品价格，不包含运费。
• 运费 (Shipping): 固定 15.00，如果 Subtotal > 200 则免运费。
• 最终总价 (Total): Subtotal - DiscountAmount + Shipping。

2. 技术约束 (Technical Constraints):

• 精度： 所有金额计算禁止使用 float/double。必须使用 Decimal 类型（Python/DB）或将金额转换为“分”（Integer）进行计算，最后再转回“元”。
• 边界检查： 如果最终总价 < 0（虽然不太可能，但要防御），强制设为 0。

💡 差异点： 这段文档明确禁止了 AI 使用 float，并定义了运费和折扣的优先级。AI 生成的代码将非常健壮，直接具备上线标准。

---

案例三：上传用户头像

❌ 1. 传统开发模式

用户故事： “用户可以在个人中心上传头像图片。”

• 潜在坑点： 用户传了一个 100MB 的 BMP 图片把服务器撑爆了；或者传了一个 .exe 文件把服务器黑了。

✅ 2. 面向文档驱动开发

User Story: 头像上传服务

描述： 允许认证用户上传个人头像，并进行压缩处理。

1. 输入验证 (Validation):

• 文件类型白名单：仅允许 ['image/jpeg', 'image/png', 'image/webp']。
• 文件大小限制：最大 2MB。如果超过，直接返回 400 Bad Request。

2. 处理逻辑 (Processing):

• 使用图像处理库（如 sharp 或 Pillow）将图片统一调整大小为 200x200 像素。
• 压缩质量设置为 80%。
• 文件重命名：使用 UUID + 原始扩展名，防止文件名冲突或包含恶意字符。

3. 存储 (Storage):

• 上传至 AWS S3（或本地 /uploads 目录，视配置而定）。
• 在数据库 users 表更新 avatar_url 字段。

---

总结：什么是“AI 友好的文档”？

从上面三个案例可以看出，面向文档驱动开发中的“用户故事”，实际上是自然语言编写的程序逻辑。

写好这种文档的秘诀在于 “C-I-R” 原则：

1. Constraints (约束)： 明确数据类型、大小限制、精度要求（如：别用 Float，最大 2MB）。
2. Input/Output (输入输出)： 明确 API 接收什么参数，报错时返回什么状态码（如：409 Conflict, 201 Created）。
3. Rules (业务规则)： 明确步骤的先后顺序（如：先校验数据库，再 Hash 密码，最后存库）。