会员与代理线下分账 — 待审核技术债
状态：🟡 待产品/运营/研发联合审核（实现已落地，未视为已验收上线）
登记日：2026-07-22
关联计划：线下分账与账务加固（支付仅计提 → 月结入账 → 提现审核线下打款）
设计参考：membership-agent-sales-guide.md、billing-agent-flows.md
本文件记录本迭代已实现但待审核确认的能力，以及明确不做、留待后续的 Phase B 项。审核通过并完成上线清单前，不得从本表删除「待审核」条目。
一、待审核清单（本迭代已实现）
| ID |
项 |
说明 |
审核关注点 |
负责人 |
预计消除 |
| BOS-01 |
佣金状态语义变更 |
pending→accrued/settled/clawed_back；历史 pending 迁移为 settled |
是否与财务口径一致；历史数据是否二次入账风险已消除 |
待定 |
审核后 1 周内确认 |
| BOS-02 |
支付成功仅计提 |
calculate_for_order 写 accrued，不加 balance_commission |
代理侧「待月结」文案与预期是否一致 |
待定 |
同上 |
| BOS-03 |
月结关账入账 |
commission_settlements + close_month；Admin API/页面 + cron 脚本 |
关账节奏（自然月/上海时区）、谁有权关账、是否需双人复核 |
待定 |
同上 |
| BOS-04 |
按条提前入账 |
旧 POST .../commission-records/settle 改为真正入余额 |
是否仍允许运营「手点提前兑付」；权限与审计 |
待定 |
同上 |
| BOS-05 |
退款冲销分 accrual/settled |
accrued 只改状态；settled 扣余额（不足扣至 0） |
与财务冲正规则是否一致 |
待定 |
同上 |
| BOS-06 |
提现路径文案 |
Admin 列表增加「待月结」；代理仪表盘增加「可提现」；口径与文案对齐 |
客户累计分佣是否含 accrued |
部分完成 |
同上 |
| BOS-07 |
日终对账 + 回放 |
recon_batches、BillingReconService、Admin 触发页、脚本 |
告警接入、mismatch 值班流程、用户配额抽样是否过严/过松 |
待定 |
同上 |
| BOS-08 |
Admin 前端最小页 |
「佣金月结」「日终对账」；分账记录状态筛选 |
UI/权限是否满足运营日常 |
待定 |
同上 |
| BOS-09 |
迁移 o7b8c9d0e1f2 |
新表 + 字段 + 历史兼容 |
预发/生产执行窗口与回滚方案 |
待定 |
上线前必须签核 |
| BOS-10 |
自动化测试基线 |
单测 + E2E 服务层套件已绿；无真实 PG/前端 Playwright 签核 |
是否要求补集成测/手工 UAT 签字 |
待定 |
审核时定 |
二、明确不做（Phase B，后续债）
下列项在本迭代范围外，禁止在未开 Phase B 前当缺陷催办本迭代实现者。
| ID |
项 |
说明 |
优先级建议 |
| BOS-B1 |
三桶积分 |
登录/充值/赠送分桶与价目版本 |
高（产品设计已有草案） |
| BOS-B2 |
登录分 24h |
登录积分时效规则 |
中 |
| BOS-B3 |
按消耗充值分提成 |
生图消耗维度提成 |
高 |
| BOS-B4 |
子账号 |
C 端主/子账号（users.master_user_id + /billing/sub-accounts）已落地；代理侧子体系另议 |
低（已接） |
| BOS-B5 |
微信/支付宝分账 API |
通道侧实时分账；本迭代刻意不做，兑付保持线下 |
低（与线下月结互斥或并行需单独立项） |
三、验证缺口（审核前建议补齐）
| ID |
缺口 |
当前状态 |
建议动作 |
| BOS-V1 |
真实 PostgreSQL 冒烟 |
单测用 SQLite；MCP/本地 PG 未跑通 |
预发 alembic upgrade + 购会员→月结→提现手工单 |
| BOS-V2 |
Admin/Agent 前端 E2E |
无 Playwright 覆盖新页 |
至少 1 条月结 + 1 条对账 UI 冒烟 |
| BOS-V3 |
并发双回调 / 双关账压测 |
仅顺序幂等单测 |
预发用唯一约束+行锁做轻量并发抽检 |
| BOS-V4 |
告警接线 |
mismatch 打 CRITICAL 日志，未确认 oncall 是否消费 |
对接现有 Loki/告警规则或登记「暂不接」 |
四、上线签核清单（关闭本债的条件）
- [ ] 产品确认：accrued / 月结 / 提现文案与财务口径
- [ ] 运营确认：月结操作人、周期、提前入账是否保留
- [ ] 研发确认：迁移在预发执行成功，回滚方案书面化
- [ ] 测试确认：§三 缺口中至少 V1 + 手工主路径签字
- [ ] 文档与前端文案无「支付即到可提现」旧表述残留（抽检）
全部勾选后，将本节状态改为 ✅ 已关闭，并在下方「变更记录」注明关闭日期与签核人。
五、代码与入口速查
| 类型 |
路径 |
| 迁移 |
alembic_backend/versions/o7b8c9d0e1f2_offline_commission_settlement.py |
| 计提/提现/冲销 |
src/backend/core/services/commission_service.py |
| 月结 |
src/backend/core/services/commission_settlement_service.py |
| 对账/回放 |
src/backend/core/services/billing_recon_service.py |
| Admin API |
src/backend/api/admin/billing.py（settlements / recon） |
| 脚本 |
src/backend/scripts/commission_month_close.py、daily_billing_recon.py |
| Admin 页 |
CommissionSettlementsPage、BillingReconPage |
| 严格单测 |
tests/unit/backend/services/test_offline_commission_e2e.py 等 |
六、变更记录
| 日期 |
变更 |
| 2026-07-22 |
初登：本迭代实现待审核 + Phase B + 验证缺口 |