# Sub2API v0.1.112 合并项目状态文档

**生成日期**: 2026-04-14
**官方版本**: v0.1.112 (D:\project\sub2api-latest)
**本地版本**: D:\project\sub2apipro
**合并目录**: D:\project\sub2api-merge

---

## 一、项目目录结构

### 1.1 合并后项目根目录

```
D:\project\sub2api-merge\
├── backend\                    # 后端代码（Go + Ent ORM）
│   ├── cmd\                    # 命令入口
│   │   └── server\             # 服务器主程序
│   ├── ent\                    # Ent ORM Schema 和生成代码
│   │   └── schema\             # 数据库 Schema 定义
│   ├── internal\               # 内部代码
│   │   ├── config\             # 配置管理
│   │   ├── domain\             # 领域模型
│   │   ├── handler\            # HTTP 处理器
│   │   ├── payment\            # 支付模块（官方新增）
│   │   ├── pkg\                # 公共包
│   │   ├── repository\         # 数据仓储层
│   │   ├── server\             # HTTP 服务器
│   │   ├── service\            # 业务服务层
│   │   ├── setup\              # 初始化设置
│   │   └── util\               # 工具函数
│   ├── migrations\             # 数据库迁移脚本
│   └── resources\              # 资源文件
├── frontend\                   # 前端代码（Vue 3 + TypeScript）
│   ├── src\
│   │   ├── api\                # API 请求
│   │   ├── components\         # Vue 组件
│   │   │   ├── sora\           # Sora 组件（本地合并）
│   │   │   ├── payment\        # 支付组件（官方新增）
│   │   │   └── ...
│   │   ├── router\             # 路由配置
│   │   ├── stores\             # Pinia 状态管理
│   │   ├── types\              # TypeScript 类型定义
│   │   ├── views\              # 页面视图
│   │   └── i18n\               # 国际化
│   └── ...
├── docs\                       # 文档目录
│   └── reviews\                # 审查报告目录
├── deploy\                     # 部署文档
├── README.md
├── README_CN.md
└── ...
```

### 1.2 关键目录说明

| 目录 | 说明 | 来源 |
|------|------|------|
| `backend/internal/payment` | 支付系统模块 | 官方版本 |
| `backend/internal/service/sora_*.go` | Sora 视频生成服务 | 本地版本 |
| `backend/ent/schema/payment_*.go` | 支付相关 Schema | 官方版本 |
| `frontend/src/components/sora` | Sora 前端组件 | 本地版本 |
| `frontend/src/views/user/SoraView.vue` | Sora 页面 | 本地版本 |

---

## 二、合并记录文件位置

### 2.1 审查报告文件

| 文件名 | 路径 | 说明 |
|--------|------|------|
| `OFFICIAL_REVIEW_REPORT_2026-04-14.md` | `D:\project\sub2api-merge\docs\reviews\` | 官方版本 v0.1.112 代码审查报告 |
| `EXPERT_REVIEW_REPORT_2026-04-14.md` | `D:\project\sub2api-merge\docs\reviews\` | 专家审核报告（评分 6.7/10） |
| `DETAILED_MERGE_PLAN_2026-04-14.md` | `D:\project\sub2api-merge\docs\reviews\` | 详细合并方案（含补充修订） |

### 2.2 原始审查报告位置

| 文件名 | 路径 | 说明 |
|--------|------|------|
| `REVIEW_REPORT_2026-04-14.md` | `D:\project\sub2apipro\docs\reviews\` | 本地版本代码审查报告 |

---

## 三、合并功能清单

### 3.1 官方版本新增功能（已合并）

| 功能模块 | 状态 | 说明 |
|----------|------|------|
| 支付系统 | ✅ 已合并 | 支付订单、支付回调、退款 |
| 订阅计划 | ✅ 已合并 | 订阅计划管理 |
| 渠道管理 | ✅ 已合并 | 渠道配置和定价 |
| TLS 指纹配置 | ✅ 已合并 | TLS 客户端指纹模拟 |
| OIDC OAuth | ✅ 已合并 | OIDC 认证集成 |
| OpenAI Messages Dispatch | ✅ 已合并 | 模型消息分发配置 |

### 3.2 本地版本保留功能（已合并）

| 功能模块 | 状态 | 说明 |
|----------|------|------|
| Sora 视频生成 | ✅ 已合并 | Sora SDK 客户端、网关服务 |
| Sora 存储配额 | ✅ 已合并 | 用户/分组存储配额管理 |
| Sora 媒体存储 | ✅ 已合并 | S3/本地存储支持 |

---

## 四、数据库迁移文件清单

### 4.1 官方版本迁移文件

| 文件 | 说明 |
|------|------|
| `092_payment_orders.sql` | 支付订单表 |
| `095_subscription_plans.sql` | 订阅计划表 |
| `096_payment_provider_instances.sql` | 支付提供商实例表 |
| `080_create_tls_fingerprint_profiles.sql` | TLS 指纹配置表 |

### 4.2 本地版本迁移文件

| 文件 | 说明 |
|------|------|
| `046_add_sora_accounts.sql` | Sora 账号表 |
| `047_add_sora_pricing_and_media_type.sql` | Sora 定价和媒体类型 |
| `063_add_sora_client_tables.sql` | Sora 客户端表 |

---

## 五、Wire 依赖注入合并清单

### 5.1 cmd/server/wire.go

| Provider | 来源 | 状态 |
|----------|------|------|
| `payment.ProvideRegistry` | 官方 | ✅ 已注册 |
| `payment.ProvideEncryptionKey` | 官方 | ✅ 已注册 |
| `payment.ProvideDefaultLoadBalancer` | 官方 | ✅ 已注册 |
| `service.ProvidePaymentConfigService` | 官方 | ✅ 已注册 |
| `service.ProvidePaymentOrderExpiryService` | 官方 | ✅ 已注册 |
| `service.ProvideSoraMediaStorage` | 本地 | ✅ 已注册 |
| `service.ProvideSoraMediaCleanupService` | 本地 | ✅ 已注册 |
| `service.ProvideSoraSDKClient` | 本地 | ✅ 已注册 |

### 5.2 internal/handler/wire.go

| Handler | 来源 | 状态 |
|---------|------|------|
| `PaymentHandler` | 官方 | ✅ 已注册 |
| `PaymentWebhookHandler` | 官方 | ✅ 已注册 |
| `TLSFingerprintProfileHandler` | 官方 | ✅ 已注册 |
| `ChannelHandler` | 官方 | ✅ 已注册 |
| `SoraGatewayHandler` | 本地 | ✅ 已注册 |
| `SoraClientHandler` | 本地 | ✅ 已注册 |

### 5.3 internal/service/wire.go

| Provider | 来源 | 状态 |
|----------|------|------|
| `NewPaymentService` | 官方 | ✅ 已注册 |
| `NewChannelService` | 官方 | ✅ 已注册 |
| `NewTLSFingerprintProfileService` | 官方 | ✅ 已注册 |
| `NewSoraGatewayService` | 本地 | ✅ 已注册 |
| `NewSoraGenerationService` | 本地 | ✅ 已注册 |
| `NewSoraQuotaService` | 本地 | ✅ 已注册 |

---

## 六、前端路由合并清单

### 6.1 官方版本路由

| 路径 | 组件 | 状态 |
|------|------|------|
| `/purchase` | PaymentView.vue | ✅ 已配置 |
| `/payment/qrcode` | PaymentQRCodeView.vue | ✅ 已配置 |
| `/payment/result` | PaymentResultView.vue | ✅ 已配置 |
| `/payment/stripe` | StripePaymentView.vue | ✅ 已配置 |
| `/admin/channels` | ChannelsView.vue | ✅ 已配置 |
| `/admin/orders/dashboard` | AdminPaymentDashboardView.vue | ✅ 已配置 |
| `/admin/orders/plans` | AdminPaymentPlansView.vue | ✅ 已配置 |

### 6.2 本地版本路由

| 路径 | 组件 | 状态 |
|------|------|------|
| `/sora` | SoraView.vue | ✅ 已配置 |

---

## 七、构建验证状态

### 7.1 后端构建

| 检查项 | 状态 | 说明 |
|--------|------|------|
| `go build ./...` | ✅ 通过 | 无编译错误 |
| `go vet ./...` | ✅ 通过 | 无代码问题 |
| `go test ./...` | ⚠️ 部分通过 | logger 超时（已知 lumberjack 问题） |

### 7.2 前端构建

| 检查项 | 状态 | 说明 |
|--------|------|------|
| `npm run typecheck` | ✅ 通过 | TypeScript 类型检查通过 |
| `npm run build` | ✅ 通过 | 构建成功，28.72s |

---

## 八、已修复的问题清单

| 问题 | 文件 | 修复内容 |
|------|------|----------|
| 缺少 `/sora/` 路径支持 | `middleware/security_headers.go` | 添加 Sora 路径到 API 路由判断 |
| `provideCleanup` 参数不匹配 | `wire_gen_test.go` | 添加 `SoraMediaCleanupService` 参数 |
| 缺少 Sora 前端组件 | `views/user/SoraView.vue` | 从本地版本复制 |
| 缺少 Sora 组件目录 | `components/sora/*.vue` | 从本地版本复制 8 个组件 |
| 缺少 Sora API 文件 | `api/sora.ts` | 从本地版本复制 |
| 缺少 Sora 路由 | `router/index.ts` | 添加 `/sora` 路由 |
| 缺少 `sora_client_enabled` 类型 | `types/index.ts` | 添加到 `PublicSettings` 接口 |
| 缺少 `sora_client_enabled` 默认值 | `stores/app.ts` | 添加默认值 `false` |

---

## 九、后续待办事项

- [ ] 执行数据库迁移脚本
- [ ] 配置支付提供商
- [ ] 配置 Sora 存储后端
- [ ] 启用 Sora 客户端功能（如需要）
- [ ] 端到端功能测试

---

**文档版本**: v1.0
**最后更新**: 2026-04-14