SA角色与组织层级管理迭代需求
1. 文档定位与责任边界
本文档描述 SA 入驻完成后的业务角色设置、RM → SM → SA 组织层级、人员异动、离职、历史关系和后台审计，是《01-SA入驻App流程需求》和《02-SA审核管理后台需求》的增量需求。
本文档只负责 SA、SM、RM 的角色与组织关系，不负责店长、店员资料及审核；后者见《06B-门店人员信息审核迭代需求》。佣金归属、绩效和结算计算见《10-PocketBuy 佣金系统需求文档》，外围数据契约见《09-PocketBuy 佣金系统外围配合改造功能点》，SA/SM/RM 的收益与政策展示见《08-PocketBuy SA、SM、RM端 H5 需求文档》。
本期不在 SA App 入驻流程中增加岗位或上级选择。SA、SM、RM 业务角色和组织关系均由有权限的后台人员设置；业务角色不自动授予后台管理权限。
2. 设计状态与原型地址
- 文档状态：
draft，表示需求待评审确认，不表示尚未形成方案。 - 建设范围：
mvp，表示本文列出的能力属于本期最小上线范围。 - 设计状态：
prototype_available，表示对应后台页面已有可交互原型；原型用于说明信息架构和交互，不替代服务端权限、状态机及数据契约。 - 生产预览：后台管理原型；进入后选择左侧
PocketBuy Operations → SA Organization。 - 本地预览：127.0.0.1:8776；需先在后台原型目录启动静态服务。
- 原型目录：
D:\Africa\blueprint\12-迭代需求管理\11-后台管理需求\后台原型。
生产预览地址已于 2026-08-10 验证可访问。当前原型没有页面级深链，必须通过左侧菜单进入；正式系统不得依赖原型前端状态作为授权依据。
3. 背景、目标与范围
现有 SA 管理主要覆盖入驻审核、培训状态和门店分配，无法完整表达 RM、SM、SA 的有效期关系，也缺少晋升、降级、调岗、跨区域调动和离职后的权限、在途业务及历史归属处理规则。
本期目标：
- 建立可查询、可变更、可按历史时点还原的 RM → SM → SA 组织模型。
- 支持角色、直属上级、区域和在职状态的受控变更。
- 人员异动前展示影响，生效时原子更新当前关系并保留历史版本。
- 明确数据权限、在途订单、佣金归属和绩效快照的边界。
- 所有高风险操作可审批、可追踪、不可无痕覆盖。
- SA、SM、RM 均可在授权范围内新建门店资料；新建流程先录入或选择 Merchant 信息，再录入 Store 信息，Store 仍须通过独立准入审核。SM、RM 可直接办单，直办奖励与本人岗位奖励按佣金规则叠加。
本期不包含：SA App 岗位选择；SM/RM 团队工作台；佣金比例、绩效阶梯和结算规则配置；店长、店员资料审核；独立 Excel 组织关系批量导入。
4. 角色与组织模型
| 角色 | 编码 | 业务职责 | 同时有效的直属上级 |
|---|---|---|---|
| SA 区域经理 | REGIONAL_MANAGER / RM | 管理授权区域及区域内 SM；可新建门店、直接办单 | 无 |
| SA 经理 | SA_MANAGER / SM | 管理直属 SA 团队；可新建门店、直接办单 | 1 个有效 RM |
| SA | SA | 展业、客户进件、订单跟进及新建门店资料 | 1 个有效 SM |
flowchart TD RM["区域经理 RM"] --> SM1["SA经理 SM"] RM --> SM2["SA经理 SM"] SM1 --> SA1["SA"] SM1 --> SA2["SA"] SM2 --> SA3["SA"]
统一约束：
- 不允许自关联、循环关系、RM → SA 跳级关系或同一时点多重有效上级。
- 同一人员同一时刻只能有一个 SA 组织业务角色；SA、SM、RM 的新建门店是其当前岗位的授权能力。SM/RM 直接办单不表示同时兼任 SA；直接办单的奖励叠加按 10 的组件防重规则处理。
- 新建门店的第一步为 Merchant 信息页：可搜索选择已有有效 Merchant，或录入 Merchant 名称、短名称和类型。录入新 Merchant 信息仅发起“Merchant + Store”资料提交；服务端完成名称规范化去重、权限及区域校验后，才创建或关联
sa_channel.merchant，不得由客户端自行生成 Merchant ID 或直接启用 Store。 - 跨区域调动必须校验目标上级、目标区域和操作者数据权限。
- 角色和关系使用
valid_from、valid_to管理，不直接覆盖已生效历史。 - 当前关系是有效期数据的查询结果，不是唯一事实来源；任何下游不得只保存一个可覆盖的
parent_id。
5. 后台信息架构与页面要求
5.1 SA Management 人员详情
展示当前业务角色、区域、直属上级、直属下属数量、在职状态、关系生效时间、历史角色/关系、最近异动和待生效异动。手机号默认脱敏；查看完整手机号需要敏感信息权限并留痕。
5.2 SA Organization
默认使用 Tree 展示 RM → SM → SA，同时保留 List 切换：
- Tree 用于查看关系、人数和选中节点详情；List 用于筛选、排序和查看有效期。
- 支持按区域、角色、在职状态、姓名、手机号、人员编号筛选。
- 支持输入历史时点，还原当时的有效组织结构。
- 选中节点后在详情区发起角色变更、上级变更、跨区域调动或离职；不使用只展示关系而无法操作的孤立树。
- 无对应权限时按钮隐藏或禁用，服务端仍必须再次校验。
5.3 Operation Audit Log
支持按人员、异动单号、操作人、动作、结果、时间和 trace_id 查询；敏感查看及导出本身也产生审计记录。
6. 角色与隶属关系变更
6.1 支持的变更
- SA 晋升为 SM；SM 降级为 SA；SM 晋升为 RM；RM 调整为 SM 或 SA。
- 同角色更换直属上级、同区域调动、跨区域调动。
- 存在直属下属时批量选择承接上级。
提交字段至少包含目标角色、目标上级、目标区域、生效时间、原因、下属处理方式、附件/审批单号和幂等键。目标为 RM 时不填直属上级；所有日期展示使用 DD/MM/YYYY，接口使用带时区的 ISO 8601 时间。
6.2 影响预览
提交前必须由服务端返回影响预览：当前/目标角色、失效/新增关系、受影响下属、待生效异动冲突、未完成订单、数据范围变化、在途业务处理和佣金/绩效归属口径。前端不得自行估算受影响数量。
6.3 校验与生效
- 人员、目标上级和区域必须有效；目标上级角色符合标准层级。
- 有未处理直属下属时不能直接完成降级、跨区域调动或离职。
- 同一人员只能有一笔相互冲突的待生效异动。
- 使用数据版本号处理并发；版本冲突提示刷新后重试。
- 同一幂等键重复提交返回同一异动单，不重复新增关系。
- 生效时关闭旧关系有效期并新增关系版本；角色、关系、承接和权限缓存更新必须原子执行或进入可恢复状态。
- 已生效变更不能删除，只能通过新的更正异动单修正。
高风险操作（RM 角色变更、跨区域调动、批量下属转移、离职）采用复核；提交人与复核人不得为同一人。
6.4 业务示例
以下示例中的人员、订单和时间均为说明数据。示例中的人员编号是稳定 person_id，前缀仅帮助识别变更前角色，晋升或降级时不得重新生成人员编号。时间以尼日利亚业务时区 Africa/Lagos 为准；“生效前/后”均以异动单的 effective_at 判断，而不是以提交或审批时间判断。
示例一：新入驻 SA 首次建立组织关系
背景：新入驻人员 Amina（SA-101）已经通过 SA 审核和培训，运营需要将其设置为 SA，并分配给 Lagos 区域的 SM Chidi（SM-010）。
操作：
- 运营在 Amina 详情页选择目标角色
SA、目标上级SM-010、目标区域LAGOS，生效时间为15/08/2026 09:00。 - 服务端校验 Chidi 为在职 SM，且其有效上级是 Lagos 区域 RM；Amina 当前没有其他有效角色或待生效异动。
- 复核通过后，到达生效时间新增 Amina 的角色记录和
SM-010 → SA-101关系记录。
结果：生效前 Amina 不属于任何 SM 的团队范围；生效后 Chidi 可以在授权页面看到 Amina 产生的新业务来源。生效前不存在的关系不能被补写到历史订单中。
示例二：SA 晋升为 SM，并承接原团队成员
背景：SA Bola（SA-205）隶属于 SM Chidi（SM-010）。Bola 晋升为 SM，晋升后直属 RM 为 Ade（RM-001），同时需要接管 Chidi 名下的两名 SA：SA-301、SA-302。
操作：
- 提交“SA 晋升 SM”异动，目标角色为
SA_MANAGER，目标上级为RM-001。 - 在影响预览中列明：Bola 原
SM-010 → SA-205关系将失效；新增RM-001 → SA-205；SA-301、SA-302的原直属关系将关闭并改为直属 Bola。 - 因涉及角色晋升和批量下属转移，异动必须由另一名有
sa.change.approve权限的人员复核。
结果：生效后 Bola 只保留 SM 组织角色，但仍可使用 SM 的直接办单权限；直接办单时获得直办奖励与 SM 岗位奖励，不创建虚假的下属 SA。SA-301、SA-302 的新订单进入 Bola 的团队范围。两名 SA 在生效前已经达到资格或已固化在途快照的订单，仍沿用原 Chidi 贡献链，不转给 Bola。
示例三：SM 降级为 SA，必须先处理直属下属
背景：SM Chidi（SM-010）因岗位调整降级为 SA，其名下仍有 SA-401、SA-402 两名直属 SA。
错误操作：只选择目标角色 SA，没有填写下属承接人。服务端必须拒绝提交，提示“存在 2 名未处理直属下属”。
正确操作：
- 运营选择由同一区域 SM Grace（
SM-011）承接SA-401、SA-402。 - 为 Chidi 指定新的有效直属 SM
SM-011。 - 生效时关闭
RM → SM-010、SM-010 → SA-401/402，新增SM-011 → SA-401/402和SM-011 → SM-010；Chidi 的稳定person_id仍为SM-010，业务角色变更为SA。
结果：关系变更必须作为一个整体生效。不能出现 Chidi 已降级但仍拥有直属 SA，或下属已经转移但 Chidi 角色尚未改变的中间状态。生效前团队绩效仍属于原组织快照，生效后新业务才进入 Grace 团队。
示例四：SA 在同一区域更换直属 SM
背景：SA Esther（SA-501）从 SM Chidi（SM-010）调整到同一 Lagos 区域的 SM Grace（SM-011），异动于 20/08/2026 00:00 生效。
时间线：
| 业务事件 | 时间 | 归属处理 |
|---|---|---|
订单 ORD-01 达到佣金资格 | 19/08/2026 18:00 | 固化 Esther、Chidi 及当时 RM，后续不改写 |
订单 ORD-02 已创建但未达到资格 | 19/08/2026 20:00 | 异动生效时固化原贡献链；之后达到资格仍归原组织快照 |
| Esther 更换直属 SM | 20/08/2026 00:00 | 关闭 SM-010 → SA-501，新增 SM-011 → SA-501 |
订单 ORD-03 创建并达到资格 | 20/08/2026 10:00 | 使用 Grace 所在的新组织关系 |
结果：当前组织树只显示 Esther 在 Grace 名下；历史时点查询仍能看到其曾隶属 Chidi。Chidi 和 Grace 的绩效报表不得同时计算同一订单。
示例五：SM 跨区域调动
背景：SM Fatima（SM-020）从 Lagos 区域调往 Abuja 区域，目标直属 RM 为 Musa（RM-002）。Fatima 名下有三名 SA，其中两名随同调动，一名留在 Lagos。
操作：
- 异动单分别指定
SA-601、SA-602随 Fatima 转入 Abuja，SA-603由 Lagos 的SM-011承接。 - 影响预览展示区域权限变化、三个下属的目标关系、未完成订单及在途快照数量。
- 服务端校验 Musa 是 Abuja 的有效 RM，随同调动人员不存在区域限制或其他待生效异动。
- 跨区域调动经不同人员复核后统一生效。
结果：Fatima 生效后不能再查看 Lagos 新增业务；只能在承接工作所需范围内处理此前指定的未完成待办。SA-601/602 的新业务进入 Abuja，SA-603 的新业务留在 Lagos；历史奖励仍按各自资格或在途快照处理。
示例六：SM 离职并完成团队与在途业务承接
背景：SM Grace（SM-011）计划于 31/08/2026 18:00 离职，名下有四名 SA 和 12 笔未完成业务。
操作：
- 运营为四名 SA 分别指定新上级，并为 12 笔未完成业务指定业务承接人。
- 影响预览区分“组织关系承接”和“业务待办承接”；两者不能用同一个模糊的“转移给某人”字段代替。
- 复核通过后，生效时关闭 Grace 的角色/组织关系、转移下属、生成在途快照、更新待办并注销 Grace 的登录会话。
结果：Grace 不能登录或新增业务；承接人可继续处理必要待办，但不会获得 Grace 的个人佣金、银行卡、KYC 或其他非必要敏感信息。Grace 生效前已取得的佣金仍保留在其名下，支付、冻结和追偿按财务及离职规则执行。
示例七：非法关系和并发变更被阻止
| 请求 | 服务端处理 |
|---|---|
| 将 SM 设置为自己的上级 | 拒绝，自关联 |
| 将 RM 调整到其下属 SM 名下 | 拒绝，将形成循环关系 |
直接建立 RM → SA | 拒绝，跳级关系 |
| 为同一 SA 在同一有效期建立两个 SM | 拒绝，多重有效上级 |
| 人员已有待生效跨区异动时再次提交降级 | 拒绝或进入冲突处理，不得覆盖前一异动 |
| 两名运营基于同一旧版本同时调整上级 | 仅第一笔成功；第二笔返回版本冲突并要求刷新 |
上述失败请求同样记录操作人、对象、失败原因、错误码和 trace_id，但不得生成角色、关系或佣金快照变更。
7. 在职状态与离职
| 状态 | 说明 | 登录/新业务 |
|---|---|---|
ACTIVE | 在职且业务资格满足 | 按权限允许 |
PENDING_CHANGE | 已有待生效调岗或离职 | 生效前维持原权限 |
LEFT | 已离职 | 禁止登录和新增业务 |
DISABLED | 风控、合规或运营停用 | 禁止登录和新增业务 |
离职申请必须包含生效时间、原因、直属下属承接人、未完成业务承接人和可选附件。生效后注销会话、停止新增客户/进件/订单/门店资料操作、关闭有效组织关系；历史订单、操作、奖励和结算记录不得删除或改名归属。
停用或离职不取消、回滚或自动改派已经提交的订单。承接人获得后续待办及完成业务所需权限，但不继承前任个人佣金、银行卡、KYC 等非必要敏感信息。
8. 数据权限、订单归属与绩效口径
统一采用“有效期组织关系 + 不可变资格时点快照 + 异动时在途快照”：
| 场景 | 处理规则 |
|---|---|
| 异动前已达到佣金资格 | 使用资格时点固化的 SA/SM/RM 归属，后续异动不回写 |
| 异动前已创建但未达到资格 | 异动生效时固化在途贡献链；达到资格后按该快照处理 |
| 异动后新建 | 使用新组织关系构建资格时点快照 |
| 后续取消、退款或质量追偿 | 冲正原受益人台账，不转给新上级或承接人 |
| 关系缺失、冲突或证据不完整 | 标记 PENDING_SNAPSHOT，重试仍失败进入 MANUAL_REVIEW，不得猜测或部分发放 |
| SM/RM 直接办单 | 固化实际办单人及其岗位；直办组件与本人 SM/RM 岗位组件叠加，不虚构下属关系 |
月度绩效按有效期和资格/在途快照拆分，同一订单不得同时计入原组织和新组织。报表可分别查看当前组织口径和资格时点历史口径，奖励结算默认使用历史口径。该约束与 09、10 中的不可变归属快照完全一致。
9. 服务端模型与接口契约
建议实体：人员角色历史、SA 组织关系、人员异动单、异动在途业务快照、审批记录和操作审计日志。所有历史记录追加保存，不物理删除。
接口能力：
- 查询当前/历史组织树及人员角色关系历史。
- 预览异动影响。
- 提交、复核、撤销未生效异动；提交离职及承接方案。
- 查询异动执行结果、异常恢复状态和审计日志。
变更接口必须校验权限、数据版本、关系合法性、状态、生效时间及幂等键，不信任前端原值。组织/运营域向佣金系统提供关系版本和有效期；佣金系统只消费并固化快照，不反向修改组织事实。
10. 权限与审计
| 权限点 | 说明 |
|---|---|
sa.role.read / sa.role.update | 查看/变更业务角色 |
sa.hierarchy.read / sa.hierarchy.update | 查看/变更组织关系 |
store.submission.create | SA/SM/RM 在各自服务端授权范围内新建门店资料，先选择或录入 Merchant 信息 |
order.create.direct | SA/SM/RM 直接办单；服务端记录实际办单角色 |
sa.employment.terminate | 提交离职 |
sa.change.approve | 复核高风险异动 |
audit.log.read / audit.log.export | 查询/导出审计 |
审计至少记录操作人及后台角色、来源/IP/设备、动作、对象、变更前后值、原因、审批单、生效时间、幂等键、结果、错误码和 trace_id。日志由服务端追加写入；不得记录明文密码、OTP、BVN、银行卡号或人脸数据。审计写入失败时，高风险变更失败关闭。
11. 异常、迁移、上线与回滚
- 上级在生效前离职、循环关系、目标区域失效、同人多笔冲突异动：阻止生效并进入待处理。
- 部分执行失败：整体回滚或保留可恢复事务状态，不允许当前关系与历史有效期不一致。
- 存量有效人员默认映射为
SA，不得自动推断 SM/RM；可确认的关系迁移为有效期记录，无法确认的进入核对清单。 - 上线前检查无上级 SA/SM、重复有效关系、循环关系和跨区域冲突；灰度监控异动失败、快照失败、待复核量和审计写入失败。
- 应用版本回滚不得删除已生效关系、异动单、快照和审计数据；通过兼容脚本继续读取。
12. 验收标准
- 可按权限设置 SA、SM、RM，并按生效时间查看当前和历史组织树。
- Tree 默认展示，List 可切换；选中节点可查看详情并执行有权操作。
- 自关联、循环、跳级、同一时点多上级和并发版本冲突均被服务端阻止。
- 晋升、降级、调岗、跨区域调动和离职均先显示服务端影响预览并保留完整历史。
- 有下属或未完成业务时必须配置承接；离职后不能登录或新增业务，历史数据不变。
- 资格前后订单使用正确组织或在途快照；关系缺失进入待复核，不错误归给新上级。
- 任意变更可反查操作人、原因、前后值、审批和执行结果；重复请求不产生重复关系。
- 与 08 的角色权限、09 的有效期关系、10 的资格时点归属快照保持一致。
- 业务示例中的晋升、降级、同区调动、跨区调动、离职承接和非法关系均可通过测试数据复现，并得到文档约定的关系版本、权限范围和快照结果。
- SA、SM、RM 可在授权范围内新建门店；Merchant 信息页可选择已有 Merchant 或录入新 Merchant 信息，名称重复或越区新建均被服务端拒绝。SM/RM 直办订单的奖励组件按 10 正确叠加且不重复。
13. 待业务确认
- 异动前在途订单是否全部沿用原贡献链；本文建议固化在途快照并沿用。
- 离职人员奖励的支付、冻结与追偿周期，由业务、财务、人力和合规确认。