跨系统主流程

涉及 Admin / Agent / Canvas / Backend。表变更见 data-model.md。

1. 系统关系

flowchart TB
  Admin[Admin_5175] --> BE[Backend_8001]
  Agent[Agent_5173] --> BE
  Canvas[Canvas_5176] --> BE
  BE --> PG[(Postgres)]
  BE --> Redis[(Redis_Stream)]
  BE --> Storage[Storage_8002]
  Worker[backend-worker] --> Redis
  Worker --> PG
  Worker --> Storage

2. 管理员配置 → C 端可用

1. Admin 维护产品树、面料、模板、模型池
2. 写 product_* / *_templates / ai_*
3. Canvas GET /user/catalog/* 与 match 读到启用数据
4. 用户生图走模型池与模板 Prompt

失败：模板未关联子类/面料 → match 空；模型池无可用成员 → 生图失败。

3. 代理获客 → 绑定 → 优惠下单

sequenceDiagram
  participant Ag as AgentSPA
  participant U as User
  participant Cv as Canvas
  participant API as Backend
  Ag->>Ag: 复制推广链 /r/CODE
  U->>Cv: 打开落地页
  Cv->>API: GET /landing/CODE
  Note over API: agent_link_clicks
  U->>Cv: 短信登录
  Cv->>API: POST /landing/CODE/bind
  Note over API: customer_agent_bindings 唯一
  U->>Cv: 购买套餐
  Cv->>API: POST /billing/orders
  Note over API: 应用 customer_discount_rate
  API->>API: 支付成功 → commission_records

幂等/约束：一客一代理；重复 bind 失败；支付回调重复不重复加配额（BE-REQ-063）。

4. 生图扣费

1. Canvas 提交 generate
2. Backend 校验配额与并发
3. ModelPoolRouter 选模型/账号
4. 上游成功 → tasks completed + consumption_records + quota.used + ledger
5. 失败 → 任务 failed；按实现决定是否扣费（以代码为准，测试需断言）

异步：Stream → Worker 更新任务；前端轮询或 SSE。

5. 提现（跨 Admin / Agent / Backend）

1. Agent（或将来前端）POST /billing/agents/me/withdraw 预占 balance_commission
2. 写 agent_withdrawals pending
3. Admin 审批 approve/reject
4. approved：withdrawn 增加；rejected：回滚预占
5. Agent 门户余额展示刷新

注意：当前 Agent SPA 无提现按钮；可用 API/Admin 测全链路。

6. 结算账户绑定

Agent Settlement → scan/merchant → 更新 agents.settlement_* → 便于线下打款（与线上支付回调独立）。

7. 联调环境建议

make up 或 recipe full-stack；make seed；hosts 绑定 *.localhost；支付用 mock。