Customer Portal 列表分页 — 前端接入说明

适用于 GET /portal/orders 和 GET /portal/invoices（只有这两个，其它列表接口未变）

接口已在生产环境验证可用

1. 快速开始

# 第 2 页，每页 25 条
curl -s "https://a1.shophive.ai/api/v1/portal/invoices?page=2&page_size=25" \
  -H "Accept: application/json" \
  -H "x-portal-token: <portal token>"

# 不带参数 = 老行为：全量 + 缓存 + 无 meta.pagination
curl -s "https://a1.shophive.ai/api/v1/portal/invoices" \
  -H "x-portal-token: <portal token>"

x-portal-token 就是 portal 现在每个请求都在带的那个 token；域名用 useGlobal().apiBaseUrl，别硬编码。

2. 请求参数

• 两个都不传 → 全量，不走下面这套分页逻辑。
• 只传一个 → 另一个用默认值（比如只传 page=3 就是第 3 页、每页 25 条）。
• 参数非法（page=0、page=abc、page_size=1.5）→ 400，不会静默忽略。

3. 响应结构

分页时，响应体在原有的 data 之外多一个 meta.pagination：

{
  "data": [
    { "invoice_no": "9463330", "invoice_date": "2026-09-30", ... },   // 25 条
    ...
  ],
  "meta": {
    "pagination": {
      "total_count": 1176,   // 整个结果集的条数
      "offset": 25,          // 本页第一条的偏移量（0 基）
      "limit": 25,           // 实际生效的每页条数
      "current": 2           // 页码（1 基）
    }
  }
}

这是每个 portal 列表接口本来就有的信封格式，usePortalHttp 已经会自动把 meta.pagination 解到 pagination 上，不用自己解析。

4. 前端接入

4.1 服务层

要能传 params，得在泛型里把 request 声明出来（现在是 request: never，TS 不让你给 fetchData 传参数）：

export const usePortalInvoiceList = () =>
  usePortalHttp<{
    request: { page?: number; page_size?: number }   // ← 加这个
    response: IPortalInvoiceType[]
  }>({
    url: '/portal/invoices',
    // 想首屏就分页就在这里带上；不传 = 全量（老行为）
    params: { page: 1, page_size: 25 },
  })

4.2 组件里翻页

const {
  data, pagination, loading, fetchData,
} = usePortalInvoiceList()

const onPageChange = (page: number, pageSize: number) =>
  fetchData({ params: { page, page_size: pageSize } })

接到 antd Table 上：

<Table
  dataSource={data ?? []}
  loading={loading}
  pagination={{
    current: pagination.current || 1,
    pageSize: pagination.limit || 25,
    total: pagination.total_count ?? data?.length ?? 0,
    showSizeChanger: true,
    onChange: onPageChange,
  }}
/>

5. 定制时必须知道的几件事

1. 搜索 / 筛选 / 列排序 / CSV 导出 / 顶部统计，现在都是对内存里的全量数组算的。 改成按页取之后，它们只能作用于当前这一页——搜不到第 2 页的记录，导出的也只有当页。 要保住这些能力，得把筛选条件也下推到接口，目前接口没有这些参数。 这是本次定制最大的取舍点，请先和产品确认。
2. 分页请求不走缓存。 不传参数的全量请求会走 portal 的缓存（15 分钟量级），分页请求每次都真去 ERP 取。所以「分页一定比全量快」不成立——首次加载可能反而更慢，换来的是响应体小、翻页稳定。
3. 最后一页可能不满，甚至可能是空的。 total_count 是 ERP 侧的计数，接口还会按该连接的「只取最近 N 个月」设置再裁一次，两者可能差几行。 所以：不要假设 offset + data.length === total_count；页码超出时会返回空数组而不是报错，这不算失败。
4. 详情页和 PDF 按钮不受影响。 它们的归属校验仍然用全量列表，所以客户点第 1 页以外的单据不会 404。前端也不需要为它们传分页参数。
5. 建议按客户开关。 这是给一家客户做的定制。建议只对那家开启分页（或只在新页面上用），其它客户/页面传都不传，保持全量，互不影响。接口侧不需要任何开关配置。
6. 目前只有 orders 和 invoices 支持。 quotes / purchases 等列表接口仍是全量；如果后面也要，走同样的模式加即可。

6. 自查清单