PocketBuy 佣金系统需求文档
1. 目标、范围与唯一口径
佣金系统负责将合格订单、订单归属、组织关系、政策配置和风险系数快照转换为可审计的佣金台账和结算批次。
系统分为三层，必须独立配置、独立留痕：
- 每单基础佣金层：计算受益角色在单笔订单上的基础应得
B。 - 绩效调整层：按角色范围的 CPD7 快照生成绩效调整额；正系数计入上月绩效，负系数形成下月扣减项。
- 结算层：每月 25 日发放上月奖励，并按规则扣减上上月已确认的负绩效调整，不回写基础佣金或绩效结果。
H5、SA App 和后台列表只展示结果，不自行推导佣金、风险系数、应发或结算金额。
2. 角色、归属与资格
2.1 受益角色
| 角色代码 | 受益人来源 |
|---|---|
CLERK | 资格事件时订单归属的、满足 06B 全部生效条件的店员 |
STORE_MANAGER | 资格事件时订单门店的、满足 06B 全部生效条件的有效主店长 |
SA | 订单显式绑定的 SA |
SA_MANAGER | 资格事件时该 SA 的有效直属 SM |
REGIONAL_MANAGER | 资格事件时该 SM 的有效直属 RM |
SM、RM 可作为实际办单人直接办单。直接办单时，同一人员可同时获得“直办奖励组件”和其岗位对应的管理奖励组件：SM 为直办奖励 + SM 奖励，RM 为直办奖励 + RM 奖励；不得虚构下属 SA/SM，也不得因同一组件身份重合而重复记账。资格事件必须保存实际办单人 ID、实际办单人角色和每个命中组件的归属原因。
资格事件发生时，系统固化订单、门店、店员、店长、SA、SM、RM、政策和适用范围快照。人员调岗、离职、调店、资料编辑或后续政策发布，不得反向改写已固化台账。
SA/SM/RM 有效期关系以《06A-SA角色与组织层级管理迭代需求》及组织域输出为准；店长/店员是否有效以《06B-门店人员信息审核迭代需求》的人员审核、账号、门店关系、门店状态和必要工牌审核联合结果为准。佣金系统不得把 H5 SUBMITTED 或单独的人员审核 APPROVED 当作有效关系。
归属缺失、冲突、重复或无法证明时，记录 PENDING_SNAPSHOT / MANUAL_REVIEW，不得猜测受益人、部分发放或按零自动结算。
2.2 订单资格
资格规则由配置指定，例如“已交机成功”。资格事件须具备 source_system + event_id 幂等键、事件时间、订单版本和撤销/冲正语义。取消、退款、欺诈、资格撤销或纠正事件，通过同一台账生成冲正/调整，不覆盖原记录。
3. 每单基础佣金层
3.1 配置模型
规则以“角色 → 场景 → 组件 → 条件调整 → 输出”配置：
| 配置对象 | 必填内容 |
|---|---|
| 规则作用域 | 角色、订单国家/区域、产品/SKU、渠道、资格事件、适用时间 |
| 场景条件 | 字段、运算符、值/集合/区间、AND/OR 分组、缺失字段策略 |
| 佣金组件 | 组件 ID、计算方式、金额/比例/公式、币种、优先级、叠加/互斥关系 |
| 调整 | MULTIPLIER、FIXED_ADD、FIXED_DEDUCT、RATE、CAP、FLOOR，及作用组件与顺序 |
| 输出 | earned_base_amount、命中规则/组件、调整前后金额、证据快照、舍入结果、异常码 |
MVP 支持固定金额、比例、条件档位、月度阶梯、加成/扣减、封顶/保底和显式组合顺序。复杂公式编辑器、佣金池、跨币种、预算控制和税费编排可保留模型，不是 MVP 上线依赖。
3.2 初版基础佣金与当前政策
基础佣金可以由固定值或月度 ACH 档位确定。当前政策展示值如下；实际生效以发布的政策配置为准：
| 角色 | 初版固定示例 | 当前 ACH 三档政策 |
|---|---|---|
| 店员 | ₦400 | <50%：₦400；50%–<80%：₦500；≥80%：₦600 |
| 店长 | ₦850 | <50%：₦850；50%–<80%：₦1,100；≥80%：₦1,300 |
| SA | ₦850 | <100%：₦850；100%–<120%：₦1,100；≥120%：₦1,300 |
| SM | 早期能力示例 ₦30–₦50 | 当前政策：₦100 / ₦110 / ₦120 |
| RM | 早期能力示例 ₦20–₦30 | 当前政策：₦25 / ₦30 / ₦35 |
SM/RM 的 ₦30–₦50、₦20–₦30 是历史“可配置区间/规则引擎能力”示例；当前 MVP 默认政策以当前政策栏为准。任何新金额必须以新政策版本发布，不能靠页面文案改变。
所有档位必须使用明确开闭区间：店员/店长为 [0,50) / [50,80) / [80,+∞)；SA/SM/RM 为 [0,100) / [100,120) / [120,+∞)。
3.3 通用条件调整：店员推荐订单 SA 九折
这是通用配置能力的首个业务实例，而不是硬编码分支：
条件：clerk_referral_id 存在
AND referral_valid = true
AND referral_store_id = order.store_id
AND 推荐店员/门店关系在资格事件时有效
目标组件：SA_BASE
调整：MULTIPLIER = 0.9
顺序：SA 基础规则 → 九折调整 → 输出 SA 的 B → 绩效调整 → 结算仅 SA_BASE 受影响，店员、店长、SM、RM 组件不受影响。证据缺失或关系无效按规则的 missing_policy 处理（不命中、阻断或人工复核），禁止依据手机号或备注猜测。
店长也可作为推荐人。推荐证据必须显式保存 referrer_id、referrer_role=STORE_MANAGER、门店和关系版本；店长作为推荐人时只获得一次店长奖励，不再叠加店员/独立推荐人奖励，也不得生成两条内容相同的店长佣金。店员推荐仍按上文规则处理。若同一订单同时提交多个推荐人，服务端必须按已确认的唯一推荐证据处理，冲突时进入人工复核。
3.4 复杂规则示例（配置能力）
| 场景 | 可配置表达 |
|---|---|
| SKU 比例与封顶/保底 | min(max(合格金额 × 1.5%, 300), 700) |
| SA 月度销量阶梯 | 1–20 单 ₦700，21–50 单 ₦850，51+ 单 ₦1,000；可配置整月回溯或仅超额计价 |
| SM 条件档位 | 合格单数、取消率等条件组互斥命中；无命中走兜底档 |
| 活动加成与质量扣减 | max(0, 固定佣金 + 活动奖励 - 质量扣减)，可配置每项上限 |
| 多角色奖金池 | 奖励池、有效参与人、权重、分母为零异常策略、单人封顶 |
所有示例都必须配置作用域、生效时间、命中优先级、叠加/互斥、舍入方式、证据字段和异常策略。
4. 绩效调整层（风险系数）
4.1 统一口径
绩效系数作用于每个受益人的基础应得，并作为独立调整额保存：
绩效调整额 A = round(B × r)对外政策可显示 CPD7；存量资料中的 FPD7 作为兼容别名。新接口和台账不以展示名作为关键字段，统一保存 risk_factor_snapshot_id 与 metric_code。当前默认展示指标为 CPD7；若风控确认采用其他指标代码，须以新版本参数发布，不改写历史快照。
4.2 当前系数区间
| CPD7 指标值 | 绩效系数 r | 业务含义 |
|---|---|---|
<5% | +0.2 | 在基础奖励上增加 20% |
≥5% 且 <10% | +0.1 | 在基础奖励上增加 10% |
≥10% 且 ≤15% | 0 | 不加不减 |
>15% | -0.2 | 形成基础奖励 20% 的负调整，并在下个月发放时扣减 |
-0.2 是跨月扣减的调整率，不是负数乘数，也不表示当月发放 B × -0.2。区间连续互斥；缺失、分母为零、口径不一致或快照未冻结时不得猜测系数。未冻结订单进入 WAITING_RISK_FACTOR，可显示预计值但不可进入正式发放批次。
4.3 90 天观察窗与小样本保护
- CPD7 使用截至绩效月月末的连续 90 个自然日观察窗，按
Africa/Lagos日历边界计算；快照必须保存cohort_start、cohort_end和实际天数。 - 订单量按该受益人角色范围内、观察窗内去重后的合格订单数计算，不使用列表行数或全平台订单量。
- 观察窗内合格订单
<10时，绩效系数上限为0（对应最终发放系数最高为1.0）：即使 CPD7 落入<5%或5%–<10%，也不发放+0.2/+0.1加成；>15%的-0.2仍按政策生成扣减项。 - 合格订单
≥10时按 4.2 的完整区间执行。订单量、去重规则、范围 hash 和是否命中小样本保护必须写入绩效快照并可导出。
4.4 角色范围和金额口径
风险指标按分佣角色自己的订单范围计算，而不是按全平台订单池：
- 店员：资格事件时归属该店员的订单。
- 店长：资格事件时归属其门店的订单。
- SA：显式绑定该 SA 的订单。
- SM：有效组织关系下 SA 的订单，以及本人作为实际办单人的直办订单；同一订单按快照去重。
- RM：有效区域/组织关系下的订单，以及本人作为实际办单人的直办订单；同一订单按快照去重。
金额加权：
分母 E = Σ(角色订单的本金 + 利息)
扣减金额 D = Σ(达到风险条件订单的本金 + 利息)
风险指标 = D / E × 100%快照需固化订单集合 hash、角色范围、principal_amount、interest_amount、total_due_amount、D/E、排除金额、来源版本、生成时间、冻结时间和状态。人员关系变化不回写已冻结范围。
5. 结算层
5.1 每月 25 日发放与跨月扣减
结算层消费月度基础奖励与已冻结的绩效调整，不修改前两层结果。每月仅有一个常规发放日：25 日，发放上一个自然月的奖励。
| 结算项 | 公式 | 发放月 M 的处理 |
|---|---|---|
| 上月基础奖励 | B(M-1) | 计入 25 日批次 |
| 上月非负绩效调整 | max(0, A(M-1)) | 与上月基础奖励一并发放 |
| 上上月负绩效扣减 | min(0, A(M-2)) | 在本月 25 日批次中扣减 |
| 本月应发 | P(M)=B(M-1)+max(0,A(M-1))+min(0,A(M-2)) | 扣减项单独列示，不覆盖原月台账 |
示例：9 月 25 日批次发放 8 月基础奖励与 8 月正向绩效；如果 7 月 CPD7 对应 -0.2，则同时扣减 7 月基础奖励 × 20%。每个扣减项必须关联原绩效月、风险快照、基础金额和系数，H5、后台和导出均可解释。
若 P(M)<0，系统不得向用户发起负数付款。剩余扣减是否结转后续月份、设置上限/期限或转人工处理，需由运营和财务补充确认；确认前此类批次进入 MANUAL_REVIEW，不得静默丢弃扣减额。
5.2 台账、结算批次与冲正
- 一条佣金明细对应一笔订单和一个受益人，保存基础、风险、结算三层的引用与快照。
- 一条佣金明细可分配至 0..n 个结算批次；常规批次为每月 25 日，异常补发/冲正可另建批次并标记原因。
- 结算状态至少包含：待资格、待风险系数、待结算、结算中、已支付、支付失败、已冲正、人工复核。
- 支付成功、失败、重试、对账差异和冲正均以不可变账务事件记录；不覆盖原金额或付款状态。
6. 后台 MVP
6.1 本期建设
- 规则列表、详情与生效状态查询。
- 角色/场景/组件、条件调整、档位、封顶保底、风险系数和结算比例配置。
- 规则校验：条件字段存在、边界连续互斥、同优先级冲突、币种/精度、循环引用、未覆盖兜底场景。
- 佣金台账、订单快照、风险快照、结算批次、支付状态、冲正和异常复核查询。
- 组织关系与门店人员的只读历史查询，供归属解释和人工复核。
- 按角色导出绩效统计数据和绩效明细数据，覆盖
CLERK、STORE_MANAGER、SA、SA_MANAGER、REGIONAL_MANAGER。
绩效统计导出至少支持绩效月、角色、区域、SM/RM、门店、人员、快照状态和发放状态筛选，包含角色/人员、订单数、90 天观察窗、小样本保护、D/E、CPD7、绩效系数、基础金额、调整额、扣减来源月、应发/已发及异常数。绩效明细导出需包含订单、资格时间、受益组件、归属快照、风险快照、政策版本、结算批次和状态；手机号、收款账号等敏感字段默认脱敏。导出使用独立权限 commission.performance.export，记录筛选条件、导出人、文件 hash、生成/过期时间和下载审计；大数据量异步生成，禁止前端拼接全量数据。
6.2 本期不建设
不建设后台规则版本详情、新建、复制模拟、定时发布等复杂交互；但数据模型必须预留 policy_version、effective_at、incremental_scope、supersedes_version 和审计字段。
6.3 生效和历史保护
- 新规则默认仅作用于
effective_at后达到资格的新订单，或明确指定的新结算批次。 - 已产生的基础佣金、风险快照、结算批次和已付款记录不可覆盖；修正通过新调整/冲正记录处理。
- 每次执行保留规则版本、输入快照、输出金额、舍入方式和异常结果，支持重放和审计。
7. 核心数据与接口输出
7.1 佣金计算输入
至少包含订单、资格事件、产品/SKU、合同金额、门店/店员/店长/SA/SM/RM 归属快照、推荐关系、渠道、活动、取消/退款/欺诈状态、政策版本和计算时间。
7.2 佣金计算输出
{
"commission_ledger_id": "CL-001",
"order_id": "ORD-001",
"beneficiary": {"role": "SA", "id": "SA-001"},
"earned_base_amount": "765.00",
"currency": "NGN",
"matched_rule_versions": ["SA_BASE_V1", "CLERK_REFERRAL_SA_90_V1"],
"attribution_snapshot_id": "ATTR-001",
"status": "WAITING_RISK_FACTOR"
}风险快照和结算输出分别带 risk_factor_snapshot_id、adjustment_rate、observation_order_count、small_sample_cap_applied、performance_adjustment_amount、扣减来源月、结算批次和支付状态；接口向 H5 返回角色范围内、已脱敏且可解释的数据。
8. 验收标准
- 同一资格事件重放不产生重复台账；撤销/纠正事件生成可追溯调整。
- 店长、店员、SA、SM、RM 均可按资格时点获得正确受益人快照；关系缺失进入复核，不部分发放。
- SM/RM 直接办单时，直办奖励与本人岗位奖励正确叠加，且不虚构下级、不重复同一组件。
- 店员推荐订单仅使
SA_BASE按 0.9 计算；店长可作为推荐人但店长奖励不叠加、不重复。 - 当前政策档位与绩效系数区间连续互斥；90 天内少于 10 单时正向系数最高为 0，且保存小样本保护证据。
- 风险系数按角色订单范围，使用本金+利息金额加权，并保存可复算快照。
- 每月 25 日正确发放上月奖励，并单列扣减上上月
-0.2调整；负数付款进入人工复核。 - 五类角色的绩效统计与明细均可按权限导出，金额口径与台账一致且敏感字段脱敏。
- 新规则只对明确生效范围增量生效，历史台账和结算不可被覆盖。