# 评估平台

**Repository Path**: ccq/qa-platform

## Basic Information

- **Project Name**: 评估平台
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QA Platform

水务管网异常检测系统（`water_project`）的端到端黑盒测试平台。

输入：被测系统版本与配置
输出：评估报告（功能完整性 + 检测指标两个并列维度）

---

## 快速开始

### 环境准备

```bash
# 1. 安装依赖
./scripts/setup.sh

# 2. 配置被测系统与数据路径
cp config/config.example.yaml config/config.yaml
# 编辑 config.yaml，填入实际路径

# 3. 环境自检
./scripts/precheck.sh
```

`precheck.sh` 会依次检查：配置文件、Python/Node 运行环境、依赖、数据集路径、阻断门禁、功能点注册表与文档一致性、上游模式。
**检查失败会直接报告具体原因，不进入后续步骤。**

### 运行评估

```bash
./scripts/run_evaluation.sh
```

结果输出到 `reports/<run_id>/`，包含 `report.md` 与 `result.json`；
`reports/latest` 记录最新成功轮次的 `run_id`。历史轮次保留数量由 `output.keep_rounds` 控制，
超过后自动清理（崩溃残留的孤儿目录会被优先清理）。

### 启动 Web 报告查看器

```bash
python3 -m backend.web
```

浏览器访问 `http://127.0.0.1:8765`（只读，零第三方依赖，无需构建步骤）。

可选参数：`--host`（默认 `127.0.0.1`）、`--port`（默认 `8765`）。

> 查看器是**只读报告浏览器**，不是评估控制台：它只读取 `reports/` 下已落盘的轮次，
> 不触发评估、不接受写操作、不暴露配置与数据库。
> `--host` 仅接受精确的 `127.0.0.1` / `localhost` / `::1`；
> 传入 `0.0.0.0`、内网地址或通配符会被直接拒绝，避免把报告意外暴露到局域网。

---

## 目录结构

```
qa-platform/
├── backend/          评估引擎、指标计算、用例执行
├── frontend/src/     只读报告查看器（静态三件套，无构建）
├── scripts/          环境准备、自检、执行入口
├── config/           配置文件
├── docs/             设计与文档
└── reports/          评估产出（持久化，不随临时目录回收）
```

---

## 数据依赖

平台**只读挂载**外部数据，不复制到本仓库。

| 数据 | 来源 | 用途 |
|---|---|---|
| 标注真值 | `train/val/test/ambiguous.jsonl` | 指标计算的真值基准 |
| 原始时序 | `monitor_data.db` | 数据回放 |
| 接口契约 | swagger.yaml | 契约核对 |
| 被测系统 | 上游在线接口 | 端到端测试对象 |

具体路径在 `config/config.yaml` 中配置；`dataset.dir` 下的相对路径由平台自动解析。

**产出必须落到 `reports/`，不得只存临时工作目录**——临时目录会被回收。

---

## 判定标准

评估报告包含两个**并列**维度，任一不达标即影响结论：

### 功能完整性
逐个功能点端到端验证，按累计覆盖率追踪。
**没测 ≠ 达标。**

### 检测指标
基于人工标注真值计算，同时报告三个口径：

| 口径 | 分母 | 报告指标 |
|---|---|---|
| A | 全部真实爆管（162） | 仅召回率 |
| B | 人眼可识别事件（21） | 仅召回率 |
| S | 监督二分类集（74） | 精确率、召回率、F1、准确率 |

口径 A / B 的样本集合中负例不足，**不计算精确率与准确率**。
口径 A 的召回率上限由数据本身决定（46.9%），不是系统缺陷。
口径 B 的正例集合与监督集正例完全相同，两者召回率数值必然相等。

**指标值不后退。** 底线类（精确率／召回率／F1／准确率）容差为 0，边界类容差为相对 10%；
同一指标连续 3 轮下降触发风险提示。任一轮样本量 `n<30` 时不判回归，只标注「波动不可判」。

完整规则见 `docs/评估报告标准.md`。

---

## 迭代

每 1-2 周运行一轮。报告重点在与上轮的**变化**：功能回归、指标回归、覆盖增量。

---

## 相关文档

- `docs/评估报告标准.md` — 报告结构与判定规则
- `docs/功能点清单.md` — 合同功能点（覆盖率的分子与分母）
- `docs/功能点粒度原则.md` — 功能点拆分与「多子项须全通过」原则
- `docs/架构设计.md` — 模块划分、数据模型、Web 查看器与容差判定
- `docs/baseline/INDEX.md` — 基线文档索引与单一事实源
- `docs/baseline/决策记录.md` — 现行决策（`D-018` 口径、`D-019` 合同目标线）

> ⚠️ 当前功能口径 A/B/C 与指标口径 A/B/S 尚无甲方书面认可，
> 报告会标注 `unratified` 并拒绝给出最终适用性结论。