wx/hl-api-changelog

派生 0

yaosutu 7c93c5b89d 发票补齐系列：管理后台财务开票闭环+定制师代申请 + 小程序端申请可见性签名下载

2026-06-21 22:47:57 +08:00

10 KiB

原始文件 Blame 文件历史

发票补齐 - 小程序端申请 + 可见性过滤 + 签名下载（小程序端）

Issue: #4174 / #4182 PR: #4181（mp 端申请+可见性）/ #4184（签名下载）日期: 2026-06-21 服务: hl-order-service-v3（invoice 域）端类型: 小程序端

1. 接口背景

小程序发票模块本次补齐三项改动：

申请门槛收紧（PR4 / Issue #4174）：原 collab 域 POST /v3/internal/mp/order/{orderId}/invoice/apply 路径不变，但实现从 collab 迁入 invoice 域，门槛由宽松（可叠加多张）改为严格（一单一票 + 订单必须 COMPLETED + 金额不超订单总价）。
出参可见性过滤（PR4）：GET /v3/internal/mp/order/{orderId}/invoice/list 和 GET /v3/internal/mp/order/invoice/{invoiceId}/detail 出参中，fileUrl 字段现在仅在 ISSUED / PUSHED 状态时返回；REQUESTED 状态返回 null（处理中，前端勿展示 PDF 链接）。
新增签名下载端点（#4184 / Issue #4182）：GET /v3/internal/mp/order/invoice/{invoiceId}/download，返回 1 小时有效期 OSS 签名 URL，供前端调 wx.openDocument 预览或下载发票 PDF。

2. 变更清单

#	接口	变更类型	说明
1	POST /v3/internal/mp/order/{orderId}/invoice/apply	修改接口（行为收紧）	申请门槛由宽松改严格：一单一票 + 订单 COMPLETED + 金额不超总价；resp status 字段值从 APPLIED 改为 REQUESTED
2	GET /v3/internal/mp/order/{orderId}/invoice/list	修改接口（字段行为变化）	fileUrl 字段：REQUESTED 状态由有值改为 null；ISSUED / PUSHED 保持有值
3	GET /v3/internal/mp/order/invoice/{invoiceId}/detail	修改接口（字段行为变化）	fileUrl 字段同上：REQUESTED 返 null，ISSUED / PUSHED 有值
4	GET /v3/internal/mp/order/invoice/{invoiceId}/download	新增接口	返回发票 PDF 的 OSS 签名下载 URL（1 小时有效期），含 IDOR 鉴权

3. 接口详情

认证：所有接口走小程序 JWT 认证，Header 携带 Authorization: Bearer token（小程序 openId → userId）。幂等性：apply 非幂等（一单一票，重复提交报 581511）；download 幂等（每次生成新签名 URL）。限流：网关全局限流。

4. 接口入参

4.1 路径参数 / Query 参数

接口	参数名	类型	必填	说明
POST /{orderId}/apply	orderId	Long	是	路径参数，订单 ID
GET /{orderId}/invoice/list	orderId	Long	是	路径参数，订单 ID
GET /invoice/{invoiceId}/detail	invoiceId	Long	是	路径参数，发票 ID
GET /invoice/{invoiceId}/download	invoiceId	Long	是	路径参数，发票 ID

4.2 请求体字段

POST /v3/internal/mp/order/{orderId}/invoice/apply

字段	类型	必填	说明
amount	String	是	开票金额（字符串，单位元），不超过订单总价
invoiceType	String	是	发票类型，枚举见 6 节
titleType	String	是	抬头类型：PERSONAL / COMPANY
title	String	是	发票抬头（姓名或公司名）
taxNo	String	条件必填	税号（titleType=COMPANY 时必填）
bankName	String	条件必填	开户行（invoiceType=VAT_SPECIAL 时必填）
bankAccount	String	条件必填	银行账号（invoiceType=VAT_SPECIAL 时必填）
registAddress	String	条件必填	注册地址（invoiceType=VAT_SPECIAL 时必填）
registPhone	String	条件必填	注册电话（invoiceType=VAT_SPECIAL 时必填）
email	String	条件必填	收票邮箱（invoiceType=ELECTRONIC 时必填）
remark	String	否	备注

GET 接口无请求体。

5. 出参字段

POST /v3/internal/mp/order/{orderId}/invoice/apply

字段	类型	说明
id	String	新建发票 ID（Long 序列化）
status	String	固定为 REQUESTED

注意：status 值此前旧实现返回 APPLIED（collab 域），新实现返回 REQUESTED（invoice 域）。请前端对齐新值。

GET /v3/internal/mp/order/{orderId}/invoice/list（单条字段，变化部分）

字段	原来行为	现在行为
fileUrl	REQUESTED / ISSUED / PUSHED 均有值	REQUESTED 返 null；ISSUED / PUSHED 有值

其余字段不变（id / orderId / status / statusName / amount / invoiceType / title / taxNo / createTime 等）。

GET /v3/internal/mp/order/invoice/{invoiceId}/detail（变化部分）

字段	原来行为	现在行为
fileUrl	同上，恒有值	REQUESTED 返 null；ISSUED / PUSHED 有值

GET /v3/internal/mp/order/invoice/{invoiceId}/download（新增接口）

字段	类型	说明
fileUrl	String	OSS 签名下载 URL（1 小时有效期，格式为 HTTPS 带签名参数的 URL）
pdfName	String	PDF 文件名（可选，用于 wx.openDocument 的 name 参数）

6. 枚举 / 数据字典

InvoiceStatus - 发票状态（影响 fileUrl 可见性）

枚举值	中文名	fileUrl 是否可见
REQUESTED	待开票	null（处理中，前端勿展示 PDF 链接）
ISSUED	已开票	有值
PUSHED	已推送	有值
VOIDED	已作废	null

InvoiceType - 发票类型

枚举值	中文名
VAT_NORMAL	增值税普通发票
VAT_SPECIAL	增值税专用发票
ELECTRONIC	电子发票

TitleType - 抬头类型

枚举值	中文名
PERSONAL	个人
COMPANY	公司

7. 错误码

错误码	常量	触发场景
581510	INVOICE_ORDER_NOT_COMPLETED	订单状态非 COMPLETED，不可申请开票
581511	INVOICE_ALREADY_EXISTS	该订单已有有效发票，不可重复申请（一单一票）
581512	INVOICE_AMOUNT_EXCEED	开票金额超过订单总价
581513	INVOICE_TYPE_INVALID	发票类型枚举值非法
581514	INVOICE_TAX_NO_REQUIRED	公司抬头 / 专票时税号为必填
581515	INVOICE_VAT_SPECIAL_FIELDS_REQUIRED	专票时开户行 / 银行账号 / 注册地址 / 注册电话为必填
581516	INVOICE_EMAIL_REQUIRED	电子发票时邮箱为必填
581517	INVOICE_NOT_DOWNLOADABLE	发票尚未开具（REQUESTED / VOIDED 状态），暂时无法下载
581518	INVOICE_FORBIDDEN	无权访问该发票（IDOR 防护，含发票不存在场景）
581519	INVOICE_SIGNED_URL_FAILED	获取签名下载 URL 失败，请稍后重试（hl-user-service 暂时不可用）

8. 示例

8.1 典型成功：申请开票

POST /v3/internal/mp/order/1234567890123456789/invoice/apply

请求体：

响应：

8.2 边界情况：列表中 REQUESTED 状态 fileUrl 为 null

GET /v3/internal/mp/order/1234567890123456789/invoice/list 响应示例（某张待开票发票）：

8.3 业务失败：REQUESTED 状态发票不可下载

GET /v3/internal/mp/order/invoice/111/download

响应：

9. 业务边界

适用：

申请：订单状态必须为 COMPLETED；无有效发票（一单一票）；金额不超订单总价
下载：发票状态为 ISSUED 或 PUSHED；且该发票属于当前登录用户的订单

不适用：

订单 COMPLETED 之前不可申请
已有有效发票，不可重复申请
REQUESTED / VOIDED 状态发票不可下载（报 581517）
访问他人订单的发票报 581518（IDOR 防护，不返回 404 以避免泄露存在性）

特殊边界：

签名 URL 有效期 1 小时。前端如果缓存了 fileUrl，每次打开下载前须重新调 download 接口获取最新签名 URL，不可长期复用。
wx.openDocument 下载后端直接返回签名 URL，前端无需中转。

10. 修改前后对比

POST apply 申请门槛变化

项目	变更前（旧 collab 实现）	变更后（invoice 域）
一单一票限制	无（可叠加多张）	有（existsActiveByOrderId 拦截）
金额校验	已开+本次 <= 总价	本次金额 <= 总价（一单一票前提下等价）
响应 status 值	APPLIED	REQUESTED

GET list / detail fileUrl 可见性变化

发票状态	变更前 fileUrl	变更后 fileUrl
REQUESTED	有值（OSS 公链）	null（前端显示处理中）
ISSUED	有值	有值（不变）
PUSHED	有值	有值（不变）
VOIDED	有值	null

11. 影响评估 / 回滚

破坏兼容性（重要）：fileUrl 字段在 REQUESTED 状态下由有值变为 null。前端如果之前有展示 REQUESTED 状态下 PDF 链接的逻辑（点击打开 OSS 文件），现在会读到 null，需要做 null 判断，展示「处理中」状态文案。
apply status 值变化：从 APPLIED 改为 REQUESTED。前端如果有对 status 值做 hardcode 判断（if status == APPLIED），需要更新。
前端同步上线建议：fileUrl null 判断 + apply 响应 status 对齐必须在本次版本同步更新。
回滚方案：回滚旧版本，fileUrl 可见性恢复，download 端点返回 404。apply 的 status 回退为 APPLIED（如旧版本有此值）。

12. 注意事项

fileUrl null 判断：list / detail 接口读到 fileUrl 为 null 时，前端应显示「处理中」或「待开票」而不是空链接。
签名 URL 勿缓存超过 1 小时：download 返回的签名 URL 有效期 1 小时，前端每次用前须重新调接口，不可全局缓存复用。
apply 响应 status 值变更：旧值 APPLIED 已废弃，现在返回 REQUESTED。如前端有 switch/if 判断该值，须对齐。
download IDOR 防护：发票不存在或不属于当前用户均返回 581518（INVOICE_FORBIDDEN），不返回 404，避免存在性枚举攻击。

13. 关联 / 联系人

Issue（小程序端 mp）: wx/HL#4174
Issue（签名下载）: wx/HL#4182
PR（mp 端 #4181）: wx/HL#4181
PR（签名下载 #4184）: wx/HL#4184
后端负责人: yaosutu

10 KiB 原始文件 Blame 文件历史 Unescape Escape