@pzy560117/codex-harness 0.1.2 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/testing/TEST_STRATEGY.md

@@ -1,97 +1,98 @@
-# 测试策略
-
-**功能 / 项目**:
-**最后更新**:
-**负责人**:
-
-## 测试层级
-
-- 单元:
-- 组件:
-- API / 契约:
-- 集成:
-- E2E:
-- 视觉:
-
-## 开发验证与验收验证分层
-
-Harness 把实现过程中的快速反馈和交付前的完整验收拆成两个独立闸门:
-
-| 闸门 | 目的 | 典型验证 | 完成条件 |
-| --- | --- | --- | --- |
-| 自然语言测试用例 | 把 PRD 每条需求转成可审查、可追溯、可转脚本的测试用例 | `NATURAL_LANGUAGE_TEST_CASES.md`、需求类型覆盖矩阵、Gherkin/步骤化用例、Oracle、测试数据、证据路径、TDD RED 预期失败 | 每条需求都要分类；P0/P1 按需求类型满足最小用例数；P2 需写用例或豁免原因；TDD 候选用例可被 `tdd_contract.red.source_case_ids` 引用 |
-| TDD RED | 在生产代码变更前证明新增或变更行为当前缺失 | 聚焦单元、组件、契约或 API 测试；必须先失败且失败原因匹配预期 | 作为 `tdd_contract.red` 证据进入任务；失败原因不是目标行为缺失时不得进入实现 |
-| TDD GREEN / REFACTOR | 用最小实现让同一聚焦测试通过，并在重构后保持相关验证绿色 | 同一 focused test、affected tests、coverage、lint 或类型检查 | 作为 `tdd_contract.green` 和 `tdd_contract.refactor_guard` 证据进入任务；不能替代最终验收 |
-| 开发验证 | 支撑编码过程中的快速反馈，证明局部改动没有破坏直接相关行为 | 单元、组件、局部 API、契约检查、affected tests、静态检查、类型检查、lint | 作为实现过程证据进入 `development_validation`，但不能单独声明任务完成 |
-| 验收验证 | 从用户、业务闭环或发布候选视角证明当前交付可被验收 | 用户故事完整链路、跨故事主流程、真实入口 E2E、数据副作用、失败态、P0/P1 回归、视觉/可访问性确认 | 作为完成前 fresh evidence 进入 `acceptance_validation`，缺失时任务必须 BLOCKED 或有 owner 批准的 exemption |
-
-开发验证通过只说明局部实现可继续推进，不等于用户验收通过。PRD 完成后、进入实现前必须先生成自然语言测试用例；每个 `feature_impl` 默认要求 TDD：从自然语言用例选择 TDD 候选，先写聚焦测试并确认 RED 失败，再写最小实现确认 GREEN，通过后才允许重构。每个 `feature_impl` 完成前必须在代码写完后重新运行故事级验收链路；每个 `release` 完成前必须运行发布候选级跨故事验收链路。验收验证不得直接复用编码中途的旧日志，除非证据协议明确证明其仍是当前变更集的 fresh evidence。
-
-## 自然语言用例规模规则
-
-自然语言测试用例不是每条需求固定写 1 条，而是先判定需求类型，再按 `NATURAL_LANGUAGE_TEST_CASES.md` 的覆盖矩阵取最小用例数。基础原则:
-
-- P0 需求默认不少于 5 条，P1 需求默认不少于 3 条，P2 可为 1-2 条并说明不进入 TDD 候选的原因。
-- 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
-- 只读查询至少覆盖正常、空数据和无权限；列表类还要覆盖筛选、分页、排序或组合条件。
-- 新增、编辑、删除等写操作至少覆盖成功副作用、输入失败、权限失败无副作用、非法状态或并发冲突。
-- 权限、状态机、异步链路、外部系统、金额库存、文件处理和安全需求必须按风险路径加量，不能只写 happy path。
-- 一个需求跨多个类型时，按风险最高类型取基准，再补齐其他类型的必需路径。
-- TESTCASE 阶段必须在覆盖检查表中写明“需求类型、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数、加量理由”，不足时不得进入 `feature_impl`。
-- 非 TDD 自然语言用例必须映射到 `story_full_chain`、`acceptance_validation`、回归或 `verify-matrix`，不能因为不适合作为 RED 种子就从验收链路消失。
-
-## QA Harness 最小闭环
-
-测试设计按下面顺序推进，不允许直接从需求跳到测试脚本:
-
-1. 资料输入: 读取需求、代码、API 契约、UI、数据模型、权限规则和历史缺陷。
-2. 风险建模: 输出业务实体、状态、角色权限、接口、数据副作用和外部依赖风险。
-3. 自然语言用例: 按 PRD / Requirement ID 识别需求类型和风险因子，按覆盖矩阵写出目标、来源、前置条件、动作、预期结果、Oracle、测试数据、证据路径和 TDD RED 预期失败。
-4. 测试意图: 将自然语言用例映射到测试层级、风险、数据和可执行验证命令。
-5. Oracle 审查: 通过后才生成或修改测试脚本。
-6. TDD RED: `feature_impl` 从 `NATURAL_LANGUAGE_TEST_CASES.md` 的 TDD 候选用例生成聚焦测试，运行 `tdd_contract.red.command`，确认失败原因匹配目标行为缺失并记录证据。
-7. TDD GREEN: 写最小实现后运行 `tdd_contract.green.command`，确认同一聚焦测试通过。
-8. TDD REFACTOR: 重构后运行 `tdd_contract.refactor_guard.command` 和必要覆盖率命令，确认相关验证仍通过。
-9. 开发验证: 编码过程中运行 affected tests、局部契约、类型检查、lint 或单元 / 组件测试，记录 `development_validation` 证据。
-10. 验收验证: 代码写完后从用户、业务闭环或发布候选视角运行完整链路，记录 `acceptance_validation` fresh evidence。
-11. 证据归档: 把命令、退出码、日志、截图、DB diff、事件、Trace 等写入证据路径。
-12. 失败归因: 区分产品缺陷、测试缺陷、环境问题和数据问题。
-13. 回归沉淀: 真实缺陷修复后补充回归用例或知识候选。
-
-## Oracle 优先规则
-
-每个测试用例必须在写脚本前定义至少一个业务 Oracle。写接口、状态流转、权限和数据一致性场景通常需要多个 Oracle 组合:
-
-| Oracle 类型 | 适用场景 | 最小要求 |
-| --- | --- | --- |
-| 返回值 | API、服务、UI 动作 | 状态码、错误码、关键字段和业务语义 |
-| Schema / Contract | API、事件、文件 | 字段类型、必填、枚举、版本兼容 |
-| 数据库副作用 | POST / PUT / PATCH / DELETE、批处理 | before / after diff、目标字段变化、非目标字段不变 |
-| 缓存 | 读写缓存、权限缓存、多租户 | key 维度、TTL、失效、跨用户隔离 |
-| 事件 / 队列 | 异步链路、Webhook、消息消费 | event type、payload、重试、幂等、DLQ |
-| 审计 | 登录、权限、资金、删除、审批 | actor、action、object、result、time |
-| 权限 | 水平越权、垂直越权、字段级权限 | 允许 / 拒绝符合权限矩阵，拒绝时无副作用 |
-| 状态机 | 订单、审批、发布、退款等状态流转 | 合法转移成功，非法转移失败且无污染 |
-| 不变量 | 金额、库存、次数、唯一性 | 余额 / 库存不为负，总额守恒，唯一业务结果 |
-| Trace / 证据 | E2E、集成、跨服务 | 命中预期链路、日志或 coverage 可证明目标路径 |
-
-## 假测试拦截规则
-
-Stage 2 必须拦截下列测试:
-
-- 只断言 `200`、`truthy`、元素存在或 snapshot，没有业务断言。
-- 写操作没有 DB、缓存、事件、审计、文件或通知等副作用断言。
-- 权限失败只断言 `403`，没有验证目标数据未变化、响应未泄露和缓存未污染。
-- mock 了当前被测 service、权限判断、状态机、数据库写入或核心业务路径。
-- 没有绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
-- 没有执行证据，或证据不是当前变更集产生的 fresh evidence。
-- 测试名称覆盖多个路径，但实际只跑 happy path。
-
-## 阻塞性失败
-
--
-
-## Fresh Evidence 策略
-
-- Stage 17 只确认 fresh evidence 和回归状态。
-- 缺少验收示例或需求追溯属于实现前缺口，不是 Stage 17 的任务。
+# 测试策略
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 测试层级
+
+- 单元:
+- 组件:
+- API / 契约:
+- 集成:
+- E2E:
+- 视觉:
+
+## 开发验证与验收验证分层
+
+Harness 把实现过程中的快速反馈和交付前的完整验收拆成两个独立闸门:
+
+| 闸门 | 目的 | 典型验证 | 完成条件 |
+| --- | --- | --- | --- |
+| 自然语言测试用例 | 把 PRD 每条需求转成可审查、可追溯、可转脚本的测试用例 | `NATURAL_LANGUAGE_TEST_CASES.md`、需求类型覆盖矩阵、Gherkin/步骤化用例、Oracle、测试数据、证据路径、TDD RED 预期失败 | 每条需求都要分类；P0/P1 按需求类型满足最小用例数；P2 需写用例或豁免原因；TDD 候选用例可被 `tdd_contract.red.source_case_ids` 引用 |
+| TDD RED | 在生产代码变更前证明新增或变更行为当前缺失 | 聚焦单元、组件、契约或 API 测试；必须先失败且失败原因匹配预期 | 作为 `tdd_contract.red` 证据进入任务；失败原因不是目标行为缺失时不得进入实现 |
+| TDD GREEN / REFACTOR | 用最小实现让同一聚焦测试通过，并在重构后保持相关验证绿色 | 同一 focused test、affected tests、coverage、lint 或类型检查 | 作为 `tdd_contract.green` 和 `tdd_contract.refactor_guard` 证据进入任务；不能替代最终验收 |
+| 开发验证 | 支撑编码过程中的快速反馈，证明局部改动没有破坏直接相关行为 | 单元、组件、局部 API、契约检查、affected tests、静态检查、类型检查、lint | 作为实现过程证据进入 `development_validation`，但不能单独声明任务完成 |
+| 验收验证 | 从用户、业务闭环或发布候选视角证明当前交付可被验收 | 用户故事完整链路、跨故事主流程、真实入口 E2E、数据副作用、失败态、P0/P1 回归、视觉/可访问性确认 | 作为完成前 fresh evidence 进入 `acceptance_validation`，缺失时任务必须 BLOCKED 或有 owner 批准的 exemption |
+
+开发验证通过只说明局部实现可继续推进，不等于用户验收通过。PRD 完成后、进入实现前必须先生成自然语言测试用例；每个 `feature_impl` 默认要求 TDD：从自然语言用例选择 TDD 候选，先写聚焦测试并确认 RED 失败，再写最小实现确认 GREEN，通过后才允许重构。每个 `feature_impl` 完成前必须在代码写完后重新运行故事级验收链路；每个 `release` 完成前必须运行发布候选级跨故事验收链路。验收验证不得直接复用编码中途的旧日志，除非证据协议明确证明其仍是当前变更集的 fresh evidence。
+
+## 自然语言用例规模规则
+
+自然语言测试用例不是每条需求固定写 1 条，而是先判定需求类型，再按 `NATURAL_LANGUAGE_TEST_CASES.md` 的覆盖矩阵取最小用例数。基础原则:
+
+- P0 需求默认不少于 5 条，P1 需求默认不少于 3 条，P2 可为 1-2 条并说明不进入 TDD 候选的原因。
+- 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
+- 只读查询至少覆盖正常、空数据和无权限；列表类还要覆盖筛选、分页、排序或组合条件。
+- 新增、编辑、删除等写操作至少覆盖成功副作用、输入失败、权限失败无副作用、非法状态或并发冲突。
+- 权限、状态机、异步链路、外部系统、金额库存、文件处理和安全需求必须按风险路径加量，不能只写 happy path。
+- 一个需求跨多个类型时，按风险最高类型取基准，再补齐其他类型的必需路径。
+- TESTCASE 阶段必须在覆盖检查表中写明“需求类型、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数、加量理由”，不足时不得进入 `feature_impl`。
+- 非 TDD 自然语言用例必须映射到 `story_full_chain`、`acceptance_validation`、回归或 `verify-matrix`，不能因为不适合作为 RED 种子就从验收链路消失。
+- 业务规则如果会影响状态流转、副作用、金额/库存、权限或幂等，必须至少有一条异常路径或无副作用路径用例。
+
+## QA Harness 最小闭环
+
+测试设计按下面顺序推进，不允许直接从需求跳到测试脚本:
+
+1. 资料输入: 读取需求、代码、API 契约、UI、数据模型、权限规则和历史缺陷。
+2. 风险建模: 输出业务实体、状态、角色权限、接口、数据副作用和外部依赖风险。
+3. 自然语言用例: 按 PRD / Requirement ID 识别需求类型和风险因子，按覆盖矩阵写出目标、来源、前置条件、动作、预期结果、Oracle、测试数据、证据路径和 TDD RED 预期失败。
+4. 测试意图: 将自然语言用例映射到测试层级、风险、数据和可执行验证命令。
+5. Oracle 审查: 通过后才生成或修改测试脚本。
+6. TDD RED: `feature_impl` 从 `NATURAL_LANGUAGE_TEST_CASES.md` 的 TDD 候选用例生成聚焦测试，运行 `tdd_contract.red.command`，确认失败原因匹配目标行为缺失并记录证据。
+7. TDD GREEN: 写最小实现后运行 `tdd_contract.green.command`，确认同一聚焦测试通过。
+8. TDD REFACTOR: 重构后运行 `tdd_contract.refactor_guard.command` 和必要覆盖率命令，确认相关验证仍通过。
+9. 开发验证: 编码过程中运行 affected tests、局部契约、类型检查、lint 或单元 / 组件测试，记录 `development_validation` 证据。
+10. 验收验证: 代码写完后从用户、业务闭环或发布候选视角运行完整链路，记录 `acceptance_validation` fresh evidence。
+11. 证据归档: 把命令、退出码、日志、截图、DB diff、事件、Trace 等写入证据路径。
+12. 失败归因: 区分产品缺陷、测试缺陷、环境问题和数据问题。
+13. 回归沉淀: 真实缺陷修复后补充回归用例或知识候选。
+
+## Oracle 优先规则
+
+每个测试用例必须在写脚本前定义至少一个业务 Oracle。写接口、状态流转、权限和数据一致性场景通常需要多个 Oracle 组合:
+
+| Oracle 类型 | 适用场景 | 最小要求 |
+| --- | --- | --- |
+| 返回值 | API、服务、UI 动作 | 状态码、错误码、关键字段和业务语义 |
+| Schema / Contract | API、事件、文件 | 字段类型、必填、枚举、版本兼容 |
+| 数据库副作用 | POST / PUT / PATCH / DELETE、批处理 | before / after diff、目标字段变化、非目标字段不变 |
+| 缓存 | 读写缓存、权限缓存、多租户 | key 维度、TTL、失效、跨用户隔离 |
+| 事件 / 队列 | 异步链路、Webhook、消息消费 | event type、payload、重试、幂等、DLQ |
+| 审计 | 登录、权限、资金、删除、审批 | actor、action、object、result、time |
+| 权限 | 水平越权、垂直越权、字段级权限 | 允许 / 拒绝符合权限矩阵，拒绝时无副作用 |
+| 状态机 | 订单、审批、发布、退款等状态流转 | 合法转移成功，非法转移失败且无污染 |
+| 不变量 | 金额、库存、次数、唯一性 | 余额 / 库存不为负，总额守恒，唯一业务结果 |
+| Trace / 证据 | E2E、集成、跨服务 | 命中预期链路、日志或 coverage 可证明目标路径 |
+
+## 假测试拦截规则
+
+Stage 2 必须拦截下列测试:
+
+- 只断言 `200`、`truthy`、元素存在或 snapshot，没有业务断言。
+- 写操作没有 DB、缓存、事件、审计、文件或通知等副作用断言。
+- 权限失败只断言 `403`，没有验证目标数据未变化、响应未泄露和缓存未污染。
+- mock 了当前被测 service、权限判断、状态机、数据库写入或核心业务路径。
+- 没有绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
+- 没有执行证据，或证据不是当前变更集产生的 fresh evidence。
+- 测试名称覆盖多个路径，但实际只跑 happy path。
+
+## 阻塞性失败
+
+-
+
+## Fresh Evidence 策略
+
+- Stage 17 只确认 fresh evidence 和回归状态。
+- 缺少验收示例或需求追溯属于实现前缺口，不是 Stage 17 的任务。

package/package-source/docs/codex-harness-engineering/templates/testing/TRACEABILITY_MATRIX.md

@@ -15,8 +15,9 @@
 ## 规则
 
 - 每条 P0/P1 需求都必须恰好出现一次，或被明确拆分。
-- 每一行都必须指向至少一个测试层级和一个证据路径。
-- UI 行必须包含所需状态或明确豁免。
-- API / 数据行必须包含契约或 schema 校验证据。
-- 写操作、权限失败、非法状态流转和异步链路必须包含副作用或无副作用 Oracle。
-- 缺少 Oracle 或证据路径的 P0/P1 行不能进入实现。
+- 每一行都必须指向至少一个测试层级和一个证据路径。
+- UI 行必须包含所需状态或明确豁免。
+- API / 数据行必须包含契约或 schema 校验证据。
+- 写操作、权限失败、非法状态流转和异步链路必须包含副作用或无副作用 Oracle。
+- 每条 P0/P1 业务规则至少要在矩阵中出现一次，并绑定页面状态、Oracle 和测试层级。
+- 缺少 Oracle 或证据路径的 P0/P1 行不能进入实现。

package/package-source/docs/codex-harness-engineering/templates/testing/coverage-policy.md

@@ -1,25 +1,25 @@
-# 覆盖率策略
-
-**功能**:
-**覆盖率工具**:
-**覆盖率报告路径**:
-
-## 阈值
-
-| 范围 | 最低要求 | 备注 |
-| --- | --- | --- |
-| 业务规则 | 80% | 定价、库存、权限、校验 |
-| API / 服务层 | 80% | 包含成功和错误分支 |
-| UI 组件 | 覆盖关键状态 | 相比原始行覆盖率，更优先覆盖交互 / 状态 |
-| E2E | 覆盖 P0/P1 主流程 | 不按行覆盖率衡量 |
-| 视觉 | P0 UI + 高风险状态 | 必须提供截图证据 |
-
-## 豁免
-
-| 路径 / 模块 | 原因 | 批准人 | 替代证据 |
-| --- | --- | --- | --- |
-| | | | |
-
-## Stage 2 规则
-
-如果关键业务逻辑未被覆盖，且不存在豁免或替代证据，Stage 2 必须失败。
+# 覆盖率策略
+
+**功能**:
+**覆盖率工具**:
+**覆盖率报告路径**:
+
+## 阈值
+
+| 范围 | 最低要求 | 备注 |
+| --- | --- | --- |
+| 业务规则 | 80% | 定价、库存、权限、校验 |
+| API / 服务层 | 80% | 包含成功和错误分支 |
+| UI 组件 | 覆盖关键状态 | 相比原始行覆盖率，更优先覆盖交互 / 状态 |
+| E2E | 覆盖 P0/P1 主流程 | 不按行覆盖率衡量 |
+| 视觉 | P0 UI + 高风险状态 | 必须提供截图证据 |
+
+## 豁免
+
+| 路径 / 模块 | 原因 | 批准人 | 替代证据 |
+| --- | --- | --- | --- |
+| | | | |
+
+## Stage 2 规则
+
+如果关键业务逻辑未被覆盖，且不存在豁免或替代证据，Stage 2 必须失败。

package/package-source/docs/codex-harness-engineering/templates/testing/e2e-plan.md

@@ -1,139 +1,139 @@
-# E2E 计划
-
-**功能**:
-**基础 URL**:
-**后端 URL**:
-**Seed 命令**:
-**测试数据计划**:
-**导航入口**: `docs/ai/repo-map.md` / `docs/context/repo-map.md`
-**关联代码理解摘要**:
-
-## 1. 功能概览
-
-- 目标:
-- 业务背景:
-- 适用角色:
-- 不覆盖范围:
-
-## 2. 代码入口与影响面
-
-先从 `repo-map` / codemap 进入，再补充局部文件阅读。不要先全仓盲扫。
-
-| 类别 | 入口 / 文件 | 说明 | 受影响测试 |
-| --- | --- | --- | --- |
-| 页面 / 路由 |  |  |  |
-| 组件 |  |  |  |
-| Hook / Store / State |  |  |  |
-| API / Service |  |  |  |
-| 数据模型 / 持久化 |  |  |  |
-
-## 3. 范围与角色
-
-- 范围内:
-- 范围外:
-- 必需角色:
-- 权限差异:
-- 登录态要求:
-
-## 4. 前置条件
-
-- 环境与服务:
-- Feature flag:
-- 账号 / 权限:
-- Seed 数据:
-- 外部依赖:
-- 已知豁免:
-
-## 5. 测试数据
-
-| 数据名称 | 用途 | 来源 | 重置方式 |
-| --- | --- | --- | --- |
-| 正常数据 | 主流程 |  |  |
-| 边界数据 | 边界 / 上下限 |  |  |
-| 非法数据 | 异常 / 权限 / 拒绝路径 |  |  |
-
-## 6. 核心主流程
-
-| ID | 角色 | 主流程 | 对应需求 | 测试数据 | 期望证据 |
-| --- | --- | --- | --- | --- | --- |
-| E2E-001 | 用户 |  |  |  | 报告 + 截图 / 视频 + 状态证据 |
-
-## 7. 异常与边界流程
-
-| ID | 类型 | 场景 | 预期结果 | 证据 |
-| --- | --- | --- | --- | --- |
-| E2E-NEG-001 | 异常 |  |  |  |
-| E2E-BND-001 | 边界 |  |  |  |
-
-至少检查：
-
-- 空数据
-- 最大 / 最小输入
-- 重复提交
-- 网络慢
-- 接口失败
-- 登录过期
-- 权限不足
-
-## 8. 页面与 UI 断言
-
-| 页面 | 状态 | 断言 | 测试层级 |
-| --- | --- | --- | --- |
-|  | 默认 |  | T5 / T6 |
-|  | 错误态 |  | T5 / T6 |
-|  | 空态 |  | T5 / T6 |
-|  | 成功态 |  | T5 / T6 |
-
-## 9. 接口与网络预期
-
-| 入口动作 | 请求 | 成功预期 | 失败预期 |
-| --- | --- | --- | --- |
-|  | `METHOD /path` |  |  |
-
-## 10. 可访问性与交互约束
-
-- 优先使用用户可见语义定位：
-  - `getByRole`
-  - `getByLabel`
-  - `getByPlaceholder`
-  - `getByTestId`
-- 避免把 DOM 层级或脆弱 CSS 选择器作为主定位手段。
-- 记录关键按钮、表单标签、错误提示、loading、键盘操作和 aria 期望。
-
-## 11. Mock 排雷
-
-- [ ] 从 `repo-map`、代码入口和测试目录搜索 `mock`、`fixture`、`fake`、`hardcoded`。
-- [ ] P0 / P1 主流程使用真实后端或明确声明的 mock server。
-- [ ] 必须 mock 的状态已在 `test-matrix.md`、`verify-matrix.md` 或豁免说明中写明。
-- [ ] 前端页面如仍依赖本地假数据，先创建清理任务，再把该 E2E 标记为可执行。
-
-## 12. 受影响测试与执行顺序
-
-| 类别 | 测试 / 命令 | 原因 | 优先级 |
-| --- | --- | --- | --- |
-| Existing |  |  | P0 |
-| New |  |  | P0 |
-
-推荐顺序：
-
-1. 先跑 affected tests / contract checks。
-2. 再跑本计划对应的最小 E2E 集。
-3. 最后跑 P0 / P1 回归或跨故事整链路。
-
-## 13. 失败归因入口
-
-失败后不要直接改测试，先分类：
-
-1. 测试代码问题
-2. 产品 Bug
-3. 需求变更
-4. 环境 / 数据问题
-5. Flaky 问题
-
-分类结果写入 `docs/testing/failure-triage.md` 或等价报告。
-
-## 14. 风险与待确认问题
-
-- 高风险点:
-- 未确认点:
-- 需要人工验收的部分:
+# E2E 计划
+
+**功能**:
+**基础 URL**:
+**后端 URL**:
+**Seed 命令**:
+**测试数据计划**:
+**导航入口**: `docs/ai/repo-map.md` / `docs/context/repo-map.md`
+**关联代码理解摘要**:
+
+## 1. 功能概览
+
+- 目标:
+- 业务背景:
+- 适用角色:
+- 不覆盖范围:
+
+## 2. 代码入口与影响面
+
+先从 `repo-map` / codemap 进入，再补充局部文件阅读。不要先全仓盲扫。
+
+| 类别 | 入口 / 文件 | 说明 | 受影响测试 |
+| --- | --- | --- | --- |
+| 页面 / 路由 |  |  |  |
+| 组件 |  |  |  |
+| Hook / Store / State |  |  |  |
+| API / Service |  |  |  |
+| 数据模型 / 持久化 |  |  |  |
+
+## 3. 范围与角色
+
+- 范围内:
+- 范围外:
+- 必需角色:
+- 权限差异:
+- 登录态要求:
+
+## 4. 前置条件
+
+- 环境与服务:
+- Feature flag:
+- 账号 / 权限:
+- Seed 数据:
+- 外部依赖:
+- 已知豁免:
+
+## 5. 测试数据
+
+| 数据名称 | 用途 | 来源 | 重置方式 |
+| --- | --- | --- | --- |
+| 正常数据 | 主流程 |  |  |
+| 边界数据 | 边界 / 上下限 |  |  |
+| 非法数据 | 异常 / 权限 / 拒绝路径 |  |  |
+
+## 6. 核心主流程
+
+| ID | 角色 | 主流程 | 对应需求 | 测试数据 | 期望证据 |
+| --- | --- | --- | --- | --- | --- |
+| E2E-001 | 用户 |  |  |  | 报告 + 截图 / 视频 + 状态证据 |
+
+## 7. 异常与边界流程
+
+| ID | 类型 | 场景 | 预期结果 | 证据 |
+| --- | --- | --- | --- | --- |
+| E2E-NEG-001 | 异常 |  |  |  |
+| E2E-BND-001 | 边界 |  |  |  |
+
+至少检查：
+
+- 空数据
+- 最大 / 最小输入
+- 重复提交
+- 网络慢
+- 接口失败
+- 登录过期
+- 权限不足
+
+## 8. 页面与 UI 断言
+
+| 页面 | 状态 | 断言 | 测试层级 |
+| --- | --- | --- | --- |
+|  | 默认 |  | T5 / T6 |
+|  | 错误态 |  | T5 / T6 |
+|  | 空态 |  | T5 / T6 |
+|  | 成功态 |  | T5 / T6 |
+
+## 9. 接口与网络预期
+
+| 入口动作 | 请求 | 成功预期 | 失败预期 |
+| --- | --- | --- | --- |
+|  | `METHOD /path` |  |  |
+
+## 10. 可访问性与交互约束
+
+- 优先使用用户可见语义定位：
+  - `getByRole`
+  - `getByLabel`
+  - `getByPlaceholder`
+  - `getByTestId`
+- 避免把 DOM 层级或脆弱 CSS 选择器作为主定位手段。
+- 记录关键按钮、表单标签、错误提示、loading、键盘操作和 aria 期望。
+
+## 11. Mock 排雷
+
+- [ ] 从 `repo-map`、代码入口和测试目录搜索 `mock`、`fixture`、`fake`、`hardcoded`。
+- [ ] P0 / P1 主流程使用真实后端或明确声明的 mock server。
+- [ ] 必须 mock 的状态已在 `test-matrix.md`、`verify-matrix.md` 或豁免说明中写明。
+- [ ] 前端页面如仍依赖本地假数据，先创建清理任务，再把该 E2E 标记为可执行。
+
+## 12. 受影响测试与执行顺序
+
+| 类别 | 测试 / 命令 | 原因 | 优先级 |
+| --- | --- | --- | --- |
+| Existing |  |  | P0 |
+| New |  |  | P0 |
+
+推荐顺序：
+
+1. 先跑 affected tests / contract checks。
+2. 再跑本计划对应的最小 E2E 集。
+3. 最后跑 P0 / P1 回归或跨故事整链路。
+
+## 13. 失败归因入口
+
+失败后不要直接改测试，先分类：
+
+1. 测试代码问题
+2. 产品 Bug
+3. 需求变更
+4. 环境 / 数据问题
+5. Flaky 问题
+
+分类结果写入 `docs/testing/failure-triage.md` 或等价报告。
+
+## 14. 风险与待确认问题
+
+- 高风险点:
+- 未确认点:
+- 需要人工验收的部分:

package/package-source/docs/codex-harness-engineering/templates/testing/failure-findings.example.json

@@ -11,9 +11,9 @@
       "requirementId": "REQ-001",
       "testCaseId": "E2E-001",
       "evidencePath": "artifacts/testing/<session>/<agent>/screenshots/FINDING-001.png",
-      "summary": "主结账按钮无法点击。",
-      "expected": "点击结账后应打开订单确认步骤。",
-      "actual": "点击后界面没有任何可见变化。",
+      "summary": "主结账按钮无法点击。",
+      "expected": "点击结账后应打开订单确认步骤。",
+      "actual": "点击后界面没有任何可见变化。",
       "retryCount": 0,
       "status": "open"
     }