袋鼠金融蓝图

Properties1
tags需求, 接口需求, sa-app, 总览

SA App 后端接口需求 — 总览

来源：从 PocketBuy SA 原型（kangaroo_prototype/src/apps/pocketbuy_sa/）反向抽取
视角：前端原型开发者 = 需求方
目的：给后端立项参考；不指定具体系统归属（架构师后续按系统域分配）
配套：每份分册按业务场景拆分；本文件给清单 + 通用约束 + 调用顺序

0. 阅读说明

项约定
接口命名业务语义命名（如「SA 登录」），不指定 URL / HTTP method
字段命名业务字段名 + 类型 + 必填 + 一句话说明
异常只列业务异常码（不穷举 HTTP / 网络层异常）
已有专项文档直接 wikilink 引用，不重复细节：[[../../../11-手机分期MVP方案/10-IMEI设备反查
字段命名风格snake_case
时间字段ISO 8601（UI 自行格式化为 DD/MM/YYYY 等本地化格式）
金额字段NGN 整数（最小单位为 Naira；不带小数）

1. 分册索引

分册涵盖业务场景接口数量（预估）
01-SA登录与账号SA 登录、当前 SA 档案查询、重置 SA 密码3
02-试算与商品商品目录、Hot Picks、POS 扫码反查、还款分期计算、IMEI 反查（引用）、信贷政策（引用）4 + 2 引用
03-客户身份验证与订单创建OTP 发送（SMS / Voice）、OTP 校验 + 同号活跃订单查询、订单创建3
04-进件资料采集暂存进件步骤（通用 saveStep）、进件详情查询、BVN / NIN 实时核验、进件提交5
05-字典服务行政区划字典、就业类型、行业、亲属关系等枚举4 必备 + N 备选
06-审批后子流程签约信息查询、合影上传、签字提交、首付收款、交付确认（含 IMEI 二次校验）、锁机激活轮询6
07-列表与汇总查询进件列表（筛选 / 分页）、首页 Pending Work 汇总2

2. 接口总清单（按业务流程顺序）

#接口业务名分册调用方页面
1SA 登录01Login
2当前 SA 档案查询01App 启动 / 鉴权续期
3重置 SA 密码01Settings → Reset Password
4商品目录查询02Calculate / Catalog
5Hot Picks 查询02Home
6POS 扫码反查02ScanPosCode
7还款分期试算02Calculate
8IMEI 设备反查02ScanImeiCode（引用渠道中心文档）
9信贷政策预览02Calculate price onBlur（引用风控文档）
10发送 OTP03Verify
11校验 OTP + 活跃订单查询 + 创建订单03Verify 提交
12暂存进件步骤数据04Identity / Personal / Work / Guarantor / Liveness
13进件详情查询04Detail / Continue 路径回填 / Review
14BVN 实时核验04Identity
15NIN 实时核验04Identity
16进件正式提交（Review）04Review
17行政区划字典（States / LGAs）05Personal
18就业类型字典05Work
19行业字典05Work
20亲属关系字典05Guarantor
21签约信息查询06Sign 子阶段 1
22合影上传06Sign 子阶段 2
23客户签字提交06Sign 子阶段 3
24首付收款提交06Pay
25交付确认（含 IMEI 二次校验）06Deliver
26锁机激活状态轮询06Deliver
27进件列表查询07Applications
28首页汇总（Pending Work + 公告）07Home

3. 业务流程调用顺序

3.1 SA 一次完整代办分期的接口调用时序

SA 启动 App
  ├─ 当前 SA 档案查询（带 token 重建会话）
  └─ 首页汇总（Pending Work / Hot Picks / 公告）

SA 点 New Application
  ├─ Calculate 页
  │   ├─ 商品目录查询（点 Product 卡进 Catalog）
  │   ├─ POS 扫码反查（顶部 POS 卡）
  │   ├─ IMEI 设备反查（Product 卡 Scan 按钮）
  │   ├─ 信贷政策预览（price onBlur 触发）
  │   └─ 还款分期试算（price / dp / frequency 变化）
  ├─ Verify 页
  │   ├─ 发送 OTP（SMS / Voice 二选一）
  │   └─ 校验 OTP + 活跃订单查询 + 创建订单
  ├─ Identity 页
  │   ├─ BVN 实时核验（用户选 BVN 时）
  │   └─ NIN 实时核验（用户选 NIN 时）
  │   └─ 暂存进件步骤（step=identity）
  ├─ Personal 页 → 暂存进件步骤（step=personal）
  ├─ Work 页 → 暂存进件步骤（step=work）
  ├─ Guarantor 页 → 暂存进件步骤（step=guarantor）
  ├─ Liveness 页 → 暂存进件步骤（step=liveness）
  └─ Review 页
      ├─ 进件详情查询（回填全步骤数据）
      └─ 进件正式提交

审批通过后（系统状态推进至 Approved）：
  ├─ Sign 页（3 子阶段；订单状态保持 Approved）
  │   ├─ 子阶段 1 Confirm Plan：签约信息查询（拉合同摘要 + 还款计划）
  │   ├─ 子阶段 2 Group Photo：合影上传
  │   └─ 子阶段 3 Sign Agreement：客户签字提交
  ├─ Pay 页：首付收款提交
  └─ Deliver 页：交付确认（含 IMEI 二次校验是否同设备）

3.2 SA 中途返回 / 切单 / 编辑场景

SA 在 Applications 页
  ├─ 进件列表查询（带状态筛选 / 分页）
  └─ 点击某单 Continue / Fix Info
      ├─ 进件详情查询（拿到 status + 已填数据）
      └─ 跳转到对应步骤（Identity / Personal / ... / Pay / Deliver）

SA 在 Review 页编辑某步
  ├─ 进件详情查询
  └─ 跳回对应步骤 → 暂存进件步骤（step=...）

4. 通用约束

4.1 字段命名

  • snake_case
  • 布尔字段不带 is_ 不强制（按业务语义；如 policy_accepted / signed / paid）
  • 枚举字符串小写 + 短横线（如 business-owner / oil-gas）

4.2 时间 / 金额

  • 时间字段：ISO 8601（2026-06-01T08:30:00+01:00），UI 自行本地化
  • 金额字段：NGN 整数 Naira（不带分），如 148300；前端按千分位格式化展示

4.3 鉴权

  • 所有非登录接口均需 token
  • token 在登录接口出参返回；具体头部字段名 / 续期机制由架构师定
  • 当前 SA 档案查询接口（01-2）可视为”用 token 重建 session 上下文”的入口

4.4 分页 / 排序

  • 列表类接口建议 cursor 分页（应对长列表 — 复借客户场景 Applications 可达数百单）
  • 排序字段：默认按业务相关字段排序（如订单列表按 updated_at desc）
  • 分页返回结构：{ items: [...], next_cursor: string | null, total?: number }

4.5 错误结构

{
  code: string,        // 业务异常码（如 OTP_INVALID / POLICY_PRICE_OVER_CAP）
  message: string,     // 给前端兜底展示的英文文案（UI 通常用 i18n key 覆盖）
  detail?: unknown,    // 可选附加信息（用于调试 / 日志）
}

前端处理原则：

  • 已知 code → 用本地 i18n 文案展示
  • 未知 code → 显示 message 或通用 fallback “Something went wrong, please retry”
  • 网络错误 → toast「Network error, please try again」

4.6 接口幂等性

  • 写操作建议支持 Idempotency-Key 头部
  • 关键接口：发送 OTP、创建订单、暂存进件步骤、签字提交、首付收款、交付确认

5. 跨域引用（已有专项文档，本清单不重复）

接口已有文档
IMEI 设备反查10-IMEI设备反查
信贷政策预览 POST /credit-policy/preview02-信贷政策计算接口.md

本清单 02 分册仅列接口名 + 调用上下文 + 链接到上述文档；不重复字段细节。

6. 范围边界（本清单不覆盖）

不在本清单原因
Achievement 业绩查询MVP 不做（独立分册后置）
Wallet / Withdraw非进件流程，独立分册
Notifications / Announcements 推送通用消息中心范畴，独立分册
Me Profile / Bank Accounts 维护SA 账户后台维护，独立分册
推送 / 长连接协议层；不在业务接口需求范畴

如需补充，请独立起新分册（避免本清单膨胀）。

关系图谱