SA管理后台需求

1. 文档定位

本文定义 PocketBuy SA 入驻审核管理后台能力，包括 SA 信息查看、审核处理、资料修改、培训状态标记、Merchant / Store 信息登记与批量导入、Store 准入审核、培训通过后的 Merchant / Store 归属维护、账号启停、各角色绩效统计/明细导出、权限控制和审计日志。

后台基于现有后台管理体系扩展：

需求目录：D:\Africa\blueprint\12-迭代需求管理\11-后台管理需求
原型目录：D:\Africa\blueprint\12-迭代需求管理\11-后台管理需求\后台原型

SA 审核管理是 PocketBuy 专项运营能力，首期不接入通用审批中心，只预留后续审批流扩展点。

2. 菜单与角色

新增菜单：

一级菜单	二级菜单	定位
PocketBuy Operations	SA Review Management	SA 入驻审核、培训、账号启停和资料维护
PocketBuy Operations	Merchant Management	Merchant 信息登记、查询、编辑、状态调整和批量导入
PocketBuy Operations	Store Management	Store 信息登记、查询、编辑、状态调整和批量导入
PocketBuy Operations	Performance Reports	店员、店长、SA、SM、RM 绩效统计与明细查询、导出

菜单权限：

sa.review.read：查看菜单、列表和详情。
sa.review.approve：审核通过、拒绝。
sa.profile.edit_rejected：修改 rejected 状态下的 SA 基础信息。
sa.training.update：标记培训状态。
sa.store.assign：在培训通过后维护 SA 归属 Merchant / Store。
sa.account.toggle：启用或停用 SA 账号。
sa.sensitive.read：查看敏感字段明文或敏感材料详情。
sa.material.upload：通过后台上传或替换 SA 图片材料，原因必填并写审计。
merchant.read、merchant.create、merchant.edit、merchant.status：分别控制 Merchant 查看、登记、编辑和状态调整。
store.read、store.create、store.edit、store.review、store.status：分别控制 Store 查看、登记、编辑、准入审核和状态调整。
store.submission.read、store.submission.convert：分别控制查看 SA/SM/RM 的 Merchant + Store 资料提交，以及完成去重校验后创建/关联 Merchant、创建待审核 Store 的受控转换。
commission.performance.read、commission.performance.export：分别控制五类角色绩效统计/明细查询与导出；导出权限不由普通列表查看权限隐式获得。

权限原则：

前端可按权限隐藏或禁用按钮，但所有操作必须由后端强校验。
rejected 状态下的资料修改仅特定权限人员可操作。
Merchant / Store 归属不是 SA 基础资料，不能通过 Edit Profile 修改；仅具备 sa.store.assign 权限的人员可在培训通过后维护。
Merchant / Store 信息登记与状态调整是独立管理能力，不能通过 SA 详情页的 Manage stores 新建或修改 Merchant / Store 主数据。
任何角色都不能在该页面修改 BVN、BVN KYC 结果、人脸比对结果、银行名称、NUBAN、银行校验结果。
Store 与 SA 图片材料必须通过后台文件上传能力维护，页面不得要求运营手工填写或维护图片 URL。

3. Merchant / Store 信息管理

3.1 数据源与页面边界

Merchant 主数据对应 sa_channel.merchant，Store 主数据对应 sa_channel.store，Store 通过 merchant_id 归属 Merchant。
Merchant / Store 状态变更统一写入 sa_channel.state_change_log，记录目标类型、目标 ID、变更前后状态、原因、操作人和时间。
Merchant Management、Store Management 负责主数据登记和管理；SA 详情页的 Manage stores 只消费已经存在且有效的 Merchant / Store，不得在分配过程中临时创建主数据。
页面展示数据为后台主数据；SA App 不展示平台审核规则、Merchant / Store 管理状态、收款校验结果或后台操作人。

3.1.1 SA/SM/RM 新建 Store 的 Merchant 信息提交

SA、SM、RM 通过 H5 的 Merchant Information → Store → Manager → Clerks → Review 流程发起资料；Merchant Information 是独立第一步，可搜索选择已有有效 Merchant，或录入新的 Merchant 名称、短名称、类型和必传 CAC Certificate。
H5 的“录入新 Merchant”仅保存到 store_submission 及其 Merchant 草稿，不直接写入 sa_channel.merchant，不允许客户端提供 merchant_id、store_id、状态或审核结果。
后台在 Store Management 查看来源为 SA/SM/RM submission 的资料。服务端完成 Merchant 名称规范化去重、CAC Certificate 文件类型/大小/可访问性、发起人角色/区域、材料完整性和幂等校验后，在受控事务中创建或关联 Merchant，再创建 Store；新 Store 固定为 review_status=pending、status=inactive。
同名 Merchant 命中时不得静默新建或合并：返回已有 Merchant 摘要供提交人选择或由运营处理；Store 审核和 Merchant 停用/启用仍由后台权限独立控制。
保存提交人 submitted_by_person_id、提交时角色、区域快照、来源和 submission ID。SM/RM 直接发起时记录其本人，不虚构为下属 SA，不改变组织关系、历史订单或佣金快照。

3.2 系统自动编号

单笔登记和批量导入均不允许前端填写、上传或覆盖 merchant_id、store_id。
Merchant 保存成功时由后端生成 MCH-{yyyyMMdd}-{6位流水号}；Store 保存成功时由后端生成 STORE-{yyyyMMdd}-{6位流水号}。
流水号必须由数据库序列、号段或其他并发安全的服务端机制生成，不能使用“查询最大值后加一”的非原子实现。
ID 在同一事务中生成并写入，必须全局唯一、生成后不可修改、删除后不可复用；批量导入预览中的 ID 仅为预分配结果，事务回滚后不得占用正式业务编号。
前端新建弹窗显示“保存后由系统生成”，详情、列表、导入结果和审计日志展示最终 ID。

3.3 Merchant Management

Merchant 字段与 sa_channel.merchant 对齐：

字段	登记规则
`merchant_id`	后端自动生成，前端只读
`merchant_name`	必填，最长 100，数据库唯一；保存前做大小写无关重复校验
`short_label`	可选，最长 50
`merchant_type`	可选，最长 20
`cac_certificate`	新 Merchant 单笔登记和 SA/SM/RM 新 Merchant 提交必填；存于 Merchant 附件关系而非 `sa_channel.merchant` 主表，保存私有文件 `file_id`、`storage_key`、文件名、类型、大小、上传人、时间和校验结果；仅接受 PDF、JPG、PNG、WEBP，单文件最多 10 MB
`status`	必填，`active` / `inactive`；默认 `active`
`created_at` / `updated_at`	数据库自动生成，详情只读展示

页面能力：

支持按 Merchant ID、名称、短名称、类型、状态查询。
支持单笔登记、编辑、详情新 Tab、批量导入、启用和停用。
单笔登记 Merchant 时 CAC Certificate 必填；详情展示可预览图片或下载受限 PDF 的文件摘要。编辑替换证书须保留旧附件、替换原因、操作人和时间，不覆盖审计记录。
merchant_name 冲突时禁止保存或导入，不自动合并或覆盖已有 Merchant。
停用 Merchant 必须填写原因。停用后禁止其下 Store 新启用、新 SA 绑定和新订单进件，但不级联改写 Store 原始状态，不删除既有 SA-Store 关系，不取消已提交订单。
Store 列表和详情同时展示 Store 自身状态与 Effective Status；Merchant 停用时，其下 Store 的 Effective Status 为 unavailable / merchant inactive。

3.4 Store Management

Store 字段与 sa_channel.store 对齐：

分组	字段
基础信息	`store_id`、`merchant_id`、`store_name`、`store_type`、`business_district`、`business_license`
门店材料	`exterior_photo`、`interior_photos`、`manager_owner_photo`
负责人	`owner_name`、`owner_phone`、`owner_nin`
收款账户	`payee_bvn`（非一期 SA 录入必填）、`payee_bank_account`、`payee_bank_code`、`payee_bank_name`、`payee_account_name`
经营与地址	`open_date`、`monthly_sales_avg`、`store_area`、`address`、`gps_location`、`state`、`city`
合作与合同	`cooperation_mode`、`deposit_amount`、`contract_sign_date`、`contract_valid_until`
管理字段	`review_status`、`review_date`、`status`、`created_at`、`updated_at`

字段和状态规则：

store_id 由后端自动生成；merchant_id、store_name、payee_bank_account、payee_account_name 必填。payee_bvn 保留为存量兼容字段，但一期 SA 录入不采集，也不得作为该流程的审核或激活前置条件。
payee_bank_account 为 10 位 NUBAN；仅通过长度校验不代表账户真实有效，后端仍须调用银行账户校验能力。若其他受控来源已提供 payee_bvn，才按 11 位数字校验和加密存储。
exterior_photo、interior_photos、manager_owner_photo 均为非必填图片字段，仅在单笔登记或导入后的 Store 编辑页补充；页面通过后台上传图片，保存 file_id、storage_key、文件名、上传人和上传时间等文件元数据，不允许运营手工填写图片链接。
interior_photos 允许多图，数据库如仍使用 JSON 字段，应保存文件元数据数组，而不是外部 URL 字符串数组。
review_status 支持 pending、approved、rejected；status 支持 active、inactive。单笔登记和批量导入新建 Store 时，后端统一写入 review_status=pending、status=inactive、review_date=null，前端不得允许录入或覆盖。
只有所属 Merchant 为 active 且 Store 为 approved + active 时，Effective Status 才是 available；pending 或 rejected Store 不允许绑定新 SA 或承接新订单。
Store 准入审核需 store.review 权限，审核通过时写入 review_status=approved、review_date=当前时间，并在所属 Merchant 为 active 时同步置为 active；审核拒绝时写入 review_status=rejected、status=inactive。审核原因必填并写入 state_change_log。
停用 Store 必须填写原因；停用后禁止新 SA 绑定和新订单进件，既有绑定、历史订单和已提交订单保留并继续原生命周期。
Store 重新启用时，后端必须复验所属 Merchant 为 active 且 Store 审核状态为 approved。

3.5 收款银行选择

可搜索银行选项来源为 bns_kasykredit.bns_support_bank_list，仅查询 status=1 的记录。
下拉支持按 bank_name、bank_code、nip 模糊搜索，选项展示 bank_name / bank_code。
选择银行后写入 payee_bank_name=bank_name、payee_bank_code=bank_code；银行代码由系统回填，前端不可手工修改。
bns_support_bank_list 不包含账户持有人姓名，因此不能用它作为 payee_account_name 的选项来源。payee_account_name 表示真实账户户名，应由 NUBAN 账户校验接口返回并回填；如因第三方异常允许人工暂存，必须保持“待校验”，不能视为验证通过。
银行列表在后端统一查询和缓存；页面不得把 334 条银行记录硬编码为最终生产数据，缓存失效时回源数据库。

3.6 Merchant / Store 批量导入

入口和文件：

Merchant、Store 列表页分别提供 Batch Import 和模板下载，模板字段不得混用。
支持 .xlsx、.xls、.csv，读取第一个工作表；单次最多 500 条。
模板不包含 merchant_id、store_id、created_at、updated_at。上传文件中的 merchant_id 或 store_id 有值时按行报错并禁止导入；时间字段由数据库生成，上传值一律忽略且不能覆盖系统字段。
Store 标准导入模板不包含准入审核字段 review_status、review_date、status，也不包含非必填图片字段 exterior_photo、interior_photos、manager_owner_photo；批量创建成功后统一进入 pending + inactive，由有权限的运营人员在线审核和补充图片。
图片材料不进入批量导入模板；后台上传支持 JPG、JPEG、PNG、WEBP，单文件大小上限建议 10 MB，上传失败不得保存业务表单。
Store 模板的 merchant_id 必须引用已经成功落库的 Merchant；如需同时导入，必须先完成 Merchant 导入，再下载或填写 Store 模板。

校验和预览：

上传后先解析并展示总行数、可导入数、错误数、预分配 ID、名称和逐行错误，不立即写库。
Merchant 校验必填、长度、状态、库内重名和文件内重名。
Store 校验 Merchant 存在且状态有效、必填字段、NIN/NUBAN 格式、银行是否在有效银行列表、金额格式；若文件提供 BVN 再校验其格式。上传文件如包含 review_status、review_date 或 status 且有值，应逐行报错，不能绕过 Store 准入审核。
Store 在同一 Merchant 下按 merchant_id + store_name 做库内及文件内重复校验；发现重复时禁止自动覆盖。
所有错误必须定位到 Excel 行号和字段；任一错误存在时禁用正式导入。

执行和结果：

批量导入采用全有或全无事务。校验全部通过后，后端在事务内重新复验数据、生成 ID 并批量写入；任一行失败则整批回滚。
使用 import_batch_id + file_hash 做幂等控制；重复提交同一文件返回上次结果，不重复创建数据。
成功后展示批次号、成功数、生成 ID 列表、操作人和完成时间；失败后提供可下载错误清单。
导入文件原文不得长期保存敏感 BVN、NIN、NUBAN；如因审计必须留存，应加密、限权并配置明确保留期限。

3.7 Merchant / Store 页面交互

列表、筛选卡片、指标卡、详情新 Tab、状态弹窗、Radio 状态选择和审计时间线沿用现有后台 Ant Design 交互。
单笔登记使用分组表单；Store 长表单在弹窗内滚动，银行下拉挂载到 body，不得被弹窗遮挡。
来源为 SA/SM/RM 的新建流程先展示 Merchant Information 页面，再展示 Store 表单；已有 Merchant 必须由服务端搜索结果选择，新 Merchant 的 CAC Certificate 必传且仅以私有附件元数据保存。转换完成后，详情页展示 submission ID、提交人、Merchant 创建/关联结果和 CAC Certificate 摘要；不把 H5 提交过程误展示为已生效主数据。
状态调整弹窗必须先展示对新绑定、新订单、既有关系和已提交订单的影响，再要求填写原因。
新建、编辑、批量导入、状态变更均展示明确成功/失败反馈；前端成功提示必须等待后端事务完成。

4. SA Review Management 列表页

4.1 查询条件

列表支持组合筛选：

Keyword：SA ID、姓名、手机号、merchant、store。
审核状态：pending_review、rejected、approved_pending_training、approved。
培训状态：pending、scheduled、passed、failed。
账号状态：active、disabled。
Merchant。
Store，支持按任一绑定门店筛选。
审核人。
提交时间范围。
更新时间范围。

4.2 列表字段

字段	说明
SA ID	SA 主键
姓名	SA 姓名
手机号	默认脱敏
Merchant / Stores	当前绑定门店，支持展示多个门店
门店分配状态	`not_ready`、`pending`、`assigned`；仅 `assigned` 可进入办单资格判断
KYC 状态	BVN KYC 摘要
Face 状态	人脸比对摘要
审核状态	当前入职审核状态
培训状态	当前培训状态
账号状态	可登录/停用
提交时间	入驻提交时间
最后操作人	最近一次后台操作人
更新时间	最近一次状态更新时间

4.3 列表操作

Detail：在后台工作区新 Tab 打开 SA 审核详情，不使用弹窗承载详情页。
Review：对待审核记录进行审核处理。
Edit Profile：仅在 rejected 状态可见，且需 sa.profile.edit_rejected 权限。
Training：标记培训状态。
Manage stores：培训通过后维护 SA 归属 Merchant / Store。
Enable/Disable：启用或停用 SA 账号。

5. 详情页设计

详情页必须在工作区新 Tab 中展示，支持和客户、工单、借款详情一样保留多 Tab 操作上下文。详情页页头右侧提供操作按钮：Review、Edit Profile、Training、Manage stores、Enable/Disable；按钮按当前状态和权限禁用或隐藏，后端仍需强校验。

详情页分区展示：

5.1 基础信息

SA ID、姓名、手机号、备用手机号、邮箱。
性别、生日、地址、State、City。
教育信息、学校、工作经验。
紧急联系人。
备注。

5.2 门店信息

展示后台已维护的 Merchant ID / 名称和 Store ID / 名称，支持多个门店。
每个门店展示绑定状态、门店状态、绑定时间和最近变更摘要。
未培训通过时仅只读展示，无 Manage stores 操作；培训通过后，具备 sa.store.assign 权限的人员才可操作。
Manage stores 在当前详情 Tab 内打开编辑区：先选择 Merchant，再多选该 Merchant 下可用的 Store；保存前必须至少保留一个有效 Store。
保存时后端校验 Merchant / Store 有效性、Store 与 Merchant 的隶属关系、SA 账号状态和培训状态；不能绑定停用、删除或不属于所选 Merchant 的 Store。
已分配后再次维护时，后端按完整集合更新 sa_store 关系；不得将有效 Store 全部解绑。被解绑、停用或删除的 Store 不再计入办单资格。
归属维护不向 SA App 展示 Merchant / Store 名称、后台操作人或处理状态。

5.3 收款信息

银行名称。
NUBAN 脱敏展示。
银行账户校验结果。
最近更新时间。

该分区只读，不允许在 SA 审核管理页面修改。

5.4 KYC 与审核材料

BVN 脱敏展示。
BVN KYC 结果摘要。
人脸比对结果摘要。
BVN / KYC 图片材料、人脸材料、用户活体验证照片，默认以脱敏/水印方式展示。
设备采集状态。
定位采集状态。
采集失败原因。
操作时间。

该分区默认展示摘要；明文或敏感材料查看需 sa.sensitive.read 并写审计日志。

图片材料维护：

SA 图片材料只能通过 Upload Materials 后台上传入口维护，不允许录入或修改图片 URL。
上传或替换 SA 图片材料需 sa.material.upload 权限、上传原因和操作审计；保存文件元数据，不改变 BVN、BVN KYC 结果、人脸比对结果、银行名称、NUBAN 或银行校验结果。
后台上传接口返回 file_id、storage_key、文件名、文件类型、大小、上传人和上传时间；页面详情只展示文件摘要，敏感原图查看仍受 sa.sensitive.read 控制。

5.5 审核轨迹

展示提交、审核、拒绝、培训标记、密码下发、账号启停、资料修改等事件。

每条轨迹包含：

时间。
操作人。
动作。
操作前状态。
操作后状态。
备注或原因。
trace_id。

6. 审核动作

6.1 Approve

适用状态：pending_review。

结果：

审核状态进入 approved_pending_training。
培训状态保持 pending 或 scheduled。
App Home 展示待培训状态。
不直接允许办单。

操作要求：

必须由 sa.review.approve 权限人员操作。
可填写审核备注。
后端复验 BVN KYC、人脸比对、银行账户和审核材料状态；此阶段不要求、也不维护门店归属。

6.2 Reject

适用状态：pending_review。

结果：

审核状态进入 rejected。
App Home 展示入驻未通过。
SA 不允许办单。

操作要求：

必须填写拒绝原因。
拒绝不删除 SA 资料和审核材料。
rejected 后如需人工更正基础资料，只允许特定权限人员通过 Edit Profile 修改。

7. 资料修改

7.1 可修改状态

仅 rejected 状态允许后台修改 SA 基础信息。

pending_review、approved_pending_training、training_passed、active、disabled 状态不允许通过 SA 审核管理页面修改基础信息。

7.2 可修改字段

允许修改：

姓名。
备用手机号。
邮箱。
地址。
State。
City。
教育信息。
学校。
工作经验。
紧急联系人。
备注。

7.3 禁止修改字段

禁止修改：

BVN。
BVN KYC 结果。
人脸比对结果。
人脸材料。
用户活体验证照片。
银行名称。
NUBAN。
银行账户校验结果。
OTP 验证结果。
密码下发结果。

7.4 rejected 状态特殊规则

rejected 状态修改基础资料需 sa.profile.edit_rejected 权限。
必须填写修改原因。
修改后不自动变成通过；仍保持 rejected，除非有权限人员重新执行审核动作。
审计日志必须记录修改前后摘要和原因。

8. 培训状态

培训状态：

pending：待安排或待确认。
scheduled：已安排培训。
passed：培训通过。
failed：培训未通过。

操作规则：

需 sa.training.update 权限。
培训 passed 后写入 store_assignment_status=pending，并开放 Manage stores；此时不得立即下发初始登录密码或允许办单。
至少一个有效 Store 保存成功后，写入 store_assignment_status=assigned，再触发初始登录密码下发。
密码下发成功后写入 login_password_issued=true；审核通过、培训通过、至少一个 Store 有效、密码已下发且账号启用时，才允许办单。
培训未通过时不允许办单。
培训状态变更必须写审计日志。

初始密码短信模板：

Welcome to PocketBuy. Your SA account is approved. Login phone: {phone}. Initial password: {password}. Please change it after login.

uSpeedo 报备信息：

Template Name	Template ID	uSpeedo 模板内容	变量映射	预估长度	长度判断
`PB_SA_ACCOUNT_APPROVED_ADMIN`	`UTB260807D1JWO2`	`Welcome to PocketBuy. Your SA account is approved. Login phone: {1}. Initial password: {2}. Please change it after login.`	`{1}=phone`, `{2}=password`	142	OK: 1 segment

说明：该后台触发场景与 App 文档中的初始密码短信内容完全一致，uSpeedo 不允许重复创建相同内容模板，后台场景复用同一供应商 Template ID。

短信发送规则：

仅在培训状态为 passed、store_assignment_status=assigned、至少一个 Store 有效且 login_password_issued=false 时触发。
{phone} 使用 SA 注册手机号。
{password} 使用服务端生成的一次性初始密码，不能由前端生成。
短信发送成功后记录密码已下发；发送失败时记录失败原因并允许后台重试。
短信内容、发送时间、发送结果、操作人和 trace_id 必须写入审计日志；审计中密码字段需脱敏。

9. 账号启停

账号状态：

active：允许登录；是否可办单仍需满足审核、培训、门店和密码条件。
disabled：阻断登录或创建客户申请。