袋鼠金融蓝图

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 去重；同一事件重放不重复创建台账。
  • 支持迟到、乱序和整单取消事件；MVP 不存在部分退。整单取消的撤销必须指向原订单/原事件。
  • 订单版本不可回退；金额、商品、门店、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统计窗口，使用尼日利亚业务时区
最终结果factor、结果状态、结果版本、生成时间；可附风险快照 ID
指标metric_code 及风控返回的展示值/最终结果，不要求业务系统返回或复算 D/E
状态数据生成状态及生成时间；本期不处理更正重算

风险系统负责角色范围、金额口径和最终系数计算；业务系统直接使用其最终结果。次月结算读取当期可用的绩效结果。

4.2 更正和延迟

  • 绩效数据未到：受影响佣金保持 WAITING_RISK_FACTOR，待数据延迟到达后再输出，不以 1.0 或 0 猜测最终结果。
  • 分母为零、数据缺失或范围 hash 不一致：保持待处理并记录异常原因；本期不建设人工复核、重算和更正流程。
  • 数据延迟不阻塞无关人员结算；受影响数据在下一次可用输出中纳入。

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

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

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

6.1 结算明细导出

首期不由佣金系统发起支付，也不导入付款记录。佣金系统仅生成并导出结算明细，供财务在其系统中完成付款、回执和入账处理；H5 不以佣金系统数据展示付款成功或已支付。常规结算日暂定为每月 25 日前的某一工作日，具体日期由运营配置。

6.2 对账与支持

  • 每日/每批核对佣金台账与导出结算明细；付款回执和财务入账不在本期佣金系统范围内。
  • H5 仅提供客服电话；客服电话由配置中心维护，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。
  • 监控覆盖资格事件延迟/重复、快照构建失败、风险数据迟到、规则执行异常、导出失败、H5 接口失败和弱网重试。

8. 联调、上线与验收

8.1 联调用例

  1. 合格事件正常投递、重复投递、迟到和整单取消。
  2. 店员推荐订单命中 SA 九折；店长推荐可识别但店长奖励不叠加；证据缺失或多个推荐人冲突时不命中或保持待处理。
  3. RM-SM-SA、门店-店长-店员关系在资格时点、调岗后和离职后的一致性；推荐关系按客户选择或扫码时点校验。
  4. SM/RM 新建门店和直接办单；越区被拒绝，直办与岗位奖励叠加且不重复。
  5. 验证风险最终结果的查询、延迟、缺失、版本和状态；业务系统不复算风险指标。
  6. 次月单阶段结算、应收减应扣和结算明细导出。
  7. Store H5/SA H5 权限、脱敏、授权协议、唯一收款户、弱网、二维码轮换和图片上传。

8.2 上线前 P0 清单

  • 确认合格资格事件、撤销事件、目标订单口径、风险指标代码和查询权限。
  • 确认 ACH/风险系数查询端点、结算日历、应扣口径和导出字段。
  • 建立事件重放、快照重建、延迟数据输出和结算明细导出 SOP。
  • 完成灰度：资格事件与台账 → 风险快照 → 结算批次 → 小范围 H5 展示 → 全量。

关系图谱