# 2026-05-30 测试能力与质量保障增强

## 背景

当前仓库虽然已经有：

- 单元测试
- SQLite 集成测试
- portal 资产检查
- real-host 验收脚本

但在测试治理上仍有两个明显短板：

1. **缺统一入口**
   - 质量门禁主要依赖开发者手动记忆若干命令
   - 缺少“一键执行 + 汇总结果 + 显式门槛”的脚本化入口

2. **缺覆盖率管理**
   - 覆盖率门槛写在 `AGENTS.md`
   - 但没有配置文件和脚本把门槛真正执行出来
   - 低覆盖包不够显性，容易在后续迭代中悄悄回落

## 本次增强

### 1. 新增统一质量门禁脚本

- [scripts/test/verify_quality_gates.sh](/home/long/project/sub2api-cn-relay-manager/scripts/test/verify_quality_gates.sh)

职责：

- 统一执行：
  - `gofmt -l .`
  - `go vet ./...`
  - `go test -cover ./internal/...`
  - `go test ./tests/integration/... -count=1`
- 生成 coverage gate 报告
- 对低覆盖包给出显式 `warn`
- 对 core 包低于门槛时直接 `fail`

### 2. 新增覆盖率阈值配置

- [tests/quality/coverage_thresholds.tsv](/home/long/project/sub2api-cn-relay-manager/tests/quality/coverage_thresholds.tsv)

当前策略分两层：

- `core`
  - 当前必须硬门槛通过
  - 先覆盖最关键业务包：
    - `internal/access`
    - `internal/pack`
    - `internal/provision`
- `watch`
  - 先做显式非回归治理
  - 对已有低覆盖或大体量包给出可见阈值，避免继续恶化

### 3. 补充脚本自检

- `scripts/test/test_real_host_scripts.sh` 新增了对 `verify_quality_gates.sh` 和阈值配置文件的静态回归

### 4. 提升低覆盖工具包测试

- [internal/overlay/executor_test.go](/home/long/project/sub2api-cn-relay-manager/internal/overlay/executor_test.go)

新增覆盖：

- nested output dir 拒绝
- missing patch 错误路径
- metadata 写入内容
- copyTree 对 `.git` 过滤
- symlink 保留

## 建议执行方式

后续每次提交前，优先跑：

```bash
bash ./scripts/test/verify_quality_gates.sh
```

如果本次还改了 portal 资产或 real-host 支撑脚本，再补：

```bash
bash ./scripts/test/test_tksea_portal_assets.sh
bash ./scripts/test/test_real_host_scripts.sh
```

## 后续建议

下一阶段如果继续增强测试能力，优先做这三件事：

1. 给 `internal/app` 增加不依赖本地监听端口的 handler 级测试，先把 coverage 稳定抬过 `70%`
2. 把 `watch` 包分批提升为 `core`
3. 给 `verify_quality_gates.sh` 增加机器可读输出，例如 JSON 汇总，方便未来接 CI 或日报