手机分期 SA App 交机页面优化 — 迭代需求

优化手机分期 SA App 的 Deliver Device / 27交付设备_输入 页面：顶部展示给商户的付款信息；Step 2 的还款 App 二维码改为后台可配置；Step 3 使用带参数链接唤醒 Installer App，未安装时进入 H5 下载引导，并在原交机页查询和轮询锁机状态。

1. 背景与目标

当前交机页已覆盖 IMEI 录入、还款 App 安装和交机状态展示，但仍有三处不足：

SA 需要在交机前明确看到商户付款是否成功，以及付款 reference、金额和时间，避免仅依据订单状态交机。
还款 App 下载二维码固化在客户端，下载地址或投放页面变化时必须发版。
手机锁没有完整安装入口。SA App 需要携带订单上下文唤醒独立的 Installer App；若设备未安装 Installer App，则进入 H5 下载引导；安装完成后仍在原交机页确认锁机状态。

本期目标是在一个页面内完成“确认商户收款 → 确认 IMEI → 引导安装还款 App → 唤醒 Installer App 安装手机锁 → 确认锁机激活”的现场交机闭环。

2. 本期范围

能力	是否纳入	说明
顶部展示商户付款信息	是	展示付款状态、reference、金额和成功时间
Step 2 还款二维码后台可配	是	客户端不再内置二维码内容或下载地址
Step 3 带参数唤醒 Installer App	是	获取后台签发的启动配置并唤醒指定 Installer App
未安装时进入 H5 下载引导	是	H5 仅负责下载安装引导及再次尝试打开 Installer App
Step 3 查询手机锁状态	是	进入页面、App 返回和手动点击时查询；前台每 60 秒轮询
锁机激活作为完成交机条件	是	仅 `ACTIVATED` 允许完成交机
独立的锁机状态查询页面	否	状态变化和查询都在原交机页面完成
在 H5 内执行锁机配置	否	锁机安装与配置由 Installer App 执行
逾期锁机、主动锁机、解锁策略	否	本需求只负责交机安装和激活确认
Installer App 开发及手机锁供应商后台	否	沿用既有能力；本需求定义与 SA App 的集成契约

3. 页面结构与交互

页面仍按以下顺序展示：

订单摘要
→ Merchant payout
→ Step 1 · Scan IMEI
→ Step 2 · Install Client App
→ Step 3 · Install Phone Lock

3.1 顶部 Merchant payout

订单摘要下方增加或保留 Merchant payout 卡片：

页面字段	数据字段	展示规则
状态	`merchant_payout.status`	成功显示 `Completed`；处理中显示 `Processing`；失败显示 `Failed`；未知显示 `Unknown`
Reference No.	`merchant_payout.reference`	展示业务 reference；为空显示 `--`
Amount	`merchant_payout.amount` + `currency`	NGN 使用 `₦` 和千分位，例如 `₦148,300`
Paid at	`merchant_payout.paid_at`	按业务时区展示；非成功状态为空时显示 `--`

业务规则：

订单状态为 Paid 不等于可以交机；商户付款必须为终态成功。
merchant_payout.status != SUCCESS 时，Step 1–Step 3 可查看，但不可完成交机。
页面刷新时重新查询付款状态，不使用本地缓存状态替代服务端结果。
不展示商户完整银行账号、BVN、token 或支付通道原始报文。

3.2 Step 1 · Scan IMEI

延续现有交互。IMEI 确认成功后才能发起手机锁安装；后续签发的安装票据必须绑定服务端已确认的 IMEI。

3.3 Step 2 · Install Client App

页面继续展示 PocketBuy 还款 App 的下载/打开二维码，但二维码由后台配置下发，客户端不得内置生产 URL、二维码图片或兜底下载地址。

3.4 Step 3 · Install Phone Lock

标题为 STEP 3 · INSTALL PHONE LOCK。卡片包含锁机状态、Open Installer 和 Check Lock Status，不新增独立查询页面。

初始状态：

Phone lock status                         Not installed
[ Open Installer ]
[ Check Lock Status ]

查询期间：

Phone lock status                         Checking...
[ Open Installer ]
[ Check Lock Status · loading ]

3.4.1 安装主链路

SA 点击 Open Installer 后，当前页状态立即从 Not installed 切换为 Checking...，并向 BNS 请求本订单最新的 Installer App 启动配置。
BNS 校验订单、商户付款、已确认 IMEI 和当前锁机状态后，签发短期、一次性安装票据，并返回 Installer App 唤醒地址、指定 Android 包名和 H5 兜底地址。
SA App 仅允许唤醒后台配置的 scheme/App Link 和包名；优先使用已验证的 Android App Link。使用自定义 scheme 时，必须同时校验目标包名，避免被其他 App 截获。
若系统可解析且目标 Installer App 可用，则携带票据唤醒 Installer App，不打开 H5。
若 Installer App 未安装、被禁用、无可用处理程序，或启动失败，则在外部浏览器打开后台返回的 fallback_h5_url，展示 Installer App 下载引导。
H5 只提供 Installer App 的下载说明、可信下载入口和 Open Installer 操作，不在 H5 内执行手机锁配置。Open Installer 应重新向后台获取有效票据后再尝试唤醒，不能复用已过期票据。
Installer App 使用票据向 BNS 换取安装上下文并执行手机锁安装。票据无效、过期、已使用或与订单/IMEI 不匹配时必须拒绝安装。
Installer App 完成或失败后，通过约定的回跳地址返回 SA App。回跳结果只用于触发查询，不作为锁机成功依据。
SA App 恢复前台后立即查询服务端锁机状态，并继续同页轮询；不得跳转到独立状态页。

3.4.2 唤醒参数与安全要求

推荐唤醒地址只携带不透明票据和追踪信息，例如：

https://installer.example.com/launch
  ?ticket=SIGNED_ONCE_TOKEN
  &request_id=LOCK_REQ_10001
  &callback_uri=pocketbuysa%3A%2F%2Fphone-lock%2Fresult

ticket：服务端签名、短期有效、一次性使用；服务端侧绑定 installment_order_id、已确认 IMEI、客户/设备上下文、nonce 和失效时间。
request_id：贯穿 SA App、BNS、Installer App 和锁机服务日志，用于排查与幂等。
callback_uri：只允许后台白名单值；Installer App 不接受调用方任意传入的回跳地址。
URL 中不得明文放置 IMEI、customer ID、手机号、BVN/NIN、登录 token 或锁机供应商密钥。
Installer App 回跳可携带 request_id 和结果提示，但 SA App 必须再次查询 BNS，以服务端状态为准。
App Link 域名、Android 包名、应用签名证书、H5 域名和下载包来源均须纳入发布白名单。

3.4.3 查询与轮询

进入交机页后自动查询一次；未发起安装且服务端为 NOT_STARTED 时显示 Not installed。
获取启动配置、唤醒 Installer App、从 Installer App/H5 返回或 SA App 恢复前台时，立即查询一次。
未进入 ACTIVATED 时，每 60 秒自动查询一次。以前一次请求完成时间为计时起点，避免慢请求叠加。
仅在交机页处于前台且订单未完成时轮询；离开页面或进入后台时暂停，重新进入前台时立即查询并恢复轮询。
点击 Check Lock Status 主动查询；已有查询进行中时不重复请求。完成后重新计算下一次 60 秒轮询。
查询期间显示 Checking...，查询按钮 loading/置灰；查询结束后恢复服务端标准状态文案。
ACTIVATED 后停止自动轮询，安装按钮替换为不可点击的 Phone Lock Activated；查询按钮保留用于人工刷新。
唤醒成功、Installer App 页面显示成功或 H5 下载完成，均不等于锁机已激活。

3.5 手机锁状态

后端标准状态	页面文案	页面行为
`NOT_STARTED`	`Not installed`	可点击安装；可查询
`INSTALLING`	`Activation in progress`	可再次唤醒 Installer App；优先查询
`ACTIVATED`	`Activated`	绿色成功态；满足交机完成条件
`FAILED`	`Activation failed`	展示可读原因；允许重试安装或查询
`UNKNOWN`	`Status unavailable`	不允许完成交机；允许重试查询

Checking... 仅为查询中的前端临时状态，不是后端状态枚举。供应商原始状态、错误码和 message 由 BNS 留存并映射为稳定状态与可展示文案，不直接透传给 SA。

4. 接口契约 _—— 供参考 _

4.1 交机页详情

现有交机详情接口增加：

{
  "merchant_payout": {
    "status": "SUCCESS",
    "reference": "PAYOUT_10001",
    "amount": 148300,
    "currency": "NGN",
    "paid_at": "2026-08-07T10:20:30+01:00"
  },
  "repayment_app": {
    "qr_content": "https://download.example.com/pocketbuy",
    "display_text": "Scan to install PocketBuy",
    "version": "2026-08-07-v1"
  },
  "phone_lock": {
    "status": "NOT_STARTED",
    "display_message": "Not installed",
    "updated_at": "2026-08-07T10:21:00+01:00"
  }
}

4.2 获取 Installer App 启动配置

建议接口：

POST /installment/orders/{order_id}/phone-lock/launch-config
Idempotency-Key: <client-generated-key>

请求：

{
  "imei": "<confirmed-imei>",
  "source": "SA_DELIVERY_PAGE"
}

{
  "request_id": "LOCK_REQ_10001",
  "installer_launch_uri": "https://installer.example.com/launch?ticket=SIGNED_ONCE_TOKEN&request_id=LOCK_REQ_10001&callback_uri=pocketbuysa%3A%2F%2Fphone-lock%2Fresult",
  "fallback_h5_url": "https://download.example.com/phone-lock-installer?request_id=LOCK_REQ_10001",
  "android_package": "com.example.phoneinstaller",
  "expires_at": "2026-08-07T10:26:00+01:00"
}

约束：

每次点击安装均获取最新配置；客户端不得长期缓存或自行拼接唤醒地址。
接口返回前需校验订单可交机、IMEI 已确认且属于当前订单。
同一幂等键重复请求不得创建多笔安装任务；票据消费接口也必须防重放。
installer_launch_uri、fallback_h5_url、包名和失效时间必须由后台统一配置和签发。
票据过期时 SA App/H5 重新调用本接口，不在客户端延长有效期。

4.3 查询锁机状态

建议接口：

GET /installment/orders/{order_id}/phone-lock/status

{
  "request_id": "LOCK_REQ_10001",
  "status": "INSTALLING",
  "display_message": "Activation in progress",
  "updated_at": "2026-08-07T10:23:00+01:00"
}

若供应商查询超时，BNS 返回可识别的暂不可用结果，客户端展示 Status unavailable 并保留重试能力，不得把超时映射为 NOT_STARTED 或 ACTIVATED。

5. 完成交机规则

只有同时满足以下条件，Complete Delivery 才可点击：

商户付款状态为 SUCCESS；
IMEI 已校验并绑定当前订单；
还款 App 步骤满足既有完成规则；
手机锁服务端状态为 ACTIVATED。

前端按钮控制仅用于交互提示；提交交机时 BNS 必须重新校验全部条件，防止缓存状态、回跳参数或修改客户端绕过。

6. 异常与提示

场景	页面处理
Installer App 已安装	直接带参数唤醒，不进入下载 H5
未安装、被禁用或无处理程序	自动打开 `fallback_h5_url`
唤醒失败或目标包不匹配	不唤醒未知 App；进入 H5，并记录失败原因
启动配置或票据过期	重新获取启动配置后再唤醒
票据被重复使用或上下文不匹配	Installer App 拒绝执行；SA App 展示可重试提示
H5/下载地址不可用	展示“Installer download unavailable, please retry”，保留重试
Installer App 回跳 SA App	立即查询服务端状态；不直接采信回跳结果
查询超时或网络异常	展示 `Status unavailable`，保留安装与手动查询能力，不允许交机
商户付款非成功	不允许完成交机，并提示先确认付款结果

袋鼠金融蓝图

探索

File History