袋鼠金融蓝图

PocketBuy 佣金系统外围配合改造功能点

1. 目标与责任边界

本文件定义佣金系统上线所需的外围系统改造、数据契约和验收责任。外围系统提供可证明的业务事实；佣金系统负责规则执行、受益人归属快照、台账、绩效调整和结算；H5/SA App 仅展示和提交资料。

领域权威系统佣金系统消费内容不允许发生的事
订单与交机BNS/订单域合格资格事件、订单版本、商品、合同金额、撤销事件佣金系统自行推测订单完成
还款与风险还款/风控域订单级本金、利息、风险扣减、指标快照及冻结状态H5/佣金系统用订单数代替金额或自行算指标
组织与人员组织/运营域SA-SM-RM 历史关系、已审核生效的门店-店长-店员关系、有效期及关系版本用当前组织关系或仅提交/仅审核状态改写历史受益人
推荐与二维码SA App/BNS推荐人、门店、二维码版本、办单选择证据仅凭手机号或二维码展示推断佣金归属
支付与财务付款/财务域收款账户审核结果、付款回执、失败原因、对账结果佣金系统把付款请求成功当作最终入账成功

2. BNS/订单域改造

2.1 合格资格事件

订单域应在满足业务定义的交机成功条件时，向佣金系统投递统一事件：

{
  "event_type": "COMMISSION_QUALIFIED",
  "event_id": "unique-event-id",
  "occurred_at": "2026-08-10T10:00:00+01:00",
  "order_id": "ORD-001",
  "order_version": 12,
  "store_id": "STORE-001",
  "sa_id": null,
  "sales_actor_id": "SM-001",
  "sales_actor_role": "SA_MANAGER",
  "product_id": "SKU-001",
  "principal_amount": "100000.00",
  "interest_amount": "20000.00",
  "currency": "NGN"
}

要求：

  • 使用 source_system + event_id 去重；同一事件重放不重复创建台账。
  • 支持迟到、乱序、取消、退款、欺诈和资格撤销事件；撤销必须指向原订单/原事件。
  • 订单版本不可回退；金额、商品、门店、SA 或推荐信息更正时保留前后版本和原因。
  • 资格事件到达时调用或携带归属快照构建所需事实；缺失项进入待复核，不能默认发放。
  • sales_actor_id + sales_actor_role 表示实际办单人。SM/RM 直接办单时不得伪造 sa_id；佣金系统据此生成直办奖励与本人岗位奖励两个可解释组件。

2.2 推荐人和二维码办单

SA App/BNS 办单流程增加明确的推荐证据：

  • 客户扫码或选择店员/店长/门店后，服务端签发并持久化 referrer_id、referrer_role、store_id、二维码版本、选择时间和校验结果；兼容期可同时返回 clerk_referral_id。
  • 店员推荐订单的 SA 九折仅依赖已验证的推荐证据及资格时点有效关系，不依赖前端显示、人工备注或手机号匹配。
  • 店长可作为推荐人，但店长奖励不得与独立推荐奖励或第二条店长奖励叠加；BNS 必须传递店长身份和关系版本，不能将店长伪装成店员。
  • 推荐/门店二维码应可撤销、轮换、设置有效期，并记录签发主体、状态和使用日志。

3. 组织、门店与人员改造

3.1 历史关系

组织/运营系统维护带有效期的关系：

  • RM → SM → SA
  • Store → Store Manager → Clerk
  • SA 与门店资料提交/正式建档关系

SA、SM、RM 均可发起门店资料提交：SA 限本人授权门店，SM 限本人团队/区域，RM 限本人授权区域。组织/运营系统必须以服务端会话校验范围并保存提交人角色；门店同一时刻只允许一名有效店长。

每条关系至少有 valid_from、valid_to、状态、来源、操作人、变更原因和版本。人员调岗、离职、调店、店长/店员信息修改均新增关系或变更记录，不覆盖历史。

3.2 佣金归属快照

资格事件触发时，佣金系统创建不可变 commission_order_snapshot：订单事实、受益角色链、关系版本、推荐证据、政策版本、产品版本、范围 hash 和创建时间。缺失或冲突进入 PENDING_SNAPSHOT，重试后仍无法完整时进入 MANUAL_REVIEW。

正式门店资料建档、账户激活和审批由组织/运营系统负责；人员关系必须满足《06B-门店人员信息审核迭代需求》的全部生效条件。SA H5 的 SUBMITTED 或单独的人员审核 APPROVED 均不能直接成为订单归属、二维码签发或佣金计算输入。

4. 风险系数数据与绩效快照改造

4.1 数据交付

还款/风控系统须提供订单级或经审批的角色级风险数据：

字段要求
metric_code已版本化指标代码；政策展示可显示 CPD7，历史 FPD7 作为兼容别名
subject_type/id角色、人员/门店/团队及其快照 ID
cohort_start/end统计窗口，使用尼日利亚业务时区
observation_days/order_countCPD7 固定 90 天观察窗及范围内去重合格订单数
金额principal_amount、interest_amount、total_due_amount、扣减金额、排除金额
指标分子 D、分母 E、百分比值、计算版本、来源批次、生成时间
冻结DRAFT、FROZEN、CORRECTED 及冻结时间

风险系数按照各角色自己的订单范围计算，金额基数为本金+利息；不可按全平台混算，也不可仅用订单笔数。订单数仅用于小样本保护：90 天内少于 10 单时正向系数最高为 0，-0.2 不受该上限影响。正式 25 日结算只能消费 FROZEN 快照。

4.2 更正和延迟

  • 快照未到：受影响佣金保持 WAITING_RISK_FACTOR，不以 1.0 或 0 猜测最终结果。
  • 分母为零、数据缺失、范围 hash 不一致：进入人工复核。
  • 上游更正：创建 CORRECTED 快照；未锁定批次重算，已付款批次生成独立差额/冲正台账。
  • 缺失项不阻塞无关人员结算，可进入异常补结算批次。

5. 产品、政策与配置配合

  • 商品主数据提供产品/SKU、品牌型号、价格、货币、上下架、区域、渠道和版本；规则按商品时使用版本快照。
  • 销售运营提供角色月度目标、ACH 分母、合格订单定义和政策生效时间。
  • 佣金后台保存角色、场景、组件、条件、区间、系数、结算比例和版本；外围系统只提供事实，不应复制佣金公式。
  • 运营政策明确 CPD7 >15% 对应 -0.2 跨月扣减，不得在外围系统转换成当月 0.8 乘数。
  • 当前政策的 SM/RM 具体金额以已发布政策为准；历史区间示例仅用于验证配置能力。

6. 付款、对账与客服配合

6.1 付款

付款/财务系统处理收款资料审核、付款请求、渠道回执、失败重试和入账确认。店长/店员暂仅允许一个有效收款户，首次校验成功即为默认户；更换时保留历史，付款批次固化所用账户快照。佣金系统向付款系统提交结算批次明细及幂等键，接收状态：SUBMITTED、PROCESSING、PAID、FAILED、REVERSED。

常规批次在每月 25 日发放上月奖励，并扣减上上月已确认的 -0.2 绩效调整；奖励与扣减来源必须分别追踪。若净额为负则转人工复核，不发起负数付款。付款渠道响应成功不等于最终已支付；仅 PAID 回执可将 H5 金额归入“已结算”。

6.2 对账与支持

  • 每日/每批对账比较佣金台账、结算明细、付款回执和财务入账；差异生成可处理工单。
  • H5 仅提供客服电话；客服查询需按角色和脱敏权限展示订单、收益、风险系数状态及结算状态。
  • 申诉、人工调整、付款追扣必须由后台工作流处理并记录原因、审批和证据。

7. H5 BFF、安全与可观测性

  • Store H5 使用手机号/OTP；SA H5 用 App 一次性授权码换短期会话。URL、日志、埋点不携带 token、BVN、完整手机号或个人佣金明细。
  • Store H5 登录提供授权协议入口并保存版本化同意证据；Profile 仅开放本人唯一收款户的新增/更换，人员与门店主数据仍只读。
  • BFF 根据服务端会话返回角色范围；SM/RM 的 SA 筛选只过滤其可见订单来源，不暴露 SA 个人佣金。
  • 所有关键链路写关联 ID：事件 ID、订单 ID、快照 ID、规则版本、风险快照 ID、结算批次 ID、付款请求 ID。
  • 监控覆盖资格事件延迟/重复、快照构建失败、风险数据迟到、规则执行异常、付款失败、对账差异、H5 接口失败和弱网重试。

8. 联调、上线与验收

8.1 联调用例

  1. 合格事件正常投递、重复投递、迟到、撤销和更正。
  2. 店员推荐订单命中 SA 九折；店长推荐可识别但店长奖励不叠加；证据缺失或多个推荐人冲突时不命中/复核。
  3. RM-SM-SA、门店-店长-店员关系在资格时点、调岗后和离职后的一致性。
  4. SM/RM 新建门店和直接办单；越区被拒绝，直办与岗位奖励叠加且不重复。
  5. 风险系数按本金+利息、角色范围和 90 天观察窗计算；少于 10 单触发正向系数上限；覆盖冻结、更正、缺失和分母为零。
  6. 25 日发放、跨月 -0.2 扣减、付款失败重试、已付款更正、冲正与对账差异。
  7. Store H5/SA H5 权限、脱敏、授权协议、唯一收款户、弱网、二维码轮换和图片上传。

8.2 上线前 P0 清单

  • 确认合格资格事件、撤销事件、目标订单口径、风险指标代码和冻结日。
  • 确认 ACH/CPD7 端点、90 天观察窗、10 单小样本上限、每月 25 日结算日历、付款回执与负余额后续处理策略。
  • 建立事件重放、快照重建、批次回滚、异常补结算和对账 SOP。
  • 完成灰度：资格事件与台账 → 风险快照 → 结算批次 → 小范围 H5 展示 → 全量。

关系图谱