366 lines
9.3 KiB
Markdown
366 lines
9.3 KiB
Markdown
|
# Sub2API v0.1.112 合并方案专家审核报告
|
|||
|
|
|
|||
|
|
**审核日期**: 2026-04-14
|
|||
|
|
**审核范围**: 完整性、安全性、技术细节、数据库迁移
|
|||
|
|
**审核专家**: 架构师、代码审查专家、数据库专家
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、综合评分
|
|||
|
|
|
|||
|
|
| 维度 | 评分 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| 策略正确性 | 8/10 | 基准策略正确，但细节有遗漏 |
|
|||
|
|
| 风险识别 | 7/10 | 识别了主要风险，遗漏依赖兼容性 |
|
|||
|
|
| 执行可行性 | 6/10 | Wire合并方案不完整 |
|
|||
|
|
| 安全性 | 7/10 | 支付签名验证存在，缺少重放攻击防护 |
|
|||
|
|
| 数据库迁移 | 8/10 | 方案基本正确，需补充索引和约束 |
|
|||
|
|
| 测试覆盖 | 6/10 | 缺少安全测试和端到端测试 |
|
|||
|
|
| 回滚完整性 | 5/10 | 数据回滚方案不完整 |
|
|||
|
|
|
|||
|
|
**总体评分: 6.7/10**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、严重问题清单 (必须修复)
|
|||
|
|
|
|||
|
|
### 问题1: Wire依赖注入合并方案不完整
|
|||
|
|
|
|||
|
|
**严重程度**: HIGH
|
|||
|
|
**影响**: 可能导致编译失败或运行时panic
|
|||
|
|
|
|||
|
|
**问题详情**:
|
|||
|
|
|
|||
|
|
1. **cmd/server/wire.go 需要合并**:
|
|||
|
|
```go
|
|||
|
|
// 官方版本新增
|
|||
|
|
import "github.com/Wei-Shaw/sub2api/internal/payment"
|
|||
|
|
|
|||
|
|
wire.Build(
|
|||
|
|
payment.ProvideRegistry,
|
|||
|
|
payment.ProvideEncryptionKey,
|
|||
|
|
payment.ProvideDefaultLoadBalancer,
|
|||
|
|
service.ProvidePaymentConfigService,
|
|||
|
|
service.ProvidePaymentOrderExpiryService,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 本地版本 cleanup 中有
|
|||
|
|
soraMediaCleanup *service.SoraMediaCleanupService
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2. **internal/handler/wire.go 需要合并**:
|
|||
|
|
```go
|
|||
|
|
// AdminHandlers 结构体
|
|||
|
|
type AdminHandlers struct {
|
|||
|
|
// 官方新增
|
|||
|
|
TLSFingerprintProfile *admin.TLSFingerprintProfileHandler
|
|||
|
|
Channel *admin.ChannelHandler
|
|||
|
|
Payment *admin.PaymentHandler
|
|||
|
|
// ...
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Handlers 结构体
|
|||
|
|
type Handlers struct {
|
|||
|
|
// 官方新增
|
|||
|
|
Payment *PaymentHandler
|
|||
|
|
PaymentWebhook *PaymentWebhookHandler
|
|||
|
|
// 本地保留
|
|||
|
|
SoraGateway *SoraGatewayHandler
|
|||
|
|
SoraClient *SoraClientHandler
|
|||
|
|
// ...
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**修复方案**: 手动合并两个结构体定义，确保所有Handler都被正确注册。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题2: PlatformSora常量缺失
|
|||
|
|
|
|||
|
|
**严重程度**: HIGH
|
|||
|
|
**影响**: 编译失败
|
|||
|
|
|
|||
|
|
**问题**: endpoint.go 中的 Sora 平台判断依赖 `service.PlatformSora` 常量，但该常量需要手动添加。
|
|||
|
|
|
|||
|
|
**修复方案**:
|
|||
|
|
```go
|
|||
|
|
// backend/internal/domain/constants.go
|
|||
|
|
const (
|
|||
|
|
PlatformAnthropic = "anthropic"
|
|||
|
|
PlatformOpenAI = "openai"
|
|||
|
|
PlatformGemini = "gemini"
|
|||
|
|
PlatformAntigravity = "antigravity"
|
|||
|
|
PlatformSora = "sora" // 必须添加
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题3: OpenAIMessagesDispatchModelConfig类型缺失
|
|||
|
|
|
|||
|
|
**严重程度**: HIGH
|
|||
|
|
**影响**: Schema定义编译失败
|
|||
|
|
|
|||
|
|
**问题**: group.go 的 `messages_dispatch_model_config` 字段依赖 `domain.OpenAIMessagesDispatchModelConfig` 类型。
|
|||
|
|
|
|||
|
|
**修复方案**: 确保合并时包含官方的 `backend/internal/domain/openai_messages_dispatch.go` 文件。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题4: SoraAccountRepository接口缺失
|
|||
|
|
|
|||
|
|
**严重程度**: HIGH
|
|||
|
|
**影响**: TokenRefreshService依赖注入失败
|
|||
|
|
|
|||
|
|
**问题**: 本地版本的 `ProvideTokenRefreshService` 注入了 `SoraAccountRepository`。
|
|||
|
|
|
|||
|
|
**修复方案**: 确保保留本地的 `backend/internal/repository/sora_account_repo.go` 文件。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题5: 前端类型定义不一致
|
|||
|
|
|
|||
|
|
**严重程度**: HIGH
|
|||
|
|
**影响**: TypeScript编译失败
|
|||
|
|
|
|||
|
|
**问题**: GroupPlatform/AccountPlatform 类型定义不一致。
|
|||
|
|
|
|||
|
|
**修复方案**:
|
|||
|
|
```typescript
|
|||
|
|
// 扩展官方类型
|
|||
|
|
export type GroupPlatform = 'anthropic' | 'openai' | 'gemini' | 'antigravity' | 'sora'
|
|||
|
|
export type AccountPlatform = 'anthropic' | 'openai' | 'gemini' | 'antigravity' | 'sora'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、中等问题清单 (建议修复)
|
|||
|
|
|
|||
|
|
### 问题6: usage_logs.channel_id 缺少索引
|
|||
|
|
|
|||
|
|
**严重程度**: MEDIUM
|
|||
|
|
**影响**: 按渠道统计查询性能差
|
|||
|
|
|
|||
|
|
**修复方案**:
|
|||
|
|
```sql
|
|||
|
|
CREATE INDEX CONCURRENTLY idx_usage_logs_channel_id
|
|||
|
|
ON usage_logs(channel_id) WHERE channel_id IS NOT NULL;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题7: payment_orders.user_id 缺少外键约束
|
|||
|
|
|
|||
|
|
**严重程度**: MEDIUM
|
|||
|
|
**影响**: 数据完整性风险
|
|||
|
|
|
|||
|
|
**修复方案**:
|
|||
|
|
```sql
|
|||
|
|
ALTER TABLE payment_orders ADD CONSTRAINT fk_payment_orders_user_id
|
|||
|
|
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题8: subscription_plans.group_id 缺少外键约束
|
|||
|
|
|
|||
|
|
**严重程度**: MEDIUM
|
|||
|
|
**影响**: 数据完整性风险
|
|||
|
|
|
|||
|
|
**修复方案**:
|
|||
|
|
```sql
|
|||
|
|
ALTER TABLE subscription_plans ADD CONSTRAINT fk_subscription_plans_group_id
|
|||
|
|
FOREIGN KEY (group_id) REFERENCES groups(id) ON DELETE CASCADE;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题9: 支付Webhook缺少重放攻击防护
|
|||
|
|
|
|||
|
|
**严重程度**: MEDIUM
|
|||
|
|
**影响**: 安全风险
|
|||
|
|
|
|||
|
|
**建议**:
|
|||
|
|
1. 添加请求速率限制
|
|||
|
|
2. 验证时间戳防止重放
|
|||
|
|
3. 添加幂等性保护
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 问题10: Sora表DDL不完整
|
|||
|
|
|
|||
|
|
**严重程度**: MEDIUM
|
|||
|
|
**影响**: 迁移脚本无法执行
|
|||
|
|
|
|||
|
|
**修复方案**: 补充完整的 sora_accounts 和 sora_generations 表DDL。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、数据库迁移审核结果
|
|||
|
|
|
|||
|
|
### 4.1 迁移风险评估
|
|||
|
|
|
|||
|
|
| 表 | 操作 | 风险等级 | 预估时间 |
|
|||
|
|
|----|------|----------|----------|
|
|||
|
|
| groups | ADD COLUMN (8个字段) | 低 | < 1秒 |
|
|||
|
|
| users | ADD COLUMN (2个字段) | 低 | < 1秒 |
|
|||
|
|
| usage_logs | ADD COLUMN (5个字段) | 低 | < 1秒 |
|
|||
|
|
| payment_orders | CREATE TABLE | 低 | < 1秒 |
|
|||
|
|
| subscription_plans | CREATE TABLE | 低 | < 1秒 |
|
|||
|
|
| usage_logs | CREATE INDEX | 中 | 取决于数据量 |
|
|||
|
|
|
|||
|
|
### 4.2 是否需要停机
|
|||
|
|
|
|||
|
|
**结论**: 不需要停机维护
|
|||
|
|
|
|||
|
|
- 所有 DDL 操作都是非阻塞或快速完成
|
|||
|
|
- 新增字段都有默认值或允许 NULL
|
|||
|
|
- 建议在业务低峰期执行
|
|||
|
|
|
|||
|
|
### 4.3 回滚方案问题
|
|||
|
|
|
|||
|
|
**发现问题**:
|
|||
|
|
- 回滚 SQL 不完整，缺少 Sora 字段
|
|||
|
|
- 未处理外键依赖
|
|||
|
|
- 缺少数据备份策略
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、遗漏项清单
|
|||
|
|
|
|||
|
|
### 5.1 代码遗漏
|
|||
|
|
|
|||
|
|
| 项目 | 描述 | 位置 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| Handlers结构体字段 | 未明确最终结构 | handler/wire.go |
|
|||
|
|
| AdminHandlers结构体字段 | 未明确最终结构 | handler/wire.go |
|
|||
|
|
| SoraMediaCleanupService | cleanup依赖 | cmd/server/wire.go |
|
|||
|
|
| OpenAIMessagesDispatchModelConfig | 类型定义 | domain/ |
|
|||
|
|
|
|||
|
|
### 5.2 迁移遗漏
|
|||
|
|
|
|||
|
|
| 项目 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| sora_accounts表DDL | 完整定义缺失 |
|
|||
|
|
| sora_generations表DDL | 完整定义缺失 |
|
|||
|
|
| channel_id索引 | 遗漏 |
|
|||
|
|
| 外键约束 | 遗漏 |
|
|||
|
|
|
|||
|
|
### 5.3 测试遗漏
|
|||
|
|
|
|||
|
|
| 项目 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| 支付端到端测试 | 完整支付流程测试 |
|
|||
|
|
| 安全测试 | SQL注入、XSS、重放攻击 |
|
|||
|
|
| Sora禁用验证 | 功能开关验证 |
|
|||
|
|
| 性能基准测试 | 并发测试 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、改进建议
|
|||
|
|
|
|||
|
|
### 6.1 立即修复
|
|||
|
|
|
|||
|
|
1. **更新Wire合并方案**
|
|||
|
|
- 明确 Handlers 结构体最终定义
|
|||
|
|
- 明确 AdminHandlers 结构体最终定义
|
|||
|
|
- 补充 payment 包依赖和 cleanup 服务
|
|||
|
|
|
|||
|
|
2. **补充类型定义**
|
|||
|
|
- 添加 PlatformSora 常量
|
|||
|
|
- 确认 OpenAIMessagesDispatchModelConfig 存在
|
|||
|
|
- 确保 SoraAccountRepository 接口保留
|
|||
|
|
|
|||
|
|
3. **完善迁移脚本**
|
|||
|
|
- 补充 Sora 表完整 DDL
|
|||
|
|
- 添加 channel_id 索引
|
|||
|
|
- 添加外键约束
|
|||
|
|
|
|||
|
|
### 6.2 安全增强
|
|||
|
|
|
|||
|
|
1. **支付系统安全**
|
|||
|
|
- 添加 Webhook 速率限制
|
|||
|
|
- 验证支付 Provider 签名实现
|
|||
|
|
- 添加幂等性保护
|
|||
|
|
|
|||
|
|
2. **Sora功能隔离**
|
|||
|
|
- 在路由层完全禁用端点
|
|||
|
|
- 添加集中功能开关管理
|
|||
|
|
- 验证禁用状态错误处理
|
|||
|
|
|
|||
|
|
### 6.3 测试补充
|
|||
|
|
|
|||
|
|
1. **添加安全测试**
|
|||
|
|
- SQL注入测试
|
|||
|
|
- 支付重放攻击测试
|
|||
|
|
- 权限绕过测试
|
|||
|
|
|
|||
|
|
2. **添加端到端测试**
|
|||
|
|
- 完整支付流程测试
|
|||
|
|
- 订阅计划购买流程测试
|
|||
|
|
- Sora禁用状态验证测试
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、修订后的时间表
|
|||
|
|
|
|||
|
|
| 阶段 | 内容 | 原计划 | 修订后 |
|
|||
|
|
|------|------|--------|--------|
|
|||
|
|
| Phase 1 | 准备阶段 | Day 1 | Day 1 |
|
|||
|
|
| Phase 2 | Schema层合并 | Day 2 | Day 2-3 |
|
|||
|
|
| Phase 3 | 后端代码合并 | Day 3-4 | Day 4-6 |
|
|||
|
|
| Phase 4 | 前端代码合并 | Day 5-6 | Day 7-8 |
|
|||
|
|
| Phase 5-6 | 数据库迁移+配置 | Day 7 | Day 9 |
|
|||
|
|
| Phase 7 | 测试验证 | Day 8-10 | Day 10-14 |
|
|||
|
|
| **总计** | | **10天** | **14天** |
|
|||
|
|
|
|||
|
|
增加时间用于:
|
|||
|
|
- Wire合并方案的详细验证
|
|||
|
|
- 安全测试和端到端测试
|
|||
|
|
- 迁移脚本的完善和测试
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 八、执行前提条件
|
|||
|
|
|
|||
|
|
在开始执行合并前，必须满足以下条件：
|
|||
|
|
|
|||
|
|
1. **代码准备**
|
|||
|
|
- [ ] 补充 PlatformSora 常量定义
|
|||
|
|
- [ ] 确认 OpenAIMessagesDispatchModelConfig 类型存在
|
|||
|
|
- [ ] 确认 SoraAccountRepository 接口保留
|
|||
|
|
- [ ] 明确 Handlers/AdminHandlers 最终结构
|
|||
|
|
|
|||
|
|
2. **迁移准备**
|
|||
|
|
- [ ] 补充完整的 sora_accounts 表 DDL
|
|||
|
|
- [ ] 补充完整的 sora_generations 表 DDL
|
|||
|
|
- [ ] 添加 channel_id 索引脚本
|
|||
|
|
- [ ] 添加外键约束脚本
|
|||
|
|
|
|||
|
|
3. **测试准备**
|
|||
|
|
- [ ] 编写支付端到端测试用例
|
|||
|
|
- [ ] 编写安全测试用例
|
|||
|
|
- [ ] 编写 Sora 禁用验证测试
|
|||
|
|
|
|||
|
|
4. **备份准备**
|
|||
|
|
- [ ] 完整备份数据库
|
|||
|
|
- [ ] 备份本地版本代码
|
|||
|
|
- [ ] 验证备份恢复流程
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 九、结论
|
|||
|
|
|
|||
|
|
合并方案整体思路正确，但在执行细节上存在重大遗漏。建议：
|
|||
|
|
|
|||
|
|
1. **先修复严重问题** (问题1-5)，否则无法成功编译
|
|||
|
|
2. **补充中等问题** (问题6-10)，确保数据完整性和安全性
|
|||
|
|
3. **延长执行周期** 从10天延长至14天，增加测试验证时间
|
|||
|
|
4. **先测试环境验证** 确保所有步骤可正常执行后再在生产环境操作
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**审核人**: 架构师 + 代码审查专家 + 数据库专家
|
|||
|
|
**审核日期**: 2026-04-14
|
|||
|
|
**文档版本**: v1.0
|