# CI 回归报告归档说明（P13-6）

更新时间：2026-02-12

## 目标

在 `ci-regression` 流水线中产出并归档结构化回归报告，确保每次回归可追溯到具体 `run_id` 与 `commit SHA`。

## 产物

- 回归脚本输出：`/tmp/hyb-oa-regression/report.json`
- Artifact 名称：`regression-report-<run_id>-<sha>`
- JSON 契约：`schema_version = "1.0"`

## 字段约定

报告包含以下关键字段：

- `schema_version`
- `generated_at`
- `git.sha`
- `git.branch`
- `overall.status | duration_ms | passed | failed | skipped | total`
- `steps[]`：`id | name | enabled | status | exit_code | duration_ms | started_at | ended_at | command`

## 回归命令

在 CI 中使用：

```bash
RUN_AUDIT_REGRESSION=1 RUN_OCR_REGRESSION=1 ./scripts/regression-all.sh --json-report /tmp/hyb-oa-regression/report.json
```

## 排障建议

- **优先查看 Job Summary**：流水线完成后会自动在 GitHub Actions 运行页面的 Summary 面板输出结构化摘要，可直接看到由于哪些 `steps` 导致阻断失败。
- 回归大面积或异常失败时，请优先下载 artifact 中的 `report.json` 进一步比对 `overall.failed` 与具体抛出的退出码。
- 若报告未生成，检查回归步骤是否在脚本启动前失败（例如服务未就绪，数据库连不上）。
- 若报告字段缺失，优先比对 `server/scripts/lib/regression-report.sh` 与 schema 版本。