requirement-collect

# 源代码解构（需求） <HARD-GATE> **强制约束：必须对所有模块进行梳理，不得偷工减料** 1. 所有源代码包/模块必须逐一分析，不得跳过任何模块 2. 每个模块的需求文档必须完整包含所有章节 3. 业务规则必须从代码中深度挖掘，不得遗漏 4. 执行进度必须使用 todowrite 记录，确保可追溯 5. 最终输出必须通过完整性检查清单验证 违反以上约束视为执行失败，必须重新执行。 </HARD-GATE> ## 核心原则 从代码逆向提炼需求，完整收集业务意图。解答**为什么建立项目**的问题。 ## 执行步骤 1. **扫描项目结构**：列出所有包/模块，形成完整模块清单 2. **逐一分析模块**：按模块清单顺序，逐个深入分析 3. **挖掘业务规则**：从每个模块代码中深度挖掘业务规则 4. **编写需求文档**：为每个模块生成完整需求文档 5. **汇总全局需求**：整合所有模块需求，生成全局需求文档 ### 进度记录 使用 `todowrite` 记录执行进度： ```markdown - [ ] 扫描项目结构，列出模块清单 - [ ] 分析模块: {module1} - [ ] 分析模块: {module2} - [ ] ... - [ ] 汇总全局需求文档 - [ ] 完整性检查 ``` ## 模块梳理要求 ### 模块清单 生成 `docs/requirements/module_inventory.md`，模板见 `templates/module_inventory.md` ### 分析顺序 1. 核心业务模块优先 2. 辅助功能模块次之 3. 工具/配置模块最后 ### 模块分析完整性 | 分析内容 | 必须产出 | 不得省略 | | ---------- | ------------------------------ | -------- | | 业务场景 | 场景列表 + 场景详情 | 否 | | 功能需求 | 核心功能 + 辅助功能 | 否 | | 业务规则 | 规则列表 + 规则详情（独立章节）| 否 | | 数据需求 | 数据实体 + 数据流转 | 否 | | 非功能需求 | 性能 + 安全 + 可用性 | 否 | | 约束条件 | 业务约束 + 技术约束 | 否 | ## 业务规则挖掘 <HARD-GATE> **业务规则必须独立成章节写入分模块文档，不得遗漏或简化** </HARD-GATE> ### 挖掘方法 | 代码特征 | 挖掘方式 | 示例 | | ---------- | ---------------------------- | ------------------------------------------------------------ | | 条件判断 | 提取 if/switch 中的业务约束 | `if (age >= 18 && status == ACTIVE)` → 用户操作权限规则 | | 计算逻辑 | 提取计算公式和边界条件 | `interest = principal * rate * days / 365` → 利息计算规则 | | 状态转换 | 提取状态流转路径 | `PENDING → PAID → SHIPPED` → 订单状态转换规则 | | 数据验证 | 提取输入校验规则 | `email.matches(regex)` → 邮箱格式验证规则 | | 异常处理 | 提取业务异常场景 | `InsufficientBalanceException` → 转账余额验证规则 | | 常量/配置 | 提取业务参数阈值 | `MAX_RETRY = 3` → 重试次数上限规则 | | 数据库约束 | 提取 CHECK/DEFAULT 约束 | `age CHECK (0-150)` → 年龄范围规则 | | 注释/文档 | 提取业务规则线索 | `VIP用户20%折扣` → VIP折扣规则 | ### AST 辅助挖掘（ast-grep-mcp 联动） 当 ast-grep-mcp 可用时，使用 `find_code_by_rule` 自动扫描业务规则候选点。 **条件判断挖掘**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: business-condition language: java rule: pattern: 'if ($VAR.equals("$VAL"))' constraints: VAL: regex: '(?i)(ACTIVE|PENDING|APPROVED|REJECTED|ENABLED|DISABLED|SUCCESS|FAILED|PAID|SHIPPED|CANCELLED)' ''' ) ``` **状态赋值挖掘**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: state-assignment language: java rule: pattern: '$OBJ.setStatus("$VAL")' constraints: VAL: regex: '(?i)(ACTIVE|INACTIVE|PENDING|APPROVED|REJECTED|ENABLED|DISABLED|SUCCESS|FAILED|PAID|SHIPPED|CANCELLED)' ''' ) ``` **异常类挖掘**： ``` find_code(pattern: 'throw new $EXCEPTION($$$ARGS)', language: java, project_folder: "<dir>") ``` **SQL 来源提取**：复用 `sql-extract` 技能的 rule，参见 `sql-extract/SKILL.md`。 > **注意**：AST 命中结果为候选点，需人工确认业务语义后写入规则文档。 ### 规则输出格式 每条规则需记录：规则ID、规则名称、规则描述、触发条件/适用场景、代码位置 模板见 `templates/business_rules.md` ## 需求分析维度 | 维度 | 分析内容 | | ---------- | ------------------------------------------------ | | 业务需求 | 业务场景、业务流程、业务规则、业务约束 | | 功能需求 | 核心功能、辅助功能、边界条件、异常处理 | | 非功能需求 | 性能要求、安全要求、可用性要求、兼容性要求 | | 数据需求 | 数据实体、数据关系、数据约束、数据流转 | ## 需求识别技巧 | 代码特征 | 需求类型 | | ------------------ | ---------------------------- | | Controller 层 | API 接口需求 | | Service 层 | 业务逻辑需求 | | DAO 层 | 数据访问需求 | | 配置文件 | 配置需求 | | 异常处理 | 异常场景需求 | | 日志记录 | 可观测性需求 | | 注释/文档 | 业务规则线索 | | 表结构/字段约束 | 数据实体/业务规则需求 | | 索引/外键/触发器 | 性能/数据关系/自动化需求 | | 测试场景/边界测试 | 业务场景/边界条件需求 | ## 源代码类型 ### 直接源码 Java(`*.java`)、Python(`*.py`)、C++(`*.cpp/*.hpp`)、ANSI C(`*.c/*.h`)、 JavaScript(`*.js/*.mjs`)、TypeScript(`*.ts/*.tsx`)、Rust(`*.rs`)、 Go(`*.go`)、Kotlin(`*.kt`)、Scala(`*.scala`)、Shell(`*.sh`)、Batch(`*.bat/*.ps1`) ### SQL 来源 | 来源 | 提取方法 | | ------------------- | ------------------------------------ | | `*.sql` | 直接读取 | | MyBatis Mapper XML | 从 SQL 标签提取，合并 include 引用 | | Hibernate/JPA 注解 | 从 `@Query`/`@NamedQuery` 提取 | | Java/Python 字符串 | 正则匹配 SQL 关键字模式 | ### SQL 提取正则 ```regex (?i)(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|TRUNCATE)\s+ (?i)(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP)\s+[\w\s\*,\.\(\)]+(FROM|INTO|TABLE|SET|VALUES|WHERE|JOIN|ORDER|GROUP|HAVING) ``` ## 输出目录结构 ```text docs/requirements/ ├── module_inventory.md # 模块清单（必须） ├── global_requirements.md # 全局需求文档 ├── {package}/ # 分模块需求文档 │ └── requirements.md ``` ## 输出模板 | 模板文件 | 用途 | | ---------------------------------- | -------------- | | `templates/module_inventory.md` | 模块清单 | | `templates/module_requirements.md` | 分模块需求文档 | | `templates/business_rules.md` | 业务规则章节 | | `templates/global_requirements.md` | 全局需求文档 | ## 完整性检查清单 <HARD-GATE> **执行完成后必须通过以下检查，否则视为执行失败** </HARD-GATE> ### 模块覆盖 - [ ] 所有模块已列入 `module_inventory.md` - [ ] 所有模块均有对应的需求文档 - [ ] 需求文档数量与模块数量一致 ### 文档完整性 - [ ] 模块概述章节 - [ ] 业务场景章节（含场景列表+场景详情） - [ ] 功能需求章节（含核心功能+辅助功能） - [ ] 业务规则章节（独立章节，含规则分类+规则详情） - [ ] 数据需求章节（含数据实体+数据流转） - [ ] 非功能需求章节 - [ ] 约束条件章节 ### 业务规则检查 - [ ] 业务规则已从代码中深度挖掘 - [ ] 业务规则已分类整理 - [ ] 每条规则有代码位置引用 - [ ] 规则详情包含触发条件、适用场景 ### 全局文档检查 - [ ] 模块清单已生成 - [ ] 全局需求文档已生成 - [ ] 业务规则汇总章节存在 - [ ] 功能全景章节存在 - [ ] 数据全景章节存在 ## 关联技能 设计解构请使用技能：`code-deconstruct` SQL 提取请使用技能：`sql-extract`（ast-grep-mcp 联动，精准提取内嵌 SQL）