From 809e2a1b40282c5723fc9d3b6f7e2e53788194de Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Fri, 12 Jun 2026 20:55:12 +0800
Subject: [PATCH] =?UTF-8?q?changelog(v2):=20=E5=8F=B8=E6=9C=BAH5=E5=B7=B2?=
 =?UTF-8?q?=E5=8F=91=E6=94=BE=E9=93=BE=E6=8E=A5=E7=AE=A1=E7=90=865?=
 =?UTF-8?q?=E7=AB=AF=E7=82=B9+H5=20init=E7=8A=B6=E6=80=81=E6=9C=BA4?=
 =?UTF-8?q?=E5=AD=97=E6=AE=B5+=E9=93=BE=E6=8E=A5URL=E6=94=B6=E5=8F=A3=20(P?=
 =?UTF-8?q?R=20#3777/#3778)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 ...�‘放链接管ç�†5端点-新增接å�£-管ç�†å�Žå�°ä¸Žå�¸æœºH5.md | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 changelogs-v2/2026-06/12_3777_�机H5已�放链接管�5端点-新增接�-管���与�机H5.md

diff --git a/changelogs-v2/2026-06/12_3777_�机H5已�放链接管�5端点-新增接�-管���与�机H5.md b/changelogs-v2/2026-06/12_3777_�机H5已�放链接管�5端点-新增接�-管���与�机H5.md
new file mode 100644
index 0000000..e298572
--- /dev/null
+++ b/changelogs-v2/2026-06/12_3777_�机H5已�放链接管�5端点-新增接�-管���与�机H5.md
@@ -0,0 +1,93 @@
+# �新增接�·管���+�机H5】�机自助 H5「已�放链接管��5 端点——列表/导出/作废/��短信/�新生�
+
+> �务:hl-fleet-service(8087/8187) + hl-user-service(8081/8181) | 分支:dev-v3 | PR:#3777+#3778(补�) | 工�:#3775 | 已部署测试�并 13 项 E2E 实测通过(2026-06-12)
+> 背景:API §4.6 此�未实现——车管�出去的 H5 录入链接看�到��能作废��能��。本次补�完整生命周期管�,�时把链接 URL 收� Nacos�H5 init 补状�机出�。
+> 对应原型:车管控制�「链接管��页。
+
+## ⚠� 关键说明(�端动作)
+
+1. **管���新增「已�放链接管��页�**(5 个新端点,� §1-§5),路径�缀 `/admin/fleet/h5/tokens`。
+2. **链接格��了**:所有生�的 H5 链接统一为 `https://hr.1814.love/driver-intake?t={token}`(�数� **`?t=`**,与短信模�一致;原硬编� `h5.hl-fleet.com/onboard?token=` 作废)。**H5 �端从页� URL 读 `t` �数**�调 init。
+3. **H5 init(`GET /app/h5/driver-onboard/init`)出�新增 4 字段**(�机 H5 需按 `tokenState` 渲染失效文案,� §6)。
+4. **§4.1 生�链接出�新增 `pendingId`**(�续作废/��/�新生�都以 pendingId 为�作键)。
+5. **测试�公网已�直达 H5 接�**:nginx 已补 `/app/` 代�(此� `/app/h5/*` � 9443 会�到 SPA 页�)。
+6. **已知外部阻塞(�影�接��调)**:��短信链路已全通(事件→通知中心→阿里云真实调用,send_log �档),但阿里云模� SMS_507390235 的 token ��类型(链接�数)容�下 32 � token 被拒�——**需 wx 在阿里云控制�调整模���规范�过审**,代�侧零改动。name 为空拒�已�端兜底(空→「师傅�)。
+7. 60 秒内对�一链接��点「���:接�返回�功但通知中心幂等拒�第二�(防轰炸),属预期。
+
+## 1. 已�放链接列表(分页)
+
+`GET /admin/fleet/h5/tokens?mode=&status=&keyword=&page=1&pageSize=20`
+
+| 入� | 必填 | 说明 |
+|---|---|---|
+| mode | � | new=新招 / renew=续签 |
+| status | � | 派生 6 �:`VOIDED`已作废/`APPROVED`已通过/`REJECTED`已驳回/`SUBMITTED`已�交/`EXPIRED`已过期/`VALID_UNSUBMITTED`有效·未�交 |
+| keyword | � | 模糊匹� 姓� OR token(**�支�手机�**——加密存储无法模糊) |
+
+实测出�(行):
+
+```json
+{
+  "pendingId": "2065414570750455809",      // �作键(字符串防精度丢失)
+  "mode": "new", "modeLabel": "æ–°æ‹›",
+  "token": "182ee9dd884e46d8a628bb98a5695252",
+  "name": "", "phone": null,                // 手机脱�返回(138****2345),未填为 null
+  "createTime": "2026-06-12T20:45:29", "expireAt": "2026-06-19T20:45:29",
+  "submittedAt": null, "reviewStatus": "pending",
+  "status": "VALID_UNSUBMITTED", "statusLabel": "有效·未�交",
+  "url": "https://hr.1814.love/driver-intake?t=182ee9dd884e46d8a628bb98a5695252"  // 直接�制��机
+}
+```
+
+## 2. 导出 CSV
+
+`GET /admin/fleet/h5/tokens/export?mode=&status=&keyword=`(��件,�分页)
+
+返回 `text/csv;charset=UTF-8` 文件�(带 UTF-8 BOM,Excel 直开�乱�),列:`类型,token,姓�,手机(脱�),生�时间,有效期至,状�,审核状�`,文件� `h5_tokens_{时间戳}.csv`。�端 blob 下载��。
+
+## 3. 作废链接
+
+`POST /admin/fleet/h5/tokens/{pendingId}/void` body(�选):`{ "reason": "�机信�有误" }`
+
+- 仅「已通过���作废(**600304**);其余状�(�已驳回/已�交)��作废;��作废幂等返回�功
+- 作废��机端立�失效:H5 init 返 `tokenState=voided`��交/OCR 被 600304 硬拦(实测�动通过)
+
+## 4. ��短信
+
+`POST /admin/fleet/h5/tokens/{pendingId}/resend` body(�选):`{ "phone": "13808612345" }`(覆盖收件�,生�时没填手机的链接由此补)
+
+- 仅「有效·未�交�「已驳回����,�则 **600308**;入�与档案手机��空 → **600307**
+- **�刷新有效期**(�延长走�新生�)
+- 出�仅 `{ "maskedPhone": "138****2345" }`——短信异步�出,**接��功≠短信已到**,到达结果看通知中心��日志
+
+## 5. �新生�
+
+`POST /admin/fleet/h5/tokens/{pendingId}/regenerate`(æ—  body)
+
+- 「已�交�「已通过����新生�(**600309**);其余(�已过期/已作废)�
+- 旧链接自动作废(审计留痕),返回**全新** pendingId/token/url/expireAt/qrCodeUrl(出�� §4.1 生�)
+- **新链接�自动�短信**——车管�制 url 或对新 pendingId 点��
+
+## 6. �机 H5 init 出�新增 4 字段(H5 �端)
+
+`GET /app/h5/driver-onboard/init?token=`
+
+| 字段 | 说明 |
+|---|---|
+| tokenState | `fresh`首次�填/`editable`已�交待审�覆盖��/`rejected_editable`已驳回�改��/`expired`已过期/`voided`已作废/`consumed`已通过(终�)/`invalid`无效 |
+| reviewStatus | pending / approved / rejected |
+| rejectReason | 驳回原因(驳回相关��有值,指导�机改哪) |
+| lastSubmittedAt | 上次�交时间(已�交过�有值) |
+
+- `tokenValid` �留��兼容(= tokenState ∈ fresh/editable/rejected_editable);**修了一个旧 bug**:审核通过��机�打开,旧实现误返 tokenValid=true(填完 8 步�交�被拦),现在 init �返 false + `consumed`
+- H5 请按 tokenState 渲染失效文案(已作废/已过期/已通过 区分展示)
+
+## 7. 错误�速览
+
+| code | message |
+|---|---|
+| 600304 | 链接已作废(作废�的 H5 �交/OCR 也返此�) |
+| 600307 | 无�用手机� |
+| 600308 | 仅有效未�交或已驳回的链接��� |
+| 600309 | 已�交或已通过的链接���新生� |
+| 600402 | 待审核记录�存在 |