PocketBuy 佣金系统需求文档
1. 目标、范围与唯一口径
佣金系统负责将合格订单、订单归属、组织关系、政策配置和风险系数快照转换为可审计的佣金台账和结算批次。
系统分为三层，必须独立配置、独立留痕：
- 每单基础佣金层：计算受益角色在单笔订单上的基础应得
B。 - 绩效调整层：消费风险系统返回的最终风险结果，计算最终应发
T = B × k。 - 结算层：按结算计划在次月计算并导出上月结算明细，不回写基础佣金或绩效结果。
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 幂等键、事件时间、订单版本和撤销语义。MVP 不存在部分退，只有整单取消；整单取消须引用原订单/原资格事件并生成可追溯的撤销记录，不覆盖原台账。事件投递通道、系统边界和重试策略由技术方案确定。
3. 每单基础佣金层
3.1 配置模型
规则以“角色 → 场景 → 组件 → 条件调整 → 输出”配置：
| 配置对象 | 必填内容 |
|---|---|
| 规则作用域 | 角色、订单国家/区域、产品/SKU、渠道、资格事件、适用时间 |
| 场景条件 | 字段、运算符、值/集合/区间、AND/OR 分组、缺失字段策略 |
| 佣金组件 | 组件 ID、计算方式、金额/比例/公式、币种、优先级、叠加/互斥关系 |
| 调整 | MULTIPLIER、FIXED_ADD、FIXED_DEDUCT、RATE、CAP、FLOOR，及作用组件与顺序 |
| 输出 | earned_base_amount、命中规则/组件、调整前后金额、证据快照、舍入结果、异常码 |
MVP 支持固定金额、比例、条件档位、月度阶梯、加成/扣减、封顶/保底和显式组合顺序。所有 NGN 金额保留整数，在总额级按 ROUND_HALF_UP 舍入；接口与导出须返回舍入规则。复杂公式编辑器、佣金池、跨币种、预算控制和税费编排可保留模型，不是 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,+∞)。订单在达到资格时点按当时 ACH 定档；后续 ACH 变化不回溯补差。SM/RM 的直办订单同时计入本人及团队 ACH。
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 统一口径
风险系统负责计算风险指标、适用系数和最终结果；佣金系统不自行推导 CPD7、D/E 或角色范围，只按受益人和统计周期读取风险系统最终计算结果并保存结果版本。
风险系数作用于每个受益人的基础应得：
最终应发 T = ROUND_HALF_UP(B × k, 0)对外政策可显示 CPD7；存量资料中的 FPD7 作为兼容别名。新接口和台账不以展示名作为关键字段，统一保存风险系统返回的 risk_factor_snapshot_id、metric_code、factor、结果状态、结果版本和生成时间。当前默认展示指标为 CPD7；若风控确认采用其他指标代码，须以新版本参数发布，不改写历史快照。
4.2 当前系数区间（风险系统口径）
| 风险指标值 | 系数 k | 业务含义 |
|---|---|---|
<5% | 1.2 | 最终应发上浮 20% |
≥5% 且 <10% | 1.1 | 最终应发上浮 10% |
≥10% 且 ≤15% | 1.0 | 按基础应得发放 |
>15% | 0.8 | 最终按基础应得的 80% 发放 |
系数区间、缺失、分母为零和口径不一致均由风险系统处理；佣金系统不得猜测系数。未取得最终结果的记录进入 WAITING_RISK_FACTOR，待结果可查询后再输出结算金额。
4.3 结果消费与快照
风险系统在其规则内处理角色范围、订单集合、金额口径及 D/E；佣金系统仅消费最终结果。每次消费必须固化风险结果快照 ID、角色/统计周期、指标代码、系数、结果状态、结果版本、生成时间和查询时间；人员关系变化不回写已固化结果。
5. 结算层
5.1 次月单阶段结算
结算层按资格月的次月计算并导出结算明细，不修改基础佣金或绩效结果。常规结算日暂定为每月 25 日前的某一工作日，具体日期由运营配置。结算金额统一为：
settlement_amount = monthly_receivable_amount - monthly_deductible_amount其中，monthly_receivable_amount 为上月已计算的应收佣金，monthly_deductible_amount 为上月适用的应扣金额；应扣不存在时按 0 计算。结算按实际值计算并输出，结果可为正数、零或负数。若绩效数据延迟，受影响记录保持 WAITING_RISK_FACTOR，待数据可查询后再纳入输出。本期不采用两阶段预发/补差，也不发起付款、自动追扣或人工异常处理。
5.2 台账与结算批次
- 一条佣金明细对应一笔订单和一个受益人，保存基础、风险、结算三层的引用与快照。
- 一条佣金明细可分配至 0..n 个结算批次；一个月可有多个导出批次。
- 结算状态至少包含：待资格、待风险系数、待结算、结算中、已导出、异常待处理。
- 台账禁止原地修改；本期仅生成结算明细导出，不发起支付、不导入付款回执，也不处理支付重试、冲正或人工复核。
6. 后台 MVP
6.1 本期建设
- 规则列表、详情与生效状态查询。
- 角色/场景/组件、条件调整、档位、封顶保底、风险系数和结算比例配置。
- 规则校验：条件字段存在、边界连续互斥、同优先级冲突、币种/精度、循环引用、未覆盖兜底场景。
- 佣金台账、订单快照、风险结果快照、结算批次、导出状态和异常待处理查询。
- 组织关系与门店人员的只读历史查询，供归属解释和异常定位。
- 按角色导出绩效统计数据和绩效明细数据，覆盖
CLERK、STORE_MANAGER、SA、SA_MANAGER、REGIONAL_MANAGER。
绩效统计导出至少支持绩效月、角色、区域、SM/RM、门店、人员、快照状态和导出状态筛选，包含角色/人员、订单数、风险指标代码、风险系数、基础金额、最终应发、应收、应扣、结算计算结果及异常数。绩效明细导出需包含订单、资格时间、受益组件、归属快照、风险结果快照、政策版本、结算批次和状态；手机号、收款账号等敏感字段默认脱敏。导出使用独立权限 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",
"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、metric_code、factor、结果版本、monthly_receivable_amount、monthly_deductible_amount、settlement_amount、结算批次和导出状态；接口向 H5 返回角色范围内、已脱敏且可解释的数据。
8. 验收标准
- 同一资格事件重放不产生重复台账；整单取消引用原资格事件并生成可追溯撤销记录。
- 店长、店员、SA、SM、RM 均可按资格时点获得正确受益人快照；关系缺失保持待处理，不部分发放。
- SM/RM 直接办单时，直办奖励与本人岗位奖励正确叠加，且不虚构下级、不重复同一组件。
- 店员推荐订单仅使
SA_BASE按 0.9 计算；店长可作为推荐人但店长奖励不叠加、不重复。 - 当前政策档位与风险系数区间连续互斥；订单按资格时点的 ACH 定档，后续 ACH 变化不回溯补差。
- 佣金系统仅消费风险系统的最终结果，并保存结果版本与消费快照；不自行计算角色范围或 D/E。
- 次月单阶段结算按“上月应收 - 上月应扣”以实际值生成结算明细；可输出负数，但不自动追扣。
- 五类角色的绩效统计与明细均可按权限导出，金额口径与台账一致且敏感字段脱敏。
- 新规则只对明确生效范围增量生效，历史台账和结算不可被覆盖。