需求结构化清单自动生成模块

1. 模块概述

🎯 模块定位：

本模块是端到端研发自动化系统的质量保障环节，负责将需求分析结果转化为可执行的结构化检查清单。通过智能识别需求中的模糊术语、缺失细节、矛盾信息等歧义点，自动生成澄清问题并标注优先级，帮助团队在开发前消除需求不确定性，降低返工风险。同时生成需求跟踪矩阵（RTM），建立从需求到测试的完整追溯链路。

📥 输入

需求分析结果（JSON）
用户故事列表
非功能性需求
原始需求文本

🔄 处理

规则引擎歧义检测
AI 增强歧义识别
检查项自动生成
依赖关系分析
阻塞状态检测

📤 输出

结构化检查清单
疑问点报告（含优先级）
需求跟踪矩阵（RTM）
Markdown/HTML/Excel 报告

💡 价值

需求歧义减少 80%+
开发返工率降低 60%
沟通成本降低 50%
需求覆盖率 100%

2. 核心功能

2.1 功能架构

接收需求分析结果

从 requirements_intent_extractor 模块获取结构化的需求分析数据

↓

歧义检测（双引擎）

基于规则引擎检测模糊术语 + AI 模型识别复杂歧义

↓

生成检查项

从用户故事、NFR、风险等生成结构化的检查项

↓

关联疑问点

将检测到的疑问关联到对应检查项，标记阻塞状态

↓

生成 RTM

建立需求→故事→测试→代码的追溯矩阵

↓

计算统计信息

汇总各类别数量、优先级分布、工作量估算、完成率等

↓

多格式导出

生成 Markdown、HTML、Excel 三种格式的报告

2.2 功能特性对比

功能	基于规则	AI 增强	输出产物
模糊术语检测	✅ 内置词库匹配	✅ 上下文理解	Ambiguity 对象列表
缺失细节识别	✅ 模式匹配	✅ 语义推理	澄清问题建议
矛盾信息检测	❌ 不支持	✅ 逻辑一致性分析	冲突报告
检查项生成	✅ 模板映射	✅ 智能拆分	ChecklistItem 列表
依赖关系识别	✅ 关键词匹配	✅ 因果推理	依赖图
阻塞状态检测	✅ 规则判断	✅ 影响分析	状态标记

3. 歧义检测引擎

3.1 基于规则的检测

                    # ===== 内置检测规则 =====

VAGUE_TERMS = [
    "快速", "高效", "友好", "美观", "强大",
    "灵活", "稳定", "大概", "左右", "一些",
    "适当", "合理", "及时", "等等", "相关"
]

MISSING_PATTERNS = [
    r"支持.*等",      # "支持 A、B 等" - 列举不完整
    r"包括.*等等",    # 列举不完整
    r"如.*所示",      # 引用缺失
    r"参考.*文档",    # 文档未指定
    r"与.*一致",      # 参照对象不明确
    r"在.*情况下",    # 条件不完整
]

METRIC_PATTERNS = [
    r"响应时间.*<[^\d]",   # 缺少具体数字
    r"并发.*>[^\d]",     # 缺少具体数字
    r"准确率.*>[^\d%]",  # 缺少具体数字
]
                

3.2 AI 增强检测

                    🤖 Claude AI 检测能力：
                    上下文理解：识别术语在具体语境中是否模糊
矛盾检测：发现前后不一致的描述
隐含假设：识别未明说但重要的前提条件
依赖分析：发现缺失的外部依赖说明
范围界定：判断功能边界是否清晰

                

3.3 疑问点优先级

优先级	标识	定义	响应时效	示例
关键	🔴 CRITICAL	阻塞开发，必须立即澄清	<4 小时	"支持多种支付方式"但未说明具体哪些
高	🟠 HIGH	影响设计决策，需尽快明确	<24 小时	"响应时间要快"无具体指标
中	🟡 MEDIUM	需要澄清但不阻塞	<3 天	"界面友好"缺乏量化标准
低	🟢 LOW	建议明确，可后续补充	<1 周	"等等"未列举完全

4. 清单生成流程

4.1 检查项分类

🔧 功能需求

来自用户故事的检查项，描述系统应提供的具体功能

示例：用户登录、订单创建、支付处理等

📊 非功能需求

性能、安全、可靠性等质量属性要求

示例：响应时间<200ms、99.9%可用性等

⚠️ 约束条件

技术约束、合规要求、业务限制等

示例：必须使用 MySQL、符合 GDPR 等

🔗 依赖关系

外部系统依赖、前置条件等

示例：依赖支付网关 API、需要先有用户数据等

4.2 状态流转

                    ChecklistItem.status:

pending (⏳)
  ↓ 开始开发
in_progress (🔄)
  ↓ 开发完成
done (✅)

特殊流转:
pending 
  ↓ 检测到高优先级疑问
blocked (🚫)
  ↓ 疑问已澄清
pending (恢复)
                

4.3 阻塞检测机制

                    ⚠️ 自动阻塞规则：
                    检查项关联的疑问点优先级为 critical 或 high
疑问点状态为 open（未回答）
满足以上条件时，检查项自动标记为 blocked
疑问回答后，检查项恢复为 pending

                

5. 需求跟踪矩阵 (RTM)

5.1 RTM 结构

字段	说明	填充时机
requirement_id	原始需求 ID	清单生成时
user_story_id	用户故事/检查项 ID	清单生成时
test_case_id	测试用例 ID	测试设计时
code_module	代码模块/文件路径	AI Coding 完成后
status	跟踪状态	实时更新
coverage	覆盖率（0-100%）	测试执行后

5.2 追溯链路

需求 (REQ-001)
  │
  ├→ 用户故事 (US-001)
  │    │
  │    ├→ 检查项 (CHK-001)
  │    │    │
  │    │    ├→ 测试用例 (TC-001)
  │    │    │    │
  │    │    │    └→ 代码模块 (src/login.py)
  │    │    │
  │    │    └→ 测试用例 (TC-002)
  │    │         │
  │    │         └→ 代码模块 (src/auth.py)
  │    │
  │    └→ 检查项 (CHK-002)
  │         ...
  │
  └→ 非功能需求 (NFR-001)
       │
       └→ 检查项 (CHK-003)
            │
            └→ 性能测试 (PT-001)
                 │
                 └→ 代码模块 (src/performance.py)

6. 多格式导出

6.1 Markdown 格式

📄 特点

纯文本格式，易于版本控制
支持 GitHub/GitLab渲染
适合技术文档和 Wiki
包含完整的层级结构

6.2 HTML 格式

🌐 特点

交互式可视化展示
颜色编码（优先级/状态）
响应式设计，适配移动端
适合演示和汇报

6.3 Excel 格式

📊 特点

多工作表结构
支持筛选、排序、透视表
便于数据分析和统计
适合项目管理和追踪

6.4 格式选择建议

场景	推荐格式	理由
纳入 Git 版本控制	Markdown	Diff 友好，易合并
向领导汇报	HTML	视觉效果佳，交互性强
项目管理追踪	Excel	便于筛选、统计、导出
团队协作审核	Markdown+HTML	兼顾可读性和交互性

7. 实战案例

7.1 案例：电商订单系统

📝 原始需求：

"我们需要做一个订单管理系统。用户应该能够方便地下单，系统要稳定可靠。响应时间要快，支持高并发。支持多种支付方式等等。还需要有订单查询和取消功能。"

检测结果

疑问 ID	类型	优先级	原文片段	建议问题
AMB-001	vague_term	🟡 MEDIUM	"方便地下单"	"方便"的具体标准是什么？几步完成下单？
AMB-002	vague_term	🟠 HIGH	"响应时间要快"	具体的响应时间指标是多少毫秒？
AMB-003	vague_term	🟠 HIGH	"支持高并发"	具体的并发用户数或 QPS 指标是多少？
AMB-004	missing_detail	🔴 CRITICAL	"多种支付方式等等"	具体支持哪些支付方式？微信、支付宝、银联、信用卡？

生成的检查项（部分）

                    CHK-001: 创建订单 [functional] [P0]
  描述：用户能够创建订单
  验收标准:
    - 用户选择商品后能添加到购物车
    - 能从购物车结算生成订单
    - 订单信息包含商品、数量、价格、收货地址
  状态：blocked ⚠️ (关联疑问：AMB-004)

CHK-002: 支付订单 [functional] [P0]
  描述：用户能够支付订单
  验收标准:
    - 支持微信支付
    - 支持支付宝支付
    - 支持银联支付
    - 支付成功后更新订单状态
  状态：blocked ⚠️ (关联疑问：AMB-004)

CHK-003: 响应时间 [non_functional] [P1]
  描述：系统响应时间要快
  验收标准:
    - TBD (待澄清具体指标)
  状态：blocked ⚠️ (关联疑问：AMB-002)

CHK-004: 高并发支持 [non_functional] [P1]
  描述：系统支持高并发
  验收标准:
    - TBD (待澄清具体并发数)
  状态：blocked ⚠️ (关联疑问：AMB-003)
                

统计摘要

📊 总体统计

检查项总数: 12

疑问点数量: 4

阻塞项数量: 4

估算总工时: 35 人天

🎯 按类别

功能需求：8 项

非功能需求：3 项

约束条件：1 项

⚡ 按优先级

P0 (Must): 5 项

P1 (Should): 5 项

P2 (Could): 2 项

8. 集成方案

8.1 与需求分析模块集成

                    from requirements_intent_extractor import RequirementsIntentExtractor
from requirements_checklist_generator import RequirementsChecklistGenerator

# Step 1: 需求意图识别
intent_extractor = RequirementsIntentExtractor()
analysis = intent_extractor.analyze_requirement(requirement_text)

# Step 2: 生成结构化清单
checklist_gen = RequirementsChecklistGenerator()
checklist = checklist_gen.generate_full_checklist(analysis, requirement_text)

# Step 3: 导出报告
checklist_gen.export_to_html(checklist, "full_report.html")
                

8.2 与 PRD 生成模块集成

                    # 清单作为 PRD 的输入
prd_data = {
    "requirements": [item.description for item in checklist.checklist_items],
    "open_questions": [
        amb.suggested_question 
        for amb in checklist.ambiguities 
        if amb.status == "open"
    ],
    "acceptance_criteria": {
        item.id: item.acceptance_criteria 
        for item in checklist.checklist_items
    }
}

# 传递给 PRD 生成器
prd_generator.generate(prd_data)
                

8.3 与项目管理工具集成

                    🔗 Jira/Trello 集成：
                    将检查项同步为 Jira Issue
疑问点创建为 Comment 或子任务
状态变更双向同步
RTM 关联 Jira Epic/Story/Test

                

9. 最佳实践

✅ 及时澄清高优先级疑问

优先处理 critical 和 high 级别的疑问，避免阻塞开发进度

🔄 迭代更新清单状态

开发过程中实时更新检查项状态，保持清单准确性

👥 多人协作审核

产品经理、开发、测试共同审核疑问点和检查项

📈 追踪度量指标

定期统计阻塞率、澄清时效、完成率等指标

🎯 验收标准 SMART 原则

确保每个检查项的验收标准具体、可衡量、可实现

🔗 维护 RTM 完整性

需求变更时同步更新 RTM，保持追溯链路完整

10. 质量指标

10.1 检测质量

指标	目标值	计算方法
歧义检出率	≥85%	(检出的真实歧义数 / 实际存在的歧义数) × 100%
误报率	≤15%	(被标记为疑问但实际清晰的数量 / 总疑问数) × 100%
清单覆盖率	100%	(有检查项的需求数 / 总需求数) × 100%
阻塞解除时效	<24 小时	高优先级疑问的平均响应时间

10.2 过程指标

📊 生成效率

平均每个需求生成时间：<10 秒

批量处理吞吐量：>100 需求/分钟

🎯 需求质量提升

需求歧义减少：80%+

开发返工率降低：60%+

💬 沟通效率

需求澄清会议减少：50%+

沟通成本降低：40%+