From 5e25e03897f07395a3dca87195e743340b387881 Mon Sep 17 00:00:00 2001
From: jw <jinwei@1814.love>
Date: Sat, 3 Oct 2026 18:59:12 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8746=20=E5=87=BA=E5=9B=A2?=
 =?UTF-8?q?=E9=80=9A=E7=9F=A5=E4=B9=A6=E5=8F=AF=E4=B8=8B=E5=8F=91=E6=94=B9?=
 =?UTF-8?q?=E4=B8=BA=E3=80=8C=E9=98=B6=E6=AE=B5=20+=20=E5=9B=9B=E9=A1=B9?=
 =?UTF-8?q?=E8=B5=84=E6=BA=90=E3=80=8D=E5=B9=B6=E6=96=B0=E5=A2=9E=20releas?=
 =?UTF-8?q?eBlockers=EF=BC=8C=E9=BB=98=E8=AE=A4=E8=BD=A6=E8=BE=86=E5=B8=A6?=
 =?UTF-8?q?=E5=8F=B8=E6=9C=BA=EF=BC=8C=E4=BF=9D=E5=AD=98=E7=95=99=E7=97=95?=
 =?UTF-8?q?=EF=BC=88=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3=C2=B7=E7=AE=A1?=
 =?UTF-8?q?=E7=90=86=E5=90=8E=E5=8F=B0=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...¥ä¹¦ä¸‹å�‘门缺项与车辆带å�¸æœº-修改接å�£-管ç�†å�Žå�°.md | 441 ++++++++++++++++++
 1 file changed, 441 insertions(+)
 create mode 100644 changelogs-v2/2026-10/03_8746_出团通知书下�门缺项与车辆带�机-修改接�-管���.md

diff --git a/changelogs-v2/2026-10/03_8746_出团通知书下�门缺项与车辆带�机-修改接�-管���.md b/changelogs-v2/2026-10/03_8746_出团通知书下�门缺项与车辆带�机-修改接�-管���.md
new file mode 100644
index 00000000..005399b8
--- /dev/null
+++ b/changelogs-v2/2026-10/03_8746_出团通知书下�门缺项与车辆带�机-修改接�-管���.md
@@ -0,0 +1,441 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8746"
+title: "出团通知书：�下�改为「阶段 + 四项资��并新增缺项清� releaseBlockers，默认车辆信�带�机，�存留痕"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: "v2.1"
+verified_at: "2026-10-03"
+status_note: "已�并 dev-v3（b90969493）并部署 TEST，自签 token �网关实测：招募中 / 待出� / 资�准备中 / 已�团 / �值��缺项��房�车回�与���缺资����存�默认车辆带�机且手机全脱��一户派车数�异常时跳过该户接�� 200��存留痕与撞版本�留痕�无��角色 589507 零写入。�端待改：通知书弹窗按 releasable 置�「打� / 存 PDF�并展示 releaseBlockers[].name。"
+updated_at: "2026-10-03"
+base: "dev-v3"
+---
+
+# order-v3: 出团通知书�下�判定补四项资�，新增 releaseBlockers
+
+**�务**: hl-order-service-v3
+**PR**: `#8770`（已�入 `dev-v3`，�并�交 `b90969493`）
+**Issue**: #8746
+
+---
+
+## ⚠� 关键�化
+
+🔴 **`releasable` �径�了**：原�团期到「待出���之�就是 `true`；现在还�求房 / 车 / 导 / 摄四项资�全部就绪。待出��房务或车务回�的团，`releasable` 会�� `false`。
+
+🟢 **新增出� `releaseBlockers`**（GET / PUT �应都有）：��下�时列出缺哪几项，�下�时为空数组。
+
+🟢 **默认车辆信� `defaults.bus` 带上�机**：�辆车「车型 车牌 �机 姓� 脱�手机�。
+
+🟢 入��路径�判��错误�全部��；�存�然��下�门。
+
+---
+
+## 一�背景
+
+出团通知书「打� / 存 PDF�按钮� `releasable` 置�。原�径�看团期阶段：团期进入待出���先过「四项资����，但进入之�房务�车务回��会把团期退回去，于是资�已�缺了的团照样能打�，页�也�知�缺什么。�外默认车辆信��有车型和车牌，没有�机。
+
+本�把「四项资�就绪�加进 `releasable`，并新增 `releaseBlockers` 告诉页�缺哪一项；默认车辆信�补上�机。
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 读出团通知书 | GET | `/v3/admin/order/group-batch/:groupBatchId/docs/notice` | 修改 | `releasable` 新�径；新增 `releaseBlockers`；`defaults.bus`（�未�存时正文 `bus`）带�机 |
+| 2 | �存出团通知书 | PUT | `/v3/admin/order/group-batch/:groupBatchId/docs/notice` | 修改 | �应�上；�存�功在团期时间线新增「�存出团通知书�一� |
+
+---
+
+## 三�接�详情
+
+**`releasable` 规则**（两个接�相�）：团期状�是 待出� `PENDING_DEPARTURE` / 出行中 `TRAVELLING` / 待核� `PENDING_REVIEW` / 核�中 `REVIEWING` / 已结算 `SETTLED` 之一，**且**�房��车��导游��摄影四项都已完�，�为 `true`。
+
+**`releaseBlockers[]` �值**（按下表顺�排列，`releasable=true` 时为 `[]`，从�为 `null`）：
+
+| key | name | 何时出现 |
+|---|---|---|
+| `STAGE` | 团期未到待出� | 团期状��在上�五个之内 |
+| `HOTEL` | �房未完� | 已�团且�房未完� |
+| `VEHICLE` | �车未完� | 已�团且�车未完�（整团�车算已完�） |
+| `GUIDE` | �导游未完� | 已�团且�导游未完�（�需�导游的团算已完�） |
+| `PHOTOGRAPHER` | �摄影未完� | 已�团且�摄影未完�（�需�摄影的团算已完�） |
+
+- 未�团（招募中 `RECRUITING`�已�团 `CANCELLED`）**�列 `STAGE`**，�列资�项。
+- 已�团但未到待出�（资�准备中�物料准备中）：`STAGE` + 缺的资�项。
+- 以��能追加�值（团车�机，#8767）。�到�认识的 `key`，按 `name` 展示��。
+
+**`bus` 默认值格�**：�辆车 `车型 车牌 �机 姓� 脱�手机`，例 `33 座大巴 蒙A·88888 �机 王师傅 138****8888`。
+- �一辆车多日�过�机，�机之间用 ` / ` 分隔：`33 座大巴 蒙A·88888 �机 王师傅 138****1234 / 赵师傅 136****9999`。
+- 车与车之间�用 `�`。
+- �机没有手机�时�有姓�；手机�一律脱�。
+- 整团派车（团车）的团，车辆信�暂�出现在默认值里（#8767 补）。
+- 已�存的正文�会自动刷新，�有 `defaults` 是实时值。
+
+### 1. 读出团通知书 `GET /v3/admin/order/group-batch/:groupBatchId/docs/notice`
+
+**VO**: `GroupBatchNoticeRespVO`（入��有路径�数）→ `Result<GroupBatchNoticeRespVO>`
+
+#### 使用场景
+
+团期详情「出团通知书�弹窗打开时调用。按 `releasable` 置�「打� / 存 PDF�，`releasable=false` 时把 `releaseBlockers[].name` 列给用户看。
+
+#### 入�字段表
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期 ID | **��** |
+
+#### 出�字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| releasable | Boolean | 🔄 是��许打� / 下�：阶段在�下�集�内且四项资�都已完�（规则�上） |
+| releaseBlockers | Object[] | 🆕 ��下�的缺项，�下�时为 `[]` |
+| releaseBlockers[].key | String | 🆕 缺项编�：`STAGE` / `HOTEL` / `VEHICLE` / `GUIDE` / `PHOTOGRAPHER` |
+| releaseBlockers[].name | String | 🆕 缺项中文�，�上表 |
+| bus | String | 🔄 未�存过（`saved=false`）时等于 `defaults.bus`，格��上；已�存时为�存的原文 |
+| defaults.bus | String | 🔄 实时默认车辆信�，�辆车带�机，格��上 |
+| title / greeting / meetTime / meetPlace / leader / contacts / service / bring | String | **��** |
+| saved / version / updateTime / defaults 其余字段 | — | **��** |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2106331639531601921/docs/notice HTTP/1.1
+Authorization: Bearer <管�员 token>
+```
+
+#### �应示例
+
+示例：待出�团期�房回��从未�存过（�稿）——`releasable=false`，缺项�有 `HOTEL`，`bus` 默认值带�机（缺项与车辆串�自 TEST 验收读数，两步读数拼�一个示例）。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "title": "冻干粉�短信给 · 出团通知书",
+    "greeting": "亲爱的团�，欢迎�加本次行程�",
+    "meetTime": "2026-11-20 08:30",
+    "meetPlace": "",
+    "leader": "",
+    "bus": "mpv 蒙A-G8888 �机 阿拉� 135****5019�suv 蒙A-E2E01 �机 �音德力格尔 135****5009�suv 蒙P301A �机 P3测试�机01 139****0001 / P3测试�机21 139****0021",
+    "contacts": "",
+    "service": "",
+    "bring": "",
+    "saved": false,
+    "releasable": false,
+    "releaseBlockers": [
+      {
+        "key": "HOTEL",
+        "name": "�房未完�"
+      }
+    ],
+    "version": 0,
+    "updateTime": null,
+    "defaults": {
+      "title": "冻干粉�短信给 · 出团通知书",
+      "greeting": "亲爱的团�，欢迎�加本次行程�",
+      "meetTime": "2026-11-20 08:30",
+      "meetPlace": "",
+      "leader": "",
+      "bus": "mpv 蒙A-G8888 �机 阿拉� 135****5019�suv 蒙A-E2E01 �机 �音德力格尔 135****5009�suv 蒙P301A �机 P3测试�机01 139****0001 / P3测试�机21 139****0021",
+      "contacts": "",
+      "service": "",
+      "bring": ""
+    }
+  }
+}
+```
+
+四项都已完�时 `releasable=true`�`releaseBlockers=[]`。
+
+#### 空数� / �级�应
+
+- 团内没有�户派车�或由团车承担：`defaults.bus` 为 `""`。
+- �一户的派车数�异常：跳过该户，其余户照常拼出车辆信�，接��返回 `code=200`。
+- �机手机���到：该�机�显示姓�。
+
+#### 错误�应
+
+| code | �件 |
+|---|---|
+| `589500` | 团期�存在或已删除 |
+| `589507` | 当�角色没有 `group-batch:docs` ��（��） |
+
+```json
+{
+  "code": 589500,
+  "message": "团期�存在",
+  "data": null
+}
+```
+
+#### 业务边界
+
+- `releasable` �管「能�打� / 下��，�影�读�与�存。
+- 招募中的团�返回 `STAGE` 一项，�使资�都没�。
+- �一个团在��时间读，`releasable` 与 `releaseBlockers` �能��（房务�车务回�或补��会�）。
+
+### 2. �存出团通知书 `PUT /v3/admin/order/group-batch/:groupBatchId/docs/notice`
+
+**VO**: `GroupBatchNoticeSaveReqVO` → `Result<GroupBatchNoticeRespVO>`
+
+#### 使用场景
+
+��编辑通知书��存。入���；�应与读接��一个结构，�样带 `releasable` 与 `releaseBlockers`。
+
+#### 入�字段表
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期 ID | **��** |
+| title | Body | String | ✅ | ≤128 字 | **��** |
+| greeting | Body | String | ✅ | ≤512 字 | **��** |
+| meetTime | Body | String | ✅ | ≤64 字 | **��** |
+| meetPlace | Body | String | ✅ | ≤256 字 | **��** |
+| leader | Body | String | ✅ | ≤256 字 | **��** |
+| bus | Body | String | ✅ | ≤256 字 | **��**；默认值带�机��长，车与�机组�很多时原样�存�能超长，需删���存 |
+| contacts | Body | String | ✅ | ≤256 字 | **��** |
+| service | Body | String | ✅ | ≤1024 字 | **��** |
+| bring | Body | String | ✅ | ≤1024 字 | **��** |
+| expectedVersion | Body | Integer | ✅ | ≥0 | **��**，�读接�的 `version` |
+
+#### 出�字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| releasable / releaseBlockers | — | 🔄 / 🆕 �读接� |
+| version | Integer | **��**，�存�的新版本 |
+| 其余字段 | — | **��** |
+
+#### 请求示例
+
+```json
+{
+  "title": "呼伦�尔亲�研学 6 日 · 出团通知书",
+  "greeting": "亲爱的团�，欢迎�加本次行程�",
+  "meetTime": "2026-11-20 08:30",
+  "meetPlace": "海拉尔东山国际机场 T1 到达厅 3 �门",
+  "leader": "�雪梅",
+  "bus": "33 座大巴 蒙A·88888 �机 王师傅 138****8888",
+  "contacts": "�雪梅 139****2756",
+  "service": "� 3 早 6 正��全程用车�景区门票",
+  "bring": "防晒霜�驱蚊液�厚外套",
+  "expectedVersion": 0
+}
+```
+
+#### �应示例
+
+示例：招募中团期首次�存（`expectedVersion=0`）——�存�功�`version=1`，缺项�有 `STAGE`（�存��下�门）。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "title": "呼伦�尔亲�研学 6 日 · 出团通知书",
+    "greeting": "亲爱的团�，欢迎�加本次行程�",
+    "meetTime": "2026-11-20 08:30",
+    "meetPlace": "海拉尔东山国际机场 T1 到达厅 3 �门",
+    "leader": "�雪梅",
+    "bus": "33 座大巴 蒙A·88888 �机 王师傅 138****8888",
+    "contacts": "�雪梅 139****2756",
+    "service": "� 3 早 6 正��全程用车�景区门票",
+    "bring": "防晒霜�驱蚊液�厚外套",
+    "saved": true,
+    "releasable": false,
+    "releaseBlockers": [
+      {
+        "key": "STAGE",
+        "name": "团期未到待出�"
+      }
+    ],
+    "version": 1,
+    "updateTime": "2026-10-03T18:33:10",
+    "defaults": {
+      "title": "冻干粉�短信给 · 出团通知书",
+      "greeting": "亲爱的团�，欢迎�加本次行程�",
+      "meetTime": "2026-11-20 08:30",
+      "meetPlace": "",
+      "leader": "",
+      "bus": "",
+      "contacts": "",
+      "service": "",
+      "bring": ""
+    }
+  }
+}
+```
+
+#### 空数� / �级�应
+
+- �涉�；�存�功�返回�存�的全�。
+
+#### 错误�应
+
+| code | �件 |
+|---|---|
+| `589500` | 团期�存在 |
+| `589507` | 当�角色没有 `group-batch:docs` ��（��） |
+| `589585` | 版本冲�（别人先�存了），请�读��存（��） |
+| `589587` | 正文��件�形�的数字（��） |
+| �数校验失败 | 字段超长或缺失（��） |
+
+```json
+{
+  "code": 589585,
+  "message": "通知书已被他人修改，请刷新��试",
+  "data": null
+}
+```
+
+#### 业务边界
+
+- �存**��**下�门：招募中�资�未�都能�存，�应里照样带缺项。
+- �存�功�，团期时间线（`GET /v3/admin/order/group-batch/:groupBatchId/status-logs`）新增一�「�存出团通知书�，内容如「�存出团通知书（第 3 版）�。�存失败（版本冲���件�拦截��数校验）�新增。
+- 打����端，�留痕。
+
+---
+
+## 四�契约约�与正确调用方�
+
+- 「打� / 存 PDF�按 `releasable` 置�；`releasable=false` 时展示 `releaseBlockers[].name`。判断用 `key`，��用中文�。
+- ��自己根�团期状�推算能�打�，以 `releasable` 为准。
+- �到�认识的 `key`（以�会加团车�机），按 `name` 展示。
+- 车辆信�里的�机拼在 `bus` 字符串里，�需�新输入框。
+
+---
+
+## 五�数�库行为
+
+- 零表结构�更�零数��移。
+- 读接�零写入。
+- �存接�：正文写入��；�功��外在团期时间线新增一�「�存出团通知书�记录。
+
+---
+
+## 六�边界行为
+
+- 团期状�是历��值（�在已知状�内）：`releasable=false`，�列 `STAGE`，�报错。
+- 四项资�中任何一项为空值（历�数�）按「未完��处�。
+- 时间线记录写失败�影��存结果。
+
+## 六.6�修改��对比
+
+| 场景 | 改� | 改� |
+|---|---|---|
+| 待出�，四项都已完� | `releasable=true` | `releasable=true`，`releaseBlockers=[]` |
+| 待出�，�房回�未完� | `releasable=true`（照样能打�） | `releasable=false`，`[HOTEL]` |
+| 招募中 | `releasable=false` | `releasable=false`，`[STAGE]` |
+| 资�准备中，�车未完� | `releasable=false` | `releasable=false`，`[STAGE, VEHICLE]` |
+| 默认车辆信� | `33 座大巴 蒙A·88888` | `33 座大巴 蒙A·88888 �机 王师傅 138****8888` |
+| �存�功 | 时间线无记录 | 时间线新增「�存出团通知书（第 N 版）� |
+
+## 六.7�影�评估
+
+- **是�破���兼容**：`releaseBlockers` 是纯新增字段；`releasable` 在「待出��资�回��时由 `true` � `false`，旧页�会置�按钮但看�到原因。
+- **�端是�必须�步上线**：建议�步展示 `releaseBlockers`；�改也�会报错。
+- **回滚**：revert PR #8770 ��新部署 order-v3。
+
+---
+
+## 七��影�范围
+
+- 两个接�的路径�入��判�（`group-batch:docs`）�错误�：��。
+- 已�存的通知书正文：�会被改写。
+- 团期时间线读接�的结构：��，�是多了一�事件「�存出团通知书�。
+- �程�端：无影�。
+
+---
+
+## 八�测试环境已验�
+
+**环境**：TEST（`https://api.test.1814.love`）　**验�时间**：2026-10-03 18:14~18:46
+**构建身份**：order-v3 部署 `dev-v3 @ b90969493`（本��并�交），18:08:56 完�；部署状�表 order-v3 行为 `dev-v3 b90969493 ok`。零写入判�：部署�连查 8 次读接�，�次�应都带 `releaseBlockers` 键（旧字节没有）。
+**身份**：自签 token 直打网关，用 TEST 真实账� ID �对应角色。
+
+### 8.1 造数
+
+载体产�「冻干粉�短信给�上新建�期「11月20日海拉尔-�尔�纳4日团�（出� 2026-11-20），下两�（� 2 �人）进�一团期 `2106331639531601921`。待出� / 资�回�用 SQL 改团期状�与四项资�完�标记模拟（与房务�车务回�的�库效果相�），�步���。
+
+### 8.2 下�门与缺项
+
+| 团期状� | 未完�项 | `releasable` | `releaseBlockers` |
+|---|---|---|---|
+| 招募中 | 四项全未完� | `false` | `[STAGE]` |
+| 待出� | 无 | `true` | `[]`（4 次读一致） |
+| 待出� | �房 | `false` | `[HOTEL]`，���回到 `true` / `[]` |
+| 待出� | �车 | `false` | `[VEHICLE]` |
+| 资�准备中 | �摄影 | `false` | `[STAGE, PHOTOGRAPHER]` |
+| 已�团 | �房��车 | `false` | `[STAGE]` |
+| 历��值 `PENDING_TRIP` | — | `false` | `[STAGE]`，接� 200 |
+
+缺资�时�存照常�功（`version` 2 → 3，�应带 `[HOTEL]`）。
+
+### 8.3 默认车辆带�机
+
+把真实派车数��制到两户�下（手机�按新订��新加密）：`defaults.bus` 出 3 辆车�4 ��机，8 次读一致；4 个手机��为 `ddd****dddd` 形�，�三�四与独立解密结果一致；�一辆车两天两��机用「 / �并列。两个实例在时间窗内的日志明文手机�零命中。
+
+### 8.4 一户派车数�异常
+
+两户中一户的派车数�改为�自洽：8 次读全部 `code=200`，`bus` ��正常户的车；两个实例�记 4 �「已跳过该户�告警，无事务回滚异常。清�� `bus` 回到空。
+
+### 8.5 �存留痕
+
+| �作 | 结果 |
+|---|---|
+| 首次�存 | `version=1`；时间线新增「�存出团通知书（第 1 版）�，�作人 jw |
+| 用旧版本��存 | `589585`，时间线�数与版本��� |
+| 用新版本��存 | `version=2`；新增「第 2 版� |
+
+### 8.6 判�
+
+| 调用方 | 读 | 存 |
+|---|---|---|
+| �带 token | 网关 `401` | 网关 `401` |
+| 车务�财务（无 `group-batch:docs`） | `589507` | `589507`，零写入 |
+| 管�员�团期管�员 | `200` | `200`，版本 +1 |
+
+### 本地��
+
+| 项 | 读数 |
+|---|---|
+| 定� 3 类（� 5 个内嵌类） | 63/0/0 |
+| �并�交�跑 6 类 | 97/0/0 |
+| 团期包 + archunit 包 + 全模�架构测试（有 Docker） | 3851 例 5 失败 2 错误，全部在基底 `d778c9a71` 干净工作区���现，本�零新增 |
+
+### 未覆盖
+
+- TEST 上没有「待出���户派车�在团户未�消�的现�团，默认车辆带�机用�制的真实派车数�验�。
+- 房务�车务回�用 SQL 模拟�库效果，真实回�业务路径未走。
+- 团车（整团派车）的车辆与�机�在本�（#8767）。
+
+---
+
+## ��相关文档
+
+- Issue `#8746`ï¼›PR `#8770`
+- 拆出：Issue `#8767`（团车车辆与�机进通知书�`DRIVER` 缺项）
+- �置：Issue `#7532`（出团通知书首版）
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#8746](https://git.1814.love/wx/HL/issues/8746)
+- **PR**: [#8770](https://git.1814.love/wx/HL/pulls/8770)
+- **Merge commit**: [b90969493](https://git.1814.love/wx/HL/commit/b90969493)
+
+### �系人
+
+- **�端负责人**: @jw