Code Test Check

代码测试核查器

根据 PRD 需求文档 或 功能测试用例（Excel / JSON），在用户指定的前后端源码中逐条核查功能点是否被实现，输出带代码证据的 Markdown 验证报告。

开始时宣布： "我正在使用代码测试核查技能。"

核心原则（最高优先级，不可违背）

1. 证据驱动：每一个实现状态判定，必须附上代码位置（文件路径:行号）和关键代码片段。无证据不得判定为"已实现"。
2. 禁止臆测：找不到对应代码就标记为"未找到/未实现"，严禁因"功能常见"或"AI 一般会写"而假设其存在。
3. 只读分析：只读取和分析源码，绝不修改源码、不连数据库、不调用真实接口。
4. 需求为准：当代码实现与需求描述（PRD 或测试用例的预期结果）不一致时，以需求为准确认，并标记为"偏离需求"。
5. 必须分析关联影响（防漏测）：验证完需求点本身，强制追加关联模块影响分析——识别本次改动触及的共享代码资产（模型/字段/接口/常量/组件），反向追溯其调用方与依赖方，评估是否受波及。不做关联影响分析 = 漏测，报告不完整。

源码位置与搜索范围（由用户指定，不预设项目）

本技能不内置任何特定项目，源码路径、技术栈、目录结构均以用户指定为准。

原则：搜索范围越小越精准、越快。 直接扫描整个项目根目录会命中大量无关代码（依赖、配置、构建产物、测试夹具等），导致噪声多、效率低。因此优先让用户指定最贴近功能点的具体目录，只有用户未指定时才回退到更大的代码目录。

开始验证前，必须先与用户确认以下信息：

若项目无后端或无前端，对应端可省略，只验证单端。

搜索范围确定流程：

1. 先问用户：询问本次需求最相关的后端接口/业务目录、前端路由/页面目录（推荐直接给出绝对路径）。
2. 用户给了具体目录 → 直接用这些目录作为 SearchCodebase 的 target_directories 和 Grep 的 path，范围最窄、噪声最少。
3. 用户未给具体目录、只给了根目录 → 回退到代码根目录，但需先用 Glob/LS 探测框架特征目录（如 controllers、routes、models、src/api、src/views、src/components），把搜索范围收敛到源码目录，排除依赖与构建产物（vendor、node_modules、dist、build、runtime、target 等）。常见技术栈的目录锚点参考 references/tech-stack-guide.md。
4. 无论哪种情况，将最终确定的「搜索范围 + 目录锚点表」整理出来并向用户确认一次，后续所有搜索都以此为范围。

⚠️ 全程不得假设目录结构，一切以用户指定或探测结果为准。能缩小范围就缩小，避免全量扫描。

工作流程

第一步：读取并理解输入材料

本技能支持两种输入源，根据用户提供的材料类型选择解析方式：

输入源 A：PRD 需求文档（Word / PDF / Markdown / 纯文本）

1. 读取用户指定的本地 PRD 文档
2. 提取核心信息：功能模块、业务规则、字段要求、接口定义、交互逻辑、约束条件、异常处理
3. 若文档较大，分模块理解，记录每个模块的验收标准

输入源 B：功能测试用例（Excel / JSON）

1. 读取测试用例文件。JSON 格式结构为 { module_name, cases: [{ case_id, module, title, precondition, steps, expected, priority }] }
2. 提取每条用例的：模块(module)、标题(title)、前置条件(precondition)、步骤(steps)、预期结果(expected)
3. 预期结果即为验证标准：测试用例的 expected 字段天然定义了可验证的验收标准，直接作为功能点的判定依据

💡 当用户同时提供 PRD 和测试用例时，以测试用例为验证主轴（因其颗粒度更细、可验证性更强），PRD 作为补充上下文。

第二步：构建原子化功能点清单

根据输入源类型，构建可独立验证的原子功能点清单。

输入源 A（PRD）：将需求拆解为原子功能点。每个功能点必须满足：

• 单一职责：一个功能点只描述一个可验证的行为
• 可验证：能在源码中通过搜索/阅读找到对应实现（接口、逻辑、UI 之一）
• 可判定：有明确的"实现/未实现"判定标准
• 归属明确：标注该功能点主要由后端还是前端实现（或两者协同）

功能点粒度示例（以"某业务对象审批"为例）：

• ✅ 好的拆解："审批列表支持按状态筛选"、"审批通过时必填审批意见"、"驳回后状态回写为待处理"
• ❌ 坏的拆解："实现审批功能"（太大，无法定位）

输入源 B（测试用例）：测试用例本身即功能点，但需做聚合优化：

1. 直接映射：每条测试用例（title + expected）作为一个待验证功能点，保留原 case_id 作为编号
2. 按模块聚合：相同 module 的用例归为一组，便于分批验证
3. 去重合并：若多条用例验证同一代码实现的不同数据场景（如同接口的不同角色），合并为一个功能点、保留子场景说明
4. 优先级继承：保留用例的 priority（P0 用例的未实现项为最高风险）

无论哪种输入源，整理为带编号的清单后，向用户确认清单再进入验证（功能点过多时分批确认）。

第三步：逐条验证（核心步骤）

对每个功能点，按以下策略在用户指定的后端/前端源码目录中查找实现证据。详细工具用法见 references/tech-stack-guide.md。

搜索策略（由广到窄）：

1. 语义搜索定位：用 SearchCodebase 在上方确认的后端、前端搜索范围（具体目录优先，无则代码根目录）中按功能语义搜索，定位相关文件
   • 每个功能点至少分别在后端、前端各做一次语义搜索
   • 搜索问题要具体，如"XX审批通过的接口实现在哪里"
2. 精确匹配确认：用 Grep 在同一搜索范围内，按关键标识符（方法名、路由路径、字段名、文案）精确匹配
3. 阅读代码验证逻辑：用 Read 读取命中的代码，核对实现逻辑是否真正满足需求描述（而非仅关键词命中）

判定实现状态：

判定要点：

• 接口类功能点：核对路由定义 + 控制器/处理方法 + 参数校验 + 业务逻辑
• 字段类功能点：核对数据库字段使用、请求参数、响应输出、前端表单绑定
• 交互类功能点：核对前端事件绑定、组件属性、状态流转
• 规则类功能点：核对校验逻辑、常量定义、条件分支

第四步：关联模块影响分析（防漏测，必做）

只验证需求点本身会漏掉回归风险。本步骤识别本次改动对其他模块的潜在影响，找出需要回归验证的关联点。

分析思路（三步反向追溯）：

4.1 识别本次触及的共享代码资产

从第三步已定位的代码中，提取被改动/新增的"共享资产"，这些是影响外溢的源头：

💡 上述"控制器/Model/常量/接口定义模块"等均指第 0 步探测到的项目对应分层目录。

4.2 反向追溯调用方与依赖方

对每个共享资产，反向查找"谁还在用它"，判断是否受波及：

• 后端：用 Grep 搜索该 Model/实体类名、方法名、字段名、路由路径在整个后端源码中的其他调用处
• 前端：用 Grep 搜索该接口方法、组件名、字段名在整个前端源码中的其他引用处
• 跨端：后端接口返回字段变化 → 搜索前端所有消费该字段的页面

4.3 评估影响并标记回归点

对每个关联调用方，判定影响等级：

分析要点（防遗漏）：

• 共享 Model 的新增字段/状态：搜索所有读写该字段的代码，尤其是列表筛选、状态流转、统计报表
• 常量/枚举变更：搜索所有引用该常量的条件分支（极易遗漏）
• 接口入参/出参变化：前端所有调用方 + 后端所有内部调用
• 公共方法签名/行为变化：所有调用链
• 数据库字段约束/默认值变化：依赖该字段的写入逻辑、统计逻辑

第五步：生成 Markdown 验证报告

按 report/report-template.md 模板生成报告，保存到需求文档同目录或 docs/ 对应模块目录下。

文件命名：<需求名称>_实现验证报告_<日期>.md，日期格式 YYYYMMDD。

第六步：输出总结

向用户展示：

1. 实现度：已实现 X / 部分 Y / 未实现 Z / 偏离 W（含百分比）
2. 风险提示：未实现和偏离的功能点（测试重点）
3. 关联影响：高风险回归点 N 个、低风险 M 个（防漏测重点）
4. 报告路径：生成的 Markdown 文件路径

注意事项

• 防误判：关键词命中 ≠ 功能实现。必须阅读代码确认逻辑，尤其注意注释掉的代码、空实现、TODO 标记。
• 前后端协同：一个功能可能需要前后端配合，两者都要验证。例如"审批通过"需要后端接口 + 前端按钮调用，缺一不可标记为部分实现。
• 版本一致性：若 PRD 引用了接口文档，优先以接口文档的字段/路径为搜索锚点。
• 局限性声明：源码静态分析无法覆盖运行时行为（如动态配置、权限控制、异步任务），报告中需说明验证边界。
• 大型需求先按模块拆分，分批验证，避免一次性功能点过多导致分析不充分。