Backend 设计文档¶

代码根：src/backend/。端口默认 8001。相关架构：overview、messaging、storage、model_pool。

1. 定位与边界¶

Backend 是 Admin / Agent / Canvas 三前端的统一业务 API：

鉴权与用户体系（Admin / User / Agent）
产品·面料·模板配置与 C 端目录只读
AI 模型池调度、生图任务、Prompt 测试
画布项目持久化与资产
会员计费、支付回调、代理分佣与结算
经 HTTP 调用 storage:8002（禁止持有 OSS AK）
经 Redis Stream 与 backend-worker 协作（短信/异步生图/SSE）

不在本服务内：OSS 密钥、前端页面、chat/

2. 分层架构¶

api/          # FastAPI 路由，仅依赖 core / schemas / dependencies
core/         # 领域服务、AI 适配器、支付客户端、Prompt 组装
db/           # ORM models + repositories（禁止依赖 api/core 业务）
schemas/      # Pydantic 入出参
composition/  # Depends 装配、单例
utils/        # http_client、storage_client、短信等
worker/       # Worker 进程入口侧业务钩子

约束（import-linter）：

API → core / schemas / dependencies
Core → db / schemas / utils；禁止依赖 api
DB → 仅 ORM/Repo
外部 HTTP 必须经 utils/http_client.py

3. 路由挂载¶

main.py：

前缀	路由器	主要消费方
`/api/admin`	`admin_router`	Admin
`/api` + `/auth`	用户短信登录	Canvas / Agent
`/api/canvas`	画布	Canvas
`/api/agents`	代理门户	Agent
`/api/landing`	推广落地	Canvas / Agent
`/api/settlement`	结算绑定	Agent
`/api/export`	Excel 导出	Agent
`/api/billing`	C 端计费	Canvas
`/api/user/*`	目录/生图/上传	Canvas
`/api/user-assets`	资产库	Canvas
`/api/tasks`	用户任务	Canvas
`/api/payment`	支付回调	支付渠道
`/api/sub-types`	公开子类目录	Canvas

统一响应：{ code, message, data }（见 schemas/response.py）。

4. 鉴权设计¶

Depends	规则
`CurrentAdmin`	Bearer JWT，`role=admin`，查 `admin_users`
`CurrentUser`	Bearer JWT，C 端用户
`CurrentAgent`	当前用户须已有有效 `agents` 行
支付回调 / mock	按渠道验签或开发开关；无用户 JWT

Admin 写操作经 middleware 记入 operation_logs。

5. 关键时序（摘要）¶

5.1 用户短信登录¶

sequenceDiagram
  participant FE as Canvas_or_Agent
  participant API as Backend
  participant Redis as Redis_SMS
  participant SMS as SMS_Provider
  FE->>API: POST /api/auth/send-code
  API->>Redis: 存验证码
  API->>SMS: 发送短信
  FE->>API: POST /api/auth/login
  API->>API: 校验码/建用户/发 JWT

5.2 生图扣费（用户任务）¶

sequenceDiagram
  participant FE as Canvas
  participant API as Backend
  participant Pool as ModelPoolRouter
  participant Up as Upstream_AI
  participant DB as Postgres
  FE->>API: POST /api/user/tasks/generate
  API->>DB: 校验配额与并发
  API->>Pool: 选物理模型与账号
  API->>Up: 调用上游
  API->>DB: 写 tasks / consumption / ledger
  API-->>FE: 结果 URL 或任务 ID

异步路径：发布 Redis Stream → backend-worker 消费 → 更新任务状态（SSE 可选）。

5.3 代理绑客¶

sequenceDiagram
  participant U as User_Browser
  participant C as Canvas
  participant API as Backend
  U->>C: 打开 /r/{code}
  C->>API: GET /api/landing/{code}
  Note over API: 记 agent_link_clicks
  U->>C: 登录
  C->>API: POST /api/landing/{code}/bind
  API->>API: 写入 customer_agent_bindings（一客一代理）

5.4 支付与分佣¶

下单 → prepay → 渠道回调 /api/payment/notify/{method} → 订单 paid → 配额入账 → 按绑定代理生成 commission_records → 账本流水。开发可用 POST /api/payment/mock-pay/{order_no}。

6. 模型池设计要点¶

逻辑池 ai_model_groups ↔ 多物理 ai_models（weight + priority）
凭证优先 ai_model_api_accounts 绑定；兼容旧 ai_model_api_keys
池级/模型级熔断参数见 group 字段
详见 model_pool.md

7. 存储依赖¶

StorageHttpClient（utils/storage_client.py）调用 STORAGE_SERVICE_URL：

上传、预签名、下载 URL 签发、图片转码等
object_key 存库；URL 短时有效，由 resolve 接口刷新

8. 配置要点¶

变量族	用途
`DATABASE_URL`	Postgres
`REDIS_URL` / `MESSAGING_*`	Stream
`STORAGE_SERVICE_URL`	OSS 微服务
`SMS_*` / `SMS_PROVIDER`	短信
支付相关	支付宝/微信或 mock
`CORS_ORIGINS`	前端来源
JWT 密钥相关	Token 签发

详见仓库 .env.example 与 src/backend/.env.example。

9. Worker¶

独立进程 worker_main.py / K8s Deployment backend-worker：

Init 等待 Redis Ready
消费短信、生图等 Stream
不得 import 前端；与 API 共享 core/db

10. 与旧设计文档关系¶

产品级细节可参考 docs/design/* 与 docs/runbooks/billing-agent-flows.md；字段与路径以本目录 + ORM/路由为准。