需求文档写不好？六层防护体系让 AI 帮你兜底

┌─────────────────────────────────────────────────────┐
│              需求文档质量保障体系                     │
├─────────────────────────────────────────────────────┤
│                                                     │
│  第一层：降低门槛 —— 让人写得轻松                    │
│  第二层：多元来源 —— 不写也能有文档                  │
│  第三层：质量门禁 —— 不好就不能往下走                │
│  第四层：主动追问 —— AI 倒逼人思考                  │
│  第五层：文档即代码 —— 文档和代码同步               │
│  第六层：逆向工程 —— 从代码反推需求                  │
│                                                     │
└─────────────────────────────────────────────────────┘

用户登录功能：
- 支持手机号和邮箱
- 要记住密码
- 错误多次要锁定

## 用户登录功能

### 功能描述
- 支持手机号 + 密码登录
- 支持邮箱 + 密码登录
- 支持"记住密码"功能（7 天免登录）

### 输入
| 字段 | 类型 | 必填 | 校验规则 |
|------|------|------|---------|
| 账号 | string | 是 | 手机号（11 位）或邮箱格式 |
| 密码 | string | 是 | 6-20 位，至少包含数字和字母 |
| 记住密码 | boolean | 否 | 默认 false |

### 输出
- **成功**：返回用户信息 + Token，跳转到首页
- **失败**：返回错误信息
  - 账号不存在
  - 密码错误
  - 账号已锁定

### 异常流程
1. **账号锁定**：连续错误 5 次，锁定 30 分钟
2. **密码过期**：90 天未修改，强制修改密码
3. **账号异常**：检测到异常登录（异地/新设备），触发二次验证

### 非功能需求
- 响应时间 < 200ms（P95）
- 密码传输加密（HTTPS）
- 敏感信息脱敏（日志中不记录密码）
- 支持并发登录：同一账号最多 5 个设备同时在线

会议录音（AI 转写）：
"产品经理：我们这个登录功能，要支持手机号和邮箱两种方式。
开发：那记住密码要不要做？
产品：要做，7 天免登录吧。
测试：错误多次要不要锁定？
产品：要，连续错 5 次锁 30 分钟。"

AI 提取并生成需求文档：
- 支持手机号登录
- 支持邮箱登录
- 记住密码（7 天免登录）
- 连续错误 5 次锁定 30 分钟

AI 分析 Figma 设计稿：
- 检测到：登录表单（账号输入框、密码输入框、记住密码复选框、登录按钮）
- 检测到：第三方登录图标（微信、Google）
- 推断：支持多种登录方式
- 生成需求文档...

GitHub Issue：
"实现用户登录功能，支持手机号和邮箱，要记住密码。"

AI 生成需求文档：
（同上，自动扩展）

# 从代码生成需求文档
cursor generate-requirement src/user/login.ts

# 从测试用例生成需求文档
cursor generate-requirement tests/user/login.test.ts

class RequirementQualityChecker:
    def check(self, doc: RequirementDoc) -> QualityReport:
        checks = [
            # 完整性检查
            ("是否有功能描述", doc.has_function_description()),
            ("是否有输入输出定义", doc.has_input_output()),
            ("是否有异常流程", doc.has_error_handling()),
            ("是否有非功能需求", doc.has_non_functional_req()),
            
            # 清晰性检查
            ("是否避免了模糊表述", not doc.has_vague_terms()),
                # 模糊表述示例："性能要好"、"用户体验要流畅"
            ("是否有可量化的指标", doc.has_quantifiable_metrics()),
                # 量化指标示例："响应时间 < 200ms"、"支持 1 万并发"
            
            # 一致性检查
            ("是否与现有需求冲突", not doc.conflicts_with_existing()),
            ("是否与原型一致", doc.matches_prototype()),
            
            # 可测试性检查
            ("是否有验收标准", doc.has_acceptance_criteria()),
            ("是否可转化为测试用例", doc.is_testable()),
        ]
        
        return QualityReport(checks)

❌ 需求文档质量不达标（60/100）

未通过项：
- [ ] 缺少非功能需求（性能、安全、可用性）
- [ ] 存在模糊表述："用户体验要好"
- [ ] 缺少可量化指标
- [ ] 缺少异常流程（账号锁定、密码过期）

建议：
1. 补充性能要求："响应时间 < 200ms（P95）"
2. 明确"用户体验好"的定义："登录成功率 > 99.9%"
3. 补充异常流程：账号锁定策略、密码过期策略

⚠️ 请修正后再提交技术方案。

需求文档 → AI 质量检查 → 通过？
                         ├─ 是 → 可创建技术方案任务
                         └─ 否 → 返回修改，无法进入下一阶段

AI：我看到你提交了"用户登录"功能的需求文档，但有几个问题想确认：

【安全性】
1. 登录失败时，是提示"用户名或密码错误"还是分别提示？
   - 分别提示：用户体验好，但可能被用于枚举账号
   - 统一提示：安全性高，但用户体验略差
   → 请选择：A. 分别提示  B. 统一提示  C. 自定义

【扩展性】
2. 是否需要支持第三方登录（微信/Google/Apple ID）？
   - 如果未来要支持，现在就要预留接口
   → 请选择：A. 不需要  B. 需要（请列出平台）

【合规性】
3. 是否需要登录日志？保留多久？
   - 某些行业要求保留 6 个月以上
   → 请输入：保留 ___ 个月

【性能】
4. 预计的并发登录量是多少？
   - 影响技术方案（单机 vs 集群）
   → 请输入：峰值 ___ QPS

【安全策略】
5. 密码规则是什么？
   - 复杂度要求（数字/字母/特殊字符）
   - 最小/最大长度
   → 请描述：_____________________

请回答以上问题，或告诉我使用默认规则。

project/
├── docs/
│   └── requirements/
│       ├── user-login.md       # 需求文档
│       ├── user-register.md
│       └── .templates/
│           └── requirement-template.md  # 需求文档模板
├── src/
│   └── user/
│       ├── login.ts            # 代码
│       ├── login.test.ts       # 测试
│       └── login.md            # 代码文档（可选）
├── .ai/
│   └── checks/
│       ├── requirement-check.sh    # 需求质量检查
│       └── sync-check.sh           # 文档代码同步检查
└── .github/
    └── workflows/
        └── requirement-quality.yml  # CI 检查

# .github/workflows/requirement-quality.yml
name: Requirement Quality Check

on:
  pull_request:
    paths:
      - 'src/**'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check if requirement doc exists
        run: |
          # 检查是否有对应的需求文档
          # 如果 src/user/login.ts 变更了，检查 docs/requirements/user-login.md 是否存在或更新
          
      - name: Run AI quality check
        run: |
          # 运行 AI 质量检查
          python .ai/checks/requirement_quality.py

# 从代码生成需求文档
cursor generate-requirement src/user/login.ts

# 输出：
# - 功能：用户登录
# - 输入：账号（手机号/邮箱）、密码
# - 输出：Token、用户信息
# - 异常处理：账号锁定、密码过期
# - 安全措施：密码加密、登录日志

# 从测试用例生成需求文档
cursor generate-requirement tests/user/login.test.ts

# 输出：
# - 正常流程：手机号登录、邮箱登录
# - 异常流程：账号不存在、密码错误、账号锁定
# - 边界条件：密码长度、账号格式

# 从 OpenAPI/Swagger 生成需求文档
cursor generate-requirement api/user.yaml

# 输出：
# - 接口定义
# - 请求参数
# - 响应格式
# - 错误码

# 从数据库 Schema 生成需求文档
cursor generate-requirement schema/user.sql

# 输出：
# - 数据模型
# - 字段含义
# - 约束条件

1. AI 扫描代码仓库
   ↓
2. 识别功能模块（登录、注册、支付...）
   ↓
3. 分析每个模块的业务逻辑
   ↓
4. 生成需求文档初稿
   ↓
5. 人工 Review 和补充
   ↓
6. 存入 docs/requirements/

【新项目】
第一层（降低门槛）+ 第三层（质量门禁）+ 第四层（主动追问）
→ 人写得轻松 + 质量有保障 + AI 帮你查漏补缺

【敏捷团队】
第二层（多元来源）+ 第三层（质量门禁）
→ 不写文档也能有文档 + 质量有保障

【大型项目】
第五层（文档即代码）+ 第三层（质量门禁）
→ 文档代码同步 + 质量有保障

【历史项目】
第六层（逆向工程）
→ 从代码反推需求，补齐文档

┌──────────────┐
│  原材料输入   │（rough notes / 会议录音 / 原型 / Issue）
└──────┬───────┘
       ↓
┌──────────────┐
│  AI 生成文档  │（第一层 + 第二层）
└──────┬───────┘
       ↓
┌──────────────┐
│  AI 主动追问  │（第四层）
└──────┬───────┘
       ↓
┌──────────────┐
│  质量门禁检查 │（第三层）
└──────┬───────┘
       ↓
    通过？
    ├─ 是 → 进入技术方案阶段
    └─ 否 → 返回修改
       
（全程：文档和代码同步维护 - 第五层）
（历史项目：逆向工程补文档 - 第六层）