8.1 KiB
8.1 KiB
发票管理列表搜索补齐（订单号接线 + 客户名 + 跨 tab 完整搜索）（管理后台）
- 接口：GET /v3/admin/order/invoice/page
- 变更类型：修改接口（新增入参
contactName；orderNo由声明变为生效；搜索跨全部 tab） - 端类型：管理后台
- 日期：2026-06-25
- Issue：#4383
- PR：#4384
发票管理列表搜索原为半成品：orderNo 声明了但未生效，titleName/requestedBy 仅部分 tab 生效，ALL/NONE 不支持搜索。本次补齐为四维度（订单号 / 客户名 / 开票抬头 / 申请人）跨全部 tab 完整生效。
1 接口背景
发票管理列表 GET /v3/admin/order/invoice/page 支持按 tab（待开票/待推送/已推送/未申请/全部）分页查询。原搜索能力残缺：
orderNo（订单号）入参已声明但后端未接线（无效字段）。titleName（开票抬头）/requestedBy（申请人）仅在 REQUESTED/ISSUED/PUSHED 三个 tab 生效。- ALL（全部）/ NONE（未申请）两个 tab 完全不支持搜索。
- 无「客户名」搜索入参。
本次补齐为四维度搜索，跨全部 tab 完整生效。
2 变更清单
| # | 变更项 | 变更前 | 变更后 |
|---|---|---|---|
| 1 | 入参 contactName |
无 | 新增，客户名模糊搜索 |
| 2 | 入参 orderNo |
已声明但未生效 | 生效，订单号模糊搜索 |
| 3 | 入参 titleName |
仅状态 tab 生效 | 全部相关 tab 生效（NONE 除外，无发票） |
| 4 | 入参 requestedBy |
仅状态 tab 生效 | 全部相关 tab 生效（NONE 除外，无发票） |
| 5 | ALL / NONE tab 搜索 | 不支持 | 支持（订单号/客户名直接搜；开票抬头/申请人对 ALL 跨表生效） |
| 6 | 角标计数 tabCounts / 顶部统计 stats | 全局 | 保持全局，不随搜索过滤（仅列表 records 过滤） |
3 接口详情
| 属性 | 值 |
|---|---|
| 方法 | GET |
| 路径 | /v3/admin/order/invoice/page |
| 描述 | 发票管理列表分页查询（tab 过滤 + 四维度模糊搜索 + 角标计数 + 顶部统计） |
| 认证 | Bearer JWT（管理员） |
| 幂等性 | 查询接口，幂等 |
| 限流 | 无特殊限制 |
4 接口入参（Query 参数）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNo | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页条数，默认 20 |
| tab | string | 否 | tab 过滤：REQUESTED / ISSUED / PUSHED / NONE / ALL，默认 ALL |
| orderNo | string | 否 | 订单号模糊搜索（本次接线生效） |
| contactName | string | 否 | 客户名模糊搜索（本次新增） |
| titleName | string | 否 | 开票抬头模糊搜索 |
| requestedBy | string | 否 | 申请人模糊搜索 |
四个搜索字段均为模糊匹配，可任意组合；为空的字段自动跳过。
搜索维度按 tab 生效矩阵
| 维度 | 字段来源 | REQUESTED/ISSUED/PUSHED | ALL | NONE |
|---|---|---|---|---|
| orderNo（订单号） | 订单 | ✅ | ✅ | ✅ |
| contactName（客户名） | 订单 | ✅ | ✅ | ✅ |
| titleName（开票抬头） | 发票 | ✅ | ✅ | ⛔（未申请无发票，命中即空） |
| requestedBy（申请人） | 发票 | ✅ | ✅ | ⛔（未申请无发票，命中即空） |
5 出参字段
响应为分页结构（InvoicePageRespVO），字段同改前未变：
| 字段 | 类型 | 说明 |
|---|---|---|
| records | array | 当前页发票/订单行列表 |
| total | long | 符合搜索条件的总条数 |
| page | int | 当前页码 |
| pageSize | int | 每页条数 |
| tabCounts | array | 各 tab 角标计数（全局口径，不随搜索过滤） |
| stats | array | 顶部统计（全局口径，不随搜索过滤） |
行字段（orderNo / contactName / customizerName / titleName / status / productName / productCoverImg 等）维持原有结构，本次不变。
6 枚举 / 数据字典
6.1 tab 取值
| code | 含义 |
|---|---|
| REQUESTED | 待开票 |
| ISSUED | 待推送（已开票） |
| PUSHED | 已推送 |
| NONE | 未申请（已完成出行、尚未申请发票的订单） |
| ALL | 全部 |
本次无新增枚举/字典。
7 错误码
本次无新增错误码。查询接口异常走全局统一处理。
8 示例
8.1 典型成功——按订单号搜索（任意 tab）
请求
GET /v3/admin/order/invoice/page?pageNo=1&pageSize=20&tab=ALL&orderNo=HL20260620152823663
Authorization: Bearer <token>
响应（命中 1 条）
{"code":200,"msg":"success","data":{"records":[{"orderNo":"HL20260620152823663","contactName":"冯雷","titleName":"张三","status":"PUSHED"}],"total":1,"page":1,"pageSize":20,"tabCounts":[],"stats":[]}}
8.2 边界——客户名搜索（一个客户多单）
请求
GET /v3/admin/order/invoice/page?tab=ALL&contactName=冯雷
响应（命中 2 条，同客户多单）
{"code":200,"msg":"success","data":{"records":[{"contactName":"冯雷"},{"contactName":"冯雷"}],"total":2}}
8.3 跨表搜索——发票视角 tab 按订单号过滤
说明：PUSHED 等状态 tab 走发票表，订单号属订单表，后端自动反查订单 ID 限定发票结果。
请求
GET /v3/admin/order/invoice/page?tab=PUSHED&orderNo=HL20260620152823663
响应（命中 1 条）
{"code":200,"msg":"success","data":{"records":[{"orderNo":"HL20260620152823663","status":"PUSHED"}],"total":1}}
8.4 无命中——返回空列表（非报错）
请求
GET /v3/admin/order/invoice/page?tab=ALL&orderNo=NOSUCH999
响应
{"code":200,"msg":"success","data":{"records":[],"total":0}}
9 业务边界
- 四个搜索字段可任意组合，均为模糊匹配，空字段跳过。
- NONE（未申请）tab 不含发票，传
titleName/requestedBy时结果为空（属预期，非报错）。 - 搜索仅影响列表
records与total；tabCounts（角标计数）和stats（顶部统计）保持全局口径，不随搜索过滤。 - 无命中返回空列表 + total=0，HTTP 200，不报错。
10 修改前后对比
入参对比
| 字段 | 变更前 | 变更后 |
|---|---|---|
| contactName | 无 | 新增，客户名模糊搜索 |
| orderNo | 声明但无效 | 生效，订单号模糊搜索 |
| titleName / requestedBy | 仅状态 tab 生效 | 全部相关 tab 生效（NONE 除外） |
搜索覆盖对比
| tab | 变更前可搜字段 | 变更后可搜字段 |
|---|---|---|
| REQUESTED/ISSUED/PUSHED | titleName / requestedBy | orderNo / contactName / titleName / requestedBy |
| ALL | 无 | orderNo / contactName / titleName / requestedBy |
| NONE | 无 | orderNo / contactName |
11 影响评估 / 回滚
破坏兼容性：否（纯增强，新增可选入参 + 原无效入参生效）
- 前端可在发票管理列表搜索框接入四个维度（订单号 / 客户名 / 开票抬头 / 申请人），任意组合提交。
- 原已传
titleName/requestedBy的前端不受影响，行为兼容并扩展到更多 tab。 - 角标计数/顶部统计为全局口径，前端若期望随搜索联动，请另行沟通（当前不联动）。
回滚方案：回滚后端至本 PR 前版本，contactName 入参失效、orderNo 回到无效状态、ALL/NONE 不支持搜索。前端入参传了也无副作用（被忽略）。
12 注意事项
contactName搜的是订单「客户名」（联系人），与「申请人 requestedBy」是两个维度，勿混。- NONE tab 传开票抬头/申请人会得到空列表，属预期——未申请订单尚无发票记录。
- 无命中是空列表 + total=0，不是错误码；前端按空态展示即可。
- 角标计数/统计为全局，搜索后角标数字与列表条数可能不一致，属设计预期。
13 关联 / 联系人
- Issue：#4383 发票管理列表搜索补齐
- PR：#4384
- 后端负责人：腰苏图（yaosutu）