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 存在严重问题：

-- 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