hl-api-changelog/changelogs-v2/2026-10/04_8755_发票短信短码免登录下载-新增接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, updated_at, base, status_note

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	updated_at	base	status_note
hl-changelog/v2	8755	发票短信短码免登录下载：新增公开端点 GET /v3/open/invoice/{code}，客户凭短信里的 8 位短码 302 到现签 1 小时的发票文件	multiple	jw(GIT)	新增接口	deployed	verified	not_required					2026-10-04	dev-v3	新增公开端点 GET /v3/open/invoice/{code}（网关新路由 invoice-open-v3 + SKIP_URLS，无登录态，凭码即鉴权）。财务推送发票选短信时，order-v3 为本次推送生成 8 位 base62 短码（列 utf8mb4_bin 区分大小写、7 天有效），客户点短信链接经本端点 302 到现签 1 小时的 OSS 发票文件；按客户端 IP 30 次/分钟限流。端点只给短信链接用，不给管理后台 / 小程序前端调用，Swagger 不展示，前端零适配。已合并 dev-v3（9cd23903a），部署 TEST（gateway、order-v3、user-service），经网关匿名实测 302 + PDF 字节一致、篡改 / 过期 / 限流均按约定拒绝，工单 #8755 已验收关单。短信模板尚在申请（#8790，wx），模板到位前客户收不到短信，本端点可用但无人拿到码。

发票短信短码：新增免登录下载端点（公开）

服务: hl-order-service-v3（端口 8086/8186）+ hl-gateway（新路由与免鉴权白名单） PR: #8776 Issue: #8755 日期: 2026-10-03 影响范围: 新增一个对外公开端点，只给发票推送短信里的链接用；管理后台、小程序前端零适配

---

⚠️ 关键变化

1. 新增公开端点 GET /v3/open/invoice/{code}：不带任何登录态，凭 8 位短码访问，成功 302 到现签 1 小时的发票文件（OSS 私有桶）。
2. 网关新前缀 /v3/open/invoice/**：新路由 invoice-open-v3 → order-service-v3，并加入 JwtAuthFilter.SKIP_URLS；客户端伪造的 X-User-Id / X-Admin-Id 会被网关剥掉。
3. 短码来源：财务在发票管理页推送并勾选「短信」时，每推一次生成一枚新码（invoice_download_code），7 天有效；码绑定发票，财务重传文件后旧码下载到的是新文件，发票作废后码失效。
4. 短信模板未到位：通知配置 INVOICE_PUSHED 仍是哨兵 TODO_PLACEHOLDER（申请见 #8790），客户暂时收不到短信；端点已上线可用。

---

一、背景

发票推送原先是假推送（#4230 定「本期不真发」）。#8755 把短信渠道接到通知中心、按订单下单手机号直发；团期子订单绝大多数没有 userId，小程序发票下载要求本人登录（order.userId == 当前用户），这些客户在小程序里拿不到发票，所以短信里放一个免登录的下载链接。阿里云短信「链接参数」变量最多 8 位，放不下签名令牌，于是落库存 8 位随机短码。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	发票短码下载	GET	/v3/open/invoice/{code}	新增接口	免登录；成功 302 到现签 1 小时的发票文件；按 IP 30 次/分钟限流

网关：新增路由 invoice-open-v3（Path=/v3/open/invoice/** → lb://hl-order-service-v3），/v3/open/invoice/** 进 SKIP_URLS。

---

三、接口详情

1. 发票短码下载 GET /v3/open/invoice/{code}

VO: ResponseEntity<Void>（成功为 302 无响应体，失败为通用 Result<Void>）

使用场景

客户收到「发票已开具」短信，点短信里的链接（模板正文写死对外域名 + 路径，变量只放 code），浏览器经本端点跳到发票 PDF 直接查看 / 下载。不给任何前端页面调用。

入参

字段	位置	类型	必填	约束	说明
code	path	string	是	恰好 8 位字母数字 ^[0-9A-Za-z]{8}$，区分大小写	发票推送短信里的下载短码

无请求头要求：不需要 Authorization，带了也不参与鉴权（网关对本前缀剥掉身份头）。

出参

字段	类型	说明
HTTP 状态	int	成功固定 302 Found
Location	header string	现签的 OSS 下载 URL，有效 1 小时（user-service oss.signed-url-expire），PDF 以 inline 方式打开
Cache-Control	header string	固定 no-store，签名 URL 不进任何缓存
body	-	成功无响应体

请求示例

GET /v3/open/invoice/K7mQ2xRb HTTP/1.1
Host: api.test.1814.love

响应示例

成功（302，无响应体；以下为响应头的结构化描述）：

{
  "httpStatus": 302,
  "headers": {
    "Location": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/invoice/2026/10/03/64674f6aa6086d1e42d7abcc2b1b50e0.pdf?Expires=1791036463&OSSAccessKeyId=***&Signature=***",
    "Cache-Control": "no-store"
  },
  "body": null
}

空数据 / 降级响应

没有空数据形态。文件服务（user-service 签名接口）不可用时不跳转，返回业务码 581519：

{
  "code": 581519,
  "message": "发票下载服务暂时不可用，请稍后重试",
  "data": null,
  "traceId": null,
  "success": false
}

错误响应

失败一律 HTTP 200 + 业务码，不带任何发票 / 订单字段：

业务码	场景
581527	码格式不符（非 8 位字母数字）、查无此码、大小写或任一字符被改动
581528	码已过期（默认生成后 7 天）
581517	码对应的发票已不可下载（已作废 / 不存在 / 文件地址异常），文案「发票尚未开具，暂时无法下载」沿用既有码
581519	现签下载链接失败（文件服务不可用）
100501	同一来源 60 秒内超过 30 次

{
  "code": 581527,
  "message": "发票下载链接无效",
  "data": null,
  "traceId": null,
  "success": false
}

{
  "code": 581528,
  "message": "发票下载链接已过期，请联系客服重新推送",
  "data": null,
  "traceId": null,
  "success": false
}

{
  "code": 100501,
  "message": "访问过于频繁,请稍后再试",
  "data": null,
  "traceId": null,
  "success": false
}

业务边界

• 每次「推送 + 勾选短信」且下单手机号非空时才生成码；邮件 / 微信推送、手机号为空都不生成。
• 同一张发票多次推送会有多枚码，各自 7 天有效、互不作废。
• 码绑定发票而不是文件：财务「重新上传」后，旧码下载到的是新文件；发票作废（重开）后旧码返回 581517。
• 302 的 Location 每次点击现签，有效 1 小时；客户隔天再点同一短信链接会拿到新的签名 URL（码 7 天内有效）。
• 限流按客户端 IP（取 X-Forwarded-For 第一段），30 次 / 60 秒。

---

四、契约约束与正确调用方式

✅ 正确 / ❌ 错误调用顺序

• ✅ 只在短信模板正文里写死「对外域名 + /v3/open/invoice/ + ${code}」（或经 nginx 短路径转发到本路径，见 #8790），变量只放 8 位码。
• ✅ 浏览器直接打开即可，跟随 302。
• ❌ 不要在管理后台 / 小程序里拼这个链接给用户：后台有发票详情与下载能力，小程序有登录态下载接口。
• ❌ 不要把 Location 里的签名 URL 存下来复用，它 1 小时过期。
• ❌ 不要对码做大小写归一化，码区分大小写。

---

五、数据库行为

• order-v3：Flyway V20261003_8755__create_invoice_download_code.sql 新建表 invoice_download_code（code_id 雪花主键、short_code VARCHAR(16) utf8mb4_bin 唯一键、invoice_id、order_id、push_log_id、expire_at + BaseDO 五列）。码在发票短信推送时写入（每次推送一行），本端点只读不写。
• 有效期配置项 hl.order-v3.invoice.download-code-ttl-days，缺省 7（未写入 nacos，取默认值）。

---

六、边界行为

场景	行为
正常码、发票 ISSUED / PUSHED	302 到现签 1 小时的发票文件
翻转码里一个字母的大小写	581527（列 utf8mb4_bin + 服务内逐字节比对，双保险）
改动任一字符 / 位数不对	581527
码过期	581528
发票已作废	581517
文件服务不可用	581519
同一 IP 60 秒内第 31 次起	100501
带伪造的 X-User-Id / X-Admin-Id	网关剥掉，按匿名处理
访问 /v3/open/ 下其他路径	网关仍按需登录拦截（白名单只放行发票前缀）

---

七、不影响范围

• 仅影响: 新增一个公开端点、一张表、一条网关路由与白名单项。
• 零影响:
  • 小程序发票下载 GET /v3/internal/mp/order/invoice/{id}/download（登录态 + 本人校验，行为不变；内部改为复用抽出的 ossKey 解析，逐字等价）
  • 管理后台发票列表、详情、开票、重传接口
  • Swagger 文档（本端点方法级 hidden，不进任何分组）
• 零权限种子变更、零前端适配。

---

八、测试环境已验证

部署：hl-user-service、hl-order-service-v3、hl-gateway = dev-v3 @ 9cd23903a（2026-10-03 20:56 / 20:59 / 21:00）；TEST flyway_schema_history order-v3 20261003.8755 success=1，invoice_download_code.short_code 排序规则实测 utf8mb4_bin；构建身份探针：匿名请求不存在的码连打 6 次全部 581527。经网关 https://api.test.1814.love 匿名实测（2026-10-03 21:05–21:11），工单 #8755 已验收关单。

#	场景	结果
1	团期子订单（user_id 为空）发票推送短信后取码访问	302；Cache-Control: no-store；响应体 0 字节；Location 签名有效期 3600 秒
2	跟随 302 下载	%PDF-1.4，SHA-256 与上传原件逐字节一致
3	翻转一个字母大小写 / 改最后一位 / 多一位	均 581527
4	把该码 expire_at 临时改到过去	581528；验后已还原，还原后恢复 302
5	同一来源 1.2 秒内连发 35 次	前 30 次 581527，第 31 次起 100501
6	日志脱敏	TEST order-v3 日志里完整短码出现 0 次，只打前 2 位（如 oK******）

---

九、相关历史 PR

PR	Issue	说明	是否仍有效
—	#4230	发票推送「本期不真发」定案	⚠️ 被 #8755 取代（短信渠道已接通知中心）
—	#3780	车务 H5 录入链接短链化（短码进短信链接先例）	✅
本 PR #8776	#8755	发票推送接短信 + 凭短码免登录下载	✅ 最新

---

十、相关文档

• 关联 Issue: wx/HL#8755
• 关联 PR: wx/HL#8776
• 短信模板申请跟进: wx/HL#8790
• 同单配套变更（推送日志新增 SKIP）: changelogs-v2/2026-10/04_8755_发票推送接短信推送日志新增SKIP-修改接口-管理后台.md

关联 / 联系人

链接

• Issue: #8755
• PR: #8776
• Merge commit: 9cd23903a

联系人

• 后端负责人: @jw
• 短信模板: @wx（#8790）