PocketBuy SA、SM、RM端 H5 需求文档
1. 定位与边界
本模块是嵌入 PocketBuy SA App 的 H5，服务 SA、SA 经理（SM）和区域经理（RM）。功能范围为收益订单、绩效政策及 SA/SM/RM 授权范围内的门店资料录入；不建设独立个人中心、消息、退出登录或 H5 内一级导航。
佣金、绩效、风险系数和结算由服务端统一计算。本 H5 只消费已授权会话中的数据与操作权限；不得将角色、用户 ID、组织 ID 或 token 放入 URL，也不信任前端传入的角色参数。
2. 角色与权限
| 角色 | Earnings 数据范围 | Policy 可见范围 | Stores |
|---|---|---|---|
| SA | 本人受益订单、本人收益和绩效 | SA | 可新建、保存、提交和维护本人授权门店资料 |
| SM | 本人受益订单、本人收益和绩效；订单可显示实际办单人/归属 SA 并按 SA 筛选 | SM、SA | 可新建、保存、提交和维护本人团队/区域授权范围内门店资料 |
| RM | 本人受益订单、本人收益和绩效；订单可显示实际办单人/归属 SA 并按 SA 筛选 | RM、SM、SA | 可新建、保存、提交和维护本人授权区域内门店资料 |
SM/RM 看到的是自己在该订单上的收益，不是 SA 的个人佣金金额；SA 姓名仅用于解释订单来源和筛选。政策向下可见不等同于订单、收益或个人资料向下可见。
SM、RM 可直接办单。本人直接办单时，Earnings 必须分别展示“直办奖励”和“SM/RM 岗位奖励”，汇总金额允许叠加，但不得重复同一组件或虚构下属 SA/SM。
3. 嵌入与信息架构
SA App 配置两个独立入口：
Earnings：SA、SM、RM 均可启动。Stores：SA、SM、RM 均可启动，数据范围由服务端会话确定。
H5 内不设置 Earnings/Stores Tab、底部导航或 Profile。页面使用紧凑返回栏，返回、关闭、重新授权、相机/相册、保存图片和网络状态通过 WebView Bridge 与宿主 App 协作。生产页面不展示手机外壳、角色切换器或 Mock 数据入口。
3.1 H5 页面地址（原型 / 联调）
| 页面 | 本地预览 | 生产预览 | 说明 |
|---|---|---|---|
| SA Earnings | localhost:4173/sa/earnings | 188.239.22.0:9000/sa/earnings | SA 本人订单、收益、绩效及政策入口 |
| SM Earnings | localhost:4173/sa/earnings?role=sm | 188.239.22.0:9000/sa/earnings?role=sm | 团队范围订单；可查看、筛选对应 SA |
| RM Earnings | localhost:4173/sa/earnings?role=rm | 188.239.22.0:9000/sa/earnings?role=rm | 区域范围订单；可查看、筛选对应 SA |
| Stores | localhost:4173/sa/stores | 188.239.22.0:9000/sa/stores | SA/SM/RM 录入、维护授权范围内门店、店长和店员资料 |
| SA 政策 | localhost:4173/policy/sa | 188.239.22.0:9000/policy/sa | SA 仅查看 SA 政策 |
| SM 政策 | localhost:4173/policy/sm | 188.239.22.0:9000/policy/sm | SM 查看 SM、SA 政策 |
| RM 政策 | localhost:4173/policy/rm | 188.239.22.0:9000/policy/rm | RM 查看 RM、SM、SA 政策 |
role仅用于原型预览和联调切换。正式内嵌页面由 SA App 传入登录凭据，并由服务端确定角色、组织范围和可访问模块；Stores 向 SA、SM、RM 开放，但必须按本人、团队或区域范围强校验。
4. Earnings
4.1 页面结构
- 宿主返回栏。
- 当前月份选择器。
- 政策提示条，进入 Policy。
- 月度收益卡片。
My orders and rewards：角色筛选（SM/RM）、搜索、订单状态/收益状态/还款状态/日期筛选、汇总与分页。
所有区域使用同一 period 与同一服务端快照。月份默认当前业务月，支持服务端返回的历史月份。
4.2 月度收益与订单
| 月份状态 | 必须展示 |
|---|---|
OPEN | 预计佣金、合格订单数、已赚基础金额、等待风险系数金额、更新时间；当月不展示结算付款记录 |
SETTLING | 预估结算总金额、订单总数、已结算金额、预计剩余结算金额，及最终以确认风险系数为准的提示 |
SETTLED | 实际已结算金额、订单总数、结算批次/付款状态 |
常规奖励每月 25 日发放上月；若上上月绩效系数为 -0.2，本月批次单列扣减来源月、基础金额和扣减额。净额为负时不展示负数付款，显示人工复核状态。
订单行主信息为商品品牌型号、脱敏客户、订单状态、逾期标签、当前角色的收益及收益状态。SA 只显示本人范围；SM/RM 额外显示 SA · 姓名，并可选择单个 SA 或全部 SA。详情页额外展示归属 SA 和脱敏手机号，但不展示该 SA 的个人佣金。
订单列表与汇总规则：
- 支持日期区间、订单状态、收益状态及还款状态（全部/逾期/未逾期）筛选。
- 逾期由服务端快照返回；
UNKNOWN不当作未逾期；前端不得按应还日期自行判断。 - 汇总订单数和预计奖励总和基于完整筛选结果；加载更多只改变可见条数。
- 风险系数未确认时，使用
Waiting for risk factor；金额标记为预计而非已支付。
5. Policy（绩效政策）
5.1 当前版本政策
| 角色 | ACH < 100% | 100% ≤ ACH < 120% | ACH ≥ 120% |
|---|---|---|---|
| SA | ₦850/合格订单 | ₦1,100/合格订单 | ₦1,300/合格订单 |
| SM | ₦100/合格订单 | ₦110/合格订单 | ₦120/合格订单 |
| RM | ₦25/合格订单 | ₦30/合格订单 | ₦35/合格订单 |
| CPD7 区间 | 绩效系数 |
|---|---|
| < 5% | +0.2 |
| 5% ≤ 指标 < 10% | +0.1 |
| 10% ≤ 指标 ≤ 15% | 0 |
| > 15% | -0.2（下个月扣减） |
上述为当前生效政策。CPD7 观察窗为 90 天；观察窗内去重合格订单少于 10 单时，正向绩效系数最高为 0（最终最多按基础奖励 1.0 发放），-0.2 仍形成次月扣减。早期“SM 30–50、RM 20–30”的金额仅为规则引擎能力示例，不是当前 MVP 默认政策。政策接口和后台配置必须返回明确的 min/max/min_inclusive/max_inclusive，确保边界连续互斥。
5.2 页面展示
- 统一显示：政策标题、适用月、可见角色切换、激励文案、当前合格订单数/目标/ACH、当前档、距下一档订单数、增长图、风险系数图例、规则表和发放说明。
orders_to_next_tier、当前档、下一档和奖励金额必须来自同一快照；H5 不自行计算 ACH 或金额。- 最高档显示
Top tier unlocked；风险系数未冻结时展示预计和待确认状态。 - 政策展示名可为
CPD7，统一业务含义为“风险系数快照”；历史 FPD7 文案仅作为兼容别名，不作为新接口字段。
6. Stores（SA、SM、RM）
6.1 记录与状态
SA、SM、RM 可查看本人创建且仍在授权范围内的门店资料记录：DRAFT、SUBMITTING、SUBMITTED、SUBMIT_FAILED。SA 按本人授权门店，SM 按团队/区域范围，RM 按授权区域；服务端必须再次校验。草稿可继续，失败可重试，已提交记录默认只读；提交成功仅表示资料被接收，不代表 Merchant、门店、店长或店员账号生效，也不得直接成为订单归属或佣金输入。
页面必须分层显示，禁止把所有结果写为一个“状态”：
| 提交人可见层 | 含义 | 下一步 |
|---|---|---|
| 提交状态 | 草稿是否已被服务端接收 | DRAFT/SUBMIT_FAILED 可继续或重试；SUBMITTED 等待审核 |
| 门店审核 | 门店基础资料当前版本的审核结果 | 待审核时等待；驳回时修改后产生新版本重提 |
| 店长/店员审核 | 对该人员当前资料版本的审核结果 | 每人独立显示，某店员被驳回不覆盖店长或其他店员 |
| 当前可用性 | 对新登录、归属和办单的最终结论 | 仅在相关审核通过、账号激活、关系有效且门店有效时显示 ACTIVE；否则显示未生效原因 |
SUBMITTED 与 APPROVED 不可互换。提交人可看到可行动的“待审核 / 需修改 / 已生效”提示，不展示审核人、风控规则或内部阈值。
已提交记录可进行当前人员资料维护：修改店长、修改店员、增加店员。该维护只改变当前联系/组织资料，不回写历史订单归属、佣金或结算快照。
6.2 新建与提交流程
Merchant Information → Store → Manager → Clerks (optional) → Review → Submitted| 环节 | 必填内容 |
|---|---|
| Merchant Information | 一期填写 Merchant 名称即可；不要求上传 CAC Certificate。Merchant 仍由后台受控创建或关联，客户端不得生成 Merchant ID。 |
| Store | 门店名称、州、LGA、详细地址、收款银行、收款账户名、10 位收款账号、门店正面照；定位失败可人工填写并标记 |
| Manager | 姓名、本地 10 位手机号、店长与提交人同框照片 |
| Clerks | 可跳过；已录入的每名店员必须填写姓名、本地 10 位手机号并上传店员与提交人同框照片。跳过不影响门店和店长提交，后续新增店员走独立人员审核。 |
| Review | 完整性、手机号重复、提交人数据范围、图片上传状态和幂等键校验 |
Merchant Information 是独立页面，完成后才进入 Store 页面。一期仅需填写 Merchant 名称，不要求上传 CAC Certificate；后端按 Merchant 名称完成受控创建或关联，不允许客户端自行生成 Merchant ID。Store 的收款信息须与门店资料一同提交：银行名称、账户名和 10 位 NUBAN；一期不采集 BVN。前端仅做格式校验；后端必须进行账户校验、加密存储和脱敏返回，不能将完整账号或账户验证结果写入日志、URL 或非授权页面。该页面不展示 Merchant 主数据状态、内部审核人、收款校验结果或后台操作人。
提交记录必须保存 submitted_by_person_id、提交时业务角色、区域快照和来源；SM/RM 直接发起时其本人就是提交人，不虚构为下属 SA，也不因此改变人员组织关系或佣金快照。
新增店员必须上传与提交人合照；编辑既有人员时如人员发生变更，应支持补传新的核验照片。图片支持相机和相册，JPG/JPEG/PNG/WEBP，建议压缩至 2MB 以内、长边不超过 1920px；文件私有存储、预签名上传、类型/病毒校验，仅授权用户可预览。
一个门店暂仅支持一名有效店长，不提供副店长或多店长入口；已存在有效店长时，提交其他店长必须进入“更换店长”流程并保留原关系有效期，不能叠加生效。
6.2.1 门店重复校验与拒绝详情
- 一期仅按门店名称做完全一致的重复校验：提交人填写名称后，前端调用服务端检索既有门店及未终止提交；服务端按去除首尾空白后的原始名称精确匹配，不做地址、模糊、大小写或标点归一化匹配。
- 命中完全相同门店名称时，必须阻止进入下一步或提交，并展示命中的门店名称、门店 ID 和地址；不因地址相同、名称近似或仅大小写/标点不同而拦截。一期前端提示仅为体验优化，提交接口必须再次执行相同的精确名称校验并以服务端结果为准。
- 已被门店审核拒绝的记录在提交人列表中显示
REJECTED；点击进入拒绝详情，展示可反馈给提交人的拒绝原因、审核时间、保留内容和“修改并重提”入口。重提创建新资料版本和新审核单，不覆盖被拒版本，也不修改历史订单、奖励或已生效人员。
6.3 草稿、弱网与异常
- 每个步骤自动保存草稿；上传失败不清空字段，支持单图重试和断点恢复。
- 提交使用幂等键；重复提交不能创建重复记录。
- 已存在手机号、完全相同门店名称、越区录入、收款账户格式不正确或证据不完整时阻止提交并提示业务支持；重复门店校验一期仅覆盖去除首尾空白后的完全相同门店名称，并在提交接口二次执行。
- Merchant / Store 主数据创建和 Store 准入审核由后台受控流程处理；H5 只提交资料，不直接写入或启用主数据。店长/店员资料、账号和门店关系审核由《06B-门店人员信息审核迭代需求》承接。正式建档或账号激活必须消费各自审核结果，
SUBMITTED不能直接生效。
7. SA App 集成与接口
| 能力 | 接口/Bridge | 关键约束 |
|---|---|---|
| 会话 | POST /sa-h5/session/exchange | 使用一次性授权码换短期会话，URL 不携带身份主键/令牌 |
| 身份上下文 | GET /me/context | 服务端返回角色、组织、数据范围和功能权限 |
| 收益/订单 | GET /earnings/summary、GET /orders | 服务端返回金额、归属 SA、逾期与分页快照 |
| 绩效/政策 | GET /performance/current、GET /incentive-policies/current | 返回档位、进度、风险系数状态和明确边界 |
| 门店资料 | POST/PATCH /store-submissions、POST /uploads/presign、POST /store-submissions/{id}/submit | SA/SM/RM 按服务端授权范围操作；一期 Merchant 信息仅收集名称，不要求 CAC；服务端校验精确门店名称重复、收款账户格式/归属、区域和提交人并保留角色/范围审计 |
| 宿主能力 | Back、Close、Camera/Album、Save image、Network、Re-auth | Bridge 白名单、来源校验、失败可降级 |
8. 非功能与验收
- 适配低端 Android 与尼日利亚弱网：骨架屏、请求重试、图片压缩、懒加载、缓存与明确离线提示。
- 所有敏感资料脱敏展示；照片不进入普通日志、排行榜或非授权导出。
- SA/SM/RM 权限与 Stores 数据范围由服务端会话强校验，前端隐藏不构成权限控制。
- SM/RM 可按 SA 筛选并识别订单来源，且不会看到 SA 的个人佣金金额。
- SA/SM/RM 可在各自授权范围内完成“Merchant Information → Store → Manager → Clerks → Review”的门店资料提交；一期 Merchant 仅填写名称、不上传 CAC；门店名称完全相同即拦截，门店正面照、收款银行/账户名/10 位账号和店长与提交人同框照为必需，店员步骤可跳过；任何必传材料缺失、已添加店员未上传必需照片或校验失败时不能提交。
- SM/RM 直接办单时，订单详情和汇总分别展示直办奖励与本人岗位奖励，金额叠加与 10 的台账一致。
- 生产环境无手机壳、无调试入口，返回行为在 App 内与 Web 降级场景均可用。