docs(changelog): #7949 定制师可读名下团期详情与子订单名单（修改接口·管理后台）

docs(changelog): #7932 团期核团 7 个新增接口与验团前置核团行为变更
Refs wx/HL#7932 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-18 18:16:37 +08:00 · 2026-09-18 18:12:53 +08:00
@@ -0,0 +1,328 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7932"
+title: "验团归档前置核团定稿并同事务推进核团为已验团，验团反确认同步退回核团"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "已上线的验团归档 POST .../settle 行为变更：核团须先提交核算（ALLOCATED）才能验团，验团同事务把核团推到已验团（CHECKED）；新增可选请求体 checkNote（验团意见）。验团反确认 POST .../settle/reopen 同事务把核团从已验团退回已核算。⚠️ 处于核单中（REVIEWING）但还没有核团记录的团，验团会返回 589567，须先在核团 Tab 完成定稿。后端 PR #7944 已合并 dev-v3 并部署 TEST。核团 7 个新接口见同日新增接口 changelog。"
+updated_at: "2026-09-18"
+base: "dev-v3"
+---
+
+# order-v3: 🔧 验团归档须先完成核团定稿，验团 / 反确认与核团状态联动
+
+> **存放目录**: `changelogs-v2/{YYYY-MM}/`（管理后台，二期 order-v3）
+>
+> **服务**: hl-order-service-v3（order-v3）
+> **PR**: #7944（合并提交 db3abc6c7；后续 #7955 未改这两个接口）
+> **Issue**: #7932
+> **日期**: 2026-09-18
+> **影响范围**: 团期详情「验团」「验团反确认」按钮
+
+---
+
+## ⚠️ 关键变化
+
+1. **⚠️ 线上已有接口的行为变更**：`POST .../settle`（验团归档）以前只要团期在「核单中」（REVIEWING）就能点；**现在还要求核团已提交核算**。
+   - **处于核单中但还没有核团记录的团，验团会返回 `589567`**（「该团期尚未进入核团：尚无核团记录，请先在核团 Tab 完成核算定稿后再验团」）。
+   - 核团还在录入中，验团返回 `589568`。
+   - 运营须先到「核团验团」Tab：打开面板（自动生成草稿）→ 保存 → 提交核算，然后再验团。
+2. 验团成功时，核团与团期**在同一个事务里**一起变：核团 `ALLOCATED → CHECKED`、团期 `REVIEWING → SETTLED`，不会出现一个变了一个没变。
+3. 验团**新增可选请求体** `{ "checkNote": "..." }`（验团意见，≤512 字）；不传 body 与以前一样能调。
+4. `POST .../settle/reopen`（验团反确认）同时把核团从「已验团」退回「已核算」，并清空验团意见；要改分摊数须再点「重新核算」。
+5. 路径、响应结构、判权方式都不变。
+
+---
+
+## 一、背景
+
+以前验团只看团期状态，「成本还没录完就能点验团」是已知缺口。#7932 上线核团后，验团改为以核团定稿为前提，并与核团「已验团」合并成一个动作（不另设 `/audit/check` 接口）。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 验团归档（GB-ADM-053） | POST | `/v3/admin/order/group-batch/{groupBatchId}/settle` | 行为变更 + 新增可选请求体 | 须核团已核算；同事务推进核团为已验团 |
+| 2 | 验团反确认 | POST | `/v3/admin/order/group-batch/{groupBatchId}/settle/reopen` | 行为变更 | 同事务把核团从已验团退回已核算 |
+
+---
+
+## 三、接口详情
+
+### 1. 验团归档（GB-ADM-053） `POST /v3/admin/order/group-batch/{groupBatchId}/settle`
+
+**VO**: `GroupBatchSettleReqVO`（可选）→ `Result<Void>`
+
+#### 使用场景
+
+团期详情 / 核团 Tab「验团」按钮：核对完成后归档，团期进入已验团终态。按钮建议只在 `batchStatus=REVIEWING` **且**核团面板 `auditStatus=ALLOCATED` 时可点（两个状态都能从核团面板 GB-ADM-050 一次拿到）。
+
+**权限（不变）**：按角色——超级管理员 / 管理员 / 财务；不看 `group-batch:audit:*` 权限码。团期管理员能核算但不能验团。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long（传字符串） | ✅ | 团期 ID | 不变 |
+| checkNote | Body | String | 否 | ≤ 512 字 | **新增**：验团意见；整个请求体都可以不传 |
+
+#### 出参
+
+不变。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 成功无数据；验团意见 / 验团时间在核团面板 GB-ADM-050 的 `checkNote` / `checkedAt` 里看 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2100857935637663745/settle
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "checkNote": "成本已逐项核对" }
+```
+
+不带意见时可以不传请求体（老前端写法照常可用）。
+
+#### 响应示例
+
+（TEST 真实响应，2026-09-18，核团已核算的团期；之后核团 `CHECKED`、团期 `SETTLED`）
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+写接口，无空数据形态。被拒时整笔回滚：团期状态、核团状态、验团意见都不变（TEST 已核对）。
+
+```json
+{ "code": 589568, "message": "核团当前状态不允许该操作：当前「录入中」，需要「已核算」；请先在核团 Tab 完成核算定稿后再验团", "data": null, "success": false }
+```
+
+#### 错误响应
+
+（TEST 真实响应：核单中、但还没有核团记录的团 —— **本次行为变更的主要影响面**）
+
+```json
+{ "code": 589567, "message": "该团期尚未进入核团：尚无核团记录，请先在核团 Tab 完成核算定稿后再验团", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 589507 | 非超级管理员 / 管理员 / 财务（不变） |
+| 589500 | 团期不存在（不变） |
+| 589555 | 团期已验团（不变；并发时后到的一次也报这个） |
+| 589501 | 团期不在核单中（不变） |
+| **589567** | **新增**：团期在核单中，但还没有核团记录 |
+| **589568** | **新增**：核团不在「已核算」（如还在录入中） |
+| **589573** | **新增**：推进核团状态时与他人操作冲突，刷新后重试 |
+| 400 | `checkNote` 超过 512 字 |
+
+#### 业务边界
+
+- 判断顺序：先判权限 → 团期存在 → 团期状态（不是核单中就按原来的 589555 / 589501 报）→ 再判核团。
+- 核团已是「已验团」（极少数并发场景）时不改验团意见，交给团期状态判断。
+- 验团后核团四张表只读：保存 / 提交核算 / 重新核算都会被拒（589568），开票仍可。
+
+---
+
+### 2. 验团反确认 `POST /v3/admin/order/group-batch/{groupBatchId}/settle/reopen`
+
+**VO**: `Result<Void>`（无请求体）
+
+#### 使用场景
+
+已验团的团发现有误时点「验团反确认」：团期 `SETTLED → REVIEWING`，**同时**核团 `CHECKED → ALLOCATED`，清空验团人、验团时间与意见（旧值写进团期时间线）。要改分摊数，再到核团 Tab 点「重新核算」（已开票的团会被拦）。
+
+**权限（不变）**：超级管理员 / 管理员 / 财务。
+
+#### 入参
+
+本次入参**不变**。
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long（传字符串） | ✅ | 团期 ID | 无请求体 |
+
+#### 出参
+
+本次出参**不变**。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 成功无数据 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2100857935637663745/settle/reopen
+Authorization: Bearer <token>
+```
+
+无请求体。
+
+#### 响应示例
+
+（TEST 真实响应，2026-09-18；之后团期 `REVIEWING`、核团 `ALLOCATED`，`checkNote` / `checkedAt` 变为 null，逐户定稿保留）
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本单上线前就已验团、没有核团记录的存量团：反确认照常成功，只退团期状态，不动核团（反确认是纠错退路，不因核团数据缺失而堵死）。
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 错误响应
+
+```json
+{ "code": 589501, "message": "团期状态不允许当前操作", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 589507 | 非超级管理员 / 管理员 / 财务（不变） |
+| 589500 | 团期不存在（不变） |
+| 589501 | 团期不是已验团（不变） |
+| **589573** | **新增**：退回核团状态时与他人操作冲突 |
+
+#### 业务边界
+
+- 反确认后核团停在「已核算」，逐户定稿不清空；需要改数时再「重新核算」。
+- 旧的验团人、时间、意见写在团期时间线（验团事件的附加信息）里，可追溯。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 前端需要做的
+
+1. **验团按钮可点条件**：`batchStatus === 'REVIEWING' && auditStatus === 'ALLOCATED'`（取自核团面板 GB-ADM-050）。核团未定稿时置灰并提示「请先在核团 Tab 完成核算定稿」。
+2. **验团弹窗加可选「验团意见」输入框**（≤512 字），作为 `checkNote` 提交；不填可不传 body。
+3. **589567 / 589568 直接展示后端 message**（已带引导语），并引导跳到核团 Tab。
+4. 验团 / 反确认成功后刷新核团面板（核团状态会一起变）。
+
+### ✅ 正确 / ❌ 错误 用法
+
+| 场景 | 做法 |
+|------|------|
+| ✅ 验团带意见 | `{ "checkNote": "成本已逐项核对" }` |
+| ✅ 验团不带意见 | 不传 body，或传 `{}` |
+| ❌ 核团还在录入中就点验团 | 589568 |
+| ❌ 核单中但从没打开过核团 Tab 就点验团 | 589567（本次新增的拒绝） |
+| ❌ 调 `/audit/check` 做验团 | 没有这个接口，验团就是 `/settle` |
+
+---
+
+## 五、数据库行为
+
+- 无表结构变更、无 Flyway。
+- 验团成功：团期状态改为已验团；核团状态改为已验团，写验团人、验团时间、验团意见，版本 +1；团期时间线的验团事件附加记录核团迁移与验团意见。
+- 反确认成功：团期状态退回核单中；核团状态退回已核算，清空验团人、时间、意见，版本 +1；旧值写进时间线。
+- 任何一步被拒，团期与核团整笔回滚，零写入（TEST 已核对 589567 / 589568 两种拒绝后团期仍为核单中、核团行数不变）。
+
+---
+
+## 六、边界行为
+
+- 核单中 + 无核团记录 → 验团 589567（**改前可以直接验团**）。
+- 核单中 + 核团录入中 → 验团 589568（**改前可以直接验团**）。
+- 核单中 + 核团已核算 → 验团成功，核团同步变已验团。
+- 已验团 → 再点验团 589555（不变）；反确认成功，核团退回已核算。
+- 本单上线前已验团的存量团（无核团记录）→ 反确认照常成功。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| settle 请求体 | 无 | 可选 `{ checkNote: String ≤512 }` |
+| settle / reopen 路径、响应 | — | 不变 |
+| settle 错误码 | 589507 / 589500 / 589555 / 589501 | 另加 589567 / 589568 / 589573 |
+| reopen 错误码 | 589507 / 589500 / 589501 | 另加 589573 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 验团前置 | 团期在核单中即可 | 团期在核单中 **且** 核团已核算 |
+| 核单中但没有核团记录的团点验团 | 成功归档 | **589567 拒绝** |
+| 验团对核团的影响 | 无（当时还没有核团） | 核团 `ALLOCATED → CHECKED`，同一事务 |
+| 验团意见 | 无处填写 | `checkNote`，在核团面板回显 |
+| 反确认对核团的影响 | 无 | 核团 `CHECKED → ALLOCATED`，清空验团意见 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 结构兼容（老前端不传 body 照常可调）；**行为上收紧**——原来能直接验团的「核单中」团期，现在必须先完成核团定稿。
+- **存量在途团影响**: TEST / 线上所有处于核单中、还没做核团的团期，验团都会被 589567 拒绝，需要运营先到核团 Tab 完成「打开面板 → 保存 → 提交核算」。上线前建议通知运营与财务。
+- **前端是否必须同步上线**: 否，不改也不会出错（后端会拦并给出引导语）；但建议同步上线第四节的按钮条件与验团意见输入框，避免运营「点了才知道不行」。
+- **前端 workaround 清理点**: 无。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 验团归档、验团反确认两个接口的前置与联动。
+- **零影响**:
+  - 发起核单 `POST .../review/start`（出行完毕 → 核单中）
+  - 团期共享成本录入 / 列表 / 汇总
+  - 订单侧第 1 层核单与财务复核
+  - 验团 / 反确认的判权口径（仍是超级管理员 / 管理员 / 财务）
+
+---
+
+## 八、测试环境已验证
+
+被测版本：hl-order-service-v3 = dev-v3（#7944 合并提交 `db3abc6c7`，其后 #7955 合并 `aed07cc3c` 未改这两个接口），经网关实测。
+
+```
+E（核单中，无核团记录）  settle        → 589567「尚无核团记录，请先在核团 Tab 完成核算定稿后再验团」；团期仍 REVIEWING、核团 0 行 ✓
+B（核团录入中，无 body）  settle        → 589568「当前「录入中」，需要「已核算」…」；团期仍 REVIEWING                 ✓
+A（核团录入中）           settle        → 589568；零写入                                                               ✓
+A（核团已核算）           settle + checkNote → 200；核团 CHECKED、版本 7→8、checkNote 已写；团期 SETTLED；
+                          时间线 BATCH_SETTLE 附核团 ALLOCATED→CHECKED                                                ✓
+A（已验团）               保存 / 提交核算 / 重新核算 → 均 589568；录共享成本 → 589501                                 ✓
+A（已验团）               reopen        → 200；团期 REVIEWING；核团 ALLOCATED、版本 8→9、验团人时与意见清空；
+                          逐户定稿 3 户保留；时间线附旧验团人时与意见                                                  ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7932](https://git.1814.love:8443/wx/HL/issues/7932)
+- 关联 PR: [wx/HL#7944](https://git.1814.love:8443/wx/HL/pulls/7944)
+- 同日新增接口：`changelogs-v2/2026-09/18_7932_团期核团核算开票导出与节点下钻-新增接口-管理后台.md`（核团 7 个接口、权限码、错误码全表）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7932](https://git.1814.love:8443/wx/HL/issues/7932)
+- **PR**: [#7944](https://git.1814.love:8443/wx/HL/pulls/7944)
+- **Merge commit**: [db3abc6c7](https://git.1814.love:8443/wx/HL/commit/db3abc6c7)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg
@@ -0,0 +1,302 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7949"
+title: "定制师可读名下团期的详情与子订单名单（调整订单弹窗恢复可用）"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "团期详情与子订单名单两个读接口：CUSTOMIZER 由「一律 589507」改为「可读本人名下团期」，其余团期仍 589507；ADMIN / FINANCE / SUPER_ADMIN 行为逐字不变。589507 文案同步订正。响应结构、字段、HTTP 状态均不变，前端无需改代码——定制师的调整订单弹窗自动恢复可用。"
+updated_at: "2026-09-18"
+base: "dev-v3"
+---
+
+# order-v3：定制师可读名下团期的详情与子订单名单
+
+> **服务**: hl-order-service-v3 (端口 8086)、hl-user-service (端口 8081，权限种子)
+> **PR**: #7951
+> **Issue**: #7949
+> **日期**: 2026-09-18
+> **影响范围**: 管理后台团期详情、团期子订单名单，以及团期子订单的「调整订单」弹窗
+
+---
+
+## ⚠️ 关键变化
+
+1. **定制师现在能打开团期子订单的「调整订单」弹窗了**。弹窗打开时会读团期详情，该接口要求 `group-batch:view`，而这个权限码此前从未授予 `CUSTOMIZER`，于是弹窗一开就弹 589507，酒店 / 用车需求提交不了。
+2. **定制师只能读「本人名下」的团期**：判据是该团期下存在 `consultant_id = 当前 adminId` 的在团子订单；读别人的团期仍然 589507。只授权限不加这层校验，等于让任一定制师读到全公司所有团期的详情与逐户名单。
+3. **`ADMIN` / `FINANCE` / `SUPER_ADMIN` 行为逐字不变**，连多余的查询都没有。
+4. **589507 文案订正**：由「无操作权限（非团期管理员 / 非本定制师名下）」改为「无操作权限（当前角色未授予团期权限，或该团期不在您名下）」——旧文案承诺的「本定制师名下」这个判定维度当时并不存在，现在两个分支才都真实存在。
+5. **响应结构与字段零变化**，前端无需改代码。
+
+---
+
+## 一、背景
+
+团期子订单的住宿与用车需求由**定制师**提交，再由团期管理员汇总、房务 / 车务接单。定制师提不了需求，整条团期资源准备链路的起点就是断的——订单流程状态会永远停在「配房待提交需求 / 配车待提交需求」。
+
+wx 2026-09-18 在测试环境以定制师身份操作订单时撞到，口径定案：「团期订单定制师不能改出行日期、行程，但出行人、酒店需求、用车需求还是能改的」。
+
+根因不在调整链路上：调整订单的提交接口本来就没有权限守卫，定制师是被挡在**弹窗打开**这一步——`GET /v3/admin/order/group-batch/{groupBatchId}` 需要 `group-batch:view`，而 `V20260831_002` 的授权名单只有 `ADMIN` / `FINANCE` / `SUPER_ADMIN`。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 修改 | 定制师可读**本人名下**团期；其余团期仍 589507；文案订正 |
+| 2 | 团期子订单名单 | GET | `/v3/admin/order/group-batch/{groupBatchId}/orders` | 修改 | 同上，同一层归属校验 |
+
+---
+
+## 三、接口详情
+
+### 1. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
+
+**VO**: `Result<GroupBatchDetailRespVO>`（结构与字段**零变化**）
+
+#### 使用场景
+
+管理后台团期详情页；以及团期子订单的「调整订单」弹窗打开时的第一跳。定制师此前在这一跳被 589507 挡住，弹窗内的酒店 / 用车需求页签渲染不出来。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID | 团期 ID（`order_group_batch.group_batch_id`） |
+| Authorization | Header | String | ✅ | Bearer token | 管理端登录令牌 |
+| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信操作人 ID，客户端传值一律忽略 |
+| X-Admin-Role | Header | String | ✅ | 网关注入 | 当前角色 key，判权与归属校验都按它走，不按库角色 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| （全部字段） | — | **与改动前逐字一致**，本次只改判权，不改响应结构 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2100856430494973953
+Authorization: Bearer <定制师 token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2100856430494973953",
+    "teamNo": "26-7060",
+    "batchStatus": "RECRUITING"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无空数据形态：团期不存在返回 589500；权限或归属不满足返回 589507。归属判定依赖在团子订单查询，查询为空即判为「不在名下」，按 589507 拒绝（失败关闭），不会降级放行。
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "data": null,
+  "success": false
+}
+```
+
+| 码 | 触发 |
+|---|---|
+| 589507 | 当前角色未获授 `group-batch:view`；**或**（本次新增）定制师读的团期下没有本人名下的在团子订单 |
+| 589500 | 团期不存在 |
+
+#### 业务边界
+
+- 归属判据是「该团期下存在 `consultant_id = 当前 adminId` 的**在团**子订单」，在团口径 = 仅排除 `CANCELLED`（含 `COMPLETED`），软删自动过滤
+- 名下子订单退团 / 取消后，该定制师对这个团期的可见性随之消失
+- 一个团期下有多个定制师的子订单时，各自都可见
+- `ADMIN` / `FINANCE` / `SUPER_ADMIN` 不走归属校验，行为逐字不变
+- 判权顺序：先角色级权限码，再数据级归属；被拒时不读团期实体，不产生任何副作用
+- 非请求上下文（定时任务 / 内部调用）按系统态放行
+
+### 2. 团期子订单名单 `GET /v3/admin/order/group-batch/{groupBatchId}/orders`
+
+**VO**: `Result<PageResult<GroupBatchOrderItemRespVO>>`（结构与字段**零变化**）
+
+#### 使用场景
+
+团期详情页的子订单名单（含联系人、人数、房 / 车需求摘要）。与详情同挂 `group-batch:view`，因此必须与详情同一层归属校验——只挡详情不挡名单，等于把同一批数据从另一个门放出去。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID | 团期 ID |
+| page | Query | Integer | ❌ | ≥1，缺省 1 | 页码 |
+| pageSize | Query | Integer | ❌ | 缺省 20，上限 200 | 每页条数 |
+| includeTravelers | Query | Boolean | ❌ | 缺省 true | 是否附出行人明细 |
+| includeNeeds | Query | Boolean | ❌ | 缺省 true | 是否附房数 / 房型 / 特殊需求 |
+| includeCancelled | Query | Boolean | ❌ | 缺省 false | 是否含已取消子订单 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| （全部字段） | — | **与改动前逐字一致** |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2100856430494973953/orders?page=1&pageSize=20
+Authorization: Bearer <定制师 token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "orderId": "2100856430239121409",
+        "orderNo": "HL20260918155619496",
+        "customerName": "王有亿"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+团期下无子订单时返回 `records: []`、`total: 0`，不报错。归属校验不满足时按 589507 拒绝，不返回空列表——「看不到」与「没有」必须区分开。
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "data": null,
+  "success": false
+}
+```
+
+| 码 | 触发 |
+|---|---|
+| 589507 | 同接口 1 |
+| 589500 | 团期不存在 |
+
+#### 业务边界
+
+- 与接口 1 同一份归属判据，同一套角色豁免
+- `includeCancelled=true` 只影响返回的子订单集合，**不影响归属判定**——归属判定恒按在团口径（已取消的单不能用来「借」可见性）
+
+---
+
+## 四、契约约束与正确调用方式
+
+- 前端**无需改动**：定制师登录后照常打开团期详情与调整订单弹窗即可，响应结构没有任何变化。
+- 收到 589507 时不要再按旧文案提示「非团期管理员 / 非本定制师名下」，新文案已覆盖两种成因（角色无权限 / 团期不在名下）。
+- 定制师**不能**通过本接口拿到别人的团期，遍历 `groupBatchId` 只会得到 589507。
+- 定制师**仍然没有**团期看板列表（`GET /v3/admin/order/group-batch`）与导出（`.../export`）权限，本次只授 `group-batch:view` 一个码。
+
+---
+
+## 五、数据库行为
+
+- 表结构 / 索引：**零变更**。
+- 数据变更：新增 `hl-user-service` 迁移 `V20260918_005__grant_group_batch_view_to_customizer.sql`，向 `admin_role_permission` 插入 `CUSTOMIZER × group-batch:view` 一行；`INSERT IGNORE` + 唯一键 `uk_role_permission(role_id, permission_id)` 保证幂等，可重复执行；按 `role_key` 子查询取 `role_id`，适配各环境角色 ID 差异。
+- 读侧：归属校验复用既有的在团子订单查询，未新增 Mapper；归团投影（一跳与回退两条通道）多带出 `order_main.consultant_id` 一列，未改变行过滤口径。
+- 本次两个接口仍是**纯读**，无任何写入。
+
+---
+
+## 六、边界行为
+
+- 权限码走 Redis 缓存（`admin_permissions:v2:role:{roleKey}`，TTL 10 分钟）：种子落库后非超管角色可能先继续收到 589507，属正常窗口期。
+- `hl-user-service` 与 `hl-order-service-v3` **必须同批部署**：只滚前者则权限是纯角色级（任一定制师可读全部团期，横向越权）；只滚后者则定制师仍不可用。
+- 团期不存在时，无权限的调用者收到的是 589507 而不是 589500——判权在存在性校验之前，不暴露团期是否存在。
+- 网关未注入 `X-Admin-Id` 时（非网关来源的请求）一律 589507，失败关闭。
+
+## 六.6、修改前后对比
+
+| 调用者 | 改前 | 改后 |
+|---|---|---|
+| `CUSTOMIZER`，读**本人名下**团期 | 589507 | **200** |
+| `CUSTOMIZER`，读**他人**团期 | 589507 | 589507（不变） |
+| `ADMIN` / `FINANCE` / `SUPER_ADMIN` | 200 | 200（逐字不变） |
+| 589507 文案 | 无操作权限（非团期管理员 / 非本定制师名下） | 无操作权限（当前角色未授予团期权限，或该团期不在您名下） |
+| `CUSTOMIZER` 调团期看板列表 / 导出 | 589507 | 589507（不变） |
+
+## 六.7、影响评估
+
+- **前端**：无需改动；定制师侧由「弹窗打不开」恢复为可用。文案变化仅影响提示文本，无需适配。
+- **权限面**：新增授权仅 1 个只读码，且叠加了数据级归属校验，净暴露面是「定制师可见自己名下团期的详情与子订单名单」。
+- **回归风险**：管理员 / 财务 / 超管路径未新增任何查询与判定；非请求上下文（定时任务）不受影响。
+- **已知遗留**：同样挂 `group-batch:view` 的六芯片逐户明细等端点，在授权后对定制师一并可见，本次只对详情与子订单名单加了归属校验，后续评估是否统一收口（见工单 #7949「后续工单」第 2 条）。
+
+---
+
+## 七、不影响范围
+
+- 调整订单的提交链路（`POST /v3/admin/order/{id}/adjustment/submit`）：一行未改，它本来就没有权限守卫。
+- 出行日期与行程的既有约束（587039 / 587041 / 587042）：未削弱，实测定制师改出发日仍返回 587039。
+- 团期子订单出行人增删拦截（587036）：不变。
+- `group-batch:list` 与 `group-batch:export` 的授权名单：不变。
+- 所有写接口、所有非团期域接口：不受影响。
+
+---
+
+## 八、测试环境已验证
+
+部署：PR #7951 合入 `dev-v3`（`73333427d`）后，`hl-order-service-v3` 与 `hl-user-service` 一起滚到测试环境；Flyway `20260918.005` 执行 `success=1`，执行后 `CUSTOMIZER` 持有的 group-batch 码恰为 `group-batch:view` 一个。
+
+| 用例 | 角色 | 请求 | 改前 | 改后 |
+|---|---|---|---|---|
+| 本人名下团期详情 | CUSTOMIZER（本团期定制师） | `GET /v3/admin/order/group-batch/2100856430494973953` | 589507 | 200 |
+| 本人名下子订单名单 | 同上 | `GET .../orders` | 589507 | 200 |
+| 他人团期详情 | CUSTOMIZER（本团期无单） | `GET .../group-batch/{id}` | 589507 | 589507 |
+| 他人团期子订单名单 | 同上 | `GET .../orders` | 589507 | 589507 |
+| 管理员 / 财务 / 超管 | ADMIN / FINANCE / SUPER_ADMIN | `GET .../group-batch/{id}` | 200 | 200 |
+| 团期看板列表 / 导出 | CUSTOMIZER | `GET /v3/admin/order/group-batch`、`.../export` | 589507 | 589507 |
+| 提交酒店 + 用车需求 | CUSTOMIZER | `POST /v3/admin/order/{id}/adjustment/submit` | 弹窗打不开 | 200，两条需求落 `PENDING_REVIEW`，团期配房 / 配车芯片由「待提交」变「待审核」 |
+| 改出发日仍被拒 | CUSTOMIZER | 同上，传 `schedule.departDate` | 587039 | 587039 |
+
+单测：`GroupBatchQueryServiceTest` 69 → 77（新增 8 条覆盖归属校验四类分支）；新增 `CustomizerGroupBatchViewMigrationMysqlTest` 6 条（真 MySQL，含幂等与「只授 view」阴性对照）；`OrderInfoMapperIT` 28/28（断言投影真的带出 `consultant_id`）。全量：`hl-user-service` 4006 例全绿；`hl-order-service-v3` 11198 例，唯一失败 `MapperBoundaryArchTest#non_refund_not_depend_on_refund_mapper` 在干净 `dev-v3 @ 701898e2f` 上逐字复现，属既有问题。
+
+---
+
+## 十、相关文档
+
+- 工单：https://git.1814.love:8443/wx/HL/issues/7949
+- PR：https://git.1814.love:8443/wx/HL/pulls/7951
+- 权限码定义来源迁移：`hl-user-service` `V20260831_002__add_group_batch_permissions.sql`（#6902）
+- 本次授权迁移：`hl-user-service` `V20260918_005__grant_group_batch_view_to_customizer.sql`
+
+---
+
+## 关联 / 联系人
+
+- 后端：jw
+- 前端：mmg（无需改动，仅周知 589507 文案变化）
+- 口径定案：wx（2026-09-18）
作者	SHA1	备注	提交日期
jw	d7c4a5d4bf	docs(changelog): #7949 定制师可读名下团期详情与子订单名单（修改接口·管理后台） changelog-filename-gate / validate (push) Failing after 1s 详情	2026-09-18 18:16:37 +08:00
jw和Claude Opus 5	8a5c34f09f	docs(changelog): #7932 团期核团 7 个新增接口与验团前置核团行为变更 Refs wx/HL#7932 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-18 18:12:53 +08:00