计费与代理

源码：src/backend/db/models/billing/ 业务规则：membership-agent-sales-guide.md、membership-tiers.md 返回 总览 字段表格式：字段 | 中文名 | 类型 | 可空 | 作用

ER

erDiagram
  users ||--o| agents : profile
  users ||--o| user_point_wallets : wallet
  users ||--o{ orders : places
  users ||--o{ payment_records : pays
  users ||--o{ consumption_records : spends
  users ||--o{ daily_login_claims : claims
  users ||--o| customer_agent_bindings : bound
  users ||--o| customer_invite_bindings : invited_as
  users ||--o{ customer_invite_bindings : refers
  member_plans ||--o{ orders : priced
  member_plans ||--o{ agent_commission_rules : rules
  agents ||--o{ agents : parent
  agents ||--o{ orders : attributed
  agents ||--o{ commission_records : earns
  agents ||--o{ commission_settlements : monthly
  agents ||--o{ agent_withdrawals : withdraws
  agents ||--o{ agent_link_clicks : clicks
  agents ||--o{ customer_agent_bindings : binds
  orders ||--o{ payment_records : payments
  orders ||--o{ commission_records : commissions
  consumption_records ||--o{ commission_records : consume_commission
  commission_settlements ||--o{ commission_records : batch
  tasks ||--o{ consumption_records : costs

user_point_wallets — 六桶积分钱包

一用户一行；生图余额以本表为准，usage_quotas.generation 为 remaining 镜像。

扣减优先级：注册 → 登录 → 充值 → 充值赠送 → 推广赠送 → 购买积分。
「计佣」指：消耗（扣点）时从该桶扣减的点数是否计入代理/销售的消耗提成基数（= 充值桶扣减 + 购买积分扣减）；不是充值入账时立刻分佣。

字段	中文名	类型	可空	作用
id	钱包 ID	UUID	NO	主键
user_id	用户 ID	UUID	NO	FK→users.id CASCADE；唯一
register_points	注册赠送	Integer	NO	注册桶；默认 0
register_expire_at	注册桶过期	timestamptz	YES	注册积分过期时刻
login_points	登录赠送	Integer	NO	登录桶；默认 0
login_expire_at	登录桶过期	timestamptz	YES	上海当日结束
purchase_points	充值积分	Integer	NO	会员/加量实付对应桶；默认 0；消耗时计入提成基数
bonus_points	充值赠送	Integer	NO	赠送桶；默认 0
referral_points	推广赠送	Integer	NO	邀请首充奖励桶；默认 0
pack_points	购买积分	Integer	NO	积分套餐入账；默认 0；消耗时计入提成基数
created_at	创建时间	timestamptz	NO
updated_at	更新时间	timestamptz	NO

member_plans — 会员方案

字段	中文名	类型	可空	作用
id	方案 ID	UUID	NO	主键
name	方案名称	String(50)	NO	前台/后台展示用方案名
plan_key	方案键	String(30)	NO	业务唯一标识，唯一
plan_type	方案类型	String(20)	NO	subscription 订阅 / extra_pack 加量包 / point_pack 积分套餐
billing_cycle	计费周期	String(10)	NO	monthly / quarterly / yearly / once
original_price	原价	Numeric(10,2)	NO	划线价；默认 0
selling_price	售价	Numeric(10,2)	NO	实际成交价；默认 0
monthly_quota	月度配额	Integer	NO	兼容现网扣点，与 purchase/first_purchase 点数桥接；默认 0
tier_rank	档位排序	Integer	NO	1 体验 … 7 至尊；升级只能升到更大 rank；默认 0
purchase_points	购买积分	Integer	NO	购买/升级时入账的首充积分（已含赠送）；默认 0
daily_login_points	每日登录积分	Integer	NO	每日登录赠送积分（仅当前生效档、主账号）；默认 0
bonus_percent	赠送比例	Integer	NO	展示用赠送百分比，如 85 表示 85%；默认 0
feature_flags	功能标志	String(500)	YES	JSON 字符串：种草/剧情/精品月额度/客服等级等扩展权益
max_resolution	最高分辨率	String(10)	YES	允许最高出图分辨率：1K / 2K / 4K
concurrent_tasks	并发任务数	Integer	NO	同时进行中的生图任务上限；默认 1
description	方案描述	String(500)	YES	方案说明文案
sort_order	排序权重	Integer	NO	列表展示排序；默认 0
status	在售状态	SmallInteger	NO	0=停售 1=在售；默认 1
cycle_days	周期天数	Integer	NO	登录积分等展示用（月30/季90/年365）；订阅到期见 billing_cycle 自然历
bonus_rate	赠送费率	Numeric(5,4)	NO	精确赠送比率（与 bonus_percent 配套）；默认 0
login_points_per_day	日登录点数	Integer	NO	按日计算的登录赠送点数；默认 0
feature_image	生图权益	Boolean	NO	是否开通普通生图能力；默认 true
feature_seed	种草权益	Boolean	NO	是否开通种草功能；默认 false
feature_story	剧情权益	Boolean	NO	是否开通剧情功能；默认 false
premium_quota_monthly	精品月额度	Integer	NO	精品能力每月额度；默认 0
cs_level	客服等级	String(20)	NO	normal / h24 / dedicated；默认 normal
sub_accounts	子账号数	Integer	NO	允许创建的子账号数量；默认 0
storage_gb	存储容量	Integer	NO	云存储配额（GB）；默认 5
priority_generate	优先生成	Boolean	NO	是否享受优先排队出图；默认 false
yuan_per_image	单图单价	Numeric(6,2)	NO	单张图折算人民币参考价；默认 0
first_purchase_points	首购积分	Integer	NO	首购入账积分（积分三字段之一）；默认 0
cycle_login_points	周期登录积分	Integer	NO	周期内登录赠送合计（= login_points_per_day × cycle_days）；默认 0
cycle_total_points	周期总积分	Integer	NO	周期内可获得积分总量；默认 0
created_at	创建时间	timestamptz	NO	行创建时间
updated_at	更新时间	timestamptz	NO	行最后修改时间
deleted_at	删除时间	timestamptz	YES	软删标记；非空表示已删除

agents — 代理商

字段	中文名	类型	可空	作用
id	代理 ID	UUID	NO	主键
user_id	关联用户 ID	UUID	NO	FK→users.id CASCADE；唯一（一用户一代理档案）
agent_code	代理编码	String(20)	NO	推广用唯一编码，唯一（与用户 invite_code 不同）
agent_name	代理名称	String(100)	NO	代理商展示名称
role	角色	String(20)	NO	默认 agent；agent=普通代理 / sales=内部销售
agent_level	代理等级	SmallInteger	NO	1=一级 2=二级；销售通常固定为 1；默认 1
parent_agent_id	上级代理 ID	UUID	YES	FK→agents.id SET NULL；二级挂在一级下
total_commission	累计佣金	Numeric(12,2)	NO	历史累计分账总额；默认 0
withdrawn_commission	已提现佣金	Numeric(12,2)	NO	已成功提现累计；默认 0
balance_commission	可提现余额	Numeric(12,2)	NO	月结入账后可提现余额；默认 0
settlement_channel	结算渠道	String(20)	YES	提现收款渠道：alipay / wechat
settlement_account	结算账号	String(100)	YES	收款账号（支付宝/微信账号）
settlement_account_name	结算户名	String(100)	YES	收款账户实名
customer_discount_rate	客户折扣率	Numeric(5,2)	NO	历史字段；现网下单不再套用该折扣改价；默认 0
sub_agent_share_rate	二级直客分成	Numeric(5,2)	NO	二级直客消耗提成比例（百分比，0～12）；未配时代码默认按 8%；默认 0
status	代理状态	SmallInteger	NO	0=停用 1=正常；默认 1
created_at	创建时间	timestamptz	NO	行创建时间
updated_at	更新时间	timestamptz	NO	行最后修改时间

customer_agent_bindings — 一客一代理

字段	中文名	类型	可空	作用
id	绑定 ID	UUID	NO	主键
customer_id	客户用户 ID	UUID	NO	FK→users.id CASCADE；唯一（一客户永久绑定一代理）
agent_id	代理 ID	UUID	NO	FK→agents.id CASCADE；绑定的代理商
referral_code	邀请码	String(20)	NO	绑定时使用的推广码（通常等于 agent_code）
source_url	来源 URL	String(500)	YES	落地页/来源链接，便于归因分析
bound_at	绑定时间	timestamptz	NO	首次永久绑定时刻

customer_invite_bindings — 人人邀请归属

与「一客一代理」并列：一客一分享者用户，用于首充双边推广积分（不计佣）。

字段	中文名	类型	可空	作用
id	绑定 ID	UUID	NO	主键
customer_id	被邀请用户	UUID	NO	FK→users.id CASCADE；唯一
referrer_user_id	分享者用户	UUID	NO	FK→users.id CASCADE；有索引
referral_code	邀请码	String(20)	NO	绑定时的 users.invite_code
source_url	来源 URL	String(500)	YES	落地页
bound_at	绑定时间	timestamptz	NO	首次永久绑定

agent_withdrawals — 提现申请

字段	中文名	类型	可空	作用
id	提现 ID	UUID	NO	主键
agent_id	代理 ID	UUID	NO	FK→agents.id CASCADE；申请提现的代理
amount	提现金额	Numeric(12,2)	NO	本次申请金额（预占余额）
status	审核状态	String(20)	NO	默认 pending；pending / approved / rejected
remark	备注	String(500)	YES	申请说明或审核意见
reviewed_by	审核人 ID	UUID	YES	审核管理员标识；无 FK
reviewed_at	审核时间	timestamptz	YES	审核完成时刻
created_at	创建时间	timestamptz	NO	申请创建时间
updated_at	更新时间	timestamptz	NO	行最后修改时间

agent_link_clicks — 推广点击

字段	中文名	类型	可空	作用
id	点击 ID	UUID	NO	主键
agent_id	代理 ID	UUID	NO	FK→agents.id CASCADE；被点击的推广归属代理
referral_code	邀请码	String(20)	NO	落地页携带的推广码
ip_hash	IP 哈希	String(64)	YES	访客 IP 哈希（脱敏统计，非明文）
user_agent	UA 信息	String(300)	YES	浏览器 User-Agent，用于渠道分析
created_at	创建时间	timestamptz	NO	点击发生时间

agent_commission_rules — 分账规则

字段	中文名	类型	可空	作用
id	规则 ID	UUID	NO	主键
agent_level	适用代理等级	SmallInteger	NO	规则适用的代理等级（如 1/2）
plan_id	会员方案 ID	UUID	YES	FK→member_plans.id；空表示通用规则，非空按方案覆盖
commission_rate	分账比例	Numeric(5,4)	NO	按比例分账时的费率；默认 0
commission_type	分账类型	String(20)	NO	默认 rate；rate 比例 / fixed 固定金额
commission_value	分账数值	Numeric(10,2)	NO	固定金额或辅助计算值；默认 0
status	规则状态	SmallInteger	NO	0=停用 1=启用；默认 1
created_at	创建时间	timestamptz	NO	行创建时间
updated_at	更新时间	timestamptz	NO	行最后修改时间
deleted_at	删除时间	timestamptz	YES	软删标记；非空表示已删除

commission_settlements — 佣金月结批次

关账后才入可提现余额。

字段	中文名	类型	可空	作用
id	月结批次 ID	UUID	NO	主键
settle_month	结算月份	String(7)	NO	结算归属月，如 2026-08
agent_id	代理 ID	UUID	NO	FK→agents.id CASCADE；本批次归属代理
agent_level	代理等级快照	SmallInteger	NO	关账时代理等级快照
total_amount	结算总额	Numeric(12,2)	NO	本批次分账合计；默认 0
record_count	明细笔数	Integer	NO	本批次包含的分账明细条数；默认 0
status	批次状态	String(20)	NO	默认 closed；open 开放中 / closed 已关账
idempotency_key	幂等键	String(128)	NO	防重复关账，唯一
closed_at	关账时间	timestamptz	YES	批次关账完成时刻
closed_by	关账操作人	UUID	YES	执行关账的操作者标识；无 FK
created_at	创建时间	timestamptz	NO	批次创建时间
updated_at	更新时间	timestamptz	NO	行最后修改时间

commission_records — 分账明细

字段	中文名	类型	可空	作用
id	分账记录 ID	UUID	NO	主键
agent_id	代理 ID	UUID	NO	FK→agents.id CASCADE；分账受益方
order_id	订单 ID	UUID	YES	FK→orders.id；首两单提成绑订单；消耗提成可空
consumption_id	消费记录 ID	UUID	YES	FK→consumption_records.id SET NULL；消耗提成绑定
order_amount	计佣金额基数	Numeric(10,2)	NO	订单实付或消耗折合人民币快照
purchase_points_consumed	计佣积分数	Integer	NO	计入提成的实付积分（充值+购买）；默认 0
commission_kind	提成种类	String(30)	NO	默认 consume；consume / first_two_orders
beneficiary_level	受益层级标签	String(20)	YES	sales / agentA / agentB 等
commission_amount	分账金额	Numeric(10,2)	NO	本笔实际分给代理的金额
commission_rate	分账比例	Numeric(5,4)	NO	本笔费率快照
status	分账状态	String(20)	NO	默认 accrued；accrued / settled / clawed_back
settle_month	结算月份	String(7)	YES	上海时区 YYYY-MM
settlement_id	月结批次 ID	UUID	YES	FK→commission_settlements.id SET NULL
idempotency_key	幂等键	String(128)	NO	防重复计提，唯一
settled_at	结算时间	timestamptz	YES	月结入余额时刻
created_at	创建时间	timestamptz	NO
updated_at	更新时间	timestamptz	NO

orders — 订单

字段	中文名	类型	可空	作用
id	订单 ID	UUID	NO	主键
order_no	订单号	String(32)	NO	对外订单编号，唯一
user_id	下单用户 ID	UUID	NO	FK→users.id CASCADE；下单用户
plan_id	目标方案 ID	UUID	NO	FK→member_plans.id；购买/升级目标会员方案
agent_id	归因代理 ID	UUID	YES	FK→agents.id SET NULL；订单归因代理商
amount	订单金额	Numeric(10,2)	NO	应付金额（可含代理折扣后价格）
order_kind	订单类型	String(20)	NO	默认 purchase；purchase 新购 / upgrade 升级
from_plan_id	原方案 ID	UUID	YES	FK→member_plans.id SET NULL；升级前原方案
points_granted	已授积分	Integer	NO	支付成功入账总积分（写入六桶钱包；usage_quotas.generation 同步镜像）；默认 0
status	订单状态	String(20)	NO	默认 pending；pending / paid / completed / cancelled / refunded
remark	备注	String(500)	YES	订单备注或运营说明
paid_at	支付时间	timestamptz	YES	支付成功时刻
created_at	创建时间	timestamptz	NO	下单时间
updated_at	更新时间	timestamptz	NO	行最后修改时间

payment_records — 支付流水

字段	中文名	类型	可空	作用
id	支付流水 ID	UUID	NO	主键
order_id	订单 ID	UUID	NO	FK→orders.id CASCADE；关联订单
user_id	支付用户 ID	UUID	NO	FK→users.id CASCADE；付款用户
amount	支付金额	Numeric(10,2)	NO	本次支付金额
payment_method	支付方式	String(20)	NO	wechat / alipay
transaction_id	第三方交易号	String(100)	YES	微信/支付宝侧交易流水号
status	支付状态	String(20)	NO	默认 pending；pending / success / failed / refunded
paid_at	支付成功时间	timestamptz	YES	渠道确认支付成功时刻
created_at	创建时间	timestamptz	NO	流水创建时间
updated_at	更新时间	timestamptz	NO	行最后修改时间

consumption_records — 任务扣点

字段	中文名	类型	可空	作用
id	扣点记录 ID	UUID	NO	主键
user_id	操作用户 ID	UUID	NO	FK→users.id CASCADE；可为子账号；计费主账号见流水
task_id	任务 ID	UUID	NO	FK→tasks.id CASCADE
task_type	任务类型	String(30)	NO	如 virtual_studio / main_image
credits_cost	消耗点数	Integer	NO	本次总扣点；应等于下列六桶合计
model_type	模型类型	String(30)	YES	AI 模型类型
resolution	分辨率	String(10)	YES	出图分辨率
quota_remaining	扣后剩余	Integer	NO	扣减后剩余点数快照（镜像）
register_used	注册桶扣减	Integer	NO	默认 0
login_used	登录桶扣减	Integer	NO	默认 0
purchase_used	充值桶扣减	Integer	NO	默认 0；计入消耗提成基数
bonus_used	赠送桶扣减	Integer	NO	默认 0
referral_used	推广桶扣减	Integer	NO	默认 0
pack_used	购买积分扣减	Integer	NO	默认 0；计入消耗提成基数
duration_seconds	时长秒	Integer	YES	视频等按时长计费
created_at	创建时间	timestamptz	NO

transaction_ledger — 统一账户流水

多态：无 FK，用 owner_type + owner_id。

字段	中文名	类型	可空	作用
id	流水 ID	UUID	NO	主键
owner_type	账户主体类型	String(20)	NO	user / agent
owner_id	账户主体 ID	UUID	NO	主体 UUID；无 FK
ledger_type	流水类型	String(30)	NO	recharge / consumption / refund / quota_gift / quota_reset / quota_adjust / points_expire / referral_bonus / commission / commission_accrual / withdraw 等
amount	变动金额	Numeric(12,2)	NO	本笔变动量
balance_after	变动后余额	Numeric(12,2)	NO	快照；默认 0
reference_type	关联对象类型	String(30)	YES	如 orders / consumption_records / commission_records
reference_id	关联对象 ID	UUID	YES	无 FK
description	流水说明	String(200)	YES	中文摘要
created_at	创建时间	timestamptz	NO

daily_login_claims — 每日登录积分

业务上每用户每天一条（幂等）；ORM 未声明 UniqueConstraint，以业务层保证。

字段	中文名	类型	可空	作用
id	领取记录 ID	UUID	NO	主键
user_id	用户 ID	UUID	NO	FK→users.id CASCADE；领取人（主账号）
claim_date	领取日期	Date	NO	业务日（Asia/Shanghai）；同用户同日仅一条
points	领取积分	Integer	NO	当日实际发放积分数
plan_id	会员方案 ID	UUID	YES	FK→member_plans.id SET NULL；领取时生效档位快照
created_at	创建时间	timestamptz	NO	领取时刻

recon_batches — 日终对账

字段	中文名	类型	可空	作用
id	对账批次 ID	UUID	NO	主键
biz_date	业务日期	String(10)	NO	对账业务日（上海时区日界，如 2026-08-11）
recon_type	对账类型	String(30)	NO	如 payment / commission / agent_balance / user_quota
status	对账状态	String(20)	NO	默认 running；running / matched / mismatch / resolved
expected_json	期望侧数据	JSONB	YES	期望汇总（如订单金额、抽样数）
actual_json	实际侧数据	JSONB	YES	实际汇总（如支付金额、不一致数）
diff_json	差异明细	JSONB	YES	不一致明细或 delta；匹配时可为 null
summary	摘要说明	String(500)	YES	人读结论一句话
created_at	创建时间	timestamptz	NO	对账任务落库时间
resolved_at	解决时间	timestamptz	YES	mismatch 人工处理完成时刻
resolved_by	解决人 ID	UUID	YES	处理人标识；无 FK