02 — 试算与商品
来源：
api/catalog.ts/api/pos.ts/api/calculate.ts/api/imei.ts/api/creditPolicy.ts
涉及页面：Calculate PRD / Catalog PRD / Scan POS PRD / Scan IMEI PRD
共 4 个独立接口 + 2 个引用已有专项文档
业务上下文
SA 帮客户在门店现场办分期，本步骤是 pre-OTP 试算阶段（订单尚未落库）：
- SA 选/扫商品 → 拿到设备识别（brand / model）
- SA 扫店内 POS 码 → 确认现场办单 + 锁定 merchant + pos
- SA 填实际售价 → 触发风控政策预览（DP 区间 / term 选项 / 价格上限）
- SA 选 frequency（weekly / monthly）+ term → 计算单期还款
- SA 客户认可方案 → 跳 Verify 步骤进入 OTP
试算数据是 本地 Draft（前端 zustand 持久化），不调后端持久化；只有调本分册的 5 个查询接口 + 03 分册的 OTP 流程。
1. 商品目录查询
业务描述：拉取 SA 授权范围内的商品全集（不分品牌；按品类）。用于 Catalog 子页让 SA 浏览选品。
触发场景：
- Calculate 页 mount（用于解析
product_id校验上下文） - Catalog 子页 mount
入参
无业务字段（鉴权 token 即可；后端按 SA 授权过滤可见商品）
出参
| 字段 | 类型 | 说明 |
|---|---|---|
| categories | array<string> | 商品品类（如 ['mobile', 'tablet']） |
| products | array<ProductSku> | 商品 SKU 列表 |
ProductSku 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| product_id | string | SKU ID |
| category | string | 品类（mobile / tablet） |
| brand | string | 品牌（如 TECNO） |
| model_name | string | 型号 + 配置（如 Camon 20 (6G+128G)） |
| estimated_price | number(NGN) | 建议价（catalog 标价；SA 现场可改成实际售价） |
| image_url | string? | 商品图（可选） |
注：catalog 仅作”录单加速器”，不持有政策语义。DP 区间 / 价格上限 / term 选项均由 信贷政策接口 在 SA 填价后动态返回。
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| CATALOG_UNAVAILABLE | 商品目录暂不可用（后台维护 / 数据库不可达） | 显示 Retry 按钮 |
2. Hot Picks 查询
业务描述：拉取首页”热推商品”列表（市场级，不 per merchant）。包含促销卡片所需的推荐分期方案（promo_term）。
触发场景：Home 页 mount。
入参
无业务字段。
出参
数组形式，每项为 ProductSku（同上）+ 以下扩展字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| hot_pick | boolean | 必为 true（本接口已隐含） |
| promo_term | int | 推荐分期期数（按 monthly 默认 frequency；Home 卡片用于展示「× N months」） |
注：Hot Picks 卡片上展示的”月供”由前端 estimated_price + promo_term + 默认 DP 比例（30%）本地估算，仅用于营销展示；客户真正办单时仍走风控政策接口拿准确 DP 区间。
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| HOT_PICKS_UNAVAILABLE | 暂无 Hot Picks 数据 | Home 卡片区显示空态文案 |
3. POS 扫码反查
业务描述：SA 在 ScanPosCode 页扫店内 QR 码（QR 内容 = pos_id），后端按 pos_id 反查 POS 详情 + 校验是否在该 SA 的授权列表里。
触发场景：ScanPosCode 页相机识别到 QR 内容时调用。
入参
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pos_id | string | ✓ | 扫到的 POS ID（QR 二维码内容） |
出参 — 返回 PosLocation 结构（与 01 分册一致）
| 字段 | 类型 | 说明 |
|---|---|---|
| pos_id / pos_name / pos_address | string | POS 基础信息 |
| merchant_id / merchant_name | string | 所属商户 |
前端拿到后写入 draft 的 pos / merchant 字段，且 Calculate 页 Next 按钮强制要求 draft.pos_id 已存在（防欺诈：办单前必扫码）。
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| POS_NOT_FOUND | POS ID 不存在 | toast “Invalid POS code” |
| POS_NOT_AUTHORIZED | 该 POS 不在当前 SA 授权列表 | toast “You’re not authorized for this POS” + 不写入 draft |
| POS_INACTIVE | POS 已停用 / 关店 | toast “This POS is no longer active” |
4. 还款分期试算
业务描述：给定 price / down_payment / frequency，返回该方案下各 term 选项对应的单期应还金额。供 Calculate 页 Payment Term tiles 与 Repayment Plan 展示。
触发场景：Calculate 页 price / down_payment / frequency 变化时重新计算。
入参
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| price | number(NGN) | ✓ | SA 填的实际售价 |
| down_payment | number(NGN) | ✓ | SA 填的首付金额 |
| frequency | enum | ✓ | weekly / monthly |
出参
| 字段 | 类型 | 说明 |
|---|---|---|
| frequency | enum | 入参回显 |
| options | array<InstallmentOption> | 各 term 选项的单期还款（用于 tile 展示） |
InstallmentOption 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| term | int | 分期期数（按 frequency 单位 — monthly 为月数 / weekly 为周数） |
| per_period_payment | number(NGN) | 单期应还（向上取整，含利息） |
注：term 选项的范围（如 monthly 3/6/9）由 信贷政策接口 的 term_options 字段决定；本接口仅根据已知 term 算金额。两个接口的协作：
- 政策接口先返回
term_options: [3, 6, 9] - 本接口对这些 term 算各自
per_period_payment - SA 选定 term → draft.term 更新
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| CALC_INVALID_INPUT | 入参不合法（price ≤ 0 / dp 超出范围） | inline 错误，前端阻止下一步 |
5. IMEI 设备反查（引用专项文档）
业务描述：SA 在 ScanImeiCode 页扫客户手机背面 IMEI 条形码，后端反查设备品牌 + 型号，写入 draft。
完整契约：见 10-IMEI设备反查
本分册补充：
- 调用方：ScanImeiCode 页取景框点击模拟识别（生产期由扫码 SDK 触发）
- 反查只返
brand/model，不带政策（政策走信贷政策接口） - 前端拿到 brand+model 写 draft 后，清空 product_id / price / down_payment / term（避免误用上一台机的金额）
6. 信贷政策预览（引用专项文档）
业务描述：Calculate 页 price onBlur 触发，向风控请求当下可批的 DP 区间 / term 选项 / 价格上限。
完整契约：见 02-信贷政策计算接口.md
本分册补充：
- 调用方：Calculate 页 price 输入失焦
- 入参：
product_id（catalog 路径）或device:{brand, model}（IMEI 路径）+price+frequency - 出参：dp_min / dp_max / dp_tiers / term_options / promo_term / price_cap / policy_version / policy_id
- 前端拿到后自动填
down_payment = suggested_dp和term = promo_term（首次拿到时）；后续 SA 修改优先
待业务方确认事项
| # | 议题 | 待确认 |
|---|---|---|
| 1 | 商品目录是否按 merchant 过滤 | 当前不传 merchant_id 拉全集；若不同 merchant 卖货品类有差异，需要在接口加 merchant_id 入参 |