# Sub2API 全面上线评审报告

> **评审日期**: 2026-05-08  
> **评审范围**: sub2api-merge 项目（Go + Vue3 + PostgreSQL + Redis）  
> **评审目标**: 判定项目是否具备上线条件，核心 AI 模型是否正常支持

---

## 执行摘要

| 维度 | 评分 | 状态 |
|------|------|------|
| 核心模型支持 | ★★★★★ | 全部主流模型链路完整 |
| 构建稳定性 | ★★★★★ | 前后端构建均成功 |
| 测试质量 | ★★★★★ | 后端单元+集成全通过，前端 364 测试全通过 |
| 代码质量 | ★★★★☆ | 架构清晰，有少量残留代码 |
| 文档一致性 | ★★★☆☆ | 版本号不一致，Sora 状态说明已到位 |

**综合判定: CONDITIONAL GO（有条件通过）**

项目在核心功能（AI 模型转发网关）上完全具备上线能力。唯一需要在上线前处理的是 **Sora 模块残留代码与已删除数据库表的不一致问题**。

---

## 一、模型支持矩阵（核心关切验证）

以下对每种 AI 模型的端到端转发链路进行了深度代码审查和架构验证：

| # | 模型/平台 | 网关端点 | 路由文件 | 账号类型 | 模型映射 | 计费支持 | 状态 |
|---|-----------|---------|---------|---------|---------|---------|------|
| 1 | **Claude (Anthropic)** | `/v1/messages` | `gateway.go:44` | OAuth / API Key / Setup Token / Bedrock | 默认+自定义映射 | ✅ 完整 | **🟢 正常** |
| 2 | **Claude (OpenAI group)** | `/v1/messages` | `gateway.go:44-50` | OpenAI OAuth | 自动路由到 OpenAIGateway | ✅ 完整 | **🟢 正常** |
| 3 | **OpenAI Chat Completions** | `/v1/chat/completions`, `/chat/completions` | `gateway.go:84-90`, `gateway.go:120-126` | OAuth / API Key | 透传+映射 | ✅ 完整 | **🟢 正常** |
| 4 | **OpenAI Responses** | `/v1/responses`, `/responses` | `gateway.go:68-81`, `gateway.go:109-118` | OAuth / API Key | 透传+映射 | ✅ 完整 | **🟢 正常** |
| 5 | **Gemini** | `/v1beta/models/*` | `gateway.go:94-106` | OAuth | 完整（2.5/3/3.1 系列） | ✅ 完整 | **🟢 正常** |
| 6 | **Antigravity Claude** | `/antigravity/v1/messages` | `gateway.go:141-145` | OAuth | `DefaultAntigravityModelMapping` | ✅ 完整 | **🟢 正常** |
| 7 | **Antigravity Gemini** | `/antigravity/v1beta/*` | `gateway.go:147-159` | OAuth | `DefaultAntigravityModelMapping` | ✅ 完整 | **🟢 正常** |
| 8 | **Codex** | `gpt-5.1-codex`, `gpt-5.3-codex` | `billing_service.go:252-272` | OpenAI OAuth | `codex_cli_only` 模式 | ✅ 专用探测+计费 | **🟢 正常** |
| 9 | **Bedrock** | `/v1/messages` | `account.go:827` | SigV4 / API Key | `DefaultBedrockModelMapping`（区域自适应） | ✅ 完整 | **🟢 正常** |
| 10 | **Sora** | — | — | — | — | — | **🔴 不可用** |

### 关键发现

1. **自动路由逻辑完善**：`gateway.go` 中 `/v1/messages`、`/v1/responses`、`/v1/chat/completions` 均实现了根据 `getGroupPlatform()` 自动路由到对应 handler（Anthropic vs OpenAI）的逻辑，确保同一 API Key 在不同 group 下正确转发。

2. **Antigravity 隔离正确**：`/antigravity/*` 路由使用 `ForcePlatform(PlatformAntigravity)` 中间件强制锁定账号平台，不会与其他平台混合调度。

3. **Codex 支持完善**：`billing_service.go` 中已为 `gpt-5.1-codex`、`gpt-5.3-codex`、`gpt-5.1-codex-max`、`gpt-5.1-codex-mini`、`codex-mini-latest` 等模型配置计费；`account_usage_service.go` 实现了 Codex 专用用量探测和 rate limit 监控。

4. **模型映射覆盖全面**：`domain/constants.go` 中的 `DefaultAntigravityModelMapping` 和 `DefaultBedrockModelMapping` 覆盖了当前主流模型版本（Claude Opus/Sonnet/Haiku 4-5/4-6 系列，Gemini 2.5/3/3.1 系列）。

---

## 二、构建与测试验证（实际执行）

### 2.1 后端

| 验证项 | 命令 | 结果 | 耗时 |
|--------|------|------|------|
| 编译构建 | `go build -tags embed -o sub2api ./cmd/server` | ✅ 成功 | ~30s |
| 单元测试 | `go test -tags=unit ./...` | ✅ 全部通过 | ~86s |
| 集成测试 | `go test -tags=integration ./...` | ✅ 全部通过 | ~36s |
| golangci-lint | `golangci-lint run ./...` | ⚠️ 未安装（环境限制） | — |

**测试通过详情**：
- `internal/handler` ✅（含 admin handler）
- `internal/handler/admin` ✅（含 Sora handler 测试）
- `internal/prommetrics` ✅（12 个测试用例全部通过）
- `internal/service` ✅（含 ops 16 个测试文件全部通过）
- `internal/server/routes` ✅（含健康检查端点测试）
- `internal/pkg/*` ✅（antigravity、gemini、openai 等）

### 2.2 前端

| 验证项 | 命令 | 结果 | 说明 |
|--------|------|------|------|
| 依赖安装 | `pnpm install --frozen-lockfile` | ⚠️ 部分失败 | npmmirror 网络问题（环境限制） |
| 构建 | `pnpm run build` | ✅ 成功 | ~29s，产出在 `backend/internal/web/dist/` |
| vitest 测试 | `pnpm test --run` | ✅ 全部通过 | 62 文件 / 364 测试 / 0 失败 |

**构建产物确认**：新增模块均正常编译：
- `OpsDashboard-BPDgd74J.js` (235KB gzip: 51KB) ✅
- `SoraView-DYa5Tfy5.js` (33KB gzip: 11KB) ✅
- `DataManagementView` ✅

---

## 三、新增模块代码质量评估

| 模块 | 文件数 | 测试文件数 | 测试通过率 | 质量评分 | 备注 |
|------|--------|-----------|-----------|---------|------|
| `prommetrics/` | 2 | 1 | 12/12 ✅ | ★★★★★ | 独立包，无循环依赖 |
| `service/ops_*.go` | 52 | 16 | 全部通过 ✅ | ★★★★☆ | 功能完善，告警/聚合/清理全覆盖 |
| `service/sora_*.go` | 21 | 0（sora 表已删除） | — | 🔴 风险 | 见下方阻塞问题 #1 |
| `handler/admin/ops_*.go` | 8 | 部分 | — | ★★★★☆ | 路由注册完整 |
| `handler/admin/sora_*.go` | 1 | 1 | 通过 ✅ | — | 依赖已删除的表 |
| `repository/ops_repo*.go` | 9 | 0 | — | ★★★☆☆ | 建议补充单元测试 |
| `frontend/views/admin/ops/` | 19 | 3 | — | ★★★★☆ | 组件化良好 |

---

## 四、阻塞问题清单

### 🔴 阻塞级 #1：Sora 模块代码残留与数据库状态不一致

**问题描述**：
- 数据库迁移 `090_drop_sora.sql` 已删除所有 Sora 表（sora_tasks、sora_generations、sora_accounts）及相关字段
- 但后端仍保留 21 个 `sora_*.go` service 文件、Sora admin handler、前端 SoraView 页面
- Admin 路由 `/admin/sora` 仍在 `admin.go:97-101` 注册
- 访问该路由将导致数据库查询失败（表不存在）

**影响**：管理员访问 Sora 管理页面时会遇到 500 错误

**修复方案**（二选一）：
1. **方案 A（推荐）**：在 `admin.go` 中注释掉 Sora 路由注册，待 Sora 功能恢复后重新启用
2. **方案 B**：回滚 `090_drop_sora.sql` 迁移，恢复 Sora 数据库表

### 🟡 中风险 #2：文档 Go 版本不一致

**问题描述**：
- `README.md`、`DEV_GUIDE.md` 写需要 Go 1.25.7
- 实际 `go.mod` 为 `go 1.26.2`
- CI 配置 `backend-ci.yml` 也校验 `go1.26.2`

**影响**：误导新开发者，可能导致本地环境配置错误

**修复方案**：将 README/DEV_GUIDE 中的 Go 版本统一更新为 1.26.2

### 🟡 中风险 #3：前端 Chunk 体积过大

**问题描述**：
- `AccountsView-kd8fcLKO.js` 544KB（超过 500KB 警告线）
- `vendor-ui-BHFCCYkz.js` 430KB

**影响**：首次加载 Admin 面板时可能出现明显延迟

**修复方案**：使用动态 import 拆分 AccountsView 等超大 chunk

### 🟢 低风险 #4：README 中 Sora 状态声明

**问题描述**：README.md 第 434 行已声明 "Sora-related features are temporarily unavailable"，但项目中 Sora 代码仍大量存在。

**影响**：认知不一致，开发者可能误以为 Sora 可用

---

## 五、安全审计

| 检查项 | 状态 | 说明 |
|--------|------|------|
| SQL 注入（ORDER BY） | ✅ 安全 | 白名单校验模式 |
| SQL 注入（CREATE DATABASE） | ⚠️ 需注意 | 有前置校验，建议加引号包裹 |
| JWT Secret 管理 | ✅ 已完善 | 有轮换告警机制 |
| URL Allowlist | ✅ 配置完善 | 支持 CORS、私网地址控制 |
| 密码复杂度 | ⚠️ 不一致 | 各模块要求不统一 |
| 响应头过滤 | ✅ 可配置 | `security.response_headers.enabled` |

---

## 六、CI/CD 评估

| Workflow | 存在 | 配置 | 评价 |
|----------|------|------|------|
| `backend-ci.yml` | ✅ | 单元测试 + 集成测试 + golangci-lint v2.9 | 完善 |
| `security-scan.yml` | ✅ | govulncheck + gosec + pnpm audit | 完善 |
| `release.yml` | ✅ | tag `v*` 触发构建 | 完善 |

---

## 七、数据库迁移评估

- 总迁移文件数：122 个 SQL 文件
- 最新迁移：`102_add_out_trade_no_to_payment_orders.sql`
- Ops 相关迁移：完整（026、033、034、036、037、038、039、042b、054、079）
- Sora 迁移：`046_add_sora_accounts.sql`、`047_add_sora_pricing_and_media_type.sql`、`063_add_sora_client_tables.sql` → **已被 090_drop_sora.sql 删除**

**风险**：Sora 相关代码依赖的表已被删除，但代码未清理。

---

## 八、上线建议

### 立即执行（上线前必做）

1. **禁用 Sora Admin 路由**（`backend/internal/server/routes/admin.go:97-101`）
   ```go
   // 暂时注释掉 Sora 路由，避免访问已删除的表
   // sora := admin.Group("/sora")
   // sora.GET("/stats", h.Admin.Sora.GetSystemStats)
   // ...
   ```

2. **同步文档版本号**
   - 更新 `README.md` 中的 Go 版本徽章
   - 更新 `DEV_GUIDE.md` 中的 Go 版本说明

### 近期执行（上线后 1-2 周）

3. **清理 Sora 残留代码**
   - 决定：彻底移除 Sora 代码，还是恢复数据库表支持
   - 如果移除：删除 `service/sora_*.go`、`handler/admin/sora_*.go`、`frontend/src/views/admin/SoraAdminView.vue`

4. **前端代码分割优化**
   - 对 AccountsView、OpsDashboard 等大 chunk 使用 `defineAsyncComponent` 懒加载

5. **统一密码复杂度要求**
   - 检查各 handler 中的密码验证逻辑，统一最小长度和字符要求

### 持续监控

6. **部署后验证各模型连通性**
   - Claude `/v1/messages`
   - Gemini `/v1beta/models`
   - OpenAI `/v1/chat/completions`
   - Codex 用量探测是否正常

7. **观察新增 Ops 监控性能**
   - 数据聚合任务对数据库负载的影响
   - Prometheus 指标端点 `/metrics` 的响应时间

---

## 九、最终判定

| 检查项 | 结果 |
|--------|------|
| 核心模型支持 | ✅ 完整（除 Sora） |
| 构建成功 | ✅ 前后端均通过 |
| 测试通过 | ✅ 单元+集成全部通过 |
| 新增模块质量 | ✅ 代码结构良好，有配套测试 |
| 数据库迁移 | ⚠️ Sora 表已删但代码残留 |
| 安全审计 | ✅ 无高风险漏洞 |
| CI/CD 配置 | ✅ 完整 |

**最终结论：CONDITIONAL GO（有条件通过）**

项目在核心 AI 模型网关功能上完全具备上线能力。唯一阻碍上线的因素是 Sora 模块的残留代码可能触发数据库错误。建议在上线前执行以下最小改动：

> **最小改动清单**：
> 1. 注释掉 `backend/internal/server/routes/admin.go` 中的 Sora 路由组（4 行代码）
> 2. 更新 README/DEV_GUIDE 中的 Go 版本说明
> 3. 重新构建验证
> 4. 即可上线

---

*报告生成时间: 2026-05-08 15:30*  
*评审执行人: 齐活林 (Qi) - 交付总监*  
*协作团队: 高见远 (架构师), 严过关 (QA 工程师)*