tokens-reef/QA_VALIDATION_REPORT.md

# Sub2API 合并版本测试验证报告

> 验证人: QA (Yan)
> 日期: 2026-05-08
> 工作目录: d:/project/sub2api-merge

---

## 1. 测试执行结果汇总表

| 测试类型 | 命令/方式 | 结果 | 说明 |
|---------|----------|------|------|
| 后端 Unit Tests | `go test -tags=unit ./...` | **通过** | 全部通过，无失败 |
| 后端 Integration Tests | `go test -tags=integration ./...` | **通过** | 全部通过，无失败 |
| 后端 Coverage 收集 | `go test -tags=unit -cover ./...` | **失败** | `internal/config` 因 BOM 问题构建失败 |
| 后端 go vet | `go vet ./...` | **通过** | 无警告 |
| 后端构建 | `go build -tags embed -o sub2api ./cmd/server` | **通过** | 二进制生成成功 |
| 前端 Unit Tests | `npx vitest run` | **通过** | 62 文件 / 364 测试全部通过 |
| 前端构建 | `pnpm run build` | **通过** | 生成成功，有动态导入警告 |
| golangci-lint | `golangci-lint run ./...` | **未执行** | 本地未安装 |

### 关键模块覆盖率（unit 测试）

| 模块 | 覆盖率 | 状态 |
|------|--------|------|
| internal/prommetrics | 100.0% | 优秀 |
| internal/service | 46.5% | 一般 |
| internal/handler/admin | 22.8% | 偏低 |
| internal/repository | 15.3% | 偏低 |
| internal/server/routes | 77.0% | 良好 |
| internal/middleware | 65.4% | 良好 |
| internal/pkg/response | 95.3% | 优秀 |
| internal/pkg/proxyurl | 100.0% | 优秀 |
| internal/pkg/usagestats | 100.0% | 优秀 |

---

## 2. 新增模块测试覆盖缺口

根据 PROJECT_DIFF.md 对新增模块的测试文件检查结果：

### 已覆盖（测试文件存在且通过）

| 模块路径 | 测试文件 | 状态 |
|---------|---------|------|
| `backend/internal/prommetrics/` | `metrics_test.go` | 通过，覆盖率 100% |
| `backend/internal/service/webhook_service.go` | `webhook_service_test.go` | 通过 |
| `backend/internal/handler/admin/sora_handler.go` | `sora_handler_test.go` | 通过 |
| `backend/internal/service/ops_service.go` | `ops_service_batch_test.go`, `ops_service_prepare_queue_test.go`, `ops_service_redaction_test.go` | 通过 |
| `backend/internal/service/ops_alert_evaluator_service.go` | `ops_alert_evaluator_service_test.go` | 通过 |
| `backend/internal/service/ops_metrics_collector.go` | `ops_health_score_test.go`, `ops_openai_token_stats_test.go` | 通过 |
| `backend/internal/service/ops_settings.go` | `ops_settings_advanced_test.go` | 通过 |
| `backend/internal/service/ops_cleanup_service.go` | `ops_partition_test.go` | 通过 |
| `backend/internal/service/ops_aggregation_service.go` | `ops_query_mode_test.go` | 通过 |
| `backend/internal/service/ops_realtime.go` | `ops_log_runtime_test.go`, `ops_upstream_context_test.go`, `ops_retry_context_test.go` | 通过 |
| `backend/internal/service/ops_scheduled_report_service.go` | `ops_system_log_service_test.go`, `ops_system_log_sink_test.go` | 通过 |
| `backend/internal/service/sora_gateway_service.go` | `sora_gateway_service_test.go` | 通过 |
| `backend/internal/service/sora_generation_service.go` | `sora_generation_service_test.go` | 通过 |
| `backend/internal/service/sora_quota_service.go` | `sora_quota_service_test.go` | 通过 |
| `backend/internal/service/sora_s3_storage.go` | `sora_s3_storage_test.go` | 通过 |
| `backend/internal/service/sora_media_storage.go` | `sora_media_storage_test.go` | 通过 |
| `backend/internal/service/sora_media_cleanup_service.go` | `sora_media_cleanup_service_test.go` | 通过 |
| `backend/internal/handler/admin/ops_handler.go` | `ops_runtime_logging_handler_test.go`, `ops_system_log_handler_test.go` | 通过 |
| `backend/internal/repository/ops_repo*.go` | `ops_repo_dashboard_timeout_test.go`, `ops_repo_error_where_test.go`, `ops_repo_latency_histogram_buckets_test.go`, `ops_repo_openai_token_stats_test.go`, `ops_repo_system_logs_test.go` | 通过 |
| `frontend/src/views/admin/__tests__/SoraAdminView.spec.ts` | - | 通过（12 测试） |
| `frontend/src/views/admin/ops/components/__tests__/OpsSettingsDialog.spec.ts` | - | 通过（3 测试） |
| `frontend/src/views/admin/ops/components/__tests__/OpsOpenAITokenStatsCard.spec.ts` | - | 通过（5 测试） |

### 测试覆盖缺口

| 模块路径 | 预期测试 | 实际状态 | 风险 |
|---------|---------|---------|------|
| `backend/internal/handler/admin/ops_dashboard_handler.go` | `ops_dashboard_handler_test.go` | **缺失** | 中 - 仪表盘数据查询接口无测试 |
| `backend/internal/handler/admin/ops_alerts_handler.go` | `ops_alerts_handler_test.go` | **缺失** | 中 - 告警管理接口无测试 |
| `backend/internal/handler/admin/ops_realtime_handler.go` | `ops_realtime_handler_test.go` | **缺失** | 低 - 实时数据接口无测试 |
| `backend/internal/handler/admin/ops_ws_handler.go` | `ops_ws_handler_test.go` | **缺失** | 低 - WebSocket 连接无测试 |
| `backend/internal/handler/admin/data_management_handler.go` | `data_management_handler_test.go` | **缺失** | 中 - 数据管理接口无测试 |
| `backend/internal/service/sora_account_service.go` | `sora_account_service_test.go` | **缺失** | 中 |
| `backend/internal/service/sora_client.go` | `sora_client_test.go` | **缺失** | 中 |
| `backend/internal/service/sora_sdk_client.go` | `sora_sdk_client_test.go` | **缺失** | 中 |
| `backend/internal/repository/ops_repo_preagg.go` | `ops_repo_preagg_test.go` | **缺失** | 低 |
| `backend/internal/repository/ops_repo_trends.go` | `ops_repo_trends_test.go` | **缺失** | 低 |
| `backend/internal/repository/ops_repo_metrics.go` | `ops_repo_metrics_test.go` | **缺失** | 低 |
| `backend/internal/repository/ops_repo_realtime_traffic.go` | `ops_repo_realtime_traffic_test.go` | **缺失** | 低 |
| `backend/internal/repository/ops_repo_request_details.go` | `ops_repo_request_details_test.go` | **缺失** | 低 |

**总结**: 新增核心模块（prommetrics、webhook、sora 主要服务、ops 核心服务）测试覆盖较好，但 Handler 层和 Repository 层部分模块测试缺失。整体新增模块测试覆盖率达到约 65%。

---

## 3. 构建验证结果

| 组件 | 命令 | 结果 | 问题 |
|------|------|------|------|
| 后端 | `go build -tags embed -o sub2api ./cmd/server` | **通过** | 无 |
| 前端 | `pnpm run build` | **通过** | 动态导入警告（非阻塞） |

### 前端构建警告（非阻塞）

- `src/stores/app.ts` 被动态导入同时也被静态导入，导致无法拆分到独立 chunk
- `src/router/title.ts` 和 `src/router/index.ts` 存在同样问题
- 部分 chunk 超过 500KB（AccountsView 544KB, vendor-ui 430KB）

**评估**: 上述警告不影响功能，属于构建优化建议。

---

## 4. CI/CD 配置评估

### 存在的配置文件

| 文件 | 状态 | 评估 |
|------|------|------|
| `.github/workflows/backend-ci.yml` | 存在 | 有版本匹配问题 |
| `.github/workflows/security-scan.yml` | 存在 | 配置合理 |
| `.github/workflows/release.yml` | 存在 | 未详细检查 |

### backend-ci.yml 问题

1. **Go 版本不匹配**:
   - CI 中校验 `go1.26.2`
   - DEV_GUIDE.md 要求 Go 1.25.7
   - 当前环境实际安装 `go1.26.2`
   - **建议**: 统一文档和 CI 中的版本要求

2. **缺少前端 CI**:
   - 没有前端测试/构建的 CI 工作流
   - 建议增加 `frontend-ci.yml`

3. **Makefile 依赖**:
   - CI 使用 `make test-unit` 和 `make test-integration`
   - Makefile 存在且配置正确

### security-scan.yml 评估

- 包含后端 `govulncheck` 和前端 `pnpm audit`
- 有定时扫描（每周一 03:00）
- 配置合理

---

## 5. 数据库迁移风险评估

### 迁移文件完整性

| 功能 | 迁移文件 | 状态 |
|------|---------|------|
| Ops 监控核心表 | `026_ops_metrics_aggregation_tables.sql` | 存在 |
| Ops 监控 vNext | `033_ops_monitoring_vnext.sql` | 存在 |
| Ops 上游错误事件 | `034_ops_upstream_error_events.sql` | 存在 |
| Ops 错误日志扩展 | `036_ops_error_logs_add_is_count_tokens.sql` | 存在 |
| Ops 告警静默 | `037_ops_alert_silences.sql` | 存在 |
| Ops 错误分类标准化 | `038_ops_errors_resolution_retry_results_and_standardize_classification.sql` | 存在 |
| Ops 任务心跳 | `039_ops_job_heartbeats_add_last_result.sql` | 存在 |
| Ops 系统指标 | `042b_add_ops_system_metrics_switch_count.sql` | 存在 |
| Ops 系统日志 | `054_ops_system_logs.sql` | 存在 |
| Ops 错误日志端点字段 | `079_ops_error_logs_add_endpoint_fields.sql` | 存在 |
| Sora 账号表 | `046_add_sora_accounts.sql` | 存在 |
| Sora 定价和媒体类型 | `047_add_sora_pricing_and_media_type.sql` | 存在 |
| Sora 客户端表 | `063_add_sora_client_tables.sql` | 存在 |

### 严重风险：迁移 090 与代码矛盾

**发现**: `090_drop_sora.sql` 存在严重问题：

```sql
-- Migration: 090_drop_sora
-- Remove all Sora-related database objects.
DROP TABLE IF EXISTS sora_tasks;
DROP TABLE IF EXISTS sora_generations;
DROP TABLE IF EXISTS sora_accounts;
ALTER TABLE groups DROP COLUMN IF EXISTS sora_image_price_360, ...;
ALTER TABLE users DROP COLUMN IF EXISTS sora_storage_quota_bytes, ...;
ALTER TABLE usage_logs DROP COLUMN IF EXISTS media_type;
```

**影响**:
- 迁移 046、047、063 创建 Sora 相关表和字段
- 迁移 090 在同一迁移序列中**全部删除**这些表和字段
- 但代码库中仍包含完整的 Sora 服务模块（`sora_*.go`）
- 如果按顺序执行所有迁移，Sora 功能将**无法运行**

**风险等级**: **高 (HIGH)**

**建议**:
1. 确认 090_drop_sora.sql 的意图：是计划下线 Sora 功能，还是误提交？
2. 如果保留 Sora 功能，应**删除或跳过** 090_drop_sora.sql
3. 如果确实要下线 Sora，应同步删除代码模块，避免运行时错误

### 迁移编号冲突

- 存在多个 `006_` 前缀的迁移文件（`006_...`, `006_fix_...`, `006b_...`）
- 存在多个 `028_` 前缀的迁移文件
- 存在多个 `029_`, `030_`, `042_`, `043_`, `044_`, `045_`, `046_`, `052_`, `053_`, `054_` 前缀文件
- 项目使用文件名排序执行迁移，相同前缀的文件执行顺序可能不稳定
- **建议**: 对相同前缀的迁移文件确认执行顺序是否符合依赖关系

---

## 6. 源码质量问题

### BOM 问题（阻塞覆盖率）

**文件**: `backend/internal/config/config_validate_gateway.go`

**问题**: 文件开头包含 UTF-8 BOM（`EF BB BF`），导致 `go test -cover` 失败：

```
internal\config\config_validate_gateway.go:1:1: invalid BOM in the middle of the file
```

**影响**:
- 常规 `go test` 和 `go build` 可以通过（Go 编译器对 BOM 容忍度不同）
- 但 `go test -cover` 和 `golangci-lint` 可能失败
- 影响 CI 中的覆盖率收集

**建议**: 移除文件开头的 BOM 字节。

---

## 7. 上线建议（GO / NO-GO / CONDITIONAL）

### 总体结论: **CONDITIONAL GO**（条件通过，需修复后上线）

### 必须修复（阻塞上线）

| # | 问题 | 优先级 | 负责人建议 |
|---|------|--------|-----------|
| 1 | **迁移 090_drop_sora.sql 与代码矛盾** | P0 | 与架构师确认意图，删除或调整 |
| 2 | **config_validate_gateway.go BOM 问题** | P0 | 移除 BOM，修复覆盖率收集 |

### 强烈建议修复（上线前）

| # | 问题 | 优先级 | 说明 |
|---|------|--------|------|
| 3 | 补充 Handler 层测试 | P1 | ops_dashboard_handler, ops_alerts_handler, data_management_handler 等缺少测试 |
| 4 | 统一 Go 版本文档 | P1 | DEV_GUIDE 与 CI、实际环境版本不一致 |
| 5 | 增加前端 CI 工作流 | P1 | 当前仅后端有 CI，前端无自动化测试 |

### 建议优化（上线后）

| # | 问题 | 优先级 |
|---|------|--------|
| 6 | 补充 sora_account_service, sora_client 等测试 | P2 |
| 7 | 补充 repository 层缺失测试 | P2 |
| 8 | 前端构建 chunk 优化 | P2 |
| 9 | 安装 golangci-lint 到本地环境 | P2 |
| 10 | 统一迁移文件编号避免前缀冲突 | P2 |

---

## 附录：执行环境信息

- **OS**: Windows 10 Enterprise LTSC 2021
- **Go**: go1.26.2 windows/amd64
- **Node**: (pnpm 可用，npx vitest 可用)
- **PostgreSQL**: 端口 5432 (配置存在，测试使用 testcontainers)
- **Redis**: 端口 6379
- **后端测试总耗时**: Unit ~160s, Integration ~140s
- **前端测试总耗时**: ~38s