# QA Automation Hub 操作手册

这份文档不再重复 `README.md` 的快速开始。它只回答三个问题：

- 这个仓库长期该维护什么
- 新需求、新业务线、线上事故发生后该怎么回写
- 哪些文件是资产，哪些只是执行产物

基础使用方式、固定输出和常用命令请先看 [README.md](/Users/fangyuehui/Desktop/codeAll/qa-team/qa-automation-hub/README.md)。

## 1. 文档分工

- `README.md`
  - 面向第一次进入仓库的人
  - 用于说明仓库用途、快速开始、固定输出、关键规则
- `操作手册.md`
  - 面向长期维护仓库的人
  - 用于说明目录职责、知识库维护、需求输入规范、结果治理策略

如果一个内容只影响“怎么开始用”，放 `README.md`。  
如果一个内容影响“仓库以后怎么维护”，放 `操作手册.md`。

## 2. 目录职责

### 长期资产

以下目录或文件是团队要持续投入维护的：

- `requirements/`
  - 正式维护版 Markdown 目录
  - 适合已经沉淀成长期维护版本的 `.md` 需求
- `knowledge_base/`
  - 团队长期沉淀的规则、缺陷、经验和案例
  - 决定仓库是否会越用越强
- `agents/`
  - 控制分析、测试点、测试用例、自审的输出风格和约束
- `.claude/`
  - Claude CLI 的入口规则和命令定义
- `AGENTS.md`
  - Codex CLI 的入口规则
- `scripts/`
  - 固定流水线脚本，负责 `prepare / verify / export`

### 执行产物

以下目录默认不作为长期知识维护区：

- `output/analysis/`
- `output/test_points/`
- `output/test_cases/`
- `output/excel_reports/`
- `output/manifests/`
- `output/normalized_inputs/`
- `output/versions/`

这些内容的定位是执行结果、回溯样例、排查依据，不应该代替知识库源文件。

### 可忽略内容

- `.DS_Store`
- `__pycache__/`
- 历史临时 Excel
- 已无参考价值的旧样例产物

### `decisions/`

这里放跨需求冲突的人为确认结论，不放测试产物，不放知识库通用规则。

适合放：

- 子需求与旧需求的关系判定
- 替代 / 补充 / 并行生效结论
- 生效范围、失效范围、影响模块
- 需要回写和重跑的需求列表

不适合放：

- 临时聊天记录
- 未确认的零散意见
- 与具体需求无关的通用规则

## 3. 知识库怎么维护

### `requirements/`

这里是正式维护版 Markdown 目录，适合已经沉淀成长期维护版本的正式需求文档，不放知识库，不放历史产物。

推荐命名：

```text
requirements/项目名_版本号.md
requirements/order_center_v1.2.md
requirements/member_coupon_v2.0.md
```

当前脚本同步正式维护版时，固定使用：

```text
requirements/{BASE_NAME}.md
```

维护建议：

- 同一主题只保留一个正式维护版文件
- 不要再派生 `xxx_final.md`、`xxx_最新版.md`、`xxx_20260426.md`
- 如果确实存在多阶段版本差异，用确认单和 `output/versions/` 做追溯，不靠在 `requirements/` 里堆文件名分叉

边界要求：

- `requirements/` 推荐只放 `.md`
- 这里的文件会被 `prepare` 当成可执行输入和关联需求扫描范围
- 当前推荐由脚本在 `export` 成功后自动同步正式维护版，不再手工复制 raw 文档
- 如果 `requirements/` 与 `source_docs/requirements_raw/` 同时存在同主题文档，后续关联识别优先使用 `requirements/` 下的维护版
- 不要把技术方案、接口说明混放进来，否则目录语义会变脏，后续也容易误用

### `source_docs/`

这里放原始输入材料和非直接执行文档。

推荐分层：

- `source_docs/requirements_raw/`
  - 原始需求稿，如 `doc`、`docx`、`pdf`
- `source_docs/technical_solutions/`
  - 技术方案、接口说明、时序图、数据结构说明等

建议原则：

- 当前主推荐做法是直接使用 `source_docs/requirements_raw/` 下的 `doc`、`docx`、`pdf` 作为 `/case_generate` 输入
- 如果需求已经沉淀为稳定的长期维护版本，`export` 后会自动同步一份到 `requirements/`
- `prepare` 会自动把原始需求稿和关联技术方案标准化到 `output/normalized_inputs/`，后续分析阶段统一消费标准化文件
- 原始需求稿和技术方案保留在 `source_docs/`，方便追溯

## 3.1 产物版本规则

当前产物和历史版本分开管理：

- 当前最新版始终使用固定文件名
  - `output/analysis/{BASE_NAME}_分析.md`
  - `output/test_points/{BASE_NAME}_测试点.md`
  - `output/test_cases/{BASE_NAME}_测试用例.md`
  - `output/excel_reports/{BASE_NAME}_测试用例.xlsx`
- 历史快照统一放到：
  - `output/versions/{BASE_NAME}/v1/`
  - `output/versions/{BASE_NAME}/v2/`
  - `output/versions/{BASE_NAME}/v3/`
  - `output/versions/{BASE_NAME}/VERSION_INDEX.md`

递增规则：

- 只在 `export` 成功后检查是否需要新增版本
- 只有当前分析、测试点、测试用例、manifest、标准化输入、Excel 任一内容相对上一个快照发生变化，才会新增 `vN`
- 如果只是重复导出同一份结果，版本不变
- `export` 还会自动迁移同一需求下遗留的时间戳 Excel，并把 `output/excel_reports/` 收敛到只保留当前最新版文件
- 每个需求最多只保留最近 `3` 个版本；新增第 `4` 个及以后版本时，会自动淘汰更早版本
- 每个 `vN/` 目录下会自动生成 `snapshot_meta.json`，用于标识快照类型
- `VERSION_INDEX.md` 会汇总每个版本是“完整流水线快照”还是“历史 Excel 导入”

这样做的目的很明确：

- 日常使用永远打开固定文件名，不需要在一堆时间戳文件里找最新版
- 需要回溯时，再到 `output/versions/` 看 `v1/v2/v3`
- 版本只跟“有效产物变化”绑定，不跟每次命令执行绑定

如果历史仓库里已经积累了大量旧时间戳 Excel，可以执行一次：

```bash
python3 scripts/case_pipeline.py migrate-history --all
```

这会把旧时间戳 Excel 迁移进对应 `BASE_NAME` 的版本目录，并从 `output/excel_reports/` 清掉旧文件。

### `knowledge_base/00_project/`

这里放项目级差异化约束，当前核心文件是：

- [project_profile.md](/Users/fangyuehui/Desktop/codeAll/qa-team/qa-automation-hub/knowledge_base/00_project/project_profile.md)

这个文件要描述：

- 项目类型与目标用户
- 业务边界和禁用能力
- 项目特有高风险规则
- 技术依赖和一致性约束
- 冲突判定口径

如果项目画像不维护，后续测试分析和用例会退化成“通用模板输出”。

### `knowledge_base/01_standards/`

这里放稳定规则，不放项目实例。

当前职责：

- `terminology.md`
  - 核心商城术语，常驻输入
- `terminology_optional_saas.md`
  - 私域、分销、储值、CRM 等扩展术语
  - 由流水线根据目标需求和项目画像自动识别是否纳入上下文
- `test_case_template.md`
  - 唯一表头、`类型` 枚举、云效导出映射和命名约束规则
- `definition_of_done.md`
  - 测试点与测试用例的完成门禁，用来约束覆盖维度、风险场景、待确认项和评审通过条件
- `review_checklist.md`
  - 测试用例生成前自检和评审阶段的逐项检查清单，用来把完成门禁落成可执行检查项

适合继续放进来的内容：

- 优先级规则
- 命名规则
- 非功能清单
- 缺陷严重度定义

### `knowledge_base/02_history/`

这里放历史问题和团队经验。

适合放：

- 常见漏测场景
- 历史缺陷
- 业务线特有规则
- 已发生过的线上事故防御结论

建议做法：

- 通用内容放公共文件
- 业务线变多后按模块拆分
- 一条缺陷至少写清模块、现象、根因、建议防御点

### `knowledge_base/03_best_practices/`

这里放优秀用例范式，不放正式执行结果。

用途是告诉 Agent：

- 什么颗粒度合适
- 什么写法可执行
- 什么预期结果是合格的
- 哪类需求应参考哪类范式，避免把支付类范式直接套到营销活动、后台配置、C 端弹窗领取等不同场景

当前建议：

- `payment_flow_cases.md`
  - 支付、收银台、订单支付状态、超时取消、支付失败切换等交易链路
- `marketing_activity_cases.md`
  - 平台端/商家端活动配置、列表管理、状态流转、C 端资格展示、领取防重等营销活动链路

## 4. 需求文档输入标准

需求文档至少应包含以下内容：

- 背景
- 目标
- 用户角色
- 功能范围
- 关键业务规则
- 主流程
- 异常流程
- 非功能要求
- 不在本期范围

以下信息如果缺失，会明显拉低生成质量：

- 状态流转规则
- 金额计算口径
- 优惠互斥或叠加规则
- 超时与重试规则
- 权限边界
- 逆向流程规则
- 兼容历史逻辑的说明

如果某条规则会影响金额、库存、权益、权限、安全或合规，需求里必须写清，不能只靠 Agent 猜。

## 5. 结果不理想时先改哪里

优先检查输入和规则源，不要先手改 `output/` 结果：

1. 需求输入是否写清楚；若当前走原始文档流程，先检查 `source_docs/requirements_raw/` 中的原始需求稿
2. `knowledge_base/` 是否缺规则、缺缺陷、缺历史漏测点
3. `knowledge_base/00_project/project_profile.md` 是否缺项目差异化信息
4. `agents/` 的 prompts 是否约束不够

只有在确认源信息已经足够时，才去微调 prompts 或脚本。

## 5.1 已有需求继续迭代时怎么处理

这类场景是当前仓库最容易“看起来能跑，实际上没有完全闭环”的地方。推荐固定按下面的顺序执行：

1. 保留旧需求文档在 `source_docs/requirements_raw/` 或 `requirements/`
2. 把新子需求放进 `source_docs/requirements_raw/`
3. 把配套技术方案放进 `source_docs/technical_solutions/`
4. 先跑一次正常流程，让 `prepare` 自动生成 `关联与冲突.md`
5. 如果识别到历史相似需求、冲突候选或高风险 `> ⚠️ 待确认`，暂停在确认阶段
6. 在 `decisions/` 下新增一份确认单
7. 确认“补充 / 替代 / 并行”关系后，执行 `python3 scripts/case_pipeline.py apply-confirmation --requirement <需求文档路径>`
8. 由脚本按确认单里的重跑列表自动重跑受影响需求，并在 `decisions/applied/` 留存维护说明

这里要特别注意：

- 旧需求如果只留在 `output/versions/`，后续不会再被当成历史需求扫描对象
- 当前脚本能自动发现候选，但不会自动帮你裁决新旧规则关系
- 当前脚本已经会因为“冲突或待确认尚未解除”阻断 `verify/export`

所以，跨需求冲突场景下，`decisions/` 不是可选附件，而是闭环证据。

## 5.2 什么情况下必须进入确认阶段

出现以下任一情况，建议不要直接把当前产物当最终结论：

- `关联与冲突.md` 识别到历史相似需求
- 冲突候选涉及金额、库存、权益、权限、安全、合规
- 新需求可能替代旧规则，而不是单纯补充子场景
- 同一对象的状态机、阈值、次数、时效口径发生变化
- 需求正文或分析结果中出现 `> ⚠️ 待确认`

建议确认阶段只让人做“拍板”，不要让人重复做机器已经能做的事。人工重点只确认：

- 关系类型：`补充 / 替代 / 并行`
- 生效范围和失效范围
- 是否需要同步回写旧需求
- 是否允许未确认前继续导出
- 哪些需求需要在确认后重跑

## 6. 新项目或新业务线接入

每次新项目接入，至少补这几类内容：

1. 新需求文档优先放进 `source_docs/requirements_raw/`；若已沉淀成稳定 Markdown 版本，也可放进 `requirements/`
2. 项目画像补进 `knowledge_base/00_project/project_profile.md`
3. 相关术语补进 `knowledge_base/01_standards/`
   - 核心共性词放 `terminology.md`
   - 只在部分项目出现的扩展词优先单独拆文件，由流水线自动识别
4. 历史缺陷补进 `knowledge_base/02_history/`
5. 易漏测点补进 `knowledge_base/02_history/`
6. 高质量案例补进 `knowledge_base/03_best_practices/`

不要只放需求文档，不补项目画像和知识库。那样只能得到一次性结果，不能形成可复用资产。

## 6.1 确认单怎么写

建议统一使用 [decisions/确认结论模板.md](/Users/fangyuehui/Desktop/codeAll/qa-team/qa-automation-hub/decisions/确认结论模板.md)。

确认单至少要写清：

- 当前需求和关联历史需求
- 关系类型：`补充 / 替代 / 并行`
- 生效范围和失效范围
- 影响模块、角色、接口或数据口径
- 最终确认口径
- 是否需要回写旧需求
- 需要重跑的需求列表

如果确认单里没有“边界”和“重跑范围”，`apply-confirmation` 最多只能安全地重跑当前需求，无法稳定帮你把旧需求一起收敛。

## 7. 线上事故或漏测后怎么回写

每次线上事故、重大缺陷或明显漏测后，至少做一次回写：

1. 把缺陷沉淀到 `knowledge_base/02_history/historical_defects.md`
2. 如果属于通用遗漏，补进 `common_missed_scenes.md`
3. 如果属于业务线特有问题，新增或更新对应模块文件
4. 如果生成逻辑本身没有覆盖到，再补 `agents/` 或 `project_profile.md`

如果事故没有回写，仓库不会积累能力，只会重复犯同类错误。

## 8. 如何控制知识库膨胀

知识库变大以后，问题通常不是“内容太多”，而是“内容混乱”。

建议遵守这几个原则：

- 一个文件只讲一类东西，不混规则、缺陷、样例
- 文件名要能直接看出业务范围
- 通用内容和项目内容分开
- 样例产物不要反向混入长期规则
- 出现 30 到 50 条以上同类内容时，考虑按模块拆分

## 9. 样例与产物怎么处理

代表性样例产物可以少量保留，用于：

- 跑通演示
- 格式参考
- 新成员理解输出结构

但不要把 `output/` 当唯一真相。真正要维护的是需求、知识库、prompts 和脚本。

如果后续历史样例过多，可以只保留：

- 1 份代表性需求
- 1 套代表性分析/测试点/测试用例
- 少量高价值 Excel 导出样例

## 10. 日常维护原则

平时最重要的不是反复改产物，而是维护好这些源头：

- `source_docs/requirements_raw/`
- `source_docs/technical_solutions/`
- `requirements/`
- `knowledge_base/`
- `knowledge_base/00_project/project_profile.md`
- `agents/`

补充原则：

- Markdown 用例是内部高质量源格式，允许保留 `测试数据`、`备注` 等细粒度字段
- Excel 导出默认对齐团队云效字段模型，`测试数据` 会自动并入 `步骤描述`
- 如果团队平台字段模型发生变化，优先更新 `test_case_template.md` 和 `scripts/export_excel.py`
- `requirements/` 目录只保留正式维护版 Markdown，不保留 Finder 缓存、临时副本或手工导出的重复文件

一句话原则：

先改输入和规则源，再改 prompts，最后才考虑改执行结果。

## 11. 流程治理检查

仓库内已提供低频治理脚本：

```bash
python3 scripts/governance_audit.py auto
```

这项检查只应在以下类型改动后触发：

- 流程脚本改动：`scripts/`
- CLI 入口规则改动：`AGENTS.md`、`.claude/`
- prompts 改动：`agents/`
- 标准规范改动：`knowledge_base/01_standards/`
- 仓库入口文档改动：`README.md`、`操作手册.md`

这项检查不会因为以下普通内容更新自动触发：

- `requirements/` 下新增或修改需求
- `knowledge_base/02_history/` 的历史缺陷、易漏场景更新
- `knowledge_base/03_best_practices/` 的案例补充
- `output/` 下的执行产物变化

这项检查的目的有两个：

- 检查 `Codex CLI` 和 `Claude CLI` 的流程是否仍然一致
- 检查 `README.md` 和 `操作手册.md` 是否落后于当前实现

## 12. 当前流程缺口与下一步实现建议

如果你希望后续真正满足“自动识别冲突、人工确认、确认后自动续跑”的闭环，还需要继续补脚本能力。当前最值得补的点是：

1. 增加回写到需求源文件的能力
   - 当前已支持写到 `decisions/applied/` 维护说明，但不会直接修改原始 `docx/md`
2. 增加更细粒度的门禁级别
   - 例如把“仅弱关联提示”和“高风险必须阻断”分开
3. 增加确认单结构化校验
   - 避免只有一句“已确认”，却没有写清边界、影响范围和重跑列表

在这些能力落地前，当前最稳的工作方式仍然是：

- 机器负责识别、汇总、出建议
- 人负责最终裁决
- 人再触发受影响需求的重跑