会员 · 充值 · 消费 · 分账 — 完整流程与健壮性说明¶

定位：端到端主叙事（流程 + 表流转 + 健壮性）。下文仍按改造前「单一配额 + 订单分佣」整理。

四桶积分 + 消耗提成（2026-08 现网）：points-consume-commission.md。

配套文档：

业务与操作流程：membership-agent-sales-guide.md

表结构：data-model/billing.md

运营/测试分步手册：billing-agent-flows.md

7 档权益总表：membership-tiers.md

线下分账待审核债：billing-offline-settlement.md

一、业务总览（两套正交资金流）¶

资金流	资产	触发点	不做什么
会员购买（充值）	人民币订单 → 用户积分配额	支付成功	不按次扣人民币
生图消费	`usage_quotas` 积分	创建任务/画布生图	不扣代理余额、不分佣
代理分佣	`agents.balance_commission`	月结关账后入可提现	支付成功仅计提；与生图无关

flowchart TB
  subgraph adminCfg [Admin配置]
    P[member_plans会员方案]
    R[agent_commission_rules分账规则]
  end

  subgraph userLife [用户生命周期]
    Reg[短信登录即注册] --> Gift[赠送10试用点]
    Gift --> Bind[可选绑定代理]
    Bind --> Order[下单购档/升级]
    Order --> Pay[微信/支付宝支付]
    Pay --> Sub[subscriptions生效]
    Pay --> Quota[usage_quotas累加]
    Pay --> Accrue[commission_records accrued]
    Sub --> LoginPts[每日登录领分]
    Quota --> Consume[生图扣点]
  end

  subgraph agentLife [代理资金]
    Accrue --> MonthClose[月结关账]
    MonthClose --> Balance[balance_commission增加]
    Balance --> Withdraw[提现申请]
    Withdraw --> Audit[Admin审核线下打款]
  end

  P --> Order
  R --> Accrue

身份正交：同一手机号可同时是 C 端会员与代理商（users + agents 一对一）。管理员在独立表 admin_users。

二、核心数据表与职责¶

表	职责	余额含义
`member_plans`	7 档会员规则（价格/积分/权益）	配置，非余额
`agent_commission_rules`	按代理等级+方案的佣金率	配置
`users`	C 端身份	无余额字段
`subscriptions`	当前有效会员档	权益状态
`usage_quotas`	积分余额（`quota_type=generation`）	`total - used`
`daily_login_claims`	每日登录领分幂等	领取记录
`orders` + `payment_records`	购档订单与支付凭证	人民币侧
`consumption_records`	生图扣点明细	消费侧
`transaction_ledger`	统一流水（user/agent）	审计账本
`agents`	代理身份与可提现余额	`balance_commission`
`customer_agent_bindings`	客户永久绑定代理	归因
`commission_records`	佣金计提明细	accrued→settled
`commission_settlements`	月结批次	关账凭证
`agent_withdrawals`	提现单	pending→approved/rejected
`recon_batches`	日终对账批次	对账结果

无独立 wallet 表：用户积分 = usage_quotas；代理人民币 = agents.balance_commission。

ORM 路径：

src/backend/db/models/billing/plan.py — MemberPlan
src/backend/db/models/billing/order.py — Order / PaymentRecord
src/backend/db/models/billing/ledger.py — 流水 / 消费 / 登录领分
src/backend/db/models/billing/commission.py — 分佣规则 / 记录 / 月结
src/backend/db/models/billing/agent.py — 代理 / 绑定 / 提现
src/backend/db/models/billing/recon.py — 对账批次
src/backend/db/models/user.py — User / Subscription / UsageQuota

三、端到端流程（按业务阶段）¶

3.1 会员规则设置（Admin）¶

入口：admin-system → PlansPage / CommissionRulesPage

后端：plan_service.py、plan_points.py；Admin API api/admin/billing/plans.py、commissions.py

流程：

初始 7 档由 Alembic s1f2a3b4c5d6 写入（trial→supreme），不再经 seed_v3 覆盖。
Admin CRUD member_plans：售价、bonus_rate、login_points_per_day、权益矩阵、status（在售/停售）、软删。
保存时服务端按公式校验积分三字段：
首充积分 = round(售价 × 10 × (1 + bonus_rate))
周期登录 = login_points_per_day × cycle_days
周期总 = 首充 + 周期登录
同步运行时字段：purchase_points / daily_login_points / monthly_quota（桥接现网单一 generation 配额）。
配置 agent_commission_rules：(agent_level, plan_id) 精确匹配，plan_id=NULL 为通配回退。

默认分佣（种子）：一级：体验 10%；基础/进阶 12%；专业/企业 15%；旗舰/至尊 12%。二级：通配 5%。

表流转：仅写配置表；不影响用户余额。

3.2 用户注册 / 登录¶

入口：Canvas AuthProvider → POST /api/auth/login

后端：user_auth_service.py → ConsumptionService.gift_trial_credits

步骤	写表	说明
验短信码	—	`send-code` + `login`
手机号不存在 → INSERT	`users`	无独立注册 API，首次登录即注册
赠送试用	`usage_quotas.total += 10`；`transaction_ledger`（`quota_gift`）	幂等：已有 gift 流水则跳过
返回 JWT	—	不创建 `subscriptions`

注册后权益：10 试用点；无付费档时清晰度上限 1K；不可领每日登录积分。

可选代理绑定（登录后静默）：

访问落地页 GET /api/landing/{referral_code} → 记 agent_link_clicks
POST /api/landing/{code}/bind → 写 customer_agent_bindings（customer_id UNIQUE，首次永久、不可改绑）
下单带 agent_code 且未绑定也会自动绑定（OrderService._resolve_agent_id）

3.3 充值（购买/升级会员）¶

入口：POST /api/billing/orders（api/user_billing.py）

报价（membership_pricing.py）：

新购：实付 = 方案标价；入账 = purchase_points（不按代理折扣）
升级：仅允许 tier_rank 升高；实付 = 新档售价 − 旧档售价；入账 = 新档首充 − 旧档首充
代理本人购档：不享客户折扣

状态机与表流转：

stateDiagram-v2
  [*] --> pending: create_order
  pending --> paid: 支付回调/查单
  paid --> completed: 履约完成
  pending --> cancelled: 超时关单
  completed --> refunded: Admin退款

阶段	表变化	关键字段
下单	INSERT `orders`	`status=pending`，`order_kind=purchase\\|upgrade`，`points_granted`，`agent_id`
预支付	调微信/支付宝；可选写预支付上下文	返回 qr/pay_url
回调成功	INSERT `payment_records`；订单 `paid`→履约→`completed`	`transaction_id`
履约-订阅	旧 `subscriptions.status=0`；新订阅 `status=1`	`plan_id`、`expires_at`
履约-积分	`usage_quotas.total += points_granted`	累加不重置
履约-流水	`transaction_ledger` `ledger_type=recharge`	`balance_after`
履约-分佣	INSERT `commission_records` `status=accrued`	不加 `balance_commission`
退款	订单 `refunded`；配额回滚；佣金 `clawed_back`	accrued 只改状态；settled 扣余额

兜底路径：回调丢失 → POST /orders/{id}/sync-pay 主动查单；pending 列表惰性关单。

3.4 消费（生图扣点）¶

入口：任务创建 / 画布生图 → ConsumptionService.deduct（默认 18 积分/图）

步骤	表变化
校验分辨率 ≤ 当前订阅 `max_resolution`	读 `subscriptions` + `member_plans`
检查剩余 ≥ 成本	读 `usage_quotas`
扣点	`usage_quotas.used += credits`
明细	INSERT `consumption_records`
流水	`transaction_ledger` `ledger_type=consumption`（负金额）
不足	HTTP 402 `InsufficientCreditsError`

每日登录积分（需有效会员档）：POST /api/billing/login-points/claim → UNIQUE (user_id, claim_date) 于 daily_login_claims → add_extra_pack 累加配额。

3.5 分账 · 月结 · 提现¶

sequenceDiagram
  participant Pay as 支付履约
  participant CS as CommissionService
  participant CSS as SettlementService
  participant Ag as agents余额
  participant Adm as Admin审核

  Pay->>CS: calculate_for_order
  CS->>CS: commission_records accrued
  Note over CS: ledger commission_accrual amount=0
  CSS->>CSS: close_month FOR UPDATE
  CSS->>Ag: balance_commission += total
  CSS->>CSS: status settled + commission_settlements
  Ag->>Adm: withdraw 预占余额
  Adm->>Adm: approve 线下打款 / reject 退回

阶段	表流转	保障
计提	`commission_records` accrued；幂等键 `comm:{order_id}:{agent_id}` UNIQUE	直推 + 二级上级各一条
月结	accrued→settled；`commission_settlements`；`balance_commission+=`；ledger `commission`	`FOR UPDATE` + 幂等键 `settle:{YYYY-MM}:{agent_id}`
提前入账	Admin 按条 settle	同行锁
提现申请	`balance_commission-=`；`agent_withdrawals` pending；ledger `withdraw`	预占模式
审核通过	`withdrawn_commission+=`；approved	线下打款（无通道实时分账）
驳回	余额退回；rejected
退款冲销	accrued→clawed_back；settled 扣余额（不足扣至 0）

脚本：src/backend/scripts/commission_month_close.py、daily_billing_recon.py。

四、全链路表状态对照（一张表看懂）¶

业务事件	users	subscriptions	usage_quotas	orders	payment_records	consumption_records	transaction_ledger	commission_records	agents.balance	withdrawals
首次登录	INSERT	—	+10	—	—	—	quota_gift	—	—	—
绑定代理	—	可同步 agent_id	—	—	—	—	—	—	—	—
下单	—	—	—	pending	—	—	—	—	—	—
支付成功	—	新旧切换	+points	completed	success	—	recharge	accrued	不变	—
登录领分	—	—	+daily	—	—	—	（经加量）	—	—	—
生图	—	—	used↑	—	—	INSERT	consumption	—	—	—
月结	—	—	—	—	—	—	commission(+)	settled	↑	—
提现申请	—	—	—	—	—	—	withdraw(-)	—	↓预占	pending
提现通过	—	—	—	—	—	—	确认	—	不变	approved
订单退款	—	视业务回滚	回滚积分	refunded	refunded	—	refund	clawed_back	可能↓	—

五、稳定性 / 健壮性保障矩阵¶

5.1 已落地¶

机制	位置	作用
下单幂等	Redis `IdempotencyStore` + `Idempotency-Key`	防重复建单（TTL 24h）
支付回调幂等	查 `payment_records.transaction_id`；订单已 paid 直接 ACK	防重复履约
履约嵌套事务	`begin_nested()`	失败回滚促通道重试
分佣幂等	DB UNIQUE `idempotency_key`	防双计提
月结行锁 + 幂等	`SELECT ... FOR UPDATE` + settle 唯一键	防双关账
试用/登录幂等	gift 流水检查；`(user_id, claim_date)` UNIQUE	防重复赠分
支付金额校验	`_amounts_compatible`	防篡改金额
退款佣金冲销	accrued/settled 分支处理	防多付佣金
日终对账 + 账本回放	`billing_recon_service.py`	支付/计提/余额/配额抽样
超时关单 / 主动查单	PaymentService	回调丢失兜底
架构约束	import-linter；支付密钥在配置；无 messaging 参与账务	边界清晰

5.2 已知缺口（运维须知）¶

缺口	风险	出处
扣点注释有 FOR UPDATE，实现未加行锁	并发超扣	`consumption_service.py`
`payment_records.transaction_id` 无 DB UNIQUE	极端双回调双插	billing-offline-settlement.md BOS-V3
任务失败未自动调 `refund`	失败任务白扣点	生产路径未接线
提现无 FOR UPDATE	并发超额提现	commission withdraw
配置双轨字段可能未回填	`tier_rank`/`purchase_points`/`daily_login_points` 与 Admin 配置字段不同步时升级/登录领分异常	迁移 `w5` 仅加列默认 0
线下分账整迭代待审核	BOS-01~10	billing-offline-settlement.md
三桶积分未落地	登录/充值/赠送不可分桶对账	Phase B（见设计文档）

健壮性缺口的代码加固需另开任务；本文仅登记与交叉引用，不视为已修复。

六、角色 × API 速查¶

角色	关键能力
C 端	登录注册、方案/报价、下单/同步支付、配额/流水/消费、登录领分、申请代理、提现
代理	注册拿 `TXAG` 码、落地页、客户列表、佣金、客户折扣比例、结算账户资料
Admin	方案/分账规则 CRUD、订单退款、月结关账、提现审核、日终对账、手动开订阅/改配额

详细业务规则见 membership-agent-sales-guide.md；表结构见 data-model/billing.md；分步操作见 billing-agent-flows.md。

七、关键代码锚点¶

环节	路径
注册赠点	`UserAuthService` → `gift_trial_credits`
报价/升级	`membership_pricing.py`、`order_service.py`
支付履约	`payment_service.handle_notify` → `order_service.mark_paid_for_notify`
扣点	`consumption_service.deduct`
分佣/月结/提现	`commission_service.py`、`commission_settlement_service.py`
Admin UI	`src/admin-system/src/features/billing/`
C 端登录	`src/infinitecanvas/src/context/AuthProvider.tsx`
代理门户	`src/agent-system/`