V2 SA团队目标与订单激励H5需求
1. 背景与目标
现有收益页面可帮助销售查看收益结果，但不能让每位销售持续了解本期目标、当前进度及其在团队中的位置。V2 在 SA App 内新增受控的 H5 联登入口和团队目标展示能力，使每个销售都能清楚知道：本期目标是什么、已完成多少、已获得哪些订单激励，以及在当前团队中的排名。
本期目标：
- SA 可查看本人本期订单激励明细、个人目标进度及在当前团队中的排名。
- SP（团队主管）可查看其直属 SA 团队的业绩、团队目标和目标差距。
- SM（区域经理）可查看其授权区域内团队的业绩、团队目标和目标差距。
- App 与 H5 之间使用受控登录态；H5 只展示服务端计算和授权后的结果，不自行计算激励、目标、排名或团队差距。
1.1 V2 当前激励政策展示口径
H5 通过 BI 返回的已发布政策版本展示以下激励结果；BI 是唯一计算方，页面不以订单列表、客户端时间或前端阈值重新计算。
| 类别 | 当前政策 / 展示要求 |
|---|---|
| 订单激励 | 开单奖励、每日首单奖、每日尾单奖、周销冠军/亚军/季军均按 BI 返回的命中组件、金额和状态逐单或逐日展示 |
| SA 梯度绩效 | 合格订单 <40：₦850/单；40–47：₦1,100/单；≥48：₦1,300/单 |
| SP 梯度绩效 | BI 返回当前发布的三档金额 ₦100 / ₦110 / ₦120，以及各档适用条件；前端不得套用 SA 的 40/48 边界 |
| SM 梯度绩效 | BI 返回当前发布的三档金额 ₦25 / ₦30 / ₦35，以及各档适用条件；前端不得套用 SA 的 40/48 边界 |
| SP/SM 自主办单 | 同一自主订单展示固定 ₦850 直办奖励与本岗位梯度绩效两个组件，二者只叠加一次 |
| CPD 最终调整 | BI 返回 CPD 系数、调整金额、结果状态和最终佣金；WAITING_CPD 时不得将预计数写为最终佣金 |
SA 与 SP 的个人月度基础任务为 40 个合格订单。SP 团队目标为当前有效直属 SA 的个人目标之和；SM 不设个人 40 单任务，展示其授权区域团队目标、当前业绩及目标差距。排名以当月已确认合格订单为口径：SA 在直属 SP 团队内按个人业绩排名，SP 在所属 SM 范围内按直属团队业绩排名，SM 按区域团队业绩排名；并列规则、人数和快照时间由 BI 返回。
2. 适用范围与非目标
2.1 本期范围
- SA App 提供“Team performance / Incentives”H5 联登入口。
- SA、SP、SM 根据服务端会话和数据范围进入同一 H5，但展示各自授权页面。
- 支持按当前业务月查看个人或团队目标、进度、排名、订单激励与团队业绩。
- 支持服务端已开放的历史业务月查询；默认当前
Africa/Lagos业务月。
2.2 非本期范围
- 不新增 H5 自助登录、注册、退出登录、个人中心或独立 H5 底部导航。
- 不改变佣金资格、激励规则、绩效系数、结算、付款、组织关系或目标配置规则。
- 不在 H5 创建、修改或审批个人目标、团队目标、组织关系或激励台账。
- 不向 SA 展示其他 SA 的订单、客户资料或个人激励金额；不以 H5 查询参数传递角色、人员 ID、团队 ID 或 token。
3. 角色、术语与数据范围
本需求中角色名称以本期业务定义为准：SA 为销售；SP 为团队主管；SM 为区域经理。既有系统如仍存在 SA_MANAGER、REGIONAL_MANAGER 等历史角色编码，须由身份/组织服务在服务端完成 V2 角色映射；前端不得依据旧编码、页面参数或本地缓存自行推断角色。
| 角色 | 可查看范围 | 禁止查看 |
|---|---|---|
| SA | 本人订单激励、本人目标、本人完成进度、本人在直属 SP 当前有效团队内的排名 | 其他 SA 的订单、客户资料、个人激励金额；团队成员明细 |
| SP | 本人直属且当前有效的 SA 团队汇总、每名 SA 的目标进度和排名 | 非本团队数据；SA 的订单激励金额明细；其他 SP 团队数据 |
| SM | 当前授权区域内 SP 团队汇总、区域目标进度和目标差距；可下钻至获授权团队的目标进度和排名 | 授权区域外数据；SA 的订单激励金额明细 |
组织范围、上下级关系和人员有效性以查询快照时点的组织服务结果为准。人员调岗、离职、组织调整或补录不得回写已生成的订单激励台账；当期目标看板须返回明确的范围快照时间。
4. App H5 联登入口
4.1 启动流程
SA App 点击 Team performance / Incentives
→ App 调用 WebView Bridge 打开 H5
→ App 提供一次性授权码
→ H5 以授权码换取短期会话
→ 服务端返回本人身份、V2 角色、授权范围和默认业务月
→ H5 加载对应页面- App 是唯一登录入口。H5 不展示手机号、OTP、密码或角色选择页。
- 一次性授权码只能使用一次、短时有效；授权码、会话 token、人员 ID、团队 ID 均不得出现在 URL、页面日志、埋点参数或持久化浏览器存储中。
- 会话失效、授权码无效或组织范围不可确认时，H5 停止加载业务数据，提示“Session expired. Return to the app and try again.”，并调用 App 重新授权或返回能力。
- 服务端必须从会话确定
person_id、V2 角色、有效组织范围和数据权限；前端隐藏模块不能替代权限校验。
4.2 页面入口与导航
- 页面使用 SA App 内嵌紧凑返回栏；返回、关闭、网络状态和重新授权由 WebView Bridge 处理。
- 生产环境不展示角色切换、Mock 开关、手机壳、调试入口或独立 H5 的 Profile/底部导航。
- 首屏默认打开
Overview。SA 可进入My incentives；SP/SM 可进入Team performance。所有页面共享同一业务月和同一服务端快照版本。
5. SA 页面
5.1 个人目标与排名概览
SA 首屏必须展示：
| 区域 | 展示内容 |
|---|---|
| 本期目标 | 目标名称、指标单位、目标值、当前完成值、完成率、距目标差值、数据更新时间 |
| 团队排名 | 当前排名 / 有效参与排名人数、排名口径、范围为当前直属 SP 的有效 SA 团队、快照时间 |
| 目标状态 | 未达标、已达标或超额完成；无目标/无排名资格时显示明确不可用原因 |
| 入口 | 进入本人订单激励明细 |
- 目标的指标类型、单位、目标值、完成值、完成率、差值及状态均由服务端返回。指标可以是合格订单数、放款金额或运营配置的其他已发布目标指标；前端不使用金额或订单列表重新计算。
- 团队排名按同一目标指标、同一业务月、同一组织范围快照排序。服务端返回排名规则、排名值、参与人数和并列规则；默认采用竞赛排名（例如
1、2、2、4）。 - 排名仅显示 SA 本人的位置与参与人数，不展示其他成员姓名、订单、目标值或激励金额。
- 首屏必须将“预计绩效金额”作为醒目金额卡展示，明确标记
Estimated、Confirmed或Waiting for CPD；仅 BI 已返回最终结果时才展示最终佣金，不能把待确认金额伪装为最终金额。 - 当前梯度激励必须以连续的三档视觉阶梯展示，突出当前命中档和下一档的奖励变化；SP/SM 的档位名称和门槛仅使用 BI 政策快照。
5.1.1 排名详情与目标时间窗口
- 首页排名卡可进入排名详情页。详情页展示本人所在排名范围、本人排名、参与人数、距上一名的合格订单差距，以及排行榜中的脱敏显示名、排名和同口径合格订单数。
- 排行榜姓名由 BI/BFF 脱敏，例如
Samuel A.；H5 不接收完整姓名、手机号、客户资料或他人个人激励金额。 - 目标未完成时，个人和团队目标卡必须展示目标截止时间窗口、剩余自然日、目标差距和达到目标所需的日均合格订单数。上述值均由 BI 返回；H5 不以本机时间或现有列表计算。
5.2 我的订单激励明细
列表仅展示当前 SA 本人在当前业务月内、服务端已授权返回的订单激励记录。每行至少包含：
- 订单号脱敏标识、订单资格时间、产品/SKU 摘要；
- 当前订单对目标的计入状态及计入值；
- 激励组件名称、当前 SA 的激励金额、币种、激励状态；
- 快照/待确认说明，例如
Estimated、Waiting for risk factor、Reversed。
金额、目标计入、资格状态、冲正状态和激励状态必须来自同一服务端台账/目标快照。订单取消、资格撤销或风险结果未确认时，页面按服务端状态展示，不以客户端日期、还款日或列表合计推断。
支持按业务月、订单资格时间、订单状态、目标计入状态和激励状态筛选及分页。列表汇总仅可展示服务端返回的完整筛选结果汇总；加载更多不得改变汇总口径。
6. SP 与 SM 团队页面
6.1 团队业绩概览
SP 查看直属 SA 团队；SM 查看授权区域内全部有效 SP 团队及其 SA 汇总。页面至少展示：
| 指标 | 说明 |
|---|---|
| 团队目标 | 当前业务月的目标名称、指标单位和目标值 |
| 当前业绩 | 同口径的实际完成值、完成率和更新时间 |
| 目标差距 | 服务端返回的未完成差距；已超额时显示超额完成值，不显示负差距 |
| 团队构成 | 有效 SA 人数、已达标人数、未达标人数、无目标/数据待确认人数 |
| 进度分布 | 按运营返回的进度区间汇总人数，用于识别需要辅导的团队状态 |
团队目标、当前业绩、差距、完成率、达标人数和进度分布必须共享同一目标版本、同一统计口径、同一业务月及同一范围快照。H5 不执行 目标 - 业绩、百分比或分组汇总计算。
6.2 团队明细
- SP 可查看直属 SA 的脱敏姓名/员工显示名、排名、目标进度、目标状态和最近刷新时间。
- SM 先查看 SP 团队卡片（团队名称/主管显示名、目标、业绩、差距、完成率、有效 SA 人数）；可在授权范围内下钻查看该团队的 SA 目标进度与排名。
- SM 的首页必须显示每个获授权 SP 团队的目标、当前完成、明确目标差距、剩余天数及日均补足量，按 BI 返回的团队范围展示。
- 团队明细不展示任一 SA 的订单行、客户资料、个人订单激励金额、收款信息或风险明细。
- 仅支持服务端已授权的业务月、区域、SP 团队及状态筛选。SM 切换团队或区域必须由服务端重新校验，不能依赖前端已加载的数据。
6.3 空态与异常状态
| 场景 | 页面处理 |
|---|---|
| 当前无有效团队关系 | 展示“Team assignment is not available.”，不显示缓存团队数据 |
| 目标尚未发布 | 展示“Target is not published for this period.”；不以 0 作为目标 |
| 业绩数据等待确认 | 展示数据待确认时间和刷新入口；不将未知值视为 0 |
| 无排名资格 | 展示服务端返回的原因，例如未纳入本期目标范围 |
| 网络/接口失败 | 保留已标记时间的可用缓存摘要并显示离线提示；不展示过期数据为实时结果 |
7. 服务端数据与接口契约
本节定义 H5 所需的能力边界，不要求前端直接连接佣金、目标或组织数据源。H5 通过 BFF/聚合服务调用，BFF 负责会话、角色、权限、组织范围、数据拼装、脱敏、快照一致性与审计。
| 能力 | 建议接口 | 必须返回/校验 |
|---|---|---|
| App 会话交换 | POST /sa-h5/session/exchange | 一次性授权码换短期会话；服务端确定身份与角色 |
| 身份与范围 | GET /me/team-performance-context | V2 角色、有效组织范围、默认/可选业务月、权限、范围快照时间 |
| SA 概览 | GET /team-performance/me/overview | 个人目标快照、本人排名、参与人数、口径和更新时间 |
| SA 激励明细 | GET /team-performance/me/incentives | 仅本人授权订单激励、目标计入状态、筛选汇总与分页快照 |
| 团队概览 | GET /team-performance/overview | SP/SM 授权范围内目标、业绩、差距、分布和范围快照 |
| 团队进度 | GET /team-performance/members | 授权团队的 SA 目标进度/排名；不返回 SA 激励金额或订单明细 |
接口金额使用十进制字符串和 ISO 币种，日期使用 ISO-8601，业务月及显示时间以 Africa/Lagos 为准。排名快照额外返回脱敏排名条目、本人距上一名差距、排名口径和并列规则；未达标目标额外返回截止时间、剩余天数及所需日均合格订单。枚举未知、口径缺失、目标版本冲突或组织范围无法确认时，BFF 返回可安全展示的不可用状态，不返回部分越权数据，也不由 H5 兜底猜测。
8. 数据口径、隐私与审计
- 订单激励以佣金台账及其资格、组织、政策、风险/结算快照为准；H5 只读展示，不能修改或重算。
- 个人及团队目标以运营已发布的目标版本为准；目标版本、指标定义、业务月、范围快照时间和数据更新时间必须可追溯。
- 团队实际业绩只纳入服务端确认的、符合该目标口径的记录；等待确认、冲正、取消或未知状态如何计入必须由目标服务返回明确状态和数值。
- SA 的订单激励金额属于个人敏感经营数据，仅本人可见。SP/SM 的团队页面仅展示团队聚合、成员目标进度与排名，不展示 SA 个人激励金额或订单明细。
- 订单号、客户信息、手机号、收款账户、token 和完整组织主键不得出现在 URL、埋点、普通日志、下载文件或非授权页面。显示层遵循服务端脱敏结果。
- 服务端记录 H5 会话交换、范围拒绝、团队/成员查询、业务月筛选和导出尝试（本期不提供导出）的审计事件；审计记录不含 token、完整手机号、客户资料或订单激励金额明细。
9. 验收标准
- SA App 可通过一次性授权码打开 H5；H5 不提供独立登录，且 URL 中不含 token、角色、人员或团队标识。
- SA 在当前业务月可看到本人目标、完成进度、在直属 SP 有效 SA 团队中的排名和本人订单激励明细；无法看到其他 SA 的数据。
- SA 排名、目标和订单激励均带服务端返回的业务月/快照时间；切换月份后所有模块使用同一业务月和同一口径，不发生前端重算。
- SP 能看到直属团队的目标、业绩、目标差距、完成分布及各 SA 的目标进度/排名，但看不到 SA 的订单激励金额或订单明细。
- SM 能看到授权区域内 SP 团队的业绩、团队目标和目标差距，并只能下钻至已授权团队；越区团队或成员请求被服务端拒绝。
- 目标未发布、组织关系无效、排名无资格、数据待确认、网络失败和会话失效均有明确且安全的页面状态；未知数据不得被当作 0、已达标或实时数据。
- 订单撤销、风险待确认、政策/组织快照变化后，页面展示服务端状态；客户端不通过订单列表、时间或金额自行改变激励、排名、目标完成或团队差距。
- 在低网络条件下，概览、排名、激励明细和团队业绩模块独立加载；失败模块可重试且不会阻塞已授权的其他模块。
10. 上线前待确认项
- V2 的 SP/SM 角色编码与既有
SA_MANAGER/REGIONAL_MANAGER编码的正式映射，以及映射生效时间。 - 每类目标的指标定义、统计口径、目标来源、发布节奏、目标版本和排名参与资格。
- “当前团队”在 SA、SP、SM 三个层级的有效组织关系取数时点，以及调岗/离职当月的展示规则。
- 订单资格、撤销、风险待确认对目标业绩、排名和团队差距的最终计入口径。
- App WebView Bridge 的授权码传递、返回/关闭、重新授权、网络状态和错误兜底协议。