docs(changelog): #8755 发票推送接短信（按下单手机号直发）推送日志新增 SKIP + 新增发票短码免登录下载端点（新增接口 / 修改接口·管理后台）

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 15:58:24 +08:00
@@ -0,0 +1,449 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8755"
+title: "发票推送接短信（按下单手机号直发）：推送日志按真实结果落库，pushStatus 新增 SKIP「未发送」，邮件 / 微信不再假写成功"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PUT /v3/admin/order/invoice/{id}/push 入参 / 出参 / 错误码不变，行为变：选 sms 时经通知中心按订单下单手机号直发「发票已开具」短信（带 8 位下载短码），推送日志按通知中心真实结果写 SUCCESS / FAILED / SKIP / PENDING；email / wechat 未接入，一律写 SKIP。GET /{id}/push-logs 与 GET /{id} 的 pushLogs[].pushStatus 新增取值 SKIP（statusText「未发送」），failReason 如实写原因。短信模板尚在申请（#8790，wx），模板到位前短信渠道写 SKIP「短信模板未配置，未发送」。已合并 dev-v3（9cd23903a）并部署 TEST，经网关实测，工单 #8755 已关。前端待做两处：推送弹窗 PushModal.vue:15 文案「本期仅记录推送状态，客户暂不会实际收到通知」改为如实说明（短信按下单手机号发送、邮件 / 微信暂不发送）；推送日志抽屉 SKIP 行的原因前缀「失败原因：」改为「原因：」，可选给 SKIP 配一个标签色。statusText 已能自动显示「未发送」。"
+updated_at: "2026-10-04"
+base: "dev-v3"
+---
+
+# 发票推送接短信：推送日志按真实结果落库、新增 SKIP（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）+ hl-user-service（通知事件配置迁移）
+> **PR**: #8776
+> **Issue**: #8755
+> **日期**: 2026-10-03
+> **影响范围**: 管理后台财务「发票管理」页的推送弹窗、推送记录抽屉、发票详情抽屉；接口签名零变化
+
+---
+
+## ⚠️ 关键变化
+
+1. **推送不再是假推送**：选「短信」时经通知中心按**订单下单手机号**直发（不依赖小程序 userId，团期子订单也能收到），短信里带 8 位下载短码，客户免登录下载发票（配套新增接口见同单另一份 changelog）。
+2. **推送日志如实落库**：`pushStatus` 新增 **`SKIP`**（`statusText`「未发送」），`failReason` 写清原因；原先三个渠道一律写 `SUCCESS` 的口径作废。
+3. **邮件 / 微信未接入**：选了照样能推（状态机不变），但日志写 `SKIP`「邮件渠道未接入，未发送」/「微信渠道未接入，未发送」。
+4. **短信模板未到位**（#8790）：模板过审填入前，短信渠道日志写 `SKIP`「短信模板未配置，未发送」，客户收不到短信。
+5. **短信结果是异步回写的**：推送接口返回时短信那行先是 `PENDING`，通常 1 秒内回写为终态；推送记录抽屉打开时再拉一次即可。
+
+---
+
+## 一、背景
+
+#4230 曾定「本期不真发」：三个推送渠道监听器只登记一条 `SUCCESS`，前端弹窗也提示「客户暂不会实际收到通知」。jw 2026-10-03 定客户触达一律短信、按下单手机号直发、模板后补，于是本单接通短信并把推送日志改为如实落库。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 推送发票给客户 | PUT | `/v3/admin/order/invoice/{id}/push` | 修改接口 | 入参出参不变；sms 真发短信，各渠道日志按真实结果落库 |
+| 2 | 发票推送明细日志 | GET | `/v3/admin/order/invoice/{id}/push-logs` | 修改接口 | `pushStatus` 新增 `SKIP`，`failReason` 如实写原因 |
+| 3 | 发票详情 | GET | `/v3/admin/order/invoice/{id}` | 修改接口 | 仅 `pushLogs[]` 同上变化，其余字段不变 |
+
+网关：本组接口无改动（在既有 `/v3/admin/**` 通配下）。
+
+---
+
+## 三、接口详情
+
+### 1. 推送发票给客户 `PUT /v3/admin/order/invoice/{id}/push`
+
+**VO**: `InvoicePushReqVO`（入参）/ `Result<Void>`（出参）
+
+#### 使用场景
+
+财务在「发票管理 · 待推送 / 已推送」点「推送」，勾选渠道后提交。发票状态 ISSUED → PUSHED（PUSHED 可再次推送）；事务提交后各渠道异步发送并写推送日志。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| id | path | string(Long) | 是 | 发票 ID | 发票主键，字符串透传 |
+| channels | body | string[] | 是 | 非空；元素 ∈ 字典 `invoice_push_channel`（email / wechat / sms） | 推送渠道，可多选 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| code | int | 200 成功 |
+| message | string | 「成功」 |
+| data | null | 无数据；各渠道发送结果看推送日志 |
+
+#### 请求示例
+
+```json
+{
+  "channels": ["sms", "email"]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": null,
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+接口本身无空数据形态。通知中心不可用、短信发送失败都**不影响推送接口返回成功**（发送在事务提交后异步进行），失败结果体现在推送日志 `FAILED` / `PENDING`：
+
+```json
+{
+  "channel": "sms",
+  "pushStatus": "FAILED",
+  "statusText": "失败",
+  "pushedBy": "王会计",
+  "pushedAt": "2026-10-03 21:05:45",
+  "failReason": "通知中心调用失败"
+}
+```
+
+#### 错误响应
+
+错误码与改前完全一致：
+
+| 业务码 | 场景 |
+|---|---|
+| 581500 | 发票不存在 |
+| 581520 | 发票当前状态不允许推送（须 ISSUED / PUSHED） |
+| 581521 | 推送渠道为空 |
+| 581522 | 推送渠道非法 |
+
+```json
+{
+  "code": 581520,
+  "message": "发票当前状态不允许推送（须已开票）",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 状态机不变：ISSUED / PUSHED → PUSHED，`pushedAt` / `pushedChannels` 每次推送覆盖。
+- 每个勾选渠道每次推送写一条日志；sms 先写 `PENDING`，发完回写终态。
+- 短信收件人 = 订单 `customer_phone`（下单手机号）；为空时写 `SKIP`「下单手机号为空，未发送短信」，不生成下载码。
+- 短信只在 sms 渠道发；email / wechat 不发、写 `SKIP`。
+- 同一发票连推两次会发两条短信（每次推送各自生成下载码）。
+
+### 2. 发票推送明细日志 `GET /v3/admin/order/invoice/{id}/push-logs`
+
+**VO**: `InvoicePushLogRespVO`
+
+#### 使用场景
+
+推送记录抽屉按推送时间倒序展示每次、每个渠道的推送结果。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| id | path | string(Long) | 是 | 发票 ID | 发票主键 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| channel | string | email / wechat / sms |
+| pushStatus | string | SUCCESS / FAILED / PENDING / **SKIP（新增）** |
+| statusText | string | 成功 / 失败 / 待发 / **未发送（新增）** |
+| pushedBy | string | 操作人真实姓名 |
+| pushedAt | string | 推送时间 `yyyy-MM-dd HH:mm:ss` |
+| failReason | string \| null | 原因：FAILED / SKIP / PENDING 时有值，SUCCESS 为 null（原注释「预留」，现已启用） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/invoice/2106369928091283458/push-logs
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "channel": "email",
+      "pushStatus": "SKIP",
+      "statusText": "未发送",
+      "pushedBy": "admin",
+      "pushedAt": "2026-10-03 21:11:53",
+      "failReason": "邮件渠道未接入，未发送"
+    },
+    {
+      "channel": "sms",
+      "pushStatus": "SKIP",
+      "statusText": "未发送",
+      "pushedBy": "admin",
+      "pushedAt": "2026-10-03 21:05:45",
+      "failReason": "短信模板未配置，未发送"
+    }
+  ],
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+从未推送过：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [],
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 581500,
+  "message": "发票不存在",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 存量日志不订正：本单上线前的历史行仍是 `SUCCESS`（当时并未真发）。
+- `pushStatus` 未知值时 `statusText` 回落为原始值（既有口径）。
+- 短信行在推送后约 1 秒内由 `PENDING` 回写为终态；结果不确定时保留 `PENDING` 并写「以通知中心发送日志为准」。
+
+### 3. 发票详情 `GET /v3/admin/order/invoice/{id}`
+
+**VO**: `AdminInvoiceDetailRespVO`
+
+#### 使用场景
+
+发票详情 / 上传抽屉。本单只影响其中的 `pushLogs[]`（与接口 2 同源同 VO），其余字段零变化。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| id | path | string(Long) | 是 | 发票 ID | 发票主键 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| pushLogs | InvoicePushLogRespVO[] | 字段与接口 2 完全一致：`pushStatus` 新增 SKIP、`statusText` 新增「未发送」、`failReason` 如实写原因 |
+| 其余字段 | - | 不变 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/invoice/2106369928091283458
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "2106369928091283458",
+    "orderNo": "HL20260930170915373",
+    "status": "PUSHED",
+    "statusText": "已推送",
+    "invoiceNo": "26152000000087551236",
+    "pushedChannels": "email",
+    "pushLogs": [
+      {
+        "channel": "email",
+        "pushStatus": "SKIP",
+        "statusText": "未发送",
+        "pushedBy": "admin",
+        "pushedAt": "2026-10-03 21:11:53",
+        "failReason": "邮件渠道未接入，未发送"
+      },
+      {
+        "channel": "sms",
+        "pushStatus": "SKIP",
+        "statusText": "未发送",
+        "pushedBy": "admin",
+        "pushedAt": "2026-10-03 21:05:45",
+        "failReason": "短信模板未配置，未发送"
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+未推送过的发票 `pushLogs` 为空数组：
+
+```json
+{
+  "pushLogs": []
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 581500,
+  "message": "发票不存在",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 判权、其余字段、`status` / `statusText` 口径均不变。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误调用顺序
+
+- ✅ 推送记录展示用 `statusText`；`failReason` 非空时都展示（SKIP、PENDING 也有原因），前缀建议用「原因：」而不是「失败原因：」。
+- ✅ 推送成功后若立刻打开推送记录，短信行可能还是 `PENDING`，可在抽屉打开时重新拉取。
+- ❌ 不要把 `SKIP` 渲染成失败（红色），它表示「没发」而不是「发失败」。
+- ❌ 不要继续展示「本期仅记录推送状态，客户暂不会实际收到通知」。
+
+---
+
+## 五、数据库行为
+
+- **order-v3**：零 DDL。`invoice_push_log.push_status`（VARCHAR(16)、无 CHECK）新增写入值 `SKIP`；`fail_reason` 由「预留」改为如实写原因。短信推送每次写一条 `invoice_download_code`（建表见同单新增接口 changelog）。
+- **user-service**：Flyway `V20261003_8755__invoice_pushed_notification.sql` 往 `notification_event_config` 插（或按 `uk_event_code` 收敛）`INVOICE_PUSHED`：只开短信、模板哨兵 `TODO_PLACEHOLDER`、`sms_field_mapping` 为 orderNo / invoiceNo / amount / code；重放不覆盖运营已填的模板编码。通知中心每次发送写一行 `notification_send_log`（`biz_type=INVOICE_PUSH`、`biz_id`=推送日志 ID，收件人脱敏）。
+
+---
+
+## 六、边界行为
+
+| 场景 | 推送日志 |
+|---|---|
+| 选 sms，模板未配置（当前） | SKIP「短信模板未配置，未发送」 |
+| 选 sms，下单手机号为空 | SKIP「下单手机号为空，未发送短信」 |
+| 选 sms，阿里云受理（带回执号） | SUCCESS |
+| 选 sms，短信通道为模拟档（无回执号） | SKIP「短信通道为模拟档（未配置短信网关），未真实发送」 |
+| 选 sms，阿里云拒发 | FAILED「短信发送失败：<原因>」 |
+| 选 sms，通知中心不可用 | FAILED「通知中心调用失败」 |
+| 选 sms，投递结果不确定 / 查不到发送记录 | PENDING（写明以通知中心发送日志为准） |
+| 选 email / wechat | SKIP「邮件 / 微信渠道未接入，未发送」 |
+| 发票状态非 ISSUED / PUSHED | 581520，不写日志（同改前） |
+
+---
+
+## 六.6、修改前后对比
+
+| 项 | 改前 | 改后 |
+|----|------|------|
+| 选 sms | 不发，日志写 SUCCESS | 经通知中心按下单手机号直发，日志按真实结果写 |
+| 选 email / wechat | 不发，日志写 SUCCESS | 不发，日志写 SKIP + 原因 |
+| `pushStatus` 取值 | SUCCESS（实际恒定）/ FAILED / PENDING（预留） | SUCCESS / FAILED / PENDING / **SKIP** |
+| `statusText` 取值 | 成功 / 失败 / 待发 | 成功 / 失败 / 待发 / **未发送** |
+| `failReason` | 恒 null | FAILED / SKIP / PENDING 时写原因 |
+| 短信行写入时机 | 推送后异步一次写入 | 推送后异步先写 PENDING，发完回写终态 |
+| 入参 / 出参 / 错误码 / 状态机 | — | 不变 |
+
+---
+
+## 六.7、影响评估
+
+- **前端（hl-ui v2.1 实查）**：
+  - `src/views/order/invoice/components/PushLogsDrawer.vue:30` 显示 `log.statusText || log.pushStatus`，「未发送」**自动生效**；`:27` 标签色 `STATUS_TYPE[s] || 'default'`，SKIP 落灰色，可选补一个色。
+  - `PushLogsDrawer.vue:41`把 `failReason` 冠以「失败原因：」前缀展示——SKIP 行也会显示，**前缀建议改「原因：」**。
+  - `src/views/order/invoice/components/PushModal.vue:15`「本期仅记录推送状态，客户暂不会实际收到通知。」**需改**为如实说明：短信按订单下单手机号发送（模板生效后），邮件、微信暂不发送。
+  - `src/api/invoice.js:191` 注释中的取值说明可同步补 SKIP。
+- **历史数据**：上线前的推送日志仍是 SUCCESS（当时未真发），不订正。
+- **其他调用方**：无。小程序端、通知中心其他事件、团期 / 订单流程零影响。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 推送接口的发送行为与推送日志取值（3 个管理端接口的 `pushLogs` 相关字段）。
+- **零影响**:
+  - 发票申请、开票、重传、重开、列表、统计接口
+  - 小程序发票查询 / 下载 / 重开
+  - 通知中心其他事件
+- 零权限种子变更、零网关变更（本组接口）。
+
+---
+
+## 八、测试环境已验证
+
+部署：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` user `20261003.8755` success=1，`INVOICE_PUSHED` 配置行读回只开短信、模板 `TODO_PLACEHOLDER`；构建身份探针 6/6 命中新代码。经网关 `https://api.test.1814.love` 真实鉴权实测（2026-10-03 21:05–21:11），工单 #8755 已验收关单。
+
+| # | 场景 | 结果 |
+|---|---|---|
+| 1 | 团期子订单（user_id 为空）发票 ISSUED，推 `["sms"]` | 200；发票 → PUSHED；推送日志 SKIP「短信模板未配置，未发送」；通知中心发送日志一行 `INVOICE_PUSHED / SMS / status=3`，收件人 `138****2356`，`params_json` 无手机号；生成下载码 1 枚（7 天） |
+| 2 | 另一张 ISSUED 发票推 `["email","wechat"]` | 200；发票 → PUSHED；两行 SKIP，原因分别为微信 / 邮件渠道未接入；不生成下载码 |
+| 3 | 已 PUSHED 发票再推 `["email"]` | 200；仍 PUSHED，`pushedAt` / `pushedChannels` 已更新 |
+| 4 | `GET /{id}/push-logs`、`GET /{id}` | `pushStatus=SKIP`、`statusText=未发送`、`failReason` 如实 |
+| 5 | 日志脱敏 | TEST order-v3 日志 11 位手机号出现 0 次 |
+| 6 | TEST 短信网关形态 | `aliyun.sms.access-key-id` 为真实 AK（非模拟档）；哨兵期在模板检查处跳过，未触达阿里云、未发出短信 |
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| — | #4230 | 发票推送「本期不真发」 | ⚠️ 被本单取代 |
+| — | #3713 | 通知中心 directPhone 收件通道 | ✅ |
+| — | #8754 | 成团通知客户短信（同样按下单手机号直发） | ✅ |
+| **本 PR #8776** | **#8755** | 发票推送接短信 + 凭短码免登录下载 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8755](https://git.1814.love/wx/HL/issues/8755)
+- 关联 PR: [wx/HL#8776](https://git.1814.love/wx/HL/pulls/8776)
+- 短信模板申请跟进: [wx/HL#8790](https://git.1814.love/wx/HL/issues/8790)
+- 同单配套新增接口: `changelogs-v2/2026-10/04_8755_发票短信短码免登录下载-新增接口-管理后台.md`
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8755](https://git.1814.love/wx/HL/issues/8755)
+- **PR**: [#8776](https://git.1814.love/wx/HL/pulls/8776)
+- **Merge commit**: [9cd23903a](https://git.1814.love/wx/HL/commit/9cd23903abe8edc75e13ca2e7c4d5c65bd9e4453)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg
+- **短信模板**: @wx（#8790）
@@ -0,0 +1,259 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8755"
+title: "发票短信短码免登录下载：新增公开端点 GET /v3/open/invoice/{code}，客户凭短信里的 8 位短码 302 到现签 1 小时的发票文件"
+consumer: "multiple"
+author: "jw(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+updated_at: "2026-10-04"
+base: "dev-v3"
+status_note: "新增公开端点 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 | - | 成功无响应体 |
+
+#### 请求示例
+
+```http
+GET /v3/open/invoice/K7mQ2xRb HTTP/1.1
+Host: api.test.1814.love
+```
+
+#### 响应示例
+
+成功（302，无响应体；以下为响应头的结构化描述）：
+
+```json
+{
+  "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：
+
+```json
+{
+  "code": 581519,
+  "message": "发票下载服务暂时不可用，请稍后重试",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 错误响应
+
+失败一律 HTTP 200 + 业务码，不带任何发票 / 订单字段：
+
+| 业务码 | 场景 |
+|---|---|
+| 581527 | 码格式不符（非 8 位字母数字）、查无此码、大小写或任一字符被改动 |
+| 581528 | 码已过期（默认生成后 7 天） |
+| 581517 | 码对应的发票已不可下载（已作废 / 不存在 / 文件地址异常），文案「发票尚未开具，暂时无法下载」沿用既有码 |
+| 581519 | 现签下载链接失败（文件服务不可用） |
+| 100501 | 同一来源 60 秒内超过 30 次 |
+
+```json
+{
+  "code": 581527,
+  "message": "发票下载链接无效",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+```json
+{
+  "code": 581528,
+  "message": "发票下载链接已过期，请联系客服重新推送",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+```json
+{
+  "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](https://git.1814.love/wx/HL/issues/8755)
+- 关联 PR: [wx/HL#8776](https://git.1814.love/wx/HL/pulls/8776)
+- 短信模板申请跟进: [wx/HL#8790](https://git.1814.love/wx/HL/issues/8790)
+- 同单配套变更（推送日志新增 SKIP）: `changelogs-v2/2026-10/04_8755_发票推送接短信推送日志新增SKIP-修改接口-管理后台.md`
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8755](https://git.1814.love/wx/HL/issues/8755)
+- **PR**: [#8776](https://git.1814.love/wx/HL/pulls/8776)
+- **Merge commit**: [9cd23903a](https://git.1814.love/wx/HL/commit/9cd23903abe8edc75e13ca2e7c4d5c65bd9e4453)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **短信模板**: @wx（#8790）