From 17210578cb364fdafc5a5778047082b9a7cae2fc Mon Sep 17 00:00:00 2001 From: jw Date: Sun, 27 Sep 2026 10:56:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8410=20=E5=9B=A2=E6=9C=9F?= =?UTF-8?q?=E3=80=8C=E9=85=8D=E7=BD=AE=20=E2=86=92=20=E7=A1=AE=E8=AE=A4?= =?UTF-8?q?=E3=80=8D=E6=96=B0=E5=A2=9E=E5=8F=AA=E8=AF=BB=E9=A2=84=E6=A3=80?= =?UTF-8?q?=20confirm-check=EF=BC=88=E6=96=B0=E5=A2=9E=E6=8E=A5=E5=8F=A3-?= =?UTF-8?q?=E7=AE=A1=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 GET /v3/admin/order/group-batch/{groupBatchId}/confirm-check：前端据 ready 提前置灰「确认」按钮， 团期级五项与逐户未满足项可见，gateMessage 与 589556 message 逐字相同；零写入。 TEST 已部署（dev-v3 @ ecc92b95c）并经网关验收，工单 #8410 已关。 Co-Authored-By: Claude Opus 5.5 --- ...8410_团期确认只读预检-新增接口-管理后台.md | 309 ++++++++++++++++++ 1 file changed, 309 insertions(+) create mode 100644 changelogs-v2/2026-09/27_8410_团期确认只读预检-新增接口-管理后台.md diff --git a/changelogs-v2/2026-09/27_8410_团期确认只读预检-新增接口-管理后台.md b/changelogs-v2/2026-09/27_8410_团期确认只读预检-新增接口-管理后台.md new file mode 100644 index 00000000..d931fc7f --- /dev/null +++ b/changelogs-v2/2026-09/27_8410_团期确认只读预检-新增接口-管理后台.md @@ -0,0 +1,309 @@ +--- +schema: "hl-changelog/v2" +ticket: "8410" +title: "团期「配置 → 确认」新增只读预检 confirm-check：前端据 ready 提前置灰「确认」按钮，团期级五项与逐户未满足项可见" +consumer: "admin" +author: "jw(GIT)" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "v2.1" +verified_at: "2026-09-27" +status_note: "新增 GET /v3/admin/order/group-batch/{groupBatchId}/confirm-check（权限码 group-batch:confirm，与确认写口同码）。返回此刻点「确认」能不能过（ready）、状态是否允许确认（statusConfirmable）、团期级五项（房 / 车 / 导游领队 / 摄影 / 物资，每项 passed + 未通过文案）、逐户未满足项（待支付 / 定制中的在团户，每户 orderNo + items[code, text]）与 gateMessage（与此刻点确认拿到的 589556 message 逐字相同）。判据与写口同源；主报账人按「确认时会先补齐人员副本」投影；零写入。状态不是 RESOURCE_PREPARING 时不做逐户预检，checkedHouseholdCount 为 null。前端需在团期详情「配置」节点进入时与点「确认」前调用，据 ready 置灰按钮、据 batchItems / unmetHouseholds 列缺项。" +updated_at: "2026-09-27" +base: "dev-v3" +--- + +# 团期确认: 新增只读预检 confirm-check，按钮可提前置灰（管理后台） + +> **服务**: hl-order-service-v3（端口 8086/8186） +> **PR**: #8411 +> **Issue**: #8410 +> **日期**: 2026-09-27 +> **影响范围**: 管理后台团期详情「配置」节点的「确认」按钮（置灰与缺项提示）；确认写口本身契约不变 + +--- + +## ⚠️ 关键变化 + +1. **新增只读端点** `GET .../{groupBatchId}/confirm-check`：点「确认」之前就能知道能不能过、差什么。 +2. **逐户未满足项第一次对前端可见**。#8339 起确认门含逐户预检（订金、出行人、户级房车、合同模板、主报账人），但团期详情只有团期级五个标记位，前端据此置灰会漏掉逐户这一半；以后以本端点的 `ready` 为准。 +3. `gateMessage` 与点确认拿到的 589556 `message` 逐字相同，可直接展示。 + +--- + +## 一、背景 + +团期「配置 → 确认」（#8268，`POST .../confirm`）的门 = 房 / 车 / 导游领队 / 摄影四项配齐 + 物资已确认，#8339 又加了逐户预检。不满足时整单返回 589556，`message` 里列出未满足项，但**没有结构化数据**，团期详情也只透出团期级五个标记位。于是出现「五项全绿、某户没付订金时按钮是亮的，点下去才报错」。需求确认与订房确认早就各有配对的只读预检（`requirement/confirm-check`、`room-plans/confirm-check`），团期确认补齐同一形态。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 团期确认预检 | GET | `/v3/admin/order/group-batch/{groupBatchId}/confirm-check` | 新增接口 | 只读；与 `POST .../confirm` 同门、同报文、同权限码 | + +网关无改动（在既有 `/v3/admin/order/group-batch` 前缀下）。 + +--- + +## 三、接口详情 + +### 1. 团期确认预检 `GET /v3/admin/order/group-batch/{groupBatchId}/confirm-check` + +**VO**: `GroupBatchConfirmCheckRespVO` + +#### 使用场景 + +团期详情「配置」节点：进入页面时与点「确认」前调用。`ready=false` 时置灰「确认」按钮，用 `batchItems` 展示团期级五项的勾叉，用 `unmetHouseholds` 逐户列出还差什么，或直接展示 `gateMessage`。`statusConfirmable=false`（不在配置节点）时按钮应隐藏或置灰，不要提示缺项。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 团期主键 | 不存在返 589500 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| groupBatchId | String | 团期主键（雪花 id，按字符串返回） | +| batchStatus | String | 团期状态码 | +| batchStatusName | String | 团期状态中文名 | +| ready | Boolean | 此刻点「确认」能否通过：`statusConfirmable=true` 且五项全过且 `unmetHouseholds` 为空 | +| statusConfirmable | Boolean | 状态是否允许确认（仅 `RESOURCE_PREPARING`）；false 时点确认会是 589501 | +| batchItems | Array | 团期级五项，固定顺序、全量返回（含已通过项），任何状态下都有值 | +| batchItems[].code | String | `HOTEL_READY` / `VEHICLE_READY` / `GUIDE_READY` / `PHOTOGRAPHER_READY` / `MATERIAL_CONFIRMED`，与团期详情同名布尔字段对应 | +| batchItems[].name | String | 房 / 车 / 导游领队 / 摄影 / 物资 | +| batchItems[].passed | Boolean | 是否通过 | +| batchItems[].unmetText | String | 未通过时的文案（与 589556 里的逐字相同），通过时 null | +| checkedHouseholdCount | Integer | 参与逐户预检的户数（待支付 + 定制中的在团户）；`statusConfirmable=false` 时不做逐户预检，为 null（null = 没查，0 = 查了没有需确认的户） | +| unmetHouseholds | Array | 不满足的户，按 orderId 升序；全满足或未做逐户预检时为空数组 | +| unmetHouseholds[].orderId | String | 子订单 id（字符串） | +| unmetHouseholds[].orderNo | String | 子订单号 | +| unmetHouseholds[].orderStatus | String | `PENDING_PAY` / `CUSTOMIZING` | +| unmetHouseholds[].items | Array | 该户未满足项，顺序同 589556 | +| unmetHouseholds[].items[].code | String | 见「六.5、枚举」 | +| unmetHouseholds[].items[].text | String | 文案，与 589556 里的逐字相同 | +| gateMessage | String | 此刻点确认会拿到的 589556 `message`（逐字相同）；`ready=true` 或 `statusConfirmable=false` 时为 null | + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/2097250563497385985/confirm-check HTTP/1.1 +Host: api.test.1814.love +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "groupBatchId": "2097250563497385985", + "batchStatus": "RESOURCE_PREPARING", + "batchStatusName": "资源准备中", + "ready": false, + "statusConfirmable": true, + "batchItems": [ + { "code": "HOTEL_READY", "name": "房", "passed": true, "unmetText": null }, + { "code": "VEHICLE_READY", "name": "车", "passed": true, "unmetText": null }, + { "code": "GUIDE_READY", "name": "导游领队", "passed": true, "unmetText": null }, + { "code": "PHOTOGRAPHER_READY", "name": "摄影", "passed": true, "unmetText": null }, + { "code": "MATERIAL_CONFIRMED", "name": "物资", "passed": false, "unmetText": "物资未确认" } + ], + "checkedHouseholdCount": 3, + "unmetHouseholds": [ + { + "orderId": "2097260000000000001", + "orderNo": "GT-26-0085", + "orderStatus": "CUSTOMIZING", + "items": [ + { "code": "PAYMENT_OK", "text": "未付订金" }, + { "code": "PRIMARY_REPORTER_MISSING", "text": "未指定主报账人" } + ] + } + ], + "gateMessage": "团期尚不满足确认条件：物资未确认；订单 GT-26-0085：未付订金、未指定主报账人" + } +} +``` + +#### 空数据 / 降级响应 + +全部满足：`ready=true`，`unmetHouseholds=[]`，`gateMessage=null`。不在配置节点（如招募中、已确认）：`statusConfirmable=false`、`ready=false`、`checkedHouseholdCount=null`、`unmetHouseholds=[]`、`gateMessage=null`，`batchItems` 照常返回五项。 + +```json +{ + "code": 200, + "success": true, + "data": { + "groupBatchId": "2097250563497385985", + "batchStatus": "MATERIAL_PREPARING", + "batchStatusName": "物料准备中", + "ready": false, + "statusConfirmable": false, + "batchItems": [ + { "code": "HOTEL_READY", "name": "房", "passed": true, "unmetText": null }, + { "code": "VEHICLE_READY", "name": "车", "passed": true, "unmetText": null }, + { "code": "GUIDE_READY", "name": "导游领队", "passed": true, "unmetText": null }, + { "code": "PHOTOGRAPHER_READY", "name": "摄影", "passed": true, "unmetText": null }, + { "code": "MATERIAL_CONFIRMED", "name": "物资", "passed": true, "unmetText": null } + ], + "checkedHouseholdCount": null, + "unmetHouseholds": [], + "gateMessage": null + } +} +``` + +#### 错误响应 + +团期不存在： + +```json +{ "code": 589500, "message": "团期不存在", "success": false, "data": null } +``` + +无权限（角色未授 `group-batch:confirm`）： + +```json +{ + "code": 589507, + "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- 权限码 `group-batch:confirm`，与确认写口同码（授 `GROUP_BATCH_MANAGER` / `ADMIN`）；看不到「确认」按钮的角色不需要调本端点。 +- 判据与 `POST .../confirm` 同源：同一阶段判断、同一张五项表、同一套逐户判据、同一个 589556 构造；`gateMessage` 就是那条异常的 message。 +- 预检只是预检：点确认时写口按当时数据重判一遍，两次调用之间数据变了以写口为准。 +- 主报账人按「确认时会先补齐团期人员副本」投影：团期层已设主报账人、订单层副本滞后的户，预检不报「未指定主报账人」（点确认时写口会先补齐再判）。 +- 零写入：不补齐副本、不写时间线、不改状态、不发事件。 +- 逐户预检的开销与点一次确认相当（每户读一次确认清单），不要轮询调用。 + +--- + +## 四、契约约束与正确调用方式 + +### ✅ 正确 / ❌ 错误调用顺序 + +| 场景 | 调用 | +|------|------| +| ✅ 置灰「确认」按钮 | 进入配置节点 → `GET confirm-check` → 按 `ready` 置灰 | +| ✅ 点「确认」 | `GET confirm-check`（`ready=true`）→ `POST confirm` | +| ❌ 只用详情的五个标记位判断能否确认 | 漏掉逐户预检，点下去仍可能 589556 | +| ❌ 自己拼 589556 文案 | 直接用 `gateMessage` 或 `batchItems[].unmetText` / `items[].text` | + +### ready 与 statusConfirmable + +`statusConfirmable=false` 表示「不在能确认的节点」（按钮不该出现或应置灰且不提示缺项）；`statusConfirmable=true` 且 `ready=false` 表示「在配置节点但还有缺项」（置灰并展示缺项）。 + +--- + +## 六、边界行为 + +- 未登录 → 401（网关拦截）。 +- 团期不存在 → 589500；无权限 → 589507（不进业务逻辑）。 +- 在团户里已是待出行 / 出行中 / 已完成的户不参与逐户预检（与写口一致）；已取消户不在「在团」口径内。 +- 库里若出现认不出的团期状态值，预检返回 `statusConfirmable=false`；确认写口同步改为返回 589501（此前是 500）。正常数据不可达。 + +--- + +## 六.5、枚举 / 数据字典 + +### 团期级五项（batchItems[].code） + +**所属字段**: `batchItems[].code` | **类型**: `String` + +| 值 | 中文 | 未通过文案 | +|----|------|------------| +| `HOTEL_READY` | 房 | 房未配齐 | +| `VEHICLE_READY` | 车 | 车未配齐 | +| `GUIDE_READY` | 导游领队 | 导游领队未配齐 | +| `PHOTOGRAPHER_READY` | 摄影 | 摄影未配齐 | +| `MATERIAL_CONFIRMED` | 物资 | 物资未确认 | + +### 逐户未满足项（unmetHouseholds[].items[].code） + +**所属字段**: `unmetHouseholds[].items[].code` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `PENDING_PAY` | 待支付（须先付订金或取消） | 订单仍是待支付；此时不再重复列 `PAYMENT_OK` | +| `PAYMENT_OK` | 未付订金 | 团期口径付订金即可（沿用单户确认清单编码） | +| `TRAVELER_COMPLETE` | 出行人信息 | 文案取单户确认清单的失败原因 | +| `HOTEL_DONE` | 房型安排 | 同上 | +| `VEHICLE_DONE` | 用车安排 | 同上 | +| `CONTRACT_TEMPLATE_OK` | 合同方案配置 | 同上 | +| `PRIMARY_REPORTER_MISSING` | 未指定主报账人 | 按「确认时先补齐副本」投影后仍无主报账人 | + +--- + +## 七、不影响范围 + +- **仅影响**: 新增一个只读端点。 +- **零影响**: + - `POST .../confirm` 的入参、出参、错误码与门条件（内部改为与预检共用判据；唯一可观察差异是库里出现非法状态值时由 500 改 589501，正常数据不可达） + - 团期详情、需求确认预检、订房确认预检 + - 小程序端 +- 零数据库变更、零配置变更、零权限种子变更（复用 #8268 的 `group-batch:confirm`）。 + +--- + +## 八、测试环境已验证 + +部署：hl-order-service-v3 = dev-v3 @ ecc92b95c（2026-09-27 10:22）；取证时 TEST 检出为 dev-v3 @ 57199b539（含 ecc92b95c），经网关 `https://api.test.1814.love` 真实鉴权实测（2026-09-27 10:45–10:56），order-v3 取证期间未被重部署；工单 #8410 已验收关单。 + +| # | 场景 | 结果 | +|---|---|---| +| 1 | ADMIN / GROUP_BATCH_MANAGER / SUPER_ADMIN 调 confirm-check | 200 | +| 2 | CUSTOMIZER 调 confirm-check | 589507，前后三表无写入 | +| 3 | 不存在的团期 / 不带 token | 589500 / 401 | +| 4 | RESOURCE_PREPARING 团期（房 / 车 / 物资未过，12 户定制中） | `batchItems` 五项顺序正确，与详情五个布尔、库值三方一致；`checkedHouseholdCount=12`，12 户逐户列出（TRAVELER_COMPLETE / HOTEL_DONE / VEHICLE_DONE / PRIMARY_REPORTER_MISSING） | +| 5 | 同一团期调 `POST .../confirm` 对照 | 589556，`message` 与预检 `gateMessage` 逐字相同（914 字）；确认被拒无写入 | +| 6 | 团期层临时设主报账人、订单层副本滞后（NONE） | 预检不再报「未指定主报账人」（按确认时先补齐副本投影），预检不补齐副本；还原后恢复原状 | +| 7 | 订单层副本是 PRIMARY 但团期层为 NONE（将被补齐降级） | 预检仍报「未指定主报账人」，预检不改该行；还原后恢复原状 | +| 8 | 连续四次调预检 | `order_group_batch` / `group_batch_status_log` / `order_staff_assignment` / 子订单状态逐字段无变化 | +| 9 | RECRUITING / MATERIAL_PREPARING / CANCELLED 团期 | `statusConfirmable=false`、`ready=false`、`checkedHouseholdCount=null`、`unmetHouseholds=[]`、`gateMessage=null`，五项照返 | + +--- + +## 九、相关历史 PR + +| PR | Issue | 说明 | 是否仍有效 | +|----|-------|------|------------| +| #8302 | #8268 | 团期人工确认写口（五项门、589556） | ✅ | +| #8346 / #8349 | #8339 | 确认门逐户预检、确认前补齐人员副本 | ✅（本端点投影的就是这次补齐） | +| — | #7210 | 需求确认预检 `requirement/confirm-check`（同形先例） | ✅ | +| **本 PR #8411** | **#8410** | 团期确认只读预检 | ✅ 最新 | + +--- + +## 十、相关文档 + +- 关联 Issue: [wx/HL#8410](https://git.1814.love/wx/HL/issues/8410) +- 关联 PR: [wx/HL#8411](https://git.1814.love/wx/HL/pulls/8411) +- 写口条目：`24_8268_团期人工确认端点与确认后才出合同保险-新增接口-管理后台.md` + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#8410](https://git.1814.love/wx/HL/issues/8410) +- **PR**: [#8411](https://git.1814.love/wx/HL/pulls/8411) +- **Merge commit**: [ecc92b95c](https://git.1814.love/wx/HL/commit/ecc92b95ca2cc9c5801f2cfab5f29456f0419875) + +### 联系人 + +- **后端负责人**: @jw