shaguabijia-app-server/docs/database/invite_cash_transaction.md

invite_cash_transaction — 邀请奖励金流水账本(分)

模型 app/models/wallet.py(InviteCashTransaction) · 仓库 app/repositories/wallet.py(grant_invite_cash / 提现路径按 source 分账) · 接口 wallet-account(余额)/ wallet-withdraw(source=invite_cash 提现) · ← 索引 · 总览

邀请奖励金(现金,分)的流水账本,与金币兑换的 cash_transaction 物理隔离、结构同构:balance_after_cents 记的是 coin_account.invite_cash_balance_cents。隔离原因:邀请奖励金有独立的发放口径(好友比价并下单才发,#113)与独立的提现对账(withdraw_order.source='invite_cash',#121),混在现金账本里无法分账校验。#82 新增(2026-06-27)。

用在哪 / 增删改查

• C(插入):每次奖励金变动一笔:

  动作 / endpoint	biz_type	amount_cents	ref_id 指向
  好友比价并下单发奖(POST /order/report → invite.try_reward_on_compare → grant_invite_cash)	invite_reward	+	被邀请人 user.id(字符串)
  发起提现 POST /wallet/withdraw(source=invite_cash)	invite_withdraw	−	withdraw_order.out_bill_no
  该提现失败/审核拒绝退款	invite_withdraw_refund	+	withdraw_order.out_bill_no
  admin 手动调整 POST /admin/api/users/{id}/cash(account=invite_cash,#95)	admin_grant / admin_deduct	+ / −	null(原因记 remark=admin:<reason>)

• U / D:无。账本只追加。

• R:admin 用户 360 / 提现资金账本校验 GET /admin/api/withdraws/ledger-check(按 source 分账对账,#121);C 端邀请页战绩(invite.get_reward_stats:余额 + 累计已提)。

字段

列	类型	约束 / 默认	说明
id	Integer	PK, autoincrement
user_id	Integer	FK→user.id, index, NOT NULL	归属用户(= 邀请人)
amount_cents	Integer	NOT NULL	本笔变动(分);正=入账(发奖/退款),负=出账(提现)
balance_after_cents	Integer	NOT NULL	本笔后奖励金余额(= 当时 coin_account.invite_cash_balance_cents)
biz_type	String(32)	NOT NULL	invite_reward / invite_withdraw / invite_withdraw_refund
ref_id	String(64)	nullable	见上表:发奖=被邀请人 id;提现/退款=withdraw_order.out_bill_no
remark	String(128)	nullable	用户可见备注(如「好友比价奖励」「提现到微信零钱(待审核)」)
created_at	DateTime(tz)	server_default now(), index

关系 / Join Key

• user_id → user.id(多对一,硬 FK)。
• ref_id →(withdraw 类)withdraw_order.out_bill_no(软关联;该单 source='invite_cash')/(invite_reward)被邀请人 user.id。
• 与 invite_relation 的联动:发奖同事务置 invite_relation.compare_reward_granted=true(幂等闸,一个被邀请人只发一次)。

索引与约束

• PK id;index user_id、created_at。

注意

• 唯一变动入口 wallet.grant_invite_cash:更新 coin_account.invite_cash_balance_cents + 写本表,不 commit,调用方同事务提交(与 grant_coins 同款约定)。
• 提现按 source 走不同账本:coin_cash → cash_transaction,invite_cash → 本表;withdraw_order 两种共用一张表靠 source 列区分。