678 行
26 KiB
Markdown
678 行
26 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8268"
|
||
title: "团期人工「确认」：新增确认端点（配置 → 确认），确认后才出合同保险并全团逐户补发；确认物资前移到配置节点；物料门复判端点下线"
|
||
consumer: "admin"
|
||
author: "jw(GIT)"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "72b5e17cada78a8f491f9dc1cb6af3d9e42ab457"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-24"
|
||
status_note: "六节点定案（SRS §0.27.3 / §0.27.5 #2～#5）：「配置 → 确认」由系统自动推进改为人工点「确认」。新增 POST /v3/admin/order/group-batch/{groupBatchId}/confirm（权限码 group-batch:confirm，授 GROUP_BATCH_MANAGER / ADMIN），门 = 房 / 车 / 导游领队 / 摄影四项 ready 全 true 且物资已确认，不满足返新码 589556 并逐项列出未满足项，状态不是 RESOURCE_PREPARING（含重复确认）返 589501；成功后团期进入 MATERIAL_PREPARING、时间线记 BATCH_CONFIRM（确认），事务提交后系统对全团已确认行程的户逐户补发合同与保险。四项 ready 翻真 / 成团 / 免车不再自动推进状态。连带改动：confirm-material 只在 RESOURCE_PREPARING 可调且不再顺带准入待出发（其它状态 589501）；合同保险出具门改为团期已确认（MATERIAL_PREPARING 及之后），确认前手动出具返 589548，文案改为「团期确认后才能出具合同与保险」，合同保险面板 issuable 同口径；POST .../recheck-material-gate 下线（589561 不再抛出）。前端需新增「确认」按钮与 589556 逐项提示、把确认物资按钮挪到配置节点、移除物料门复判入口。 前端已交付并验证：团期详情工具条新增平铺 primary「确认」按钮（仅 RESOURCE_PREPARING，不可撤销二次确认弹窗，589556 逐项清单透 message）；确认物资按钮可调状态翻转为仅 RESOURCE_PREPARING，成功文案引导点「确认」；合同保险 issueTip 改「团期确认后才能出具合同与保险」（issuable 仍直读面板）；recheck-material-gate 前端零调用零删除。SuppliesPanel 13 例+ChipStaffDisplay 5 例+index 7 例全绿，hl-admin@72b5e17c（+8da805a4 回归锁）。"
|
||
updated_at: "2026-09-24"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 团期状态流转: 人工「确认」取代自动推进，确认后才出合同保险（管理后台）
|
||
|
||
> **服务**: hl-order-service-v3（端口 8086/8186）；权限种子在 hl-user-service
|
||
> **PR**: #8302
|
||
> **Issue**: #8268
|
||
> **日期**: 2026-09-24
|
||
> **影响范围**: 管理后台团期详情页的「确认」按钮（新增）、「确认物资」按钮、「合同保险」页签的出具按钮与可出具提示；原「复判物料门」入口下线
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
1. **团期不会再自己从「资源准备中」走到「物料准备中」**。改前四项 ready 齐 + 合同保险出齐时系统自动推进；现在必须由团期管理员点「确认」（新端点）。
|
||
2. **合同 / 保险在确认前一律不出**。改前资源准备中四项配齐即可出具；现在确认前手动出具被 589548 拒，面板 `issuable=false`。确认后系统自动给全团已确认行程的户逐户补发。
|
||
3. **确认物资挪到确认之前**。`confirm-material` 以前只在物料准备中可调、还会顺带尝试进入待出发；现在只在资源准备中可调，且只置物资已确认，不改团期状态。
|
||
4. **`recheck-material-gate` 端点已删除**，调用会得到 404。
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
六节点定案里「配置 → 确认」是一个**不可撤销的人工动作**：确认之后四项配置与物资锁定（锁定写口见 #8269 条目），系统随即对客出合同与保险。因此它不能再由系统在 ready 位翻真时悄悄推进，也需要独立于 `group-batch:manage` 的授权。
|
||
|
||
| 节点 | 持久态 | 本单之后怎么进入 |
|
||
|---|---|---|
|
||
| 配置 | `RESOURCE_PREPARING` | 成团（不变） |
|
||
| 确认 | `MATERIAL_PREPARING` | **仅**人工调用确认端点 |
|
||
| 出行·待出发 | `PENDING_DEPARTURE` | 七项硬门（不变） |
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 团期确认 | POST | `/v3/admin/order/group-batch/{groupBatchId}/confirm` | 新增接口 | 配置 → 确认；门不满足 589556 逐项回执 |
|
||
| 2 | 确认团期物资 | POST | `/v3/admin/order/group-batch/{groupBatchId}/confirm-material` | 修改（可调状态 + 行为） | 只在 `RESOURCE_PREPARING` 可调；不再顺带准入待出发 |
|
||
| 3 | 手工复判物料门 | POST | `/v3/admin/order/group-batch/{groupBatchId}/recheck-material-gate` | 删除接口 | 自动推进已删，复判入口随之下线 |
|
||
| 4 | 手动开合同 / 保险（GB-ADM-031） | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/issue` | 修改（前置门 + 文案） | 确认前 589548，文案改 |
|
||
| 5 | 作废重开合同 / 保险（GB-ADM-031） | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/reissue` | 修改（前置门 + 文案） | 同上 |
|
||
| 6 | 合同保险面板（GB-ADM-030） | GET | `/v3/admin/order/group-batch/{groupBatchId}/contracts` | 修改（出参语义） | `issuable` 改为「团期已确认」 |
|
||
|
||
网关无改动（均在既有 `/v3/admin/order/group-batch` 前缀下）。
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 团期确认 `POST /v3/admin/order/group-batch/{groupBatchId}/confirm`
|
||
|
||
**VO**: `Result<Void>`（无请求体）
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页「配置」节点的「确认」按钮。房、车、导游领队、摄影四项配齐且物资已确认后，团期管理员点确认，团期进入「确认」节点，配置锁定，系统开始逐户出合同与保险。**没有撤销确认。**
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | 不存在返 589500 |
|
||
|
||
无请求体。
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | Void | 成功返回 null；团期状态已是 `MATERIAL_PREPARING`，重新拉详情即可看到 `stage=CONFIRM` |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/2097250563497385985/confirm HTTP/1.1
|
||
Host: api.test.1814.love:9443
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": null,
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
本接口无列表出参。确认成功后的逐户补发合同保险是**异步**的：确认接口立即返回 200，补发结果在「合同保险」页签逐户可见；单户出具失败不影响确认结果，也不影响其余户，可在该页签手动开（GB-ADM-031）补出。
|
||
|
||
```json
|
||
{ "code": 200, "data": null, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
确认门不满足（逐项列出，顺序固定为 房、车、导游领队、摄影、物资）：
|
||
|
||
```json
|
||
{
|
||
"code": 589556,
|
||
"message": "团期尚不满足确认条件：车未配齐、物资未确认",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
状态不是「配置」（含已确认后再点一次）：
|
||
|
||
```json
|
||
{
|
||
"code": 589501,
|
||
"message": "团期状态不允许当前操作",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
无权限（角色未授 `group-batch:confirm`）：
|
||
|
||
```json
|
||
{
|
||
"code": 589507,
|
||
"message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 权限码 `group-batch:confirm`，授给 `GROUP_BATCH_MANAGER` 与 `ADMIN`；其余角色 589507。与 `group-batch:manage` 分开授权。
|
||
- 判定顺序：团期存在（589500）→ 状态为 `RESOURCE_PREPARING`（589501）→ 确认门（589556）→ CAS 推进。任一步拒绝**零写入**。
|
||
- 589556 的未满足项取值只有五种：`房未配齐`、`车未配齐`、`导游领队未配齐`、`摄影未配齐`、`物资未确认`，以「、」连接。
|
||
- 不需要导游 / 摄影的团、整团免车的团，其 ready 位已由成团免闸 / 免车写口置真，确认时不会被这几项挡住。
|
||
- 并发确认只有一个成功，其余 589501；重复确认不会重复推进。
|
||
- 成功后时间线新增一条 `eventType=BATCH_CONFIRM`、`eventTypeName=确认`，带操作人。
|
||
- 补发只处理子订单状态为待出发 / 出行中（已确认行程）的户；尚未确认行程的户跳过，等其确认行程时由既有自动出具链路出；已出具的户逐项跳过；已取消户不出。
|
||
|
||
---
|
||
|
||
### 2. 确认团期物资 `POST /v3/admin/order/group-batch/{groupBatchId}/confirm-material`
|
||
|
||
**VO**: `Result<Void>`（无请求体）
|
||
|
||
#### 使用场景
|
||
|
||
「物资」页签的「确认物资」按钮。本次起它是团期确认的前置条件之一，在「配置」节点点。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | 不存在返 589500 |
|
||
|
||
无请求体。
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | Void | 成功返回 null；团期状态**不变**，物资已确认标记置真 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/2097250563497385985/confirm-material HTTP/1.1
|
||
Host: api.test.1814.love:9443
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": null,
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无列表出参。确认前物资可反复增删改、反复确认，每次确认都在时间线记一条「确认物资」流水（内容「确认物资清单」）。
|
||
|
||
```json
|
||
{ "code": 200, "data": null, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期不在 `RESOURCE_PREPARING`（含招募中、已确认及之后）：
|
||
|
||
```json
|
||
{
|
||
"code": 589501,
|
||
"message": "团期状态不允许当前操作",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 权限码 `group-batch:manage`（不变）。
|
||
- **只在 `RESOURCE_PREPARING` 可调**；改前只在 `MATERIAL_PREPARING` 可调，两者正好相反。
|
||
- **不再推进团期状态**：改前确认物资后会顺带尝试进入待出发；现在进入待出发改由子订单确认、定时扫描与「复判待出发硬门」端点负责，七项硬门本身不变。
|
||
- 取消成团会把物资已确认标记重置（不变）。
|
||
|
||
---
|
||
|
||
### 3. 手工复判物料门 `POST /v3/admin/order/group-batch/{groupBatchId}/recheck-material-gate`
|
||
|
||
**VO**: `GroupBatchMaterialGateRespVO`（已删除）
|
||
|
||
#### 使用场景
|
||
|
||
**已下线。** 该端点原用于在「资源准备中 → 物料准备中」自动推进卡住时手工复判。自动推进已删除，这一跳只剩人工确认一条路，复判入口不再有意义。请改用新端点 `POST .../confirm`。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | - | 端点已删除 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| advanced | Boolean | 已删除（原：是否推进了团期） |
|
||
| currentStatus / currentStatusName | String | 已删除 |
|
||
| blockedGate / blockedOrderId / blockedReason | String / Long / String | 已删除 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/2097250563497385985/recheck-material-gate HTTP/1.1
|
||
Host: api.test.1814.love:9443
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
路由已不存在，经网关调用返回业务信封 `code=404`（TEST 2026-09-24 实测）：
|
||
|
||
```json
|
||
{ "code": 404, "msg": "接口不存在: POST /v3/admin/order/group-batch/2102932276390383618/recheck-material-gate" }
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无。端点不存在，不会返回任何业务数据。
|
||
|
||
#### 错误响应
|
||
|
||
任何调用都返回 `code=404`「接口不存在」（同上）：
|
||
|
||
```json
|
||
{ "code": 404, "msg": "接口不存在: POST /v3/admin/order/group-batch/2102932276390383618/recheck-material-gate" }
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 原错误码 589561「团期当前状态为「{0}」，不在「资源准备中」，无需复判物料门」不再抛出，仅保留占位防号段复用。
|
||
- 前端所有调用点与按钮需移除；替代动作是「确认」。
|
||
|
||
---
|
||
|
||
### 4. 手动开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue`
|
||
|
||
**VO**: `GroupBatchContractIssueReqVO` → `GroupBatchIssueResultVO`
|
||
|
||
#### 使用场景
|
||
|
||
「合同保险」页签逐户开合同 / 保险。本次只改前置门与拒绝文案，入参出参结构不变。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | - |
|
||
| orderIds | Body | List<Long> | 否 | - | 为空 = 本期全部尚未出具的户 |
|
||
| target | Body | String | ✅ | `CONTRACT` / `INSURANCE` / `BOTH` | 出具目标 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalCount | Integer | 本次处理户数 |
|
||
| successCount | Integer | 成功户数 |
|
||
| failCount | Integer | 失败户数 |
|
||
| skipCount | Integer | 跳过户数（已出具 / 已签等） |
|
||
| results[].orderId | String | 子订单 ID |
|
||
| results[].target | String | `CONTRACT` / `INSURANCE` |
|
||
| results[].outcome | String | `SUCCESS` / `SKIPPED` / `FAILED` |
|
||
| results[].message | String | 失败或跳过原因 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{ "orderIds": ["770145"], "target": "CONTRACT" }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 1,
|
||
"successCount": 1,
|
||
"failCount": 0,
|
||
"skipCount": 0,
|
||
"results": [
|
||
{ "orderId": "770145", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
已出具的户逐项 `SKIPPED`，不算失败；单户失败只记在 `results` 里，不影响其余户（不变）。
|
||
|
||
```json
|
||
{ "code": 200, "data": { "totalCount": 1, "successCount": 0, "failCount": 0, "skipCount": 1, "results": [ { "orderId": "770145", "target": "CONTRACT", "outcome": "SKIPPED", "message": "该户合同已出具，自动跳过" } ] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期尚未确认（`RECRUITING` / `RESOURCE_PREPARING`，即便四项已配齐）：
|
||
|
||
```json
|
||
{
|
||
"code": 589548,
|
||
"message": "团期确认后才能出具合同与保险",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 权限码 `group-batch:contract:issue`（不变）。
|
||
- 可出具的团期状态：`MATERIAL_PREPARING` / `PENDING_DEPARTURE` / `TRAVELLING` / `REVIEWING` / `SETTLED`；其余一律 589548，整单拒绝、零写入。
|
||
- 改前 `RESOURCE_PREPARING` 且四项 ready 全真时可出具，本次起不可。
|
||
|
||
---
|
||
|
||
### 5. 作废重开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/reissue`
|
||
|
||
**VO**: `GroupBatchContractIssueReqVO` → `GroupBatchIssueResultVO`
|
||
|
||
#### 使用场景
|
||
|
||
「开错」态的补救通路：先作废该户现有单据再重开。前置门与手动开完全一致。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | - |
|
||
| orderIds | Body | List<Long> | 否 | - | 为空 = 本期全部户 |
|
||
| target | Body | String | ✅ | `CONTRACT` / `INSURANCE` / `BOTH` | 重开目标 |
|
||
| reason | Body | String | 否 | - | 作废原因 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalCount / successCount / failCount / skipCount | Integer | 同手动开 |
|
||
| results[] | List | 逐户结果，同手动开 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{ "orderIds": ["770145"], "target": "CONTRACT", "reason": "方案选错" }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 1,
|
||
"successCount": 1,
|
||
"failCount": 0,
|
||
"skipCount": 0,
|
||
"results": [
|
||
{ "orderId": "770145", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
作废失败的户直接记 `FAILED`，不进重开，不影响其他户（不变）。
|
||
|
||
```json
|
||
{ "code": 200, "data": { "totalCount": 1, "successCount": 0, "failCount": 1, "skipCount": 0, "results": [ { "orderId": "770145", "target": "CONTRACT", "outcome": "FAILED", "message": "作废失败" } ] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 589548,
|
||
"message": "团期确认后才能出具合同与保险",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 与手动开共用同一出具门与同一文案。
|
||
- 确认前没有任何已出具的单据可重开，调用即 589548。
|
||
|
||
---
|
||
|
||
### 6. 合同保险面板 `GET /v3/admin/order/group-batch/{groupBatchId}/contracts`
|
||
|
||
**VO**: `GroupBatchContractBoardVO`
|
||
|
||
#### 使用场景
|
||
|
||
「合同保险」页签首屏：顶部三格统计 + 逐户卡片；`issuable` 决定出具按钮是否可点。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | - |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| issuable | Boolean | **语义改变**：= 团期已人工确认（`MATERIAL_PREPARING` 及之后的可出具状态）；改前 = 四项配齐 |
|
||
| batchStatus | String | 团期状态存储值，`issuable=false` 时可据此提示（不变） |
|
||
| totalCount / contractIssuedCount / contractSignedCount / insuranceIssuedCount | Integer | 不变 |
|
||
| items | List | 逐户明细（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/2097250563497385985/contracts HTTP/1.1
|
||
Host: api.test.1814.love:9443
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"groupBatchId": "2097250563497385985",
|
||
"issuable": false,
|
||
"batchStatus": "RESOURCE_PREPARING",
|
||
"totalCount": 3,
|
||
"contractIssuedCount": 0,
|
||
"contractSignedCount": 0,
|
||
"insuranceIssuedCount": 0,
|
||
"items": []
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无活跃子订单时 `totalCount=0`、`items` 为空数组（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "data": { "issuable": false, "batchStatus": "RESOURCE_PREPARING", "totalCount": 0, "items": [] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 589500,
|
||
"message": "团期不存在",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- `RESOURCE_PREPARING` 且四项已配齐时，改前 `issuable=true`，现在 `false`；提示文案建议为「团期确认后才能出具合同与保险」。
|
||
- 其余字段口径不变。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
### ✅ 正确 / ❌ 错误调用顺序
|
||
|
||
| 场景 | 调用 |
|
||
|------|------|
|
||
| ✅ 配置节点收尾 | 配房 / 车 / 导摄 → `confirm-material` → `confirm` |
|
||
| ❌ 先确认团期再确认物资 | `confirm` → 589556「…物资未确认」；确认后再调 `confirm-material` → 589501 |
|
||
| ❌ 确认前出具合同 | `contracts/issue`（`RESOURCE_PREPARING`）→ 589548 |
|
||
| ❌ 继续调复判物料门 | `recheck-material-gate` → 404 |
|
||
|
||
### 589556 的处理
|
||
|
||
message 的冒号之后就是未满足项清单，可直接展示给操作人；不要再去调已下线的复判端点找原因。
|
||
|
||
---
|
||
|
||
## 五、数据库行为
|
||
|
||
| 前端动作 | 外部可观察的写入 |
|
||
|----------|------------------|
|
||
| `confirm` 成功 | 团期状态 `RESOURCE_PREPARING → MATERIAL_PREPARING`（CAS，一次）+ 时间线一条「确认」（含操作人）；提交后异步逐户生成合同 / 保单 |
|
||
| `confirm` 被拒（589501 / 589556 / 589507） | 零写入 |
|
||
| `confirm-material` 成功 | 物资已确认标记置真 + 时间线一条「确认物资」；团期状态不变 |
|
||
| `confirm-material` 被拒 | 零写入 |
|
||
| `contracts/issue` / `reissue` 被 589548 拒 | 零写入 |
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录 → 401（网关拦截）。
|
||
- 团期不存在 → 589500。
|
||
- 四项 ready 翻真、成团、整团免车**都不会再推进团期状态**；团期会停在「配置」直到有人点确认。
|
||
- 确认后补发是异步的，确认接口不等补发完成；补发整轮失败（如团期被并发流团）只影响出具，不回滚确认，可在「合同保险」页签手动补出。
|
||
- 进入待出发的七项硬门不变。
|
||
|
||
---
|
||
|
||
## 六.5、枚举 / 数据字典
|
||
|
||
### 589556 未满足项（GroupBatchService.unmetConfirmConditions）
|
||
|
||
**所属字段**: 错误 `message` 冒号后的清单 | **类型**: `String`（「、」分隔）
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `房未配齐` | 房 | 团期配房完成标志为假 |
|
||
| `车未配齐` | 车 | 团期配车完成标志为假（整团免车时为真） |
|
||
| `导游领队未配齐` | 导游领队 | 不需要导游的团成团时已置真 |
|
||
| `摄影未配齐` | 摄影 | 不需要摄影的团成团时已置真 |
|
||
| `物资未确认` | 物资 | 未调用 `confirm-material` |
|
||
|
||
### 时间线事件（GroupBatchLogEventType，新增一值）
|
||
|
||
**所属字段**: 团期状态流水 `eventType` / `eventTypeName` | **类型**: `String`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `BATCH_CONFIRM` | 确认 | 本次新增；人工确认时写入，`fromStatus=RESOURCE_PREPARING`、`toStatus=MATERIAL_PREPARING` |
|
||
| `BATCH_RESOURCE_READY` | 资源就绪·进物资准备 | 原自动推进事件，本次起不再写入；历史行照常显示 |
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 合同保险面板 `issuable` | 四项配齐（或已进物料准备中）即 true | 团期已确认（物料准备中及之后）才 true |
|
||
| 589548 message | 房/车/导/摄四项配齐后才能出具合同与保险 | 团期确认后才能出具合同与保险 |
|
||
| 589556 | 无 | 新增：团期尚不满足确认条件：{0} |
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 资源准备中 → 物料准备中 | 四项 ready + 逐户合同已签、保险已出 → 系统自动推进 | 只能人工 `confirm`，门 = 四项 ready + 物资已确认 |
|
||
| 确认物资可调状态 | `MATERIAL_PREPARING` | `RESOURCE_PREPARING` |
|
||
| 确认物资的副作用 | 顺带尝试进入待出发 | 不改团期状态 |
|
||
| 合同保险出具时机 | 资源准备中四项配齐即可 | 确认后；确认时对已确认行程的户自动补发 |
|
||
| 复判物料门端点 | 可用 | 删除（404） |
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **是否破坏向后兼容**: 是。复判端点删除；确认物资的可调状态翻转；确认前不能出合同保险。
|
||
- **前端是否必须同步上线**: 是。缺少「确认」按钮时，新成团的团期会一直停在「配置」节点。
|
||
- **前端 workaround 清理点**: 移除「复判物料门」入口及其结果弹窗；「确认物资」按钮的显示条件由物料准备中改为资源准备中；合同保险页签按 `issuable` 置灰的提示文案改为「团期确认后才能出具合同与保险」。
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- **仅影响**: 团期「配置 → 确认」这一跳、确认物资、合同保险出具门。
|
||
- **零影响**:
|
||
- 成团、取消成团、流团的入参与出参
|
||
- 进入待出发的七项硬门与「复判待出发硬门」端点
|
||
- 子订单确认行程后的逐户自动出具链路（团期已确认时照常出）
|
||
- 小程序端
|
||
- 另：内部定时任务端点 `/v3/internal/jobs/group-batch-material-gate/run` 与其定时任务同批下线，属服务间内部接口，管理后台不调用。
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
部署：hl-user-service + hl-order-service-v3 = dev-v3 @ d9fdd7fe0（2026-09-24 09:18 / 09:20），经网关 `https://api.test.1814.love` 真实鉴权实测（2026-09-24 09:22–09:45）；工单 #8268 已验收关单。
|
||
|
||
| # | 场景 | 结果 |
|
||
|---|---|---|
|
||
| 1 | 四项 ready + 物资已确认，GROUP_BATCH_MANAGER 调 `POST /confirm` | 200，RESOURCE_PREPARING → MATERIAL_PREPARING，时间线 `BATCH_CONFIRM`（含操作人） |
|
||
| 2 | 门不满足调 confirm | 589556「团期尚不满足确认条件：房未配齐、车未配齐、摄影未配齐、物资未确认」，状态不变 |
|
||
| 3 | 招募中 / 已确认后重复调 confirm | 589501，不推进 |
|
||
| 4 | ROOM_MANAGER / VEHICLE_MANAGER / CUSTOMIZER / FINANCE 调 confirm | 589507；Flyway `20260923.268` 已执行，仅授 ADMIN 与 GROUP_BATCH_MANAGER |
|
||
| 5 | 成团及四项依次翻真 | 不再自动推进，停在 RESOURCE_PREPARING 直到人工确认 |
|
||
| 6 | 确认前户确认行程 / 手动出具 | 不自动出具；`GET /contracts` 的 `issuable=false`；手动出具 589548「团期确认后才能出具合同与保险」 |
|
||
| 7 | 确认后全团补发 | `total=6 success=4 skipped=2 failed=0`：已确认行程两户合同 GENERATED + 保险 INSURED；已取消户、未确认行程户不出；再次出具返回 SKIPPED |
|
||
| 8 | 配置阶段 / 确认后调 `confirm-material` | 200（`material_confirmed=1`）/ 589501 |
|
||
| 9 | 旧 `recheck-material-gate` 与内部 job 端点 | `code=404`「接口不存在」；sys_job 与 QRTZ 均无 1044 |
|
||
| 10 | 合同签齐 + 七门满足后复检 | 进入 PENDING_DEPARTURE（签署以 SQL 模拟） |
|
||
|
||
---
|
||
|
||
## 九、相关历史 PR
|
||
|
||
| PR | Issue | 说明 | 是否仍有效 |
|
||
|----|-------|------|------------|
|
||
| — | #7105 | 合同保险出具门（四项配齐，589548） | ❌ 门条件被本单替换，码值保留 |
|
||
| — | #7526 | 物料门兜底复判（端点 + 定时任务） | ❌ 本单下线 |
|
||
| — | #7528 | 确认物资后顺带准入待出发 | ❌ 本单删除该顺带准入 |
|
||
| **本 PR #8302** | **#8268** | 人工确认 + 确认后出合同保险 | ✅ 最新 |
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#8268](https://git.1814.love/wx/HL/issues/8268)
|
||
- 关联 PR: [wx/HL#8302](https://git.1814.love/wx/HL/pulls/8302)
|
||
- 同批六节点条目：确认后锁定配置（#8269）、六节点展示与看板七桶（#8271）
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8268](https://git.1814.love/wx/HL/issues/8268)
|
||
- **PR**: [#8302](https://git.1814.love/wx/HL/pulls/8302)
|
||
- **Merge commit**: [d9fdd7fe0](https://git.1814.love/wx/HL/commit/d9fdd7fe038952ac3ffdd31913dfcc4a2fc40574)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @jw
|