marco
b4780e256e
- 重写 15 张已有表文档:每张补「用在 App 哪/增删改查时机/字段取值/join key 指向」 - 新建 4 张缺失表文档:wechat_transfer_authorization / ad_watch_log / price_report / app_config - 新增 OVERVIEW.md:功能↔表映射 + 写入路径 + 表间关系(含语义 join key)+ ER + 资金模型 - README 索引补齐到 19 表 + 置顶 OVERVIEW + 通用约定补全 - 纠正过时:withdraw_order(reviewing/rejected/user_name)、savings_record(/order/report 真实写入)、coin_transaction(biz_type) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
4.2 KiB
4.2 KiB
withdraw_order — 提现单(现金 → 微信零钱)
模型
app/models/wallet.py· 仓库app/repositories/wallet.py· 接口 wallet-withdraw / wallet-withdraw-status / wallet-withdraw-orders · admin admin-withdraws-list / admin-withdraw-refresh · ← 索引 · 总览
用户把现金余额提到微信零钱的工单。含人工审核(2026-06 起):发起即扣现金、进 reviewing 待审核、不打款;管理员后台审核通过才真正发起微信商家转账,拒绝则退款。
状态机:
发起 ──扣现金+建单──▶ reviewing
reviewing ──admin 审核通过──▶ pending(微信转账在途) ──▶ success / failed(失败自动退款)
reviewing ──admin 审核拒绝──▶ rejected(已退款)
用在哪 / 增删改查
- C(插入):
POST /wallet/withdraw(create_withdraw)→ 校验额度([10 分, 5,000,000 分])+ 必须已绑微信 → 原子扣现金 + 写cash_transaction(withdraw,−)+ 建单status='reviewing',同事务。out_bill_no客户端可传作幂等键(同号重发返回现状,不重复扣款建单)。 - U(更新,改
status/ 微信回执):- admin 审核通过
approve_withdraw→pending→ 调微信转账 →success(到账)/ 失败_settle_after_ambiguous(查单后定夺)。 - admin 审核拒绝
reject_withdraw→ 退款 +rejected。 - 用户/系统查单
refresh_withdraw_status(GET /wallet/withdraw/status)、对账reconcile_pending_withdraws(定时任务扫 >15min 的 pending)→ 按微信侧状态归一化success/failed。 - 落微信回执:
wechat_state/transfer_bill_no/package_info。
- admin 审核通过
- D:无。
- R:
GET /wallet/withdraw/orders(用户提现单列表);admin 提现管理列表/查单。
字段
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|---|---|---|---|
id |
Integer | PK, autoincrement | |
user_id |
Integer | FK→user.id, index, NOT NULL | 归属用户 |
out_bill_no |
String(64) | UNIQUE, index, NOT NULL | 商户单号(幂等键 + 微信查单键)。客户端可传([0-9A-Za-z_-]{8,32}),不传则服务端 uuid4().hex。被 cash_transaction.ref_id 引用 |
amount_cents |
Integer | NOT NULL | 提现金额(分) |
user_name |
String(64) | nullable | 提现实名;微信达额转账要求实名,发起时存下、审核打款时传给微信 |
status |
String(16) | NOT NULL, default reviewing |
归一化状态:reviewing(待审核,已扣款未打款)/ pending(打款在途)/ success / failed(打款失败已退)/ rejected(审核拒绝已退) |
wechat_state |
String(32) | nullable | 微信侧原始状态:WAIT_USER_CONFIRM / SUCCESS / FAIL / CANCELLED / CLOSED … |
transfer_bill_no |
String(64) | nullable | 微信转账单号(转账成功后回填) |
package_info |
String(512) | nullable | 待用户确认时返回 App 拉起微信确认页用(确认模式有,免确认转账无) |
fail_reason |
String(256) | nullable | 失败/拒绝技术原因(不外露,用户只看流水 remark) |
created_at |
DateTime(tz) | server_default now(), index | 发起时间 |
updated_at |
DateTime(tz) | server_default now(), onupdate now() | 更新时间 |
关系 / Join Key
user_id→user.id(多对一)。out_bill_no← 被cash_transaction.ref_id引用(发起withdraw一笔 −,失败/拒绝withdraw_refund一笔 +)。- 打款方式依赖
wechat_transfer_authorization(用户有生效授权 → 免确认转账,否则确认模式)。
索引与约束
- PK
id;UNIQUE+indexout_bill_no;indexuser_id、created_at。
注意
- 资金安全:原子扣款(
WHERE cash_balance_cents >= amount)+out_bill_no幂等 + 结果不明时先查单再决定,绝不盲目退款(防退款后又到账)+ 孤儿 pending 单reconcile_pending_withdraws对账兜底。 WITHDRAW_MIN_CENTS=10(0.1 元,微信商家转账地板价),可经app_config.withdraw_min_cents后台调。- "待审核期间钱已扣减",防用户拿同一笔余额重复发起多笔提现。