会员 · 消费 · 代理 · 分账完整流程手册¶

面向运营 / 研发 / 测试。覆盖：会员注册、购买与消费、代理注册与分享、分账与提现、各角色查数、管理员配置会员方案。

四桶积分 + 消耗提成（2026-08 现网）：操作步骤与数据流转见四桶积分与消耗提成。下文仍含「单一配额 + 订单实付分佣」历史口径，冲突时以新文档为准。

端到端主叙事（表流转 + 健壮性）：会员 · 充值 · 消费 · 分账 E2E。 表结构权威说明：数据模型 · 计费与代理；业务规则见会员 · 代理 · 销售 · 积分分佣说明书。设计背景见归档用户体系方案。

一、角色与入口¶

角色	前端	典型域名（ACK）	API 前缀
C 端会员	`src/infinitecanvas`	canvas.tuxianai.com	`/api/auth`、`/api/billing`、画布任务 API
代理商	`src/agent-system`	agent.tuxianai.com	`/api/agents`、`/api/landing`、`/api/settlement`、`/api/billing`
管理员	`src/admin-system`	admin.（见部署）	`/api/admin/*`

关系简述：

会员：买方案 → 得订阅/配额 → 生图扣点。
代理：拿推广码 → 客户绑定/带码下单 → 支付成功分佣 → 申请提现。
同一手机号可既是会员又是代理（两套身份正交）。

二、总览流程图¶

flowchart TB
  subgraph member [会员侧]
    M1[短信注册/登录] --> M2[赠送试用 10 点]
    M2 --> M3[浏览方案并下单]
    M3 --> M4[支付成功]
    M4 --> M5[订阅生效 + 配额到账]
    M5 --> M6[生图消费扣点]
  end

  subgraph agent [代理侧]
    A1[代理注册拿 TXAG 码] --> A2[分享落地页 /r/CODE]
    A2 --> A3[客户点击+绑定]
    A3 --> M3
    M4 --> A4[按规则分账]
    A4 --> A5[看板/客户/佣金]
    A5 --> A6[提现申请]
    A6 --> A7[Admin 审核打款]
  end

  subgraph admin [管理侧]
    ADM1[配置会员方案] --> M3
    ADM2[配置分账规则] --> A4
    ADM3[订单/退款/收入看板]
    ADM4[提现审核] --> A7
  end

三、会员注册与试用¶

3.1 流程¶

用户打开 Canvas，输入手机号。
POST /api/auth/send-code 发送验证码（开发环境多为 mock 固定码）。
POST /api/auth/login { phone, code }：用户不存在则自动注册。
新用户创建后赠送 10 点试用配额（流水 quota_gift，幂等，只送一次）。
返回 JWT；后续请求 Authorization: Bearer <token>。

3.2 试用权益¶

项	规则
点数	10
清晰度	无付费订阅时上限 1K
过期	当前不按日历强制过期；买会员后配额按方案重置/累加

3.3 相关 API¶

方法	路径	说明
POST	`/api/auth/send-code`	发短信
POST	`/api/auth/login`	登录/注册
GET	`/api/auth/me`	当前用户
GET	`/api/billing/quotas`	剩余配额

四、购买会员（含代理归因）¶

4.1 流程¶

GET /api/billing/plans 拉取在售方案。

用户选择方案 → POST /api/billing/orders：

{
  "plan_id": "<uuid>",
  "payment_method": "wechat|alipay|mock",
  "agent_code": "TXAG0001",
  "client_request_id": "可选幂等键"
}

服务端创建 pending 订单并预支付，返回 pay_url / qr_code。
支付成功回调 → 订单 paid → completed，并：
订阅方案：失效旧订阅，新建有效订阅，重置月配额；
加量包：累加 usage_quotas.total；
写用户流水 recharge；
若订单有 agent_id → 触发分账。

4.2 代理归因规则（首次永久）¶

场景	行为
客户已绑定代理	订单强制用绑定代理；请求里的其他 `agent_code` 忽略
未绑定 + 带有效 `agent_code`	写入 `customer_agent_bindings`，订单挂该代理
未绑定且无码	`agent_id=null`，无分佣
Canvas	自动读取 `localStorage.referral_code` 或 URL `?ref=` / `?agent_code=`

落地页绑定：POST /api/landing/{code}/bind（需登录）。已绑定他人 → 跳过（不改绑）。

4.3 支付模式¶

`PAYMENT_ENABLED`	行为
`false`（默认）	一律 mock；可用 `POST /api/payment/mock-pay/{order_no}`
`true`	禁止 mock；须配置微信/支付宝凭证与 `PAYMENT_NOTIFY_URL`

4.4 默认方案种子（可 Admin 改）¶

plan_key	名称	售价	月配额	清晰度	并发
pro_monthly / pro_yearly	专业版月/年	68 / 680	200	2K	3
premium_monthly / premium_yearly	高级版月/年	128 / 1280	500	4K	5
extra_50 / 100 / 500	加量包	50 / 90 / 400	50/100/500	4K	—

五、会员消费（扣点）¶

5.1 流程¶

用户在 Canvas 发起生图/任务。
任务创建前调用扣点（ConsumptionService.deduct）：
校验分辨率 ≤ 当前订阅 max_resolution（无订阅按 1K）；超限 → 403；
校验剩余点数；不足 → 402；
used += credits，写 consumption_records + 流水 consumption。
并发受订阅 concurrent_tasks 限制。

5.2 点数计算（摘要）¶

多数任务基础 1～4 点（按 task_type）。
分辨率附加：1K +0 / 2K +1 / 4K +2。

5.3 会员自助查数¶

方法	路径	说明
GET	`/api/billing/quotas`	配额
GET	`/api/billing/concurrency`	并发
GET	`/api/billing/orders`	我的订单
GET	`/api/billing/consumption`	消费记录
GET	`/api/billing/ledger`	账户流水

前端：Canvas「账户 / 订单 / 配额」页。

六、代理商注册¶

6.1 公开注册（推荐）¶

打开 agent-system 注册页。
POST /api/agents/register { phone, code }。
系统创建/复用用户，开通一级代理，生成 agent_code（如 TXAG0001）。
返回推荐码与链接：{APP_BASE_URL}/r/{agent_code}。

6.2 其他开通方式¶

方式	路径	说明
已登录用户申请	`POST /api/billing/agents/register`	可填上级码、等级
Admin 创建	`POST /api/admin/agents`	指定 `user_id`、上级、等级

二级代理：agent_level=2 + parent_agent_id；支付成功时二级与上级一级各拿一笔分账。

6.3 结算账户（提现前建议配置）¶

方法	路径	说明
GET	`/api/settlement/status`	当前结算信息
POST	`/api/settlement/merchant-info`	提交商户/账户并落库
POST	`/api/settlement/scan/alipay\\|wechat`	扫码会话（开发可 mock）

七、分享与获客¶

7.1 流程¶

代理在「推广链接」复制：https://canvas.tuxianai.com/r/{referral_code}（主站落地）。
访客打开落地页 → GET /api/landing/{code}：
返回代理名与推荐码；
记一次点击（agent_link_clicks，看板 today_clicks）。
前端把码写入 localStorage.referral_code，并跳转主页 /。
若访客已登录：
无代理 → POST /api/landing/{code}/bind 自动永久绑定；
已有代理 → 跳过（不改绑，HTTP 200）。
若访客未登录：仅保存推荐码；登录成功后自动补绑（规则同上）。
Canvas 下单时仍可带码（首次下单也会建绑定）。

7.2 注意¶

首次绑定永久，已有代理时新链接不会改绑。
点击统计按 UTC 自然日汇总到仪表盘「今日点击」。
客户列表 = 绑定客户 ∪ 历史付费订单客户。

八、分账¶

8.1 触发时机¶

仅在订单支付成功时计算（CommissionService.calculate_for_order），不是每次生图扣点时。

8.2 默认规则（Admin 可改）¶

代理等级	方案	比例
一级	专业版	15%
一级	高级版	12%
一级	加量包	10%
二级	全部	5%

示例：客户经一级代理买专业版月付 ¥68 → 代理佣金 ¥10.20，平台留 ¥57.80。若经二级代理：二级 5% + 其上级一级再按一级规则拿一笔。

8.3 分账结果（线下月结）¶

写 commission_records（accrued），不立刻增加可提现余额；
写审计流水 commission_accrual（金额 0）；
月结关账（Admin / cron）后：记录 → settled，增加 balance_commission / total_commission，写流水 commission。

可选：Admin 对单条 accrued 提前入账（同入账原语）。

8.4 退款冲销¶

Admin 退款时：

生产环境先调支付通道退款；
回滚用户配额与流水；
佣金状态 → clawed_back：
仍为 accrued：不改余额；
已 settled：扣回代理余额（不足则扣到 0 并备注差额）；
停用对应订阅；订单 → refunded。

九、代理提现¶

仅可提现已月结入账的 balance_commission。

代理申请提现
  → 预占 balance（创建 agent_withdrawals = pending）
  → Admin 审核
       ├─ 通过：withdrawn += 金额（线下打款）
       └─ 驳回：退回 balance

角色	方法	路径
代理	POST	`/api/billing/agents/me/withdraw` `{ "amount": "100.00" }`
Admin	GET	`/api/admin/withdrawals`
Admin	POST	`/api/admin/withdrawals/{id}/approve`
Admin	POST	`/api/admin/withdrawals/{id}/reject`

Admin 前端：计费 → 提现审核。

十、代理查看数据¶

页面 / 能力	API
个人资料	`GET /api/agents/me`
仪表盘（客户数、佣金、今日点击/新客、近 6 月）	`GET /api/agents/me/dashboard`
客户列表 / 详情	`GET /api/agents/me/customers`、`.../customers/{id}`
交易明细	`GET /api/agents/me/transactions`
分佣记录	`GET /api/agents/me/commissions`
推广链接	前端拼 `/r/{referral_code}`
结算账户	`/api/settlement/*`

十一、管理员：查数与运营¶

11.1 会员方案（设置「会员方案」）¶

操作	方法	路径
列表	GET	`/api/admin/plans`
新建	POST	`/api/admin/plans`
详情	GET	`/api/admin/plans/{id}`
更新	PUT	`/api/admin/plans/{id}`
排序	POST	`/api/admin/plans/reorder`

可配置字段要点：name、plan_key、plan_type（subscription / extra_pack）、billing_cycle、价格、monthly_quota、max_resolution、concurrent_tasks、status（0 停售 / 1 在售）。

前端：Admin → 计费 → 会员方案。

11.2 订单与退款¶

操作	路径
订单列表/详情	`GET /api/admin/orders`、`/orders/{id}`
退款	`POST /api/admin/orders/{id}/refund` `{ "reason", "amount?" }`

11.3 代理与分账¶

操作	路径
代理 CRUD	`/api/admin/agents`
分账规则	`/api/admin/commission-rules`
分账记录 / 提前入账	`/api/admin/commission-records`、`.../settle`
月结关账	`/api/admin/commission-settlements/close`
日终对账	`/api/admin/billing/recon/run`、`.../batches`
提现审核	`/api/admin/withdrawals`
统一流水	`/api/admin/ledger`
用户消费	`/api/admin/consumption?user_id=`
收入看板	`/api/admin/statistics/revenue`
手动月配额重置	`POST /api/admin/quota-reset`

11.4 用户订阅（运营补发）¶

Admin 用户管理支持为指定用户手动开订阅（见 /api/admin/users/{id}/subscriptions 相关接口与用户页）。

十二、端到端验收清单（建议）¶

A. 会员主路径¶

新手机号登录 → 配额显示试用 10 点。
用 2K 生图 → 无订阅应被拒绝（上限 1K）。
mock 购买专业版 → 配额 200、可用 2K。
生图成功 → 消费记录与配额 used 增加。

B. 代理主路径¶

代理注册 → 得到 TXAG####。
打开 /r/{code} → 代理看板今日点击 +1。
客户登录并 bind → 绑定成功；再用其他码 bind → 跳过（仍归属原代理）。
客户带码（或已绑定）购买 ¥68 专业版 → 一级代理余额约 +10.20。
Admin 月结关账 → 余额增加 → 代理申请提现 → Admin 通过 → withdrawn 增加；或驳回 → 余额退回。

C. Admin¶

新建/停售方案 → C 端方案列表同步变化。
调整分账规则 → 新订单按新比例。
退款：accrued 仅冲状态；已月结则扣余额。

十三、关键表（便于排查）¶

表	用途
`users` / `subscriptions` / `usage_quotas`	用户、订阅、配额
`member_plans` / `orders` / `payment_records`	方案、订单、支付
`consumption_records` / `transaction_ledger`	消费与统一流水
`agents` / `agent_commission_rules` / `commission_records`	代理与分账
`customer_agent_bindings`	客户永久归属
`agent_link_clicks`	推广点击
`agent_withdrawals`	提现申请

十四、环境与迁移¶

# 数据库迁移（含绑定/提现/点击/结算字段）
make backend-migrate
# 或：poetry run alembic -c alembic_backend.ini upgrade head

# 种子方案与分账规则（开发）
# 会员方案/分账规则：alembic upgrade（数据迁移 s1f2a3b4c5d6），勿用 seed 覆盖

支付生产化变量见 src/backend/.env.example：PAYMENT_ENABLED、PAYMENT_NOTIFY_URL、微信/支付宝商户字段。

十五、相关文档与代码入口¶

文档/代码	路径
设计方案	docs/design/用户体系设计方案.md
订单/退款	`src/backend/core/services/order_service.py`
分账/提现	`src/backend/core/services/commission_service.py`
扣点/清晰度/试用点	`src/backend/core/services/consumption_service.py`
代理门户	`src/backend/core/services/agent_portal_service.py`
Admin 计费 API	`src/backend/api/admin/billing.py`
Canvas 下单	`src/infinitecanvas/src/shared/api/billingApi.ts`
代理前端	`src/agent-system/src/features/*`
Admin 前端	`src/admin-system/src/features/billing/`、`features/agents/`