袋鼠金融蓝图

Properties1
tags需求, pocketbuy, 门店, 店长, 店员, 人员审核, 资料版本, 审计

门店人员信息审核迭代需求

1. 文档定位与责任边界

本文档描述 SA 通过 SA App 内嵌 Stores H5 录入或维护店长、店员后，后台如何接收资料版本、审核人员身份及门店关系、控制生效、处理转店/换店长/停用并保存审计记录。

本文档负责门店人员主数据、关系与审核，不负责门店基础资料审批、RM → SM → SA 组织关系、佣金计算或门店端收益展示。相关边界如下：

  • SA 端资料录入、草稿与提交：见《08-PocketBuy SA、SM、RM端 H5 需求文档》。
  • 店长/店员登录及只读展示：见《07-PocketBuy门店端H5需求文档》。
  • 正式关系向下游提供有效期事实：见《09-PocketBuy 佣金系统外围配合改造功能点》。
  • 资格时点受益人及不可变台账：见《10-PocketBuy 佣金系统需求文档》。
  • SA、SM、RM 角色与层级：见《06A-SA角色与组织层级管理迭代需求》。

门店资料提交成功只表示服务端已接收，不代表门店、店长、店员、登录账号、二维码或佣金归属已经生效。

2. 设计状态与原型地址

  • 文档状态：draft；建设范围：mvp。
  • 设计状态：prototype_available，对应后台审核页已有可交互原型。
  • 生产预览：后台管理原型；进入后选择 PocketBuy Operations → Store Personnel Review。查看门店人员汇总时可进入 Store Management → Store detail → Store Personnel。
  • 本地预览：127.0.0.1:8776；需先在后台原型目录启动静态服务。
  • 原型目录：D:\Africa\blueprint\12-迭代需求管理\11-后台管理需求\后台原型。

生产预览地址已于 2026-08-10 验证可访问。当前原型没有页面级深链；正式权限、字段和状态以本文档及服务端接口为准。

3. 背景、目标与范围

SA App 的 Stores H5 已承担 SA/SM/RM 授权范围内的门店、店长和店员资料录入，但提交态与正式生效态需要隔离。若直接把提交资料用于登录、订单归属或佣金计算，会造成重复手机号、跨店绑定、无效店长关系和历史归属被覆盖。

本期目标：

  1. 建立店长/店员人员、门店关系、核验资料和审核单的独立版本。
  2. 提供 Store → Store Manager → Clerk 的关系树和列表审核工作台。
  3. 支持通过、驳回、重提、转交、停用、转店和更换主店长。
  4. 仅将满足全部生效条件的关系提供给登录、办单、二维码和佣金系统。
  5. 保留历史资料、关系、审核和敏感访问记录。

本期不包含：门店基础信息审批流程；门店端自行编辑人员资料；多个店长或副店长；线上申诉；自动根据手机号或备注推断人员关系。本期每个门店仅支持一名有效店长。

4. 角色、来源与数据流

参与方能力不允许的操作
SA/SM/RM在 Stores H5 新增、保存、提交和维护本人服务端授权范围内的门店、店长和店员资料越出本人门店/团队/区域范围，自审、自行激活账号、覆盖历史版本
后台审核员查看资料与证据，审核、驳回、转交修改 BVN/银行/人脸等强实名结果，绕过冲突校验
后台管理员按权限停用、转店、更换主店长、处理异常物理删除人员/关系/审核历史
店长/店员审核生效后登录门店端 H5 并只读查看资料状态在门店端修改主数据或关系
flowchart LR
    H5["SA/SM/RM Stores H5 草稿/提交"] --> Submission["资料提交版本"]
    Submission --> Review["后台人员审核"]
    Review -->|驳回| H5
    Review -->|通过| Effective["有效人员与门店关系"]
    Effective --> StoreH5["门店端登录/只读展示"]
    Effective --> BNS["办单与推荐证据"]
    Effective --> Commission["佣金资格时点快照"]

来源统一为 SA_CREATED、SA_UPDATED、SM_CREATED、SM_UPDATED、RM_CREATED、RM_UPDATED、OPERATIONS_MIGRATED。提交和审核均保留创建人/更新人角色、人员 ID、授权范围、版本、时间和操作人。

5. 对象、关系与状态模型

5.1 审核对象

  • 店长身份与账号信息。
  • 店长与门店的主店长关系。
  • 店员身份与账号信息。
  • 店员与店长、门店的关系。
  • 店员工牌资料及每次重新提交的资料版本。

门店基础信息审核与人员审核相互独立：门店通过不代表人员通过，人员通过也不能使未通过或已停用的门店生效。

5.2 状态分层

不得用一个 status 同时表示提交、审核、账号、关系和门店状态：

状态维度状态说明
H5 提交DRAFT / SUBMITTING / SUBMITTED / SUBMIT_FAILED仅表示资料保存和接收结果，与 08 一致
人员审核NOT_SUBMITTED / PENDING_REVIEW / APPROVED / REJECTED表示当前资料版本的审核结果
账号PENDING_ACTIVATION / ACTIVE / DISABLED表示是否可登录；审核通过不等于已激活
门店关系PENDING_REVIEW / ACTIVE / INACTIVE表示人员与门店/店长关系是否在有效期内
工牌审核NOT_REQUIRED / PENDING_REVIEW / APPROVED / REJECTED仅适用于要求工牌的店员

旧文档中把 DISABLED 同时作为人员审核状态的写法不再使用；停用属于账号或关系状态，审核结果仍保留为 APPROVED，从而可以解释“曾审核通过但后来被停用”。页面另输出只读的 effective_status：仅当人员审核为 APPROVED、账号为 ACTIVE、关系为 ACTIVE、门店审核通过且门店有效，以及适用时工牌审核通过，才为 ACTIVE。该字段是新登录/新归属是否允许的最终结论，不反写任一上游状态。

5.3 关系约束

  • 每个门店同一时刻有且仅有一个有效主店长。
  • 本期没有副店长、协同店长或多店长角色；再次提交其他店长必须走“更换主店长”，先关闭原关系后才能生效新关系。
  • 一个店员同一时刻只能有一个有效门店关系；其店长必须是该门店当前有效主店长。
  • 转店、更换店长和更换主店长必须关闭原关系有效期并新增关系，不能覆盖原记录。
  • 手机号同一时刻只能绑定一个有效人员账号；重复或疑似同人进入人工复核。
  • 门店停用后禁止人员新增业务，历史人员、关系、订单和佣金快照不变。

6. SA/SM/RM Stores H5 提交契约

SA、SM、RM 可在服务端会话授权的数据范围内录入门店、店长和店员资料。SA 范围为本人获授权门店，SM 范围为本人管理团队/区域，RM 范围为本人授权区域；范围由服务端返回并校验，不能信任前端角色或区域参数。可录入店长姓名、手机号、门店关系，以及店员姓名、手机号、店长关系、工牌照片/编号/说明和要求的核验资料。每一步可保存草稿；提交使用幂等键；失败可重试且不清空已上传资料。

服务端接收成功返回 submission_id、profile_version、接收时间和 SUBMITTED，随后创建或关联 PENDING_REVIEW 审核单。已提交版本默认只读；SA 修改被驳回或已生效资料时创建新版本，不原地覆盖。

以下情况在提交阶段阻止或标记人工复核：手机号已被有效账号占用、人员存在其他有效门店关系、越出提交人授权范围、必填证据缺失、店长关系无效、资料版本已过期。

7. 后台页面与交互

7.1 Store Personnel Review

默认 Tree 展示 Store → Store Manager → Clerk，并保留 List 切换：

  • Tree 用于理解门店、主店长和店员关系；List 用于按角色、来源、审核/账号/关系/工牌状态、提交时间和审核人筛选。
  • 选中节点后在详情区展示当前版本、提交批次、提交人及角色、人员审核、账号、关系、工牌、effective_status、生效条件、冲突、历史版本和审核时间线，并保留审核/停用/变更操作。
  • 对来源为 SA_CREATED/SA_UPDATED/SM_CREATED/SM_UPDATED/RM_CREATED/RM_UPDATED 的人员，详情和审核弹窗必须展示提交人上传的门店正面照、店长与提交人合照、店员与提交人合照等文件名、file_id、上传时间和受控预览；无店员的提交显示“本次未提交店员”，不能被误判为缺少店长或门店材料。
  • 审核页须显示店长关联提示：审核店长时查询该店长已关联的门店；审核店员时查询其指定店长已关联的门店。提示至少展示门店 ID、门店名称、人员关系和 effective_status。发现店长同时存在多个有效主店长关系、店员指定的店长不在当前门店有效，或关系待审核/停用时，审批按钮必须提示冲突并按规则阻止或转人工复核。
  • 列表和树默认脱敏姓名与手机号；BVN 不在列表或导出中出现。

7.2 Store Management → Store Personnel

门店详情展示当前及历史主店长/店员、账号状态、关系状态与有效期、人员审核、工牌审核、来源、加入时间、最近登录、最近审核及驳回原因。该页用于门店维度汇总，不替代审核工作台。

7.3 审核详情

展示提交版本、字段差异、图片/工牌证据、重复手机号/跨店冲突、门店和主店长状态、历史审核及操作审计。若门店提交因门店资料审核被拒绝，SA 端只显示可反馈原因、审核时间和重提入口；审核人端保留完整内部审计与证据。审核操作只能更新“人员审核”；审核通过后由服务端原子激活账号和关系。停用只能更新账号/关系，不能把已通过的人员审核改写为 DISABLED。敏感原图默认加水印和遮罩，仅持有 store.personnel.sensitive.read 的人员可查看，查看行为留痕。

8. 审核、重提与停用流程

审核人可通过、驳回或转交。驳回必须选择标准原因并填写可反馈给 SA 的说明；通过前服务端校验门店有效、手机号唯一、关系唯一、主店长合法、资料完整、工牌满足要求且当前版本未被新版本替代。

重提规则：

  • REJECTED 版本保持只读；SA 修改后生成新 profile_version 和新审核单。
  • 审核期间再次提交新版本时，旧审核单标记 SUPERSEDED 结束原因但保留原审核状态和历史，不允许继续审批旧版本。
  • 重复审核请求使用审核单版本和幂等键，不能产生两个最终结果。

停用规则：

  • 仅对已通过的账号或关系执行，必须填写原因和生效时间。
  • 停用后禁止登录、新订单归属和新二维码使用，不取消或改写历史订单、奖励及结算。
  • 恢复需重新校验人员、门店、关系和必要资料；高风险停用/恢复建议复核。

9. 生效条件与下游输出

人员参与登录、办单、推荐或订单归属必须同时满足：

  1. 当前资料版本的人员审核为 APPROVED。
  2. 账号为 ACTIVE。
  3. 门店关系在当前时点为 ACTIVE。
  4. 门店审核通过且门店状态有效。
  5. 要求工牌的店员，其工牌审核为 APPROVED。
  6. 店长/店员关系不存在未解决冲突。

门店端 H5 只读消费上述生效结果；不满足时统一提示联系 SA 或客服，不暴露内部风控策略。组织/运营域向 BNS 和佣金系统输出人员、门店、角色、关系版本、valid_from、valid_to 和状态。佣金系统只在资格事件时固化有效关系；后续编辑、转店或停用不得回写历史快照。

10. 人员变更场景

场景当前数据处理历史订单/佣金
增加店员新建资料版本和待审核关系审核生效前不可成为新归属
修改联系/工牌资料新版本审核；高风险字段按规则暂停生效不回写历史快照
店员更换店长关闭旧关系并新增待审核关系原资格时点归属不变
店员转店校验无其他有效关系，按生效时间切换转店前后分别按资格时点关系固化
更换主店长必须先处理原主店长和下属承接，建议双人复核历史主店长佣金不转移
停用人员/门店禁止新增业务和登录已固化台账不变；退款冲正原受益人

11. 服务端模型、接口与权限

建议实体：门店人员、门店人员关系、人员资料版本、工牌资料版本、审核单、审核动作、账号激活记录和操作审计日志。手机号、BVN、银行卡等敏感字段加密存储并按权限脱敏；所有版本和关系不得物理删除。

接口能力：查询门店人员树/列表/详情与历史；提交资料版本；审核、驳回、转交；停用/恢复；转店/换店长/更换主店长影响预览与提交；查询审计日志。所有写接口校验权限、对象版本、状态、关系合法性和幂等键。

权限点说明
store.personnel.read查看门店人员及脱敏资料
store.personnel.sensitive.read查看受控敏感材料
store.personnel.review审核、驳回和转交
store.personnel.disable停用/恢复账号或关系
store.personnel.relation.update转店、换店长、更换主店长
audit.log.read / audit.log.export查询/导出审计

12. 审计、异常与安全

审计记录 SA/SM/RM 提交/重提、审核、驳回、转交、账号激活/停用、主店长变更、店员转店/换店长、敏感查看和导出。至少包含操作人及角色、授权范围、对象、版本、前后值、原因、生效时间、结果、错误码、幂等键和 trace_id；日志仅保存脱敏值或字段变更标记。

异常处理：

  • 同一店员已在其他门店有效：不覆盖，进入人工复核。
  • 同一门店出现多个主店长：阻止新关系生效。
  • 审核期间出现更新版本：旧单终止为被替代，不允许继续操作。
  • 门店审核撤销或门店停用：相关人员暂停新增业务，历史不变。
  • 关系生效部分失败：整体回滚或进入可恢复状态，禁止出现账号已激活但关系未生效。
  • 文件读取失败、恶意格式或超限：隔离文件并保留提交记录，不能绕过扫描直接审核。

13. 数据迁移、上线与监控

迁移现有店长、店员、门店关系、账号状态和可用核验资料；已停用人员及历史关系也必须迁移。无法确认来源或有效期的数据标记 OPERATIONS_MIGRATED 并进入核对清单，不直接推定审核通过。

上线前检查重复手机号、跨店人员、无主店长、多主店长、缺少工牌、已通过但未激活和历史有效期重叠。监控待审核量/时长、驳回率、重提率、冲突量、激活失败、关系生效失败、敏感访问及审计写入失败。回滚不得删除已产生的提交、审核、关系和审计记录。

14. 验收标准

  1. SA/SM/RM Stores H5 的 SUBMITTED 只创建资料版本和待审核单，不直接激活人员或参与佣金归属，越权/越区提交被服务端拒绝。
  2. Tree 默认展示 Store → Manager → Clerk，List 可切换；选中节点可查看详情并执行有权操作。
  3. 人员审核、账号、门店关系、工牌和门店状态相互独立，页面可解释未生效原因。
  4. 通过、驳回、重提、转交、停用、恢复、转店和更换主店长均保留版本与历史。
  5. 重复手机号、跨店有效关系、多主店长和过期版本被服务端阻止或进入人工复核。
  6. 店长/店员仅在全部条件满足后登录或成为新订单归属；07 只读消费生效结果。
  7. 人员调店、资料修改和停用不回写 09、10 定义的资格时点归属及佣金台账。
  8. 敏感资料按权限脱敏，查看/导出和所有写操作均可通过 trace_id 追溯。
  9. 任一门店同一时刻只能有一名有效店长；新增第二名店长被阻止，更换必须保留前后关系有效期。

15. 待业务确认

  1. 店员工牌是否为所有渠道必填，或由门店类型/区域配置决定。
  2. 主店长变更、跨店调动和批量停用是否强制双人复核；本文建议强制。
  3. 门店基础信息审批的责任系统和上线批次；本需求只消费其最终状态。

关系图谱