07 — 列表与汇总查询
来源：
api/applications.ts fetchOrders+api/home.ts fetchHomeData
涉及页面：Applications PRD / Home PRD
共 2 个接口
业务上下文
SA 工作日常的”工作汇总视图”：
- 首页（Home）：一眼看到「Pending Work」各状态的订单数 + 公告（推动 SA 立刻处理待办）
- 进件列表（Applications）：按状态 / 时间 / merchant 筛选历史订单（支持复借场景的同号搜索）
关键设计：
- 首页汇总是 轻量计数 + 公告（不返回订单详情；点 Pending Work 卡片跳进 Applications 用对应筛选）
- 列表接口支持多维筛选 + 分页（应对 SA 长期工作 → 数百单累积）
1. 进件列表查询
订单状态机完整定义见 手机分期订单状态机（SoT）。本文涉及 status / close_reason / fix_reason / offer_type 等枚举取值与 UI Tab 映射，均以 SoT 为准。
业务描述：拉取该 SA 历史订单列表 — 支持按状态分类（4 Tab：UI 标签 Pending / Reviewing / Completed / Closed；技术字段 status_tab = pending / in_approval / completed / closed）+ merchant 筛选 + 关键字搜索 + 分页。
触发场景：
- Applications 页 mount / Tab 切换 / 筛选变化 / 搜索 / 下拉刷新 / 加载更多
入参
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status_tab | enum | ✓ | pending / in_approval / completed / closed（技术字段名；UI Tab label 分别为 Pending / Reviewing / Completed / Closed；映射规则见下方） |
| merchant_id | string | merchant 筛选；不传 = 全部 merchant | |
| search | string | 关键字（按客户姓名 / 手机号 / 订单短码搜索） | |
| cursor | string | 分页 cursor；首次拉取不传 | |
| page_size | int | 每页数量；默认 20 |
status_tab 与 order.status 映射规则
| status_tab | 包含的 status |
|---|---|
| pending | Drafting / FixRequired / Approved / Signed / Paid（SA 待处理的） |
| in_approval | Reviewing（已提交风控审批中） |
| completed | Completed（已交付 + 锁机激活） |
| closed | Closed（含 close_reason 细分原因，见 OrderListItem 字段） |
出参
| 字段 | 类型 | 说明 |
|---|---|---|
| items | array<OrderListItem> | 订单列表项 |
| next_cursor | string? | 下一页 cursor；null 表示无更多 |
| total | int? | 总数（可选；MVP 不强求） |
OrderListItem 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | string | |
| short_code | string | 短码（UI 紧凑展示，如 #8A2F1C） |
| customer_name | string | 客户姓名（若 Identity 已采集，否则空） |
| phone_tail | string | 手机号末 4 位（隐私脱敏；UI 展示用） |
| product | string | 商品描述（品牌 + 型号 + 配置） |
| amount | number(NGN) | 订单金额 |
| merchant_id | string | |
| merchant_label | string | merchant 短名（如 Ikeja，UI 紧凑展示） |
| status | enum | 同 04 分册 status 枚举 |
| close_reason | enum? | 仅 status = Closed 时有；declined / returned / expired |
| fix_reason | enum? | 仅 status = FixRequired 时有；identity_mismatch / income_insufficient / guarantor_invalid / address_unverified / other |
| fix_notes | string? | FixRequired 时的自由文本补充（其它状态可空） |
| offer_type | enum? | 仅 status ∈ {Approved, Signed, Paid, Completed} 时有；original / revised（风控调价） |
| expires_at | string(ISO 8601)? | 当前状态过期时间（如 Approved 有 24h 限时签约） |
| updated_at | string(ISO 8601) | 最后更新时间（默认列表排序字段） |
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| INVALID_STATUS_TAB | tab 不在枚举内 | 兜底 — 不应该发生 |
| MERCHANT_NOT_AUTHORIZED | 入参 merchant_id 不在 SA 授权列表 | 清空筛选 + toast |
2. 首页汇总（Pending Work + 公告）
业务描述：Home 页一次性拉取多个维度的汇总数据 — 待办计数（Pending Work 6 类）+ 公告列表。设计成”轻量汇总接口”减少 Home mount 时的多次请求。
触发场景：Home 页 mount / 下拉刷新。
入参
无业务字段（鉴权 token 即可）
出参
| 字段 | 类型 | 说明 |
|---|---|---|
| pending | PendingCounts | 待办计数（按子类型） |
| announcements | array<Announcement> | 平台公告列表（如运营推广 / 系统通知） |
PendingCounts 结构
| 字段 | 类型 | 含义 | UI 标签 |
|---|---|---|---|
| submit | int | 进件中（Drafting 状态计数） | Submit |
| fix_info | int | 需补正资料（FixRequired） | Fix |
| sign | int | 待签约（Approved） | Sign |
| pay | int | 待收首付（Signed） | Pay |
| deliver | int | 待交付（Paid） | Deliver |
| in_approval | int | 审批中（Reviewing） | Review |
| tasks | int? | 其它平台分发任务（如运营让 SA 拜访某商户） | Tasks |
Announcement 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 公告 ID |
| title | string | 标题 |
| subtitle | string | 副标题 / 摘要 |
| link_url | string? | 详情跳转链接（可选） |
| priority | int? | 排序权重（可选） |
前端处理：
- 点击 Pending Work 某个数字卡 → 跳 Applications 页并自动应用对应 status_tab 筛选
- 点击 Announcement → 浏览器打开 link_url 或显示详情 sheet
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| HOME_DATA_PARTIAL | 部分子数据拉取失败（如 announcement 服务挂） | 局部空态 + 其它正常显示 |