四桶积分 · 消耗扣费 · 分账提成 — 操作步骤与数据流转¶
定位：现网实现（2026-08 四桶改造后）的功能说明。覆盖操作步骤、表写入、数据流转。
运营/测试人话说明书（六桶与菜单联动）：
membership-agent-sales-guide.md。 产品规则：docs/archive/家纺AI生图平台·积分与会员系统规则文档.mdv1.2。 验收口径：图片 1K=18 / 2K=36 / 4K=72（忽略规则文档第一节曾写的 1K=12）；视频 768P=8 积分/秒、2K=12 积分/秒。旧文档：
membership-billing-e2e.md与billing-agent-flows.md仍描述「单一配额 + 订单实付分佣」，仅作历史对照。
0. 一句话¶
用户付钱买积分，生图/视频按四桶优先级扣点；只有「充值积分」被消耗时才给代理计提成；用户前两笔已付订单另记一笔 实付 25% 首两单提成。月结后代理才能提现。微信支付通道不做实时分账。
flowchart LR
pay[支付成功] --> split[拆桶入账]
split --> wallet[四桶钱包]
wallet --> consume[生图/视频消耗]
consume --> ledger[消耗流水拆桶]
ledger --> comm[purchase_used 计提成]
pay --> first2[前两单 25%]
first2 --> month[次月月结]
comm --> month
month --> withdraw[代理提现]
1. 角色与入口¶
| 角色 | 前端 | 典型入口 | 做什么 |
|---|---|---|---|
| C 端会员 | infinitecanvas |
画布 / 账户 | 注册领赠送、领登录分、购会员、生图扣点 |
| 代理商 | agent-system |
仪表盘 / 客户 / 分账 / 设置 | 看已计提 vs 待产生、客户四桶、申请提现 |
| 管理员 | admin-system |
计费：方案 / 消费 / 分账规则 / 分账记录 / 收入 / 对账 | 配方案、查拆桶、月结、退款、对账 |
| 运维 | — | Alembic / Admin 对账页 | 跑迁移、日终对账、关账 |
子账号共用主账号积分池；登录积分只发给主账号。
2. 核心对象（改造后）¶
| 表 / 字段 | 职责 |
|---|---|
user_point_wallets |
四桶余额：register_points(+expire_at)、login_points(+expire_at)、purchase_points、bonus_points |
usage_quotas.generation |
镜像：remaining = total - used，应等于四桶合计（过期清零后） |
consumption_records |
扣点凭证：credits_cost + 四列 used + duration_seconds |
transaction_ledger |
追加式流水：quota_gift / recharge / consumption / refund / points_expire / quota_reset |
orders + payment_records |
人民币订单与支付成功凭证 |
commission_records |
commission_kind=first_two_orders 绑 order_id；consume 绑 consumption_id |
customer_agent_bindings |
客户永久绑定代理（消耗提成归因） |
member_plans |
售价、赠送%、登录分/天、权益开关、storage_gb（体验档 1GB） |
消耗优先级（跨桶可拆一笔）：
注册赠送（7 天） → 登录（24h） → 充值（计佣） → 充值赠送
| 桶 | 来源 | 过期 | 计入提成 |
|---|---|---|---|
| 注册赠送 | 一生一次 18 分 | 7 天 | 否 |
| 登录 | 每日领取 | 到账 24h | 否 |
| 充值 | 实付 × 10（不超过本单入账积分） | 终生 | 是 |
| 充值赠送 | 本单入账 − 充值桶 | 终生 | 否 |
3. 价目与权益门禁¶
| 项目 | 积分 | 说明 |
|---|---|---|
| 图片 1K | 18 | 质量档不可选，固定 medium |
| 图片 2K | 36 | 清晰度仍受会员 max_resolution 限制 |
| 图片 4K | 72 | 清晰度仍受会员 max_resolution 限制 |
| 视频 768P / 1K | 8 × 秒 | 缺时长时按 5 秒计价 |
| 视频 2K（含按高清处理的 4K 视频） | 12 × 秒 | grass_video / drama_video |
失败不收费：统一预扣；任务/镜头失败调用 ConsumptionService.refund / refund_one_for_task 按四桶退回（同一消费单只退一次）。视频 C 端试跑同样预扣，failed/cancelled 退点。
到期 / 无有效订阅：只能用图片类任务；种草视频、剧情视频、无限画布（canvas_image / infinite_edit）拒绝。体验档本身也不能用无限画布。充值/赠送积分不清零。
4. 数据流转（按业务事件）¶
4.1 首次登录注册 → 赠送 18 分¶
操作：C 端短信登录；用户不存在则自动注册。
sequenceDiagram
participant U as 用户
participant API as Auth
participant W as user_point_wallets
participant Q as usage_quotas
participant L as transaction_ledger
U->>API: 验证码登录
API->>L: 若已有 quota_gift 则跳过
API->>W: register_points += 18，expire_at = now+7d
API->>Q: total += 18
API->>L: quota_gift +18
| 写入 | 内容 |
|---|---|
user_point_wallets |
register_points=18，register_expire_at |
usage_quotas |
total += 18 |
transaction_ledger |
ledger_type=quota_gift，幂等一生一次 |
4.2 每日领取登录积分¶
操作：主账号在会员有效期内点「领取今日登录积分」。当日已领、无有效会员、积分为 0、子账号：拒绝。
| 写入 | 内容 |
|---|---|
daily_login_claims |
每用户每天一行 |
user_point_wallets |
先清过期登录桶，再 login_points += n，login_expire_at = now+24h |
usage_quotas |
total += n |
transaction_ledger |
recharge（描述为每日登录赠送） |
过期：下次读余额 / 扣点前把到期登录/注册桶清零，写 points_expire（负数），并减少 usage_quotas.total。当日不领不补发。
4.3 支付成功 → 拆桶入账 + 首两单提成¶
操作：C 端选方案下单 → 微信/支付宝支付 → 回调 mark_paid_for_notify。
本单入账积分 credits = points_granted（旧单缺省则用方案 purchase_points / monthly_quota）
充值桶 purchase = min(credits, 实付×10)
赠送桶 bonus = credits - purchase
例：基础档 ¥588、赠送 10% → 入账 6468；充值 5880，赠送 588。
flowchart TD
cb[支付回调] --> paid[orders.status=paid]
paid --> sub[开通/升级订阅]
paid --> split[拆桶入钱包]
split --> q[配额 total 累加]
split --> led[ledger recharge]
paid --> cnt{该用户已付单数 ≤ 2?}
cnt -->|是且有 agent_id| f2[commission_kind=first_two_orders<br/>金额=实付×25%]
cnt -->|否| skip[不写订单提成]
paid --> done[orders.status=completed]
| 写入 | 内容 |
|---|---|
payment_records |
成功支付 |
subscriptions |
旧档 status=0，新建生效档 |
user_point_wallets |
purchase_points / bonus_points 增加 |
usage_quotas |
total 增加（不重置 used，积分累加） |
transaction_ledger |
recharge +credits |
commission_records |
仅第 1、2 笔已付单：first_two_orders，幂等键 comm:first2:{order_id}:{agent_id} |
不在此时按整单实付写 12%/8% 消耗提成。
4.4 生图 / 视频消耗¶
操作：C 端提交任务（或画布生图）。预检余额不足 → 402。
flowchart TD
req[创建任务] --> feat{权益门禁}
feat -->|种草/剧情/画布且无资格| 403[Forbidden]
feat --> res{清晰度 ≤ 方案上限?}
res -->|否| 403
res --> cost[计算积分]
cost --> lock[过期清零 + 四桶扣减]
lock -->|不足| 402
lock --> rec[consumption_records 拆桶]
rec --> led[ledger consumption 负数]
rec --> pu{purchase_used > 0?}
pu -->|是且已绑定代理| acc[消耗提成]
pu -->|否| end1[不计佣]
消耗提成：
计佣金额（元）= purchase_used ÷ 10
代理 A 直客：× 12%（或 Admin 规则覆盖）
代理 B 直客：× 8%
代理 A 拿 B 的客户：× 4%（固定，不走让渡比例）
幂等键：comm:consume:{consumption_id}:{agent_id}
无 customer_agent_bindings → 不计提。内部销售「消耗 3% + 底薪发薪」未实现（无销售实体）。
| 写入 | 内容 |
|---|---|
user_point_wallets |
按优先级减少四桶 |
usage_quotas |
used += credits |
consumption_records |
四列 used、分辨率、视频秒数 |
transaction_ledger |
consumption 负数 |
commission_records |
仅 purchase_used>0 时 kind=consume |
4.5 任务失败退点¶
操作：系统在失败路径调 refund(consumption_id)（运营无需点按钮）。
- 按该行四列 used 退回对应桶；历史单若四列为 0，整笔退回充值桶
- 写
ledger_type=refund（正数）；同一consumption_id不重复退 - 不自动冲销已产生的消耗提成（退的是用户积分；消耗提成以当时
purchase_used为准）
4.6 订单退款¶
操作：Admin「订单」→ 退款（若开了通道则先打通道退款）。
| 步骤 | 行为 |
|---|---|
| 1 | 只扣尚未消耗的充值桶：min(钱包 purchase_points, 实付×10×退款比例) |
| 2 | 不动赠送桶 |
| 3 | 写用户 refund 流水（负数回滚积分） |
| 4 | clawback_for_order：冲该订单上的 首两单提成（accrued 只改状态；settled 扣可提现） |
| 5 | 停用该单开通的订阅；orders.status=refunded |
消耗提成记录 order_id 为空，不会随订单退款自动冲销。
4.7 月结与提现¶
操作：Admin 分账记录页「月结关账」（settle_month=YYYY-MM）。
- 当月
accrued（含首两单 + 消耗提成）→settled，增加agents.balance_commission - 关账幂等
- 代理在仪表盘申请提现：预占余额 → Admin 审核 → 线下打款（通道不实时分账）
4.8 日终对账¶
操作：Admin「日终对账」选业务日执行。
校验口径：用户配额剩余 ≈ SUM(user ledger)（含 points_expire）；代理可提现 ≈ 已月结流水；支付金额 vs 订单；当日分账合计。
5. 操作步骤（按角色）¶
5.1 运维上线（一次）¶
- 部署含本次改造的 backend / admin / agent 镜像。
- 执行 Alembic：
jj0e1f2a3b4c_point_wallets_and_consume_commission（建user_point_wallets、消耗拆桶列、提成consumption_id；历史配额剩余回填到充值桶；体验档storage_gb=1）。 - Admin 打开「会员方案」，确认体验档储存 1GB，价目预览：充值积分 = 售价×10，赠送 = 首充 − 充值。
- Admin「分账规则」：默认可按 A=12%、B=8% 配直客费率；下级 4% 为代码常量，不必配让渡。
- 跑一次「日终对账」，抽查几个有余额用户：四桶合计 = 配额 remaining。
5.2 C 端会员（完整操作步骤）¶
入口：画布站点（本地 canvas.localhost:5173 / ACK canvas.tuxianai.com）。账号中心路径：/account。
A. 注册 / 登录（拿试用积分）¶
- 打开画布站点，点登录。
- 输入手机号 → 获取短信验证码 → 提交。
- 首次登录：系统自动建号，到账 注册赠送 18 积分（约可出 1 张 1K 图）。
- 这 18 分 7 天内优先扣光；到期未用自动清零，不补发。
- 再次登录：不重复赠送。
若从代理落地页
/r/推广码进入再登录，会永久绑定该代理（之后充值积分消耗才计代理提成；用户侧无感知）。
B. 查看积分与领取每日登录分¶
- 顶栏进入 账号中心（
/account，默认「概览」）。 - 查看剩余积分（四桶合计；过期桶会自动清掉）。
- 有有效会员时：点 「领取今日积分」。
- 规则：
- 每天只能领一次；当天不领视为放弃，不累计。
- 到账后 24 小时内未用清零。
- 子账号不能领；会员到期后不能领。
- 相关 Tab：
- 消费记录：每次生图/视频扣了多少、扣的是哪一类积分。
- 充值记录：支付到账、赠送、过期清零等流水。
C. 购买 / 升级会员（充值拿积分）¶
- 账号中心 → 「充值升级」，或顶栏「充值」、生图时余额不足弹出的充值窗。
- 选择档位（体验 / 基础 / … / 至尊）或加量包；已有档位时一般只能升到更高档。
- 选支付方式（微信 / 支付宝）→ 下单。
- 到 「我的订单」：待支付订单点「立即支付」，扫码完成。
- 支付成功后：
- 会员档位立刻生效（权益、并发、储存等）。
- 积分拆成两桶：充值积分（实付×10）+ 充值赠送积分（档位赠送部分）；累加不清零旧余额。
- 可在「充值记录」核对到账；概览里看最新剩余。
示例（基础档 ¥588、赠送 10%）：一共到账 6468 分 ≈ 充值 5880 + 赠送 588。
D. 生图（扣积分）¶
- 进入 AI 工作区 / 对应生图功能。
- 只选清晰度 1K 或 2K（质量档固定，不可选 low/high）。
- 提交前系统预检余额：
- 1K = 18 积分，2K = 36 积分，4K = 72 积分。
- 不足会提示并引导充值，不会出图。
- 扣费顺序（自动，用户不用选）：注册赠送 → 登录积分 → 充值积分 → 充值赠送。
- 生成失败不扣费（若已预扣会退回）；成功才稳定扣点。
- 会员清晰度上限不够时（例如仅允许 1K），选 2K 会被拒绝。
E. 视频（扣积分）¶
- 进入种草 / 剧情等视频能力（需会员档开通对应功能）。
- 按分辨率与时长计费：768P = 8 积分/秒，2K = 12 积分/秒。
- 视频失败：不收费。
- 无资格或会员到期：种草 / 剧情 / 精品 / 无限画布不可用；普通图片仍可用剩余积分。
F. 子账号（专业档及以上）¶
- 账号中心 → 「子账号」 创建/管理。
- 子账号与主账号共用积分池，不能单独充值、不能领登录分。
- 子账号生图扣的仍是主账号四桶积分。
G. 会员到期后用户还能做什么¶
| 能做 | 不能做 |
|---|---|
| 用剩余充值 / 赠送积分继续打图片 | 领每日登录积分 |
| 续费 / 升级恢复档位权益 | 种草视频、剧情视频、精品视频、无限画布 |
| — | 体验档权益以外的并发/储存/优先生成等 |
积分不会因到期清零；只有注册赠送（7 天）、登录积分（24h）会过期。
H. 推荐每日/常用路径（最短）¶
登录 → 账号中心领今日积分（有会员时）
→ 不够则「充值升级」支付
→ 去工作区选 1K/2K 生图
→ 账号中心「消费记录」核对扣点
5.3 管理员¶
| 页面 | 操作 |
|---|---|
| 会员方案 | 改售价/赠送%/登录分/权益；保存前看「充值积分 vs 赠送积分」预览 |
| 消费记录 | 输手机号查询；看四桶扣减、是否计佣（purchase_used>0）、视频秒数 |
| 分账规则 | 覆盖直客消耗费率；不要再按「整单实付」理解默认计提 |
| 分账记录 | 类型=首两单 / 消耗计提；可按条提前入账或月结关账 |
| 收入看板 | 「计佣充值积分消耗金额」vs「不计佣积分」 |
| 日终对账 | 选日执行，展开 mismatch |
| 订单 | 退款：只回滚未消耗充值积分 + 冲首两单提成 |
5.4 代理商¶
| 页面 | 看什么 |
|---|---|
| 仪表盘 | 待月结 = 已按消耗/首两单计提未关账；待产生 = 名下客户未消耗充值积分 × 直客费率估算 |
| 客户列表/详情 | 累计消费（点）、计佣充值积分、四桶余额；只有充值桶消耗才进自己的提成 |
| 分账记录 | 消耗发生后才出现 consume 行；含计佣积分、费率、类型 |
| 设置 | 「平台消耗提成规则」只读（12%/8%/4%）；客户折扣仍可用于获客，与提成独立 |
| 提现 | 月结入可提现后才能申请 |
推广：分享落地页 → 客户绑定 customer_agent_bindings → 之后该客户消耗充值积分才记到本代理。
6. 公式速查¶
1 元 = 10 积分
首充到账 = round(售价 × 10 × (1 + 赠送%))
充值桶 = min(首充到账, 实付 × 10)
赠送桶 = 首充到账 − 充值桶
图片 1K = 18 图片 2K = 36 图片 4K = 72
视频 768P = 8×秒 视频 2K = 12×秒
消耗提成（元）= purchase_used ÷ 10 × 费率
首两单提成（元）= 该笔订单实付 × 25%
示例：绑定代理 A 的客户充值 ¥100（第 1 单）→ 充值桶 1000 分；同时记首两单 ¥25。之后该客户用掉 500 充值积分 → 再记消耗提成 500÷10×12% = ¥6。注册/登录/赠送桶扣掉的部分不产生这 ¥6。
7. 关键代码入口¶
| 能力 | 路径 |
|---|---|
| 四桶扣减 / 过期 | src/backend/core/services/point_wallet_service.py |
| 价目 | src/backend/core/services/point_pricing.py |
| 扣点 / 退点 / 赠送 | src/backend/core/services/consumption_service.py |
| 权益门禁 | src/backend/core/services/membership_entitlements.py |
| 支付拆桶 / 退款 | src/backend/core/services/order_service.py |
| 登录 24h | src/backend/core/services/login_points_service.py |
| 首两单 + 消耗计提 | src/backend/core/services/commission_accrual.py |
| 月结 / 提现 | src/backend/core/services/commission_service.py |
| 迁移 | alembic_backend/versions/jj0e1f2a3b4c_point_wallets_and_consume_commission.py |
8. 明确未做¶
| 项 | 说明 |
|---|---|
| 微信/支付宝通道实时分账 | 仍为线下月结 |
| 内部销售 3% 消耗提成 + ¥3000 发薪 | 无销售实体；首两单 25% 记在绑定代理上 |
| 无限画布单独单价 | 到期禁用，无独立价目 |
| 退款冲已产生的消耗提成 | 退款只动未消耗充值桶 + 冲该订单首两单提成 |
9. 验收清单（抽测）¶
- [ ] 新用户配额 remaining=18，且在
register_points；7 天后清零并有points_expire - [ ] 1K 扣 18、2K 扣 36、4K 扣 72；视频 10 秒 768P 扣 80
- [ ] 先扣注册再扣充值：一笔流水四列拆开
- [ ] 仅
purchase_used>0出现消耗提成；纯赠送/登录消耗无提成 - [ ] 用户第 1、2 笔已付单各有一笔 25% 首两单；第 3 笔支付不再写首两单
- [ ] 二级客户消耗：B 得 8%、上级 A 得 4%
- [ ] 退款后充值桶减少、赠送桶不变
- [ ] 月结后代理可提现余额增加；重复关账不双加