袋鼠金融蓝图

PocketBuy 门店端 H5 需求文档

1. 定位与边界

门店端 H5 服务店长（STORE_MANAGER）和店员（CLERK），用于查看本人或本店范围内的订单收益、绩效政策、结算进度及推荐二维码。

H5 是展示与操作端，不计算基础佣金、风险系数或结算金额；所有金额、状态、政策边界和数据范围均以佣金系统接口返回为准。计算规则见《10-PocketBuy 佣金系统需求文档》，外围依赖见《09-PocketBuy 佣金系统外围配合改造功能点》。

本期不支持线上申诉，仅提供客服电话入口。店长、店员及其门店关系的新增、编辑、启停和核验资料录入统一由 SA/SM/RM 在 SA App 的 Stores H5 中完成，门店端 H5 只读消费生效后的人员与关系数据。个人中心仅对“本人唯一收款户”开放新增/更换能力，不因此获得人员主数据或门店关系写权限。

人员信息审核、账号/关系状态及生效条件见《06B-门店人员信息审核迭代需求》。本文档中的“生效”统一指人员审核、账号、门店关系、门店状态和必要工牌审核均满足该文档定义的条件；SUBMITTED 或单独的 APPROVED 均不等于可登录或可参与订单归属。

2. 角色与数据权限

角色数据范围可用能力
店员本人归属订单、本人收益、本人绩效与推荐码使用已审核生效的账号登录，查看 Earnings/订单详情/政策/结算，查看并保存个人推荐二维码，签署/查看授权协议，新增或更换本人唯一收款户，查看客服电话
店长本人收益、本店订单、店员归属、店员在同一订单中的收益信息使用已审核生效的账号登录，按店员筛选并查看同单店员收益，查看并保存门店二维码，签署/查看授权协议，新增或更换本人唯一收款户，查看客服电话

约束：

  • 店长可查看店长与店员政策；店员仅可查看店员政策。
  • 店长不可查看店员跨门店订单、银行资料、BVN 或独立月度总收益；订单详情只展示该订单必要的店员身份与收益信息。
  • 店员不可查看其他店员、店长个人收益或管理能力。
  • 人员主数据和门店关系由 SA/SM/RM Stores H5 统一维护；门店端 H5 仅提供订单归属和同单收益的只读查看，以及本人唯一收款户的受控维护。
  • 历史订单的受益人、组织关系和佣金快照不可由 H5 修改。

3. 信息架构

一期保留三个一级入口：

  1. Earnings：默认首页，合并订单、佣金、绩效和结算信息。
  2. Policy：奖励阶梯、风险系数、当前进度与距离下一档。
  3. Profile：展示个人/门店信息、推荐二维码、人员核验状态、授权协议、唯一收款户和客服电话；除收款户外，人员/门店资料只读。

独立 Orders 一级页、排行榜、热销手机等能力不属于本期 MVP；订单搜索、筛选、分页及详情均纳入 Earnings。

3.1 H5 页面地址（原型 / 联调）

页面本地预览生产预览说明
店员 Earningslocalhost:4173/?persona=clerk188.239.22.0:9000/?persona=clerk店员本人订单、收益、绩效与政策入口
店长 Earningslocalhost:4173/?persona=manager188.239.22.0:9000/?persona=manager本店订单收益；可按店员筛选并查看店员收益
店员政策localhost:4173/policy/clerk188.239.22.0:9000/policy/clerk店员可见的 ACH、CPD7 及发放政策
店长政策localhost:4173/policy/store-manager188.239.22.0:9000/policy/store-manager店长可见本角色及店员政策

persona 仅用于原型预览和联调切换。正式环境的角色、门店范围及数据权限必须由登录态和服务端接口确定，不能以 URL 参数作为授权依据。

4. 登录与账号

4.1 手机号与 OTP

  • 所有输入统一使用尼日利亚本地 10 位手机号码；页面固定展示 +234，用户无需输入国家码，服务端保存 E.164。
  • 仅 SA/SM/RM 已在授权范围内录入并审核生效的店长/店员号码可以申请 OTP；OTP 的有效期、发送频率、错误次数、日上限及锁定策略由服务端配置。
  • 手机号变更通过后台复核或原/新号码双验证完成，保留变更历史，不允许直接覆盖。

4.2 登录页面

登录页仅承接门店账号认证，不承接人员或门店关系录入。

  1. 手机号页：展示 PocketBuy 品牌、登录说明、固定 +234 前缀、本地 10 位手机号输入框和 Send OTP 按钮。
  2. OTP 页：展示脱敏手机号、6 位验证码输入框、Sign in 和 Change mobile number。
  3. 手机号页与 OTP 页均提供 Authorization Agreement 入口；首次登录或协议版本升级时，用户须勾选同意并由服务端保存用户、角色、协议版本、同意时间、IP/设备和证据 hash。未同意时不得完成登录，但可打开协议全文。
  4. 店长和店员均使用已录入并生效的手机号登录；验证成功且协议已同意后直接进入 Earnings。
  5. 账号、门店关系或核验状态不满足登录条件时，页面提示 Please contact your SA or customer support。
  6. OTP 错误、过期、频控、离线或服务异常时，保留当前手机号并展示可重试提示。

4.3 人员资料变更

  • 店长、店员及门店关系的新增和变更统一由 SA/SM/RM 在授权范围内通过 Stores H5 提交，并按人员审核和生效规则处理。
  • 门店端 Profile 只读展示已生效人员/门店信息和核验状态，仅本人收款户使用专用接口新增或更换。
  • 人员资料变更不回写历史订单、佣金和结算快照。

5. Earnings（订单、佣金与结算）

5.1 页面顺序

  1. 当前月份选择器。
  2. 政策提示条，进入 Policy。
  3. 月度收益卡片。
  4. 有结算记录时展示结算批次。
  5. Orders and earnings：搜索、筛选、汇总、列表和“加载更多”。

月份默认当前业务月，至少支持当前月及前 7 个月；切换月份时卡片、订单汇总、结算记录、绩效状态和列表必须使用同一服务端快照。

5.2 月度卡片

月份状态展示内容
OPEN（当月）预计佣金、订单总数、已赚基础金额、待确认风险系数金额、更新时间；不展示已结算金额或结算批次
SETTLING（上一月或未完成月）预估结算总金额、订单总数、已结算金额、预计剩余结算金额；固定提示：The final amount is subject to the confirmed risk factor.
SETTLED（历史完成月）实际已结算金额、订单总数、结算完成状态及各批次记录

金额语义必须清楚区分“预计”“已结算”“待结算”。风险系数未冻结时显示 Waiting for risk factor，不得显示“Waiting for FPD7”。

常规奖励每月 25 日发放上一个自然月；若上上月 CPD7 产生 -0.2，本月 25 日批次必须单列该扣减来源月、基础金额和扣减额。H5 不把扣减合并成无法解释的净额，也不展示负数付款；异常负余额显示 Under review。

5.3 订单与收益列表

  • 主信息：手机品牌和型号、脱敏客户、订单状态、订单时间、收益状态及当前角色对应金额；不以订单号作为主标题。
  • 逾期订单显示 Overdue 及可选逾期天数；逾期仅用于展示/筛选，不能由前端改变佣金。
  • 支持按日期区间、订单状态、收益状态、还款状态（全部/逾期/未逾期）搜索和筛选。
  • 店长增加店员筛选；订单行显示归属店员。订单详情展示店长本人的收益，并展示该订单对应店员姓名和店员收益。
  • 汇总订单数及预计奖励总和始终基于完整筛选范围；“加载更多”只增加已显示行数，不改变汇总。

5.4 订单详情与关系解释

订单详情至少展示：品牌型号、脱敏客户与设备信息、订单状态、还款/逾期状态、当前角色收益、基础金额、风险系数、预计/实际应发、已支付、待支付和说明。

订单
  └── 当前受益人的佣金明细（单订单、单受益人）
        └── 绩效周期及风险系数快照
              └── 0..n 条结算批次明细

订单是交易；佣金明细是财务权益；结算批次是付款动作。三者不可互相替代，也不可将预计金额展示为已付款。

6. Policy（奖励政策与进度）

6.1 可见性与统一结构

Policy 统一按“角色切换（如有）→ 激励说明 → 当月进度 → 距下一档 → 三档增长图 → 风险系数图例 → 完整规则表 → 发放说明”展示。

  • 店员：仅 Shop Promoter。
  • 店长：Shop Manager 与 Shop Promoter，仅切换政策内容，不扩大订单和佣金数据权限。

6.2 当前政策展示值

角色ACH < 50%50% ≤ ACH < 80%ACH ≥ 80%
Shop Promoter（店员）₦400/合格订单₦500/合格订单₦600/合格订单
Shop Manager（店长）₦850/合格订单₦1,100/合格订单₦1,300/合格订单
CPD7 区间绩效系数
< 5%+0.2
5% ≤ 指标 < 10%+0.1
10% ≤ 指标 ≤ 15%0
> 15%-0.2（下个月扣减）

展示名称可为 CPD7；系统内统一称“风险系数快照”，并由 metric_code 区分当前或历史指标口径。CPD7 观察窗为 90 天；观察窗内去重合格订单少于 10 单时，正向系数最高为 0（最终最多按基础奖励 1.0 发放），-0.2 仍形成次月扣减。政策接口必须提供明确的开闭区间、观察窗、订单数与小样本保护标记，H5 不根据文案推断边界。

6.3 当前进度

服务端返回目标订单数、合格订单数、ACH、当前档、下一档阈值和 orders_to_next_tier。H5 仅展示：

  • Sell more. Earn more. 与“客户质量越好，最终奖励越高”的说明。
  • 当前档及每单奖励。
  • 距下一档尚需合格订单数；最高档显示 Top tier unlocked。
  • 风险系数未冻结时的预计与待确认提示。

7. 二维码、个人资料与客服

7.1 二维码

  • 店员显示个人推荐二维码，用于客户在 PocketBuy 分期购买手机时选择该店员；支持点击放大、保存为带 PocketBuy 图标和品牌样式的图片。
  • 店长显示可用于推荐归属的门店/店长二维码，交互和保存样式与店员推荐二维码一致；服务端证据标记 referrer_role=STORE_MANAGER，同一订单的店长奖励只记一次，不叠加独立推荐奖励；不显示内部 STORE-xxx 编码作为用户文案。
  • 二维码对应的推荐/门店主体、有效期、状态和版本由服务端签发；H5 不生成可写入归属的业务编码。

7.2 Profile、授权协议、收款户与客服

  • 店员 Profile：姓名、脱敏手机号、人员核验状态、个人二维码、授权协议、本人收款户和客服电话；除收款户外只读。
  • 店长 Profile：门店信息、门店二维码、授权协议、本人收款户和客服电话；除收款户外只读。
  • 收款户暂仅支持一户。首次校验成功后自动成为默认收款户，不提供“新增第二户”或默认户切换；更换收款户必须重新校验并保留旧户历史、变更原因和审计，不得覆盖历史付款快照。
  • 新增/更换至少采集银行、NUBAN；服务端完成银行账户解析并返回账户名，用户确认后保存。账号未校验、户名不匹配、重复请求、银行不支持或风控拦截时不得设为默认收款户。
  • 页面仅展示银行名、账户名和脱敏 NUBAN；完整账号、校验请求/响应和历史账户不得进入普通日志或前端缓存。付款批次必须固化当次使用的收款户快照。
  • 授权协议入口展示当前协议版本、同意时间和可查阅全文；协议升级后按配置要求重新确认，历史同意记录不可覆盖。
  • 客服文案以门店用户视角描述“订单、账号、奖励或结算疑问可电话咨询”；不承诺 H5 内申诉。

8. 弱网、安全与非功能

  • 首屏展示骨架屏；列表按页加载；静态图片懒加载、压缩并缓存；请求可重试且保留最近成功数据与更新时间。
  • 所有敏感字段、手机号、BVN、二维码主体、收益信息均通过受控接口返回；列表脱敏，BVN 不在列表/导出展示。
  • 页面支持点击空白处收起键盘；所有页面处理安全区和 393px 等移动端宽度，不产生横向滚动。

9. 验收标准

  1. SA/SM/RM 已在授权范围内录入并生效的店长/店员使用登记手机号和 OTP 登录，同意当前授权协议并验证成功后进入 Earnings。
  2. 门店端 H5 的人员和门店关系信息均为只读，所有录入和变更由 SA/SM/RM Stores H5 按授权范围承接；本人收款户是唯一例外写能力。
  3. 账号或关系未生效时，H5 提示联系 SA 或客服。
  4. Earnings 对当前月、结算中月、已结算月正确区分预计与实发；订单、佣金、绩效、结算关系可解释。
  5. 店长可按店员筛选并查看同单店员收益；店员无越权数据。
  6. 政策页按角色权限展示，ACH 与风险系数边界无空档/重叠，下一档差距来自服务端快照。
  7. 逾期标签、日期/还款状态筛选、汇总和分页口径一致。
  8. 店员推荐二维码与店长门店二维码可放大、保存，且使用 PocketBuy 品牌样式。
  9. 登录页可查看并同意授权协议，协议版本和同意证据可审计；未同意时不能完成登录。
  10. 店长/店员可在 Profile 新增或更换本人唯一收款户，校验成功后自动为默认户；不能存在两条同时有效账户，历史付款仍指向原快照。
  11. 25 日发放批次能区分上月奖励和上上月 -0.2 扣减，负余额进入人工复核。

关系图谱