袋鼠金融蓝图

PocketBuy 门店端 H5 联调、测试与上线 SOP（MVP）

版本：V1.2
日期：2026-08-11
适用团队：产品、设计、前端、后端、测试、运营、财务、风控、SRE

1. 目标与基本原则

本 SOP 用于将现有 Mock H5 安全切换到真实后端，并完成测试、UAT、发布、监控和回滚。任何阶段都必须遵守以下原则：

  • 订单佣金、绩效结果、结算结果由后端生成，H5 只展示。
  • 所有联调以冻结的 OpenAPI 契约和示例为准，不口头约定字段。
  • 先验证身份和数据范围，再验证页面字段；财务结果无法追溯时不允许上线。
  • Mock 数据、测试数据和生产数据明确隔离；生产构建不得携带 Mock 控制器。
  • 变更只影响规定生效时间之后的数据，历史账本和政策快照不可被覆盖。

2. 参与方与职责

角色职责
产品冻结需求、状态文案、角色权限、验收范围
前端OpenAPI 类型、页面集成、缓存/弱网、埋点、构建产物
后端鉴权、数据隔离、聚合接口、幂等、审计、错误码
佣金/结算服务单笔权益、绩效、结算的可追溯结果和快照
测试契约、功能、权限、弱网、安全、回归测试
SA/运营SA App Stores H5 中 SA/SM/RM 的人员资料录入、关系维护、审核流程、政策、客服电话与短信
财务/风控金额、CPD7/风险系数、结算批次 UAT
SRE环境、发布、监控、告警、回滚

3. 阶段 0：需求与契约冻结

3.1 输入

3.2 操作

  1. 产品逐页演示当前原型，建立页面—接口—权限映射。
  2. 后端确认每个字段的来源系统、刷新频率、数据负责人。
  3. 财务和风控确认金额语义：预计、基础应得、最终应发、已结算、剩余预计。
  4. 将契约落成 OpenAPI 3.1；前后端从同一文件生成类型或 Mock。
  5. 对待确认项建立负责人和截止时间，不允许开发自行猜测边界。

3.3 退出条件

  • API 路径、字段、枚举、nullability、错误码和权限评审通过。
  • ACH/CPD7 边界、90 天观察窗、10 单小样本规则、每月 25 日付款及跨月扣减日历已书面确认。
  • Dashboard 与 Commission 共用月度汇总来源。
  • 每个写接口已定义幂等键、审计字段和重复提交结果。

4. 阶段 1：环境与数据准备

4.1 环境

至少准备 DEV、SIT、UAT、PROD。各环境分别配置 API 域名、短信、对象存储、推荐码域名、客服电话、埋点和功能开关。

禁止 H5 根据 hostname 隐式启用 Mock；使用构建变量，例如：

  • VITE_DATA_MODE=mock|api
  • VITE_API_BASE_URL=https://...
  • VITE_APP_ENV=dev|sit|uat|prod
  • VITE_BUILD_VERSION=<commit-or-release>

生产构建校验：VITE_DATA_MODE=api，且没有 Preview mode、固定 OTP、原型手机外壳、Mock 网络切换器。

4.2 标准测试人物

准备并登记以下不可复用到生产的测试账号：

  1. SA/SM/RM 已在授权范围内录入、门店关系有效且核验通过的店员。
  2. SA/SM/RM 已录入但账号/门店关系尚未生效的店员，用于验证登录限制和联系 SA/客服提示。
  3. 正常店长。
  4. SA 侧已停用店员一名，用于验证会话与未来业务被阻断。
  5. 另一门店店长和店员，用于越权测试。

4.3 标准业务数据

  • 当前月 OPEN：至少 12 笔订单，覆盖处理中、合格、取消和无佣金。
  • 上一月 SETTLING：存在已结算和预计剩余，风险系数待确认。
  • 前两月及更早 SETTLED：存在真实结算记录和多种绩效系数。
  • 佣金状态覆盖 ESTIMATED/EARNED/WAITING_METRIC/PAID/REVERSED。
  • 排行榜至少 5 行，前三名、本人/本店、趋势状态齐全。
  • 热销商品至少 3 个，覆盖固定佣金和区间佣金。

所有期望金额由后端/财务提供测试真值表，前端不得根据 Mock 反推。

5. 阶段 2：后端自测与契约测试

5.1 后端自测

  • 使用 OpenAPI 示例跑 schema validation。
  • 每个接口覆盖成功、空数据、非法参数、无权限、跨店、限流、冲突、依赖失败。
  • 验证 user_id + role + store_id 数据范围，跨范围资源统一 404。
  • 验证金额是字符串、时间含时区、月份为 YYYY-MM。
  • 验证日志无 BVN、OTP、令牌、完整手机号/IMEI。

5.2 核心不变量

  • 同一用户同一月份：Dashboard monthly_summary 等于 Commission summary。
  • estimated_remaining_amount >= 0；若服务端业务扣减结果小于 0，展示剩余应为 0，并保留账务审计明细。
  • SETTLED.actual_settled_amount 等于成功结算批次汇总。
  • 一条佣金只归属一个订单和受益人；结算行可多条，但总额可对账。
  • WAITING_METRIC.total_payable=null，不能返回未经确认的最终金额。
  • 停用店员不修改历史订单、佣金和结算。

5.3 自动契约测试

在 CI 中运行：

  1. OpenAPI lint。
  2. 后端响应 schema test。
  3. 前端生成类型编译。
  4. Provider/consumer contract test。
  5. Dashboard/Commission 一致性和分页汇总不变量测试。

退出条件：阻断级契约测试 100% 通过，示例响应提交到版本库。

6. 阶段 3：前端接入顺序

建议按依赖顺序联调，避免同时替换所有 Mock：

  1. /app-config、OTP、令牌刷新、/me。
  2. Dashboard、政策、排行榜、热销商品。
  3. 订单列表/详情及筛选汇总。
  4. 可选月份、月度佣金汇总、佣金列表/详情。
  5. 结算列表/详情。
  6. 推荐码。
  7. 消息和埋点。

每接入一个域必须同时处理：loading、empty、cached、401、403、404、409、429、5xx/timeout，不允许只接成功响应。

6.1 Mock 切换规范

  • 保留 Mock 服务用于本地演示和自动化测试。
  • 页面组件不直接 import 生产 Mock 数组；通过 repository/API client 注入数据源。
  • Mock 响应形状与 OpenAPI 完全一致。
  • PROD 构建通过静态检查阻止 mock/data 和 Preview controls 进入产物。

6.2 前端缓存规范

  • 缓存 key 至少包含 environment + user_id + endpoint + filters + schema_version。
  • 注销、切换账号、令牌失效时清除用户数据。
  • 缓存数据展示 Saved data 与 data_as_of；后台刷新失败不覆盖缓存。
  • 财务详情默认不长期持久化；如需离线展示，必须加密并设短 TTL。

7. 阶段 4：功能与交互测试

7.1 账号流程

  • 输入本地号码、粘贴 0/234 开头号码、非法号码。
  • OTP 正确、错误、过期、频控、账号停用。
  • 手机号页包含固定 +234、Send OTP；OTP 页包含脱敏号码、6 位验证码、Sign in 和 Change mobile number。
  • 登录页可打开当前授权协议；未勾选、版本不匹配、首次同意和协议升级重新同意均按契约处理并留痕。
  • 店长和店员均在 OTP 与协议校验成功后直达 Earnings。
  • 账号或关系尚未由 SA/SM/RM 完成并生效时，返回可理解的限制文案并引导联系 SA/客服，不出现可直达补录路由。

7.2 首页与详情

  • 角色快捷入口正确；店员二维码入口只在 BOUND 时出现。
  • 首页与佣金当月卡片字段和值一致。
  • 排行榜 Tab、前三样式、脱敏、本店/本人标识。
  • 商品列表、图片失败占位、上下滑整页切换、标题同步。
  • 政策按角色显示，边界和值与接口一致。

7.3 订单与佣金

  • 关键字、时间、状态组合筛选；清空和切换筛选重置游标。
  • 首 10 条、加载更多成功/失败/重试；汇总值始终覆盖完整筛选范围。
  • 订单详情使用后端 commission_id 跳转。
  • 当前月、上一月、已结算月份切换；空月份和被暂缓月份。
  • 结算记录位于订单佣金前；金额和状态不混淆。
  • 验证每月 25 日发放上月奖励、上上月 -0.2 扣减单列展示，以及净额为负时 Under review 且不发起付款。

7.4 人员数据、收款户与二维码

  • 店长和店员 Profile 仅展示 SA/SM/RM 维护并已生效的人员/门店信息；除本人收款户外均为只读。
  • 首次新增收款户校验成功后自动为唯一默认户；更换保留旧版本，重复请求幂等，户名不匹配/银行异常/风控拦截不能生效。
  • 前端页面和 API client 不包含除本人收款户外的人员主数据写入能力；账号仅脱敏展示且不进入日志/埋点。
  • 二维码有效/失效；放大、扫描、保存 PNG、图片内 Logo/文案/码可扫描。

8. 阶段 5：非功能测试

8.1 弱网与性能

在 3G、400–800ms RTT、1–5% 丢包、离线切换下验证：

  • 首屏骨架稳定，无无限 loading。
  • 缓存先展示后刷新；数据时间正确。
  • 翻页失败不清空已有列表。
  • 图片懒加载和失败占位不导致横向溢出。
  • 360×640、390×844、427×952 等视口无内容被刘海、摄像头、底部导航遮挡。

记录 Lighthouse/Web Vitals 或等价指标：LCP、INP、CLS、JS bundle、图片体积、API P50/P95。

8.2 安全

  • 店员访问店长接口、店长访问其他门店资源、修改 URL ID、重放写请求。
  • OTP/二维码枚举和限流；门店角色令牌仅允许访问当前契约定义的只读人员数据、协议记录和本人唯一收款户。
  • XSS、恶意文件、过期上传凭证、跨账号缓存泄露。
  • 访问令牌刷新/撤销；停用店员后现有会话立即失效。
  • 日志、埋点、错误平台和网络抓包检查敏感字段。

8.3 兼容性

覆盖低端 Android WebView/Chrome、iOS Safari、软键盘、相机/相册权限、系统字体放大和下载权限。

9. 阶段 6：UAT

9.1 UAT 参与人

产品、门店运营、至少一名店长和一名店员、佣金负责人、财务、风控、客服。

9.2 UAT 场景

  1. SA/SM/RM 在授权范围内通过 Stores H5 完成店员及门店关系录入/审核生效 → 店员同意授权协议并完成 OTP 后进入 Earnings。
  2. 店长和店员的门店端 H5 除本人唯一收款户外均无人员资料写入能力；店长仍可按店员筛选本店订单。
  3. 店员打开二维码 → SA 扫码建立订单推荐归属 → 订单出现在店员订单列表。
  4. 订单从 Processing → Qualified → Commission Earned/Waiting risk factor。
  5. 月份由 Open → Settling → Settled，卡片和明细按状态变化。
  6. 结算记录金额与财务真值表逐笔、逐月对账，覆盖 25 日发放和上上月负绩效扣减。
  7. 店长/店员新增或更换唯一默认收款户，付款批次引用正确账户快照。

9.3 UAT 签字条件

  • 所有 P0/P1 用例通过；P2 有明确上线接受人和修复日期。
  • 财务抽样对账 100% 一致，至少覆盖 +0.2、+0.1、0、-0.2 和冲正订单；覆盖 90 天内 <10 单时正向系数封顶为 0、-0.2 次月扣减、25 日批次和负净额转人工复核。
  • 权限和脱敏测试通过。
  • 客服已取得状态/错误码说明和 trace_id 查询路径。

10. 阶段 7：发布准备

10.1 发布清单

  • 需求、OpenAPI、前后端版本、DB migration、配置变更均有关联发布单。
  • PROD 环境变量复核；Mock 和 Preview 功能关闭。
  • 政策快照、有效时间和当前月份配置复核。
  • 短信模板、授权协议版本、银行账户校验、对象存储、CDN、推荐码域名、客服电话已验证。
  • 数据库变更向前兼容；回滚不删除账本或审核数据。
  • Dashboard/订单/佣金/结算依赖服务容量与超时已配置。
  • 监控面板和告警接收人已确认。

10.2 构建验证

当前原型工程至少执行：

npm run check:runtime
npm run build
npm run test:sites

真实 API 接入后补充单元测试、契约测试和 E2E。构建产物需记录 SHA-256；部署前后校验一致。

10.3 灰度

建议按内部账号 → 1 家测试门店 → 5% 门店 → 25% → 100% 放量。每阶段至少观察一个业务高峰时段；任何财务不一致立即停止放量。

11. 阶段 8：发布与冒烟

发布顺序：向后兼容后端/数据库 → 配置 → H5 静态资源 → 功能开关。禁止先发布依赖新字段且无 fallback 的前端。

发布后 15 分钟内完成：

  1. 外部 HTTPS、静态资源和 API 健康检查。
  2. 店员/店长 OTP 登录。
  3. Earnings、订单、佣金、政策、二维码、授权协议、除本人收款户外只读的 Profile 和客服核心路径。
  4. Dashboard 与 Commission 当前月一致性查询。
  5. 日志检查 4xx/5xx、CORS、CSP、资源 404、JS 异常。
  6. 从公网弱网设备进行一次真实页面加载。

12. 监控与告警

12.1 技术指标

  • H5 JS error、白屏率、资源加载失败率、版本分布。
  • API QPS、成功率、P50/P95/P99、401/403/409/429/5xx。
  • OTP/SMS、对象存储、推荐码和下游财务服务可用性。
  • 缓存命中率和数据延迟 now - data_as_of。

12.2 业务与财务指标

  • 登录、账号/关系未就绪拒绝、二维码保存转化。
  • 订单数量、归属成功率、无佣金订单率。
  • OPEN/SETTLING/SETTLED/WITHHELD 月份数量。
  • Dashboard 与 Commission 汇总不一致数，目标为 0。
  • 佣金账本与结算行差异数、负剩余展示数、未知状态数，目标为 0。

12.3 建议告警阈值

  • 核心 API 5xx > 2% 持续 5 分钟。
  • OTP 成功率低于 95% 持续 10 分钟。
  • P95 > 2 秒持续 10 分钟。
  • 月度汇总一致性出现任意一条差异立即 P1。
  • 跨店授权测试或敏感信息泄露任意一条立即 P0。

13. 回滚 SOP

13.1 触发条件

  • 金额、月份、用户归属或结算状态错误。
  • 越权或敏感信息泄露。
  • 登录/首页/佣金核心路径大面积不可用。
  • 新版本错误率或延迟超过阈值且无法快速降级。

13.2 操作顺序

  1. 停止灰度并冻结相关财务批次，记录开始时间和 trace_id。
  2. 关闭新功能开关；如仅展示层问题，回滚 H5 到上一静态版本和哈希。
  3. 若后端有问题，切回上一兼容版本；禁止回滚已产生的账本数据。
  4. 对受影响期间执行只读对账，生成用户/订单/佣金/结算影响清单。
  5. 修复后使用原幂等键或正式补偿流程，不直接改历史账本。
  6. 产品、财务、SRE共同确认后恢复灰度。

13.3 回滚验证

  • 外部页面可访问，版本号和资源哈希正确。
  • 登录、Dashboard、订单、佣金和结算冒烟通过。
  • 新版本错误停止增长；数据一致性告警清零。

14. 故障处理与客服 SOP

客服收集：用户角色、脱敏手机号后四位、门店、页面、业务月份、订单尾号、发生时间、页面 trace_id，不得要求用户发送 BVN/OTP/完整银行卡信息。

分流：

  • 无法登录：先核对 SA 人员/关系录入与生效状态，再分流到账号与 OTP 服务。
  • 无订单或归属错误：订单/推荐归属服务。
  • 单笔金额或状态错误：佣金账本服务。
  • 风险系数疑问：绩效/风控服务。
  • 已发/未到账：结算与支付服务。
  • 页面错位/白屏：H5 与 CDN。

P0/P1 事故必须保留时间线、影响范围、根因、修复、补偿、复盘和长期预防项。

15. 交付物清单

  • 已签字的 PRD、接口契约、OpenAPI 3.1、错误码表。
  • 前后端版本与构建哈希、数据库 migration、配置清单。
  • Mock/Provider 契约测试、功能回归、弱网、安全、UAT 报告。
  • 财务真值表和对账结果。
  • 发布单、灰度记录、冒烟结果、监控链接和回滚版本。
  • 客服话术与 trace_id 查询说明。

关系图谱