# self-test-flow — reference

## Scope
- 面向接口与数据链路的联调自测（非替代 `go test ./...` 单元测试）。
- 不默认编写或修改 `*_test.go`；不未经用户同意改动业务代码。
- 依赖不可达（中间件/库/网络）或环境阻塞时停止并说明原因，不空转等待。

## Hard Rules（展开）
- 失败即停：某步骤校验不通过则记录现象，不强行执行后续依赖该结果的步骤（除非用户要求继续探测）。
- 启动进程前检查已有终端，避免重复拉起相同服务。
- 模拟数据需可复现：记录 topic/URL、请求体、关键 header、时间范围等。
- 区分数据入口：**NSQ 消费**（客户端上报类 → 常落 ClickHouse）；**HTTP**（多为查 MySQL/ClickHouse，或写 MySQL/ClickHouse）。步骤设计须与真实路径一致。
- 每步完成后必须做**结果校验**（HTTP 响应、DB/CH 查询行数与字段、NSQ 消费日志或下游表数据等）。
- 每个接口或 NSQ 消息执行后，必须做**数据库一致性校验**（MySQL/ClickHouse 至少其一，按真实落库路径选择），并与该步模拟数据逐字段比对；未完成该校验或比对不一致，**该步骤一律判定 FAIL**。

## Workflow（详细）

### 1）梳理接口测试方式
- 列出本次要测的接口或消息：HTTP 路径与方法、NSQ topic（及期望消费者）。
- 将测试文档写为可执行步骤列表；默认按**整套 CRUD 逻辑**组织，例如：
  1. 插入/创建数据  
  2. 查询验证  
  3. 修改/更新  
  4. 再次查询验证  
  5. 删除（若适用）  
  6. 最终状态校验  
- 文档中注明每步对应的存储：**MySQL / ClickHouse / 仅缓存**等，便于选对校验方式。

### 2）启动进程
- 按项目约定启动被测服务（及依赖：NSQ、MySQL、ClickHouse 等）；确认监听端口与配置与测试文档一致。
- 记录启动命令与关键配置来源（如配置文件路径、环境变量名，不写敏感值）。

### 3）开始测试
- 严格按步骤顺序操作：发 HTTP、或向 NSQ 生产消息、或调用既有工具脚本。
- **NSQ 路径**：模拟客户端上报 payload → 等待消费完成（合理超时 + 重试快照）→ 再查 ClickHouse（或文档指定的落库）。
- **HTTP 路径**：模拟查询/写入请求；若接口写 MySQL 或 ClickHouse，后续步骤用查询接口或直接查库校验（以项目可接受方式为准）。

### 4）每步校验
- 每步结束后立即校验：**状态码/错误码、响应体关键字段、数据库或 ClickHouse 中记录是否与输入一致**（含时间字段、枚举、关联 ID）。
- 记录**本步输入（模拟数据）**与**校验依据**（例如执行的 SQL/CH 查询条件、期望行数或字段快照）。
- 强制要求：无论 HTTP 还是 NSQ，均需提供可复现的 SQL/CH 查询语句（或等价查询条件）与查询结果摘要，证明落库数据与模拟数据一致后方可标记 PASS。
- 若与预期不符：保留请求/消息原文、响应或查询结果摘要、相关日志片段（脱敏）。

### 5）输出测试报告
- 使用结构化小节，**逐步**对应测试文档，每步至少包含：
  - **步骤编号与名称**  
  - **模拟数据**（完整可复现：URL、方法、body、topic、消息体等）  
  - **执行结果**（成功/失败）  
  - **校验过程**（查了哪里、期望什么、实际什么）  
  - **结论**（PASS / FAIL）  
- 文末给出**总览**：通过步骤数/总步骤数、未通过项与阻塞原因、建议下一步（修代码/补数据/改配置）。

## Output Contract
- 每个大步骤汇报 `PASS` 或 `FAIL`；`FAIL` 须含：操作内容、错误现象、与预期差异、建议定位方向。
- `PASS` 前置条件：必须包含数据库一致性校验证据（查询条件/SQL、关键结果、与模拟数据逐字段对照结论）；缺一不可。
- 完整成功时额外给出：服务启动确认、测试覆盖的接口/Topic 列表、报告已按上节结构输出。
