chore: initial public snapshot for github upload

2026-03-26 20:06:14 +08:00
commit 0e5ecd930e
3497 changed files with 1586236 additions and 0 deletions
--- a/docs/supply_detailed_design_v1_2026-03-18.md
+++ b/docs/supply_detailed_design_v1_2026-03-18.md
@@ -0,0 +1,644 @@
+# 用户供应LLM功能 - 完整详细设计（补充版）
+
+> 本文档对"用户分享LLM供应"功能进行完整详细的设计补充，包括安全机制、账单记录等完整内容。
+
+---
+
+## 1. 功能架构
+
+### 1.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           供应侧功能完整架构                                      │
+├─────────────────────────────────────────────────────────────────────────────────┤
+│                                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                        供应方侧（User A）                               │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │   │
+│  │  │ 账号挂载   │  │ 套餐发布   │  │ 收益查看   │  │  提现      │   │   │
+│  │  │ 模块       │  │ 模块       │  │ 模块       │  │  模块      │   │   │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                           │
+│                                    ▼                                           │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                        平台核心层                                        │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │   │
+│  │  │ 账号验证   │  │ 套餐管理   │  │ 调度引擎   │  │  计费引擎   │   │   │
+│  │  │ 服务       │  │ 服务       │  │             │  │             │   │   │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │   │
+│  │  │ 风控服务   │  │ 合规检测   │  │ 通知服务   │  │ 审计服务   │   │   │
+│  │  │             │  │ 服务       │  │             │  │             │   │   │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                           │
+│                                    ▼                                           │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                        需求方侧（User B）                               │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │   │
+│  │  │ 套餐选购   │  │  调用API   │  │ 使用账单   │  │  消耗统计   │   │   │
+│  │  │ 模块       │  │  模块       │  │ 模块       │  │  模块      │   │   │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 安全机制详细设计
+
+### 2.1 账号安全
+
+#### 2.1.1 账号挂载安全流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        账号挂载安全验证流程                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+步骤1: 用户提交账号
+       │
+       ▼
+步骤2: 账号格式校验
+       │  ├── API Key 格式检查
+       │  ├── OAuth 授权链接生成
+       │  └── 格式不合格 → 拒绝
+       ▼
+步骤3: 账号有效性验证
+       │  ├── 调用供应商 API 验证账号可用
+       │  ├── 获取账号基本信息
+       │  └── 验证失败 → 拒绝
+       ▼
+步骤4: 额度查询
+       │  ├── 获取当前剩余额度
+       │  ├── 记录额度快照
+       │  └── 额度不足 → 警告
+       ▼
+步骤5: ToS 合规检查
+       │  ├── 检查供应商 ToS 是否允许共享
+       │  ├── 检查账号类型是否合规
+       │  └── 不合规 → 拒绝
+       ▼
+步骤6: 风险评估
+       │  ├── 账号历史行为分析
+       │  ├── 异常检测
+       │  └── 高风险 → 人工审核
+       ▼
+步骤7: 加密存储
+       │  ├── 使用 KMS 加密
+       │  ├── 生成账号唯一标识
+       │  └── 存储到数据库
+       ▼
+步骤8: 通知用户
+            ├── 挂载成功/失败通知
+            └── 后续操作指引
+```
+
+#### 2.1.2 账号存储安全
+
+| 安全措施 | 说明 | 实现 |
+|----------|------|------|
+| **加密存储** | API Key 必须加密存储 | AES-256-GCM 加密 |
+| **KMS 集成** | 使用密钥管理服务 | AWS KMS / 自建 |
+| **字段级加密** | 敏感字段单独加密 | 密钥ID + 密文 |
+| **访问控制** | 最小权限原则 | RBAC 控制 |
+| **审计日志** | 所有访问记录日志 | 操作人 + 时间 + IP |
+| **禁止导出** | 禁止明文导出 Key | 脱敏展示 |
+
+#### 2.1.3 凭证边界强制约束
+
+1. 供应方上游凭证仅由平台密态托管（KMS + 字段级加密）。
+2. 需求方只允许使用平台签发凭证调用统一入口。
+3. 平台禁止向需求方返回供应方上游凭证（API/控制台/导出均不允许）。
+
+### 2.2 调用安全
+
+#### 2.2.1 请求验证流程
+
+```
+请求进入
+    │
+    ▼
+┌─────────────────┐
+│  1. API Key 验证 │ ──▶ 无效 → 401 Unauthorized
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  2. 套餐有效性  │ ──▶ 过期/售罄 → 403 Forbidden
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  3. 额度检查    │ ──▶ 额度不足 → 402 Payment Required
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  4. 风控检查    │ ──▶ 风险拦截 → 429 Too Many Requests
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  5. ToS 合规   │ ──▶ 违规拦截 → 403 Forbidden
+└────────┬────────┘
+         │
+         ▼
+    转发到上游
+```
+
+#### 2.2.2 安全防护措施
+
+| 防护项 | 说明 | 配置 |
+|--------|------|------|
+| **IP 白名单** | 限制调用来源 IP | 可配置 |
+| **Referer 校验** | 限制调用来源域名 | 可配置 |
+| **调用频率限制** | RPM/TPM 限制 | 按套餐配置 |
+| **并发限制** | 同时请求数限制 | 按套餐配置 |
+| **模型限制** | 可用模型白名单 | 按套餐配置 |
+| **额度预警** | 额度低于阈值告警 | 可配置 |
+
+### 2.3 防欺诈机制
+
+#### 2.3.1 欺诈检测规则
+
+| 规则 | 描述 | 动作 |
+|------|------|------|
+| **额度异常消耗** | 单日消耗 > 平均3倍 | 告警 + 审核 |
+| **短时间大量调用** | 1分钟内 > 100次 | 限流 + 审核 |
+| **新账号高额使用** | 注册24h内使用 > $100 | 审核 |
+| **跨地区调用** | IP 地区突然变化 | 告警 |
+| **模式异常** | 调用模式偏离历史 | 告警 |
+| **账号共享检测** | 多 IP 同时使用 | 封禁 + 审核 |
+
+#### 2.3.2 保证金机制
+
+| 供应方类型 | 保证金要求 | 退还条件 |
+|------------|------------|----------|
+| 个人 | ¥500 | 最后一笔交易30天后无异常 |
+| 企业 | ¥5,000 | 最后一笔交易90天后无异常 |
+
+**扣除场景**：
+- 欺诈行为
+- 账号封禁导致需求方损失
+- 恶意套现
+
+---
+
+## 3. 账单与记录详细设计
+
+### 3.1 数据模型
+
+执行口径说明（重要）：
+1. 本节内联 SQL 用于逻辑模型说明，不作为生产执行脚本。
+2. 生产执行 DDL 以 `sql/postgresql/supply_schema_v1.sql` 为唯一脚本来源（PostgreSQL 方言）。
+3. 若内联示意与执行脚本冲突，以执行脚本为准。
+
+#### 3.1.1 供应方账号表
+
+执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_accounts`）。
+
+关键字段：
+1. 基础：`id/user_id/platform/account_type/status`。
+2. 凭证：`encrypted_credentials/key_id`（仅密态托管）。
+3. 风控：`risk_level/risk_score/is_frozen`。
+4. 审计：`created_at/updated_at/created_by/updated_by`。
+
+#### 3.1.2 供应套餐表
+
+执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_packages`）。
+
+关键字段：
+1. 关联：`supply_account_id/user_id/platform/model`。
+2. 定价：`price_per_1m_input/price_per_1m_output`。
+3. 额度：`total_quota/available_quota/sold_quota/reserved_quota`。
+4. 状态：`draft/active/paused/sold_out/expired`。
+
+#### 3.1.3 订单表
+
+执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_orders`）。
+
+关键字段：
+1. 订单主键：`id/order_no`。
+2. 交易信息：`buyer_user_id/supplier_user_id/supply_package_id`。
+3. 金额信息：`total_amount/platform_fee/supplier_earnings`。
+4. 状态：`pending/paid/using/expired/refunded`。
+
+#### 3.1.4 使用记录表（详细到每一次调用）
+
+执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_usage_records`）。
+
+关键字段：
+1. 追踪主键：`request_id/upstream_request_id/order_id`。
+2. 模型维度：`platform/model/endpoint`。
+3. 计费维度：`request_tokens/response_tokens/total_tokens/total_cost`。
+4. 响应维度：`response_status/latency_ms/success`。
+
+#### 3.1.5 供应方收益表
+
+执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_earnings`）。
+
+关键字段：
+1. 收益类型：`usage/bonus/refund`。
+2. 资金状态：`pending/available/withdrawn/frozen`。
+3. 金额字段：`amount/available_amount/frozen_amount/withdrawn_amount`。
+
+#### 3.1.6 结算记录表
+
+执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_settlements`）。
+
+关键字段：
+1. 结算状态：`pending/processing/completed/failed`。
+2. 金额字段：`total_amount/fee_amount/net_amount`。
+3. 周期字段：`period_start/period_end`。
+
+### 3.2 账单查询API
+
+#### 3.2.1 供应方账单API
+
+```yaml
+# 供应方账单查询
+GET /api/v1/supplier/billing
+
+Query Parameters:
+- start_date: string (可选) 开始日期 YYYY-MM-DD
+- end_date: string (可选) 结束日期 YYYY-MM-DD
+- page: int (可选) 页码
+- page_size: int (可选) 每页数量
+
+Response:
+{
+  "data": {
+    "period": {
+      "start": "2026-03-01",
+      "end": "2026-03-31"
+    },
+    "summary": {
+      "total_revenue": 12500.00,      # 总收入
+      "total_orders": 156,            # 订单数
+      "total_usage": 500000000,      # 总tokens
+      "total_requests": 15800,        # 总请求数
+      "avg_success_rate": 99.2,      # 平均成功率
+      "platform_fee": 1875.00,       # 平台服务费
+      "net_earnings": 10625.00       # 净收益
+    },
+    "by_platform": [
+      {
+        "platform": "openai",
+        "revenue": 8000.00,
+        "orders": 100,
+        "tokens": 320000000,
+        "success_rate": 99.5
+      },
+      {
+        "platform": "anthropic",
+        "revenue": 4500.00,
+        "orders": 56,
+        "tokens": 180000000,
+        "success_rate": 98.8
+      }
+    ],
+    "by_model": [...],
+    "trend": [...]
+  },
+  "pagination": {...}
+}
+```
+
+#### 3.2.2 需求方账单API
+
+```yaml
+# 需求方账单查询
+GET /api/v1/consumer/billing
+
+Response:
+{
+  "data": {
+    "balance": {
+      "total_paid": 5000.00,         # 已支付总额
+      "total_used": 3200.00,        # 已使用
+      "remaining": 1800.00,        # 剩余
+      "frozen": 0.00                # 冻结
+    },
+    "usage": {
+      "this_month": {
+        "tokens": 120000000,
+        "cost": 960.00,
+        "requests": 5200
+      },
+      "by_platform": [...],
+      "by_model": [...]
+    },
+    "orders": [...]
+  }
+}
+```
+
+### 3.3 详细使用记录
+
+```yaml
+# 详细使用记录查询
+GET /api/v1/consumer/usage-records
+
+Query Parameters:
+- start_date: string
+- end_date: string
+- platform: string (可选)
+- model: string (可选)
+- success: boolean (可选)
+- page: int
+- page_size: int
+
+Response:
+{
+  "data": [
+    {
+      "id": 1001,
+      "request_id": "req_abc123",
+      "order_id": 500,
+      "platform": "openai",
+      "model": "gpt-4o",
+      "endpoint": "/v1/chat/completions",
+      "tokens": {
+        "input": 1500,
+        "output": 800,
+        "total": 2300
+      },
+      "cost": {
+        "input": 0.0075,     # $7.5/1M
+        "output": 0.032,     # $32/1M
+        "total": 0.0395      # $0.0395
+      },
+      "latency_ms": 1250,
+      "status": "success",
+      "timestamp": "2026-03-18T10:30:00Z"
+    }
+  ],
+  "pagination": {...}
+}
+```
+
+---
+
+## 4. 完整业务流程
+
+### 4.1 供应方完整流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          供应方完整业务流程                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+1. 入驻认证
+   ├── 注册账号
+   ├── 实名认证 (个人/企业)
+   └── 缴纳保证金
+        │
+        ▼
+2. 账号挂载
+   ├── 选择供应商
+   ├── 选择认证方式 (API Key / OAuth)
+   ├── 提交凭证
+   ├── 平台验证 (有效性/额度/ToS)
+   └── 通过 → 激活账号
+        │
+        ▼
+3. 套餐发布
+   ├── 选择要共享的模型
+   ├── 设置配额 (全部/部分额度)
+   ├── 设置售价
+   ├── 设置有效期
+   └── 上架销售
+        │
+        ▼
+4. 日常运营
+   ├── 监控账号状态
+   ├── 查看订单通知
+   ├── 处理异常 (如有)
+   └── 收益查看
+        │
+        ▼
+5. 收益结算
+   ├── 收益累积 (T+7 可提现)
+   ├── 申请提现
+   ├── 平台审核
+   └── 到账
+```
+
+### 4.2 需求方完整流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          需求方完整业务流程                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+1. 浏览选购
+   ├── 浏览可用套餐
+   ├── 按供应商/模型筛选
+   ├── 查看套餐详情 (额度/价格/评价)
+   └── 选择购买
+        │
+        ▼
+2. 下单购买
+   ├── 选择配额数量
+   ├── 确认价格
+   ├── 选择支付方式
+   └── 支付成功
+        │
+        ▼
+3. 获取凭证
+   ├── 获取平台 API Key（平台签发）
+   ├── 不返回供应方上游凭证
+   ├── 配置使用限制
+   └── 开始使用
+        │
+        ▼
+4. 使用API
+   ├── 调用统一API
+   ├── 实时扣减配额
+   ├── 查看使用统计
+   └── 配额不足 → 续费
+        │
+        ▼
+5. 账单管理
+   ├── 查看使用明细
+   ├── 下载账单
+   └── 对账
+```
+
+---
+
+## 5. 调度策略
+
+### 5.1 请求调度流程
+
+```
+请求进入 (指定模型: gpt-4o)
+    │
+    ▼
+查找可用套餐 (gpt-4o + 有剩余配额 + 正常状态)
+    │
+    ├── 多个套餐可用
+    │       │
+    │       ▼
+    │   选择策略:
+    │   1. 最低价格优先
+    │   2. 负载均衡 (选择负载最低)
+    │   3. 轮询
+    │   4. 供应商偏好
+    │       │
+    │       ▼
+    │   选择最优套餐
+    │
+    └── 单个套餐可用 → 使用该套餐
+        │
+        ▼
+检查套餐配额 (足够? → 继续; 不足? → 拒绝)
+    │
+    ▼
+检查账户状态 (正常? → 继续; 异常? → 拒绝)
+    │
+    ▼
+转发到上游供应商
+    │
+    ▼
+获取响应
+    │
+    ▼
+记录使用记录
+    │
+    ├── 更新订单剩余配额
+    ├── 更新套餐已售配额
+    ├── 计算费用
+    └── 更新供应方收益
+        │
+        ▼
+返回响应给需求方
+```
+
+### 5.2 调度策略配置
+
+| 策略 | 说明 | 适用场景 |
+|------|------|----------|
+| **最低价格** | 选择售价最低的套餐 | 成本优先 |
+| **负载均衡** | 选择负载最低的套餐 | 性能优先 |
+| **轮询** | 依次选择各套餐 | 公平使用 |
+| **供应商偏好** | 优先特定供应商 | 稳定性优先 |
+| **混合** | 综合考虑价格/负载/偏好 | 默认 |
+
+---
+
+## 6. 监控与告警
+
+### 6.1 监控指标
+
+#### 6.1.1 供应方监控
+
+| 指标 | 说明 | 告警阈值 |
+|------|------|----------|
+| 账号可用率 | 账号正常比例 | < 99% |
+| 成功率 | 请求成功率 | < 95% |
+| 平均延迟 | 平均响应时间 | > 5000ms |
+| 配额消耗速度 | 配额日消耗比例 | > 80%/天 |
+| 异常请求比例 | 失败请求比例 | > 10% |
+| 收益异常 | 收益突增/突降 | 偏离 > 50% |
+
+#### 6.1.2 套餐监控
+
+| 指标 | 说明 | 告警阈值 |
+|------|------|----------|
+| 剩余配额 | 可用配额 | < 10% |
+| 订单量 | 新增订单 | 突降 > 30% |
+| 评分 | 用户评分 | < 4.0 |
+| 投诉 | 用户投诉 | > 3次/周 |
+
+### 6.2 告警通知
+
+| 告警类型 | 通知对象 | 通知方式 |
+|----------|----------|----------|
+| 账号异常 | 供应方 | 站内信/邮件 |
+| 配额不足 | 供应方 | 站内信/短信 |
+| 收益到账 | 供应方 | 站内信/邮件 |
+| 异常订单 | 平台运营 | 邮件/短信 |
+| ToS 违规 | 平台运营 | 邮件 |
+
+---
+
+## 7. 报表导出
+
+### 7.1 供应方报表
+
+| 报表 | 内容 | 格式 |
+|------|------|------|
+| 账单汇总 | 收入/订单/费用 | CSV/Excel |
+| 使用明细 | 每笔调用详情 | CSV/Excel |
+| 账户流水 | 收益/提现/冻结 | CSV/Excel |
+| 对账单 | 平台与供应方对账 | PDF |
+
+### 7.2 需求方报表
+
+| 报表 | 内容 | 格式 |
+|------|------|------|
+| 消费账单 | 消费汇总 | CSV/Excel |
+| 使用明细 | 调用明细 | CSV/Excel |
+| 成本分析 | 按模型/部门分析 | PDF |
+
+---
+
+## 8. 数据统计SQL示例
+
+### 8.1 供应方收入统计
+
+```sql
+SELECT
+    sa.user_id,
+    u.username,
+    sa.platform,
+    SUM(sur.total_cost) as total_revenue,
+    SUM(sur.total_cost) * :platform_fee_rate as platform_fee,
+    SUM(sur.total_cost) * :supplier_settlement_rate as supplier_earnings,
+    COUNT(DISTINCT sur.order_id) as order_count,
+    SUM(sur.total_tokens) as total_tokens,
+    AVG(sur.success) as avg_success_rate
+FROM supply_usage_records sur
+JOIN supply_accounts sa ON sur.supply_account_id = sa.id
+JOIN users u ON sa.user_id = u.id
+WHERE sur.created_at >= '2026-03-01' AND sur.created_at < '2026-04-01'
+GROUP BY sa.user_id, u.username, sa.platform
+ORDER BY total_revenue DESC;
+```
+
+### 8.2 套餐消耗统计
+
+```sql
+SELECT
+    sp.id as package_id,
+    sp.model,
+    sp.platform,
+    sp.total_quota,
+    sp.available_quota,
+    sp.sold_quota,
+    (sp.sold_quota / sp.total_quota * 100) as sold_rate,
+    COUNT(DISTINCT so.id) as order_count,
+    SUM(sur.total_cost) as total_revenue,
+    AVG(sur.latency_ms) as avg_latency,
+    AVG(sur.success) as success_rate
+FROM supply_packages sp
+LEFT JOIN supply_orders so ON sp.id = so.supply_package_id
+LEFT JOIN supply_usage_records sur
+       ON sur.supply_account_id = sp.supply_account_id
+      AND sur.model = sp.model
+WHERE sp.created_at >= '2026-03-01'
+GROUP BY sp.id, sp.model, sp.platform, sp.total_quota, sp.available_quota, sp.sold_quota
+ORDER BY total_revenue DESC;
+```
+
+---
+
+**文档状态**：完整详细设计（已补 PostgreSQL 执行口径与 SQL 示例修正）
+**关联文档**：
+- `supply_side_product_design_v1_2026-03-18.md`
+- `supply_feature_technical_analysis_v1_2026-03-18.md`