Code Test Check

SKILL.md

---
name: code-test-check
description: |
  根据本地 PRD 需求文档或功能测试用例(Excel/JSON)，分析用户指定的后端与前端源码，验证需求功能点/测试用例是否被代码实现，输出 Markdown 验证报告（含代码证据与实现状态矩阵）。
---

# 代码测试核查器

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

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

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

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

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

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

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

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

| 确认项 | 说明 |
|--------|------|
| 后端源码目录 | 后端代码绝对路径。优先指定功能最相关的具体目录（如控制器层、路由层、对应业务模块的 Model/Service 目录），范围越小、搜索越精准；未指定具体目录时使用后端代码根目录。 |
| 前端源码目录 | 前端代码绝对路径。优先指定功能最相关的具体目录（如涉及模块的 `views/pages` 目录、`api` 接口定义目录）；未指定具体目录时使用前端代码根目录。 |
| 技术栈与分层约定 | 框架（如 ThinkPHP/Spring Boot/Django/Express/Gin 等；Vue/React 等）及关键目录的位置，用于锁定接口层、数据层、常量层等。 |

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

**搜索范围确定流程：**

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` 读取命中的代码，核对实现逻辑是否真正满足需求描述（而非仅关键词命中）

**判定实现状态：**

| 状态 | 标记 | 判定标准 |
|------|------|---------|
| 已实现 | ✅ | 找到对应代码，且实现逻辑符合 PRD 描述 |
| 部分实现 | ⚠️ | 找到相关代码，但存在缺失分支/未覆盖场景/逻辑不完整 |
| 未实现 | ❌ | 在前后端均未找到对应代码 |
| 偏离需求 | 🔀 | 找到代码，但实现方式与 PRD 描述不一致 |

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

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

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

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

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

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

| 资产类型 | 后端识别方法 | 前端识别方法 |
|---------|------------|------------|
| 数据模型/字段 | 改动的 Model/实体类、新增/变更的数据库字段 | 接口返回字段变化 |
| 接口 | 新增/改动的路由路径、控制器/处理方法 | 前端接口定义模块中改动的接口 |
| 常量/枚举 | 常量/枚举定义处改动的状态码、枚举值 | 前端状态映射常量 |
| 公共方法 | 被修改的 Model/Service 公共方法、公共函数 | 被修改的公共组件、工具函数 |
| 事件/钩子 | 改动的事件监听、模型事件 | - |

> 💡 上述"控制器/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 引用了接口文档，优先以接口文档的字段/路径为搜索锚点。
- **局限性声明**：源码静态分析无法覆盖运行时行为（如动态配置、权限控制、异步任务），报告中需说明验证边界。
- 大型需求先按模块拆分，分批验证，避免一次性功能点过多导致分析不充分。