文档：发票待办补齐三 PR - 财务列表 NONE Tab + 订单字段 + 推送接口（#4233/#4235/#4238，Issue #4228~4230）

2026-06-22 17:10:23 +08:00 · 2026-06-22 17:10:23 +08:00 · 41acbe58bb
--- a/changelogs-v2/2026-06/22_4229_发票财务列表未申请tab与列表行订单信息-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/22_4229_发票财务列表未申请tab与列表行订单信息-修改接口-管理后台.md
@ -0,0 +1,273 @@
+# 发票财务列表 - 未申请 Tab 与列表行订单信息补齐（管理后台）
+
+> Issue: [#4228](https://git.1814.love:8443/wx/HL/issues/4228) / [#4229](https://git.1814.love:8443/wx/HL/issues/4229)
+> PR: [#4233](https://git.1814.love:8443/wx/HL/pulls/4233) / [#4235](https://git.1814.love:8443/wx/HL/pulls/4235)
+> 日期: 2026-06-22
+> 服务: hl-order-service-v3（invoice 域）
+> 端类型: 管理后台
+
+---
+
+## 1. 接口背景
+
+发票财务管理列表（GET /v3/admin/order/invoice/page）本次做两处补齐：
+
+1. **NONE Tab（未申请）**：新增 tab 可选值 NONE，返回「已完成（COMPLETED）且尚无有效发票」的订单列表，作为财务「代客申请」入口的候选。NONE Tab 下每行是「订单维度」，发票相关字段均为空，status 固定返回 NONE、statusText 固定返回「未申请」。
+2. **列表行补订单冗余信息**：所有 Tab 下的列表行新增 5 个订单展示字段（产品名、档位名、客户名、定制师名、出发日期），供列表直接渲染，无需二次请求。另，orderNo（订单号）字段此前已定义但未正确回填，本次修复。
+3. **tabCounts 新增 noneCount**：Tab 计数对象新增 noneCount 字段，表示「已完成且无发票」的订单数；allCount 含义不变（仍为 requested + issued + pushed 之和，不含 none）。
+
+关联 PR #4233 修复 orderNo 回填 + 新增 5 个订单字段；PR #4235 新增 NONE Tab 查询与 noneCount 统计。
+
+---
+
+## 2. 变更清单
+
+| # | 接口 | 变更类型 | 说明 |
+|---|------|----------|------|
+| 1 | GET /v3/admin/order/invoice/page | 修改接口 | 入参 tab 新增可选值 NONE |
+| 2 | GET /v3/admin/order/invoice/page | 修改接口 | 出参 records[] 新增 5 个字段（productName / tierName / contactName / customizerName / departureDate） |
+| 3 | GET /v3/admin/order/invoice/page | 修改接口 | 出参 records[].orderNo 字段由恒 null 修复为正确回填 |
+| 4 | GET /v3/admin/order/invoice/page | 修改接口 | 出参 tabCounts 新增 noneCount 字段 |
+---
+
+## 3. 接口详情
+
+**接口**：GET /v3/admin/order/invoice/page
+**功能描述**：发票管理分页列表，含 Tab 过滤、统计数据与关键词搜索。
+**认证**：管理后台 JWT，Header 携带 Authorization: Bearer <token>。
+**请求方式**：GET，参数均以 Query String 传入。
+**幂等性**：只读查询，天然幂等。
+**限流**：网关全局限流，无接口级特殊限流。
+
+---
+
+## 4. 接口入参
+
+### 4.1 路径参数 / Query 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| page | Integer | 否 | 页码，默认 1 |
+| pageSize | Integer | 否 | 每页条数，默认 20 |
+| tab | String | 否 | Tab 过滤，默认 ALL；本次新增可选值 NONE，见 6 节枚举 |
+| keyword | String | 否 | 关键词搜索（发票号 / 申请人）；NONE Tab 下该参数暂不生效 |
+| startDate | String | 否 | 申请开始日期，格式 yyyy-MM-dd；NONE Tab 下暂不生效 |
+| endDate | String | 否 | 申请结束日期，格式 yyyy-MM-dd；NONE Tab 下暂不生效 |
+
+### 4.2 请求体字段
+
+GET 接口无请求体。
+---
+
+## 5. 出参字段
+
+**响应结构**（Result<PageResult<InvoicePageItemRespVO>>）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| records | Array | 发票 / 订单列表（见下方单条字段表） |
+| total | Long | 总记录数 |
+| page | Integer | 当前页码 |
+| pageSize | Integer | 每页条数 |
+| tabCounts | Object | 各 Tab 计数，见下方 tabCounts 字段表 |
+| stats | Object | 当月统计（currentMonthIssuedCount / currentMonthIssuedAmount） |
+
+**records 单条字段**（含本次新增字段，标注 NEW）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 发票 ID（Long 序列化）；NONE Tab 下为 null |
+| orderId | String | 所属订单 ID（Long 序列化） |
+| orderNo | String | 订单号（此前未回填，本次修复） |
+| productName | String | 产品名 [NEW] |
+| tierName | String | 档位名 [NEW] |
+| contactName | String | 客户名（订单联系人） [NEW] |
+| customizerName | String | 定制师名 [NEW] |
+| departureDate | String | 出发日期，格式 yyyy-MM-dd [NEW] |
+| status | String | 发票状态枚举，见 6 节；NONE Tab 下固定返回 NONE |
+| statusText | String | 发票状态中文名；NONE Tab 下固定返回「未申请」 |
+| amount | String | 开票金额（字符串，单位元）；NONE Tab 下为 null |
+| invoiceType | String | 发票类型枚举；NONE Tab 下为 null |
+| invoiceTypeName | String | 发票类型中文名；NONE Tab 下为 null |
+| titleType | String | 抬头类型；NONE Tab 下为 null |
+| title | String | 发票抬头；NONE Tab 下为 null |
+| taxNo | String | 税号；NONE Tab 下为 null |
+| fileUrl | String | 发票 PDF 地址；NONE Tab 下为 null |
+| pdfName | String | PDF 文件名；NONE Tab 下为 null |
+| pdfSize | Long | PDF 文件大小（字节）；NONE Tab 下为 null |
+| invoiceNo | String | 发票号码；NONE Tab 下为 null |
+| issuedAt | String | 开票时间（ISO 8601）；NONE Tab 下为 null |
+| issuedBy | String | 开票人姓名；NONE Tab 下为 null |
+| requestedAt | String | 申请时间（ISO 8601）；NONE Tab 下为 null |
+| requestedBy | String | 申请人；NONE Tab 下为 null |
+| createTime | String | 记录创建时间；NONE Tab 下为 null |
+
+**tabCounts 字段**（含本次新增字段，标注 NEW）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requestedCount | Integer | 待开票数量 |
+| issuedCount | Integer | 已开票数量 |
+| pushedCount | Integer | 已推送数量 |
+| allCount | Integer | 全部（= requested + issued + pushed，不含 none） |
+| noneCount | Integer | 未申请（已完成订单无发票）数量 [NEW] |
+---
+
+## 6. 枚举 / 数据字典
+
+**Tab 过滤值（入参 tab 字段）**
+
+| 值 | 说明 |
+|----|------|
+| ALL | 全部（默认），仅含有发票记录的数据 |
+| REQUESTED | 仅待开票 |
+| ISSUED | 仅已开票 |
+| PUSHED | 仅已推送 |
+| NONE | 未申请（已完成订单且无发票）[NEW] |
+
+**InvoiceStatus - 发票状态（records[].status）**
+
+| 枚举值 | 中文名 | 说明 |
+|--------|--------|------|
+| REQUESTED | 待开票 | 用户 / 定制师已申请，等待财务处理 |
+| ISSUED | 已开票 | 财务已完成开票并上传 PDF |
+| PUSHED | 已推送 | 发票已推送给客户 |
+| VOIDED | 已作废 | 发票已作废 |
+| NONE | 未申请 | 仅 NONE Tab 下返回，表示该订单尚无发票 [NEW] |
+
+**InvoiceType - 发票类型**
+
+| 枚举值 | 中文名 |
+|--------|--------|
+| VAT_NORMAL | 增值税普通发票 |
+| VAT_SPECIAL | 增值税专用发票 |
+| ELECTRONIC | 电子发票 |
+
+---
+
+## 7. 错误码
+
+本次修改为纯出参扩展与入参新增可选值，无新增错误码。已有行为：
+
+| 情况 | 行为 |
+|------|------|
+| tab 传入非法枚举值（如 tab=INVALID） | HTTP 400 参数校验错误 |
+---
+
+## 8. 示例
+
+### 8.1 典型成功：ALL Tab 列表（含新增 5 个订单字段）
+
+请求：
+
+
+
+响应：
+
+
+### 8.2 边界情况：NONE Tab（代客申请候选列表，发票字段全 null）
+
+请求：
+
+
+
+响应（NONE Tab 下发票相关字段均为 null，id 为 null，status 固定 NONE）：
+
+
+
+### 8.3 业务失败：tab 传入非法枚举值
+
+请求：
+
+
+
+响应：
+
+
+---
+
+## 9. 业务边界
+
+**适用：**
+- 财务人员查看所有发票记录，按 Tab 分类处理
+- NONE Tab：列出已完成（COMPLETED）且尚未申请发票的订单，财务可点击「代客申请」按钮（调 POST /v3/admin/order/{orderId}/invoice/apply，该接口本次未变更）
+
+**不适用：**
+- NONE Tab 不展示非 COMPLETED 订单（如 CUSTOMIZING、PAID、TRAVELLING 等状态的订单不出现在 NONE Tab）
+- VOIDED 发票不算有效发票，该订单仍可出现在 NONE Tab（后端实现口径以实测为准）
+
+**特殊边界：**
+- NONE Tab 下 keyword（关键词）与 startDate / endDate（日期范围）参数暂不生效，传了也不做过滤
+- noneCount 不计入 allCount；两者相互独立，前端 Tab 计数需分别展示
+- NONE Tab 每行「id」字段为 null，前端渲染「代客申请」按钮时须使用 orderId，而非 id
+
+---
+
+## 10. 修改前后对比
+
+**入参 tab 字段变化：**
+
+| tab 可选值 | 变更前 | 变更后 |
+|-----------|--------|--------|
+| ALL | 支持 | 不变 |
+| REQUESTED | 支持 | 不变 |
+| ISSUED | 支持 | 不变 |
+| PUSHED | 支持 | 不变 |
+| NONE | 不存在 | 新增（未申请订单） |
+
+**出参 records[] 字段变化：**
+
+| 字段名 | 变更前 | 变更后 |
+|--------|--------|--------|
+| orderNo | 有定义但恒 null（bug） | 正确回填订单号 |
+| productName | 不存在 | 新增（产品名） |
+| tierName | 不存在 | 新增（档位名） |
+| contactName | 不存在 | 新增（客户名） |
+| customizerName | 不存在 | 新增（定制师名） |
+| departureDate | 不存在 | 新增（出发日期，yyyy-MM-dd） |
+
+**出参 tabCounts 字段变化：**
+
+| 字段名 | 变更前 | 变更后 |
+|--------|--------|--------|
+| requestedCount | 存在 | 不变 |
+| issuedCount | 存在 | 不变 |
+| pushedCount | 存在 | 不变 |
+| allCount | 存在（= requested+issued+pushed） | 不变（仍不含 none） |
+| noneCount | 不存在 | 新增（未申请订单数） |
+---
+
+## 11. 影响评估 / 回滚
+
+**破坏兼容性：**
+- 出参新增字段（productName / tierName / contactName / customizerName / departureDate / noneCount）为纯新增，不破坏旧字段，向后兼容。
+- orderNo 由 null 变为有值：如前端已有 null 防护（判 null 不渲染），行为不变；原先已渲染 orderNo 列但始终空白，现在将正常显示。
+- tab=NONE 为新可选值；旧版前端不传，不影响现有功能。
+
+**前端同步上线：**
+- 新增 NONE Tab 入口与「代客申请」按钮需前端接线，否则 NONE Tab 功能不可见。
+- 新增 5 个订单字段可直接接线渲染到列表列，无需二次请求。
+
+**回滚方案：**
+回滚后端至旧版本后：新增字段消失、orderNo 重新恒 null、tab=NONE 入参不识别（返回空列表或 400）、noneCount 消失。前端可对缺失字段做 null 防护兜底。
+
+---
+
+## 12. 注意事项
+
+1. NONE Tab 列表行的 id 为 null，前端渲染「代客申请」按钮须用 orderId（Long 序列化字符串）传给 POST /v3/admin/order/{orderId}/invoice/apply。
+2. departureDate 类型为字符串，格式固定 yyyy-MM-dd，前端直接展示，无需额外格式化。
+3. noneCount 与 allCount 互不包含，前端 Tab 头需分别渲染。
+4. NONE Tab 暂不支持 keyword / startDate / endDate 过滤；前端可在 NONE Tab 时隐藏对应搜索框，或保留但提示「当前 Tab 不支持筛选」。
+5. orderNo 恒 null 为历史 bug，本次修复后所有 Tab 下均有值；原先前端若有「有 orderNo 才渲染」的逻辑可直接保留，无需改动。
+6. amount 等金额字段均为 String 类型，前端须按字符串接收，避免 JS 大数精度丢失。
+
+---
+
+## 13. 关联 / 联系人
+
+- Issue（订单字段补齐）: https://git.1814.love:8443/wx/HL/issues/4228
+- Issue（NONE Tab）: https://git.1814.love:8443/wx/HL/issues/4229
+- PR（订单字段补齐 + orderNo 修复 #4233）: https://git.1814.love:8443/wx/HL/pulls/4233
+- PR（NONE Tab + noneCount #4235）: https://git.1814.love:8443/wx/HL/pulls/4235
+- 后端负责人: yaosutu
--- a/changelogs-v2/2026-06/22_4230_发票推送客户-新增接口-管理后台.md
+++ b/changelogs-v2/2026-06/22_4230_发票推送客户-新增接口-管理后台.md
@ -0,0 +1,193 @@
+# 发票推送客户 - 新增接口（管理后台）
+
+> Issue: [#4230](https://git.1814.love:8443/wx/HL/issues/4230)
+> PR: [#4238](https://git.1814.love:8443/wx/HL/pulls/4238)
+> 日期: 2026-06-22
+> 服务: hl-order-service-v3（invoice 域）
+> 端类型: 管理后台
+
+---
+
+## 1. 接口背景
+
+invoice 域开票完成后，财务需要将发票推送给客户。本次新增 PUT /v3/admin/order/invoice/{id}/push 接口，财务指定推送渠道（邮件 / 微信 / 短信）后调用，发票状态置为 PUSHED 并记录推送时间与渠道。
+
+**注意**：本期推送仅记录状态与渠道，后端**暂不真正发送**邮件 / 微信 / 短信通知（通知网关后续单独接入）。前端可正常调用并据返回展示「已推送」，但客户实际不会收到通知，功能上线后再由后端对接通知网关。
+
+---
+
+## 2. 变更清单
+
+| # | 接口 | 变更类型 | 说明 |
+|---|------|----------|------|
+| 1 | PUT /v3/admin/order/invoice/{id}/push | 新增接口 | 推送发票给客户（记录状态与渠道，暂不真发通知） |
+---
+
+## 3. 接口详情
+
+**接口**：PUT /v3/admin/order/invoice/{id}/push
+**功能描述**：推送已开票发票给客户，指定推送渠道。
+**认证**：管理后台 JWT，Header 携带 Authorization: Bearer <token>。
+**请求方式**：PUT，请求体 Content-Type: application/json。
+**幂等性**：不保证幂等，多次调用=多次推送记录（PUSHED 状态再次调用视为「再次推送」）。
+**限流**：网关全局限流，无接口级特殊限流。
+
+---
+
+## 4. 接口入参
+
+### 4.1 路径参数 / Query 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | Long | 是 | 发票 ID（路径参数） |
+
+### 4.2 请求体字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| channels | Array<String> | 是 | 推送渠道列表，至少一个，合法值仅 email / wechat / sms，见 6 节枚举 |
+---
+
+## 5. 出参字段
+
+**响应类型**：Result<Void>（data 为 null）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | Integer | 200 表示推送成功 |
+| data | null | 固定为 null |
+| msg | String | 成功时为 null 或 success；失败时为错误描述 |
+
+---
+
+## 6. 枚举 / 数据字典
+
+**推送渠道（channels 数组合法值）**
+
+| 值 | 说明 |
+|----|------|
+| email | 电子邮件 |
+| wechat | 微信通知 |
+| sms | 短信 |
+
+**InvoiceStatus 发票状态（推送前后）**
+
+| 枚举值 | 中文名 | 说明 |
+|--------|--------|------|
+| REQUESTED | 待开票 | 不允许推送 |
+| ISSUED | 已开票 | 允许推送，推送后变 PUSHED |
+| PUSHED | 已推送 | 允许再次推送，状态维持 PUSHED |
+| VOIDED | 已作废 | 不允许推送 |
+
+---
+
+## 7. 错误码
+
+| 错误码 | 触发场景 |
+|--------|----------|
+| 581520 | 发票当前状态不允许推送（发票处于 REQUESTED 或 VOIDED 状态时调用） |
+| 581521 | 推送渠道不能为空（channels 为 null 或空数组） |
+| 581522 | 推送渠道非法（channels 中含 email / wechat / sms 以外的值） |
+---
+
+## 8. 示例
+
+### 8.1 典型成功：ISSUED 状态首次推送（邮件 + 微信）
+
+请求：
+
+
+
+请求体：
+
+
+
+响应：
+
+
+
+调用后，发票状态由 ISSUED 变为 PUSHED，记录推送时间与渠道 [email, wechat]。
+
+### 8.2 边界情况：PUSHED 状态再次推送（新增 sms 渠道）
+
+发票已处于 PUSHED 状态，再次调用视为「再次推送」，状态维持 PUSHED，渠道记录更新为 [sms]。
+
+请求：
+
+
+
+请求体：
+
+
+
+响应：
+
+
+
+### 8.3 业务失败：发票处于 REQUESTED 状态（未开票）调用推送
+
+请求：
+
+
+
+请求体：
+
+
+
+发票当前状态为 REQUESTED（待开票），响应：
+
+
+
+追加：空 channels 触发 581521：
+
+
+
+响应：
+
+
+---
+
+## 9. 业务边界
+
+**适用：**
+- 发票状态为 ISSUED（已开票）时可调用，推送后状态变为 PUSHED
+- 发票状态为 PUSHED（已推送）时可再次调用，状态维持 PUSHED，记录最新推送渠道
+
+**不适用：**
+- 发票状态为 REQUESTED（待开票）时禁止推送，须先财务开票
+- 发票状态为 VOIDED（已作废）时禁止推送
+
+**特殊边界：**
+- 本期推送为「记录意图」：调用成功仅更新状态 / 记录渠道，后端不真正发送邮件 / 微信 / 短信。通知网关对接为后续迭代。
+- channels 可同时传多个渠道（如 [email, wechat, sms]），后端均记录，但通知未接通时均不发送。
+- channels 中只要有一个非法值（如 [email, phone]），整个请求返回 581522 错误，不部分推送。
+
+---
+
+## 10. 修改前后对比
+
+（本文件为新增接口，无修改前对比。）
+
+---
+
+## 11. 影响评估 / 回滚
+
+（本文件为新增接口，无兼容性破坏。）
+
+---
+
+## 12. 注意事项
+
+1. **推送不真发**：本期调用成功后客户实际收不到邮件 / 微信 / 短信。前端展示「已推送」状态，但需在 UI 说明或等通知网关接入后再对外宣传此功能。
+2. channels 字段必须是字符串数组（即使只有一个渠道也要用数组形式：[email]），不能传字符串 email。
+3. PUSHED 状态再次调用成功，可用于「重新推送」场景（如客户反馈未收到，财务再次操作）。
+4. id 为发票 ID（Long 序列化字符串），非订单 ID；调用前需先通过发票列表接口获取发票 id。
+
+---
+
+## 13. 关联 / 联系人
+
+- Issue（发票推送客户）: https://git.1814.love:8443/wx/HL/issues/4230
+- PR（发票推送 #4238）: https://git.1814.love:8443/wx/HL/pulls/4238
+- 后端负责人: yaosutu