819 行
32 KiB
Markdown
819 行
32 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8339"
|
||
title: "团期人工确认联动子订单确认行程：确认门加逐户预检（589556 逐户列订单号 + 未满足项）；团期单在团期确认前单户确认行程返新码 581065；时间线新增 BATCH_SUB_ORDER_CONFIRM_FAILED；合同保险出具门补出行完毕"
|
||
consumer: "admin"
|
||
author: "jw(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "65ce203dc20e5b475d52ce6797ec1b069f52cfff"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-24"
|
||
status_note: "六节点定案（SRS §0.27.7）：团期人工确认时，团期单子订单一并确认行程（定制中 → 待出行），团期单不再允许单户自行确认，合同保险只由逐户确认链路出具。POST /v3/admin/order/group-batch/{groupBatchId}/confirm 的确认门在四项 ready + 物资已确认之外加逐户预检（待支付 / 定制中的活跃户须已付订金、出行人齐全且有成人手机号、户级房车完成、合同模板已设、有主报账人），不满足仍返 589556，message 由「、」连接的团期级清单改为「；」分段：首段团期级未满足项（有才出现），其后每户一段「订单 {订单号}：{未满足项}」；确认成功后事务提交后系统异步逐户确认行程，合同保险由逐户链路出具（#8268 的确认后全团补发下线），单户失败不回滚团期确认，写团期时间线新事件 BATCH_SUB_ORDER_CONFIRM_FAILED（extra 带 orderId / orderNo / reason）。POST /v3/admin/order/{id}/confirm-itinerary 与 POST /v3/admin/order/{id}/transition（eventCode=CONFIRM）对团期单在团期确认前返新码 581065「团期单随团期确认，不可单独确认」，团期确认后仍在定制中的户放行作补确认，散客单不受影响。合同保险出具门可出具状态集补 TRIP_FINISHED（出行完毕）：GET .../contracts 的 issuable 在出行完毕为 true，contracts/issue、contracts/reissue 在出行完毕不再返 589548。前端需：589556 按「；」分段逐户展示；团期单订单详情在团期确认前隐藏或置灰「确认行程」并处理 581065；时间线显示新事件（eventTypeName 后端已给）。 前端已交付并验证(hl-admin@65ce203d):订单详情底栏「确认订单」团期单+团期未确认置灰+NTooltip 说明(isGroupConfirmBlocked 共享判据,六态集与合同保险出具门同源,null fail-open/非空未知 fail-closed),openLockConfirmModal 同源防御闸拦旁路入口;团期详情 confirm 文案改逐户确认行程链路,589556 改 silentError+dialog 按「；」分段逐行展示(不按「、」切碎/不解析订单号),其余码直弹 message;StatusLogsPanel 新事件 eventTypeName 直显零改动;contract.js 出具门补 TRIP_FINISHED JSDoc。4 个定向 spec 58 例全绿,新增 #8339 用例 25 例。"
|
||
updated_at: "2026-09-24"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 团期确认: 确认门加逐户预检、子订单随团期确认行程、团期单禁单户确认（管理后台）
|
||
|
||
> **服务**: hl-order-service-v3（端口 8086/8186）
|
||
> **PR**: #8346（主体）、#8349（TEST 验收缺陷修复：主报账人副本补齐、逐户确认失败留痕）
|
||
> **Issue**: #8339
|
||
> **日期**: 2026-09-24
|
||
> **影响范围**: 管理后台团期详情页「确认」按钮的 589556 提示、团期时间线、「合同保险」页签的可出具判断；订单详情页「确认行程」按钮（团期单）
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
1. **团期确认会连带确认子订单行程**。确认成功后，系统在后台逐户把「定制中」的户推到「待出行」，每户的合同与保险随之自动出具；前端不需要再逐户点「确认行程」。
|
||
2. **589556 的 message 格式变了**：由「、」连接的一串，变成「；」分隔的若干段，每个不满足的户一段「订单 {订单号}：{未满足项}」。
|
||
3. **团期单在团期确认前不能单独「确认行程」**：订单详情 `confirm-itinerary` 与通用 `transition`（CONFIRM）返新码 **581065**。团期确认之后仍在定制中的户（逐户确认失败 / 确认后加入的户）可以单户补确认。
|
||
4. **团期时间线新增事件 `BATCH_SUB_ORDER_CONFIRM_FAILED`**（子订单确认行程失败），逐户确认失败时写入，带订单号与原因。
|
||
5. **出行完毕（`TRIP_FINISHED`）也可出具合同保险**：面板 `issuable=true`，手动开 / 重开不再返 589548。
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
#8268 把「配置 → 确认」改成人工确认，但子订单仍需运营逐户点「确认行程」，而合同保险由团期确认后的「全团补发」与逐户确认链路两条路出具，存在并发重复出具风险。SRS §0.27.7 定案：
|
||
|
||
| 项 | 改前 | 改后 |
|
||
|---|---|---|
|
||
| 子订单确认行程 | 运营逐户点 | 团期确认提交后系统逐户确认（每户独立事务，单户失败隔离） |
|
||
| 团期确认门 | 四项 ready + 物资已确认 | 另加逐户预检，任一户不满足整团不可确认 |
|
||
| 合同保险出具 | 确认后全团补发 + 逐户确认链路 | 只剩逐户确认链路 |
|
||
| 团期单单户确认 | 可以 | 团期确认前 581065；确认后可补确认 |
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 团期确认 | POST | `/v3/admin/order/group-batch/{groupBatchId}/confirm` | 修改（门条件 + 错误 message + 副作用） | 逐户预检；589556 逐户列订单号与未满足项；成功后逐户确认行程 |
|
||
| 2 | 确认行程 | POST | `/v3/admin/order/{id}/confirm-itinerary` | 修改（新增错误码） | 团期单在团期确认前 581065 |
|
||
| 3 | 状态变更操作（内部通用） | POST | `/v3/admin/order/{id}/transition` | 修改（新增错误码） | `eventCode=CONFIRM` 与 #2 同一守卫，581065 |
|
||
| 4 | 团期状态流水 | GET | `/v3/admin/order/group-batch/{groupBatchId}/status-logs` | 修改（枚举新增值） | 新事件 `BATCH_SUB_ORDER_CONFIRM_FAILED` |
|
||
| 5 | 合同保险面板（GB-ADM-030） | GET | `/v3/admin/order/group-batch/{groupBatchId}/contracts` | 修改（出参取值） | `issuable` 在 `TRIP_FINISHED` 为 true |
|
||
| 6 | 手动开合同 / 保险（GB-ADM-031） | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/issue` | 修改（前置门放宽） | `TRIP_FINISHED` 不再 589548 |
|
||
| 7 | 作废重开合同 / 保险（GB-ADM-031） | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/reissue` | 修改（前置门放宽） | 同上 |
|
||
|
||
网关无改动（均在既有 `/v3/admin/order` 前缀下）；无新增权限码；无 DB schema 变更。
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 团期确认 `POST /v3/admin/order/group-batch/{groupBatchId}/confirm`
|
||
|
||
**VO**: `Result<Void>`（无请求体）
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页「配置」节点的「确认」按钮。本次起点一次确认 = 团期进入「确认」+ 全团定制中的户确认行程 + 逐户出合同保险。门不满足时，运营从 589556 的 message 里直接看到是哪几户、差什么。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | 不存在返 589500（不变） |
|
||
|
||
无请求体（不变）。
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | Void | 成功返回 null（不变）；团期进入 `MATERIAL_PREPARING`，子订单逐户确认在后台异步进行 |
|
||
|
||
#### 请求示例
|
||
|
||
```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，不等逐户确认完成。逐户确认在团期确认事务提交后异步执行、每户独立事务：
|
||
|
||
- 单户失败（如出具外的副作用异常）不回滚团期确认、不影响其他户，该户留在「定制中」；
|
||
- 失败户写团期时间线 `BATCH_SUB_ORDER_CONFIRM_FAILED`（见接口 4），可在订单详情单户补确认；
|
||
- 已是待出行 / 出行中的户跳过，不重复确认、不重复出具。
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": null, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
门不满足（团期级 + 逐户，「；」分段）：
|
||
|
||
```json
|
||
{
|
||
"code": 589556,
|
||
"message": "团期尚不满足确认条件：物资未确认；订单 HL2609240001：未付订金、未指定主报账人；订单 HL2609240002：未提交用车需求",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
只有逐户不满足时，没有团期级那一段：
|
||
|
||
```json
|
||
{
|
||
"code": 589556,
|
||
"message": "团期尚不满足确认条件：订单 HL2609240003：待支付（须先付订金或取消）",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
状态不是「配置」（含重复确认）：
|
||
|
||
```json
|
||
{
|
||
"code": 589501,
|
||
"message": "团期状态不允许当前操作",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 判定顺序不变：589500 → 589501 → 确认门 589556 → CAS 推进；权限码 `group-batch:confirm`（不变，589507）。
|
||
- 团期级与逐户预检**一并求值、一次列全**，不会改一项点一次。
|
||
- 逐户预检范围：待支付、定制中的活跃户（已取消不在内）；待出行 / 出行中 / 已完成的户跳过。
|
||
- 逐户未满足项（同一户内以「、」连接）：
|
||
- `待支付（须先付订金或取消）`：订单仍在待支付；
|
||
- `未付订金`：付款项未过——团期口径**付订金即可**，`DEPOSIT_PAID` / `FULLY_PAID` 都算满足；
|
||
- 出行人：`未添加出行人` / `出行人信息未完善 {已完成}/{总数}（部分待补全）` / `至少需要一名成人出行人填写手机号用于合同签署`；
|
||
- 户级房：`未提交用房需求` / `用房需求未完成（当前: {状态}）`；
|
||
- 户级车：`未提交用车需求` 或用车清单项给出的原因（整团免车 / 团车完成来源视为满足）；
|
||
- `产品未配置合同方案`；
|
||
- `未指定主报账人`（与单户确认 581062 同一判据）。
|
||
- 预检前系统会按团期人员配置补齐各户的团期人员副本（PR #8349），先设主报账人后下单的户不会再被误报「未指定主报账人」。
|
||
- 团期级未满足项取值不变：`房未配齐` / `车未配齐` / `导游领队未配齐` / `摄影未配齐` / `物资未确认`。
|
||
- 任一户不满足整团不可确认，团期与子订单状态均不变。
|
||
|
||
---
|
||
|
||
### 2. 确认行程 `POST /v3/admin/order/{id}/confirm-itinerary`
|
||
|
||
**VO**: `ConfirmItineraryReqVO` → `OrderTransitionRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
订单详情页「确认行程」按钮（定制中 → 待出行）。散客单用法不变；团期单改为随团期确认，只在团期确认后作为补确认入口使用。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| id | Path | Long | ✅ | 订单主键 | 不变 |
|
||
| reporterAssignmentId | Body | Long | 否 | 本单人员 assignmentId | 新的主报账人；不传沿用当前主报账人（不变）；请求体整体可省略 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | Boolean | 是否成功（不变） |
|
||
| oldStatus / newStatus | String | 变更前 / 后粗状态，如 `CUSTOMIZING` → `PENDING_DEPARTURE`（不变） |
|
||
| oldFlowStatus / newFlowStatus | String | 变更前 / 后细状态（不变） |
|
||
| triggeredEvents | List<String> | 副作用事件，如 `ASYNC_CONTRACT_GENERATE` / `ASYNC_INSURANCE_ISSUE`（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"reporterAssignmentId": "2072930844657283074"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"success": true,
|
||
"oldStatus": "CUSTOMIZING",
|
||
"newStatus": "PENDING_DEPARTURE",
|
||
"oldFlowStatus": "待确认",
|
||
"newFlowStatus": "待出行",
|
||
"triggeredEvents": ["ASYNC_CONTRACT_GENERATE", "ASYNC_INSURANCE_ISSUE"]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无列表出参。请求体可整体不传（不变）：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期单、所属团期尚未确认（招募中 / 配置 / 已流团等）：
|
||
|
||
```json
|
||
{
|
||
"code": 581065,
|
||
"message": "团期单随团期确认，不可单独确认",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
其余既有码不变，例如清单未通过：
|
||
|
||
```json
|
||
{
|
||
"code": 581036,
|
||
"message": "确认订单前置校验未通过，请先补全所有必填项",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 581065 只在「定制中 + CONFIRM」这一跳判，且在五项清单（581036）、主报账人（581062）之前；散客单不判。
|
||
- 判「团期单」走统一归团解析（`group_batch_id` 或按 `product_batch_id` 反查），与团期详情口径一致。
|
||
- 团期已确认（`MATERIAL_PREPARING` 及之后，与合同保险出具门同一状态集）时放行：用于逐户确认失败后的重试、确认后转入 / 加入的户。
|
||
- 团期管理员角色（`GROUP_BATCH_MANAGER`）调本接口仍被既有写守卫 581008「无权查看此订单」拒绝（不变），补确认需由有订单写权限的角色操作。
|
||
- CONFIRM 落库改为带原状态条件的 CAS：团期驱动的逐户确认与人工补确认同时打到同一户时只有一个成功，输家报错回滚，不会重复出具合同保险。
|
||
|
||
---
|
||
|
||
### 3. 状态变更操作（内部通用） `POST /v3/admin/order/{id}/transition`
|
||
|
||
**VO**: `OrderTransitionReqVO` → `OrderTransitionRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
通用状态机入口（Swagger 隐藏）。本次只影响 `eventCode=CONFIRM`：与「确认行程」落到同一道 Service 层守卫，团期单在团期确认前 581065。其它事件不变。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| id | Path | Long | ✅ | 订单主键 | 不变 |
|
||
| eventCode | Body | String | ✅ | `PAY_DEPOSIT` / `PAY_FULL` / `CANCEL` / `CONFIRM` / `DEPART` / `FINISH` / `TERMINATE` | 本次只有 `CONFIRM` 行为变化 |
|
||
| reason | Body | String | 否 | - | 操作原因（不变） |
|
||
| payload | Body | Map | 否 | - | CONFIRM 可传 `reporterAssignmentId`（不变） |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | Boolean | 不变 |
|
||
| oldStatus / newStatus / oldFlowStatus / newFlowStatus | String | 不变 |
|
||
| triggeredEvents | List<String> | 不变 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"eventCode": "CONFIRM",
|
||
"reason": "定制师确认所有前置条件已完成"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"success": true,
|
||
"oldStatus": "CUSTOMIZING",
|
||
"newStatus": "PENDING_DEPARTURE",
|
||
"oldFlowStatus": "待确认",
|
||
"newFlowStatus": "待出行",
|
||
"triggeredEvents": ["ASYNC_CONTRACT_GENERATE", "ASYNC_INSURANCE_ISSUE"]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无列表出参；非 CONFIRM 事件行为不变。
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "success": true }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 581065,
|
||
"message": "团期单随团期确认，不可单独确认",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 与接口 2 完全同一判据与放行条件；散客单不受影响。
|
||
- 非 CONFIRM 事件的落库仍是原写法；CONFIRM 落库改为 CAS（同接口 2）。
|
||
|
||
---
|
||
|
||
### 4. 团期状态流水 `GET /v3/admin/order/group-batch/{groupBatchId}/status-logs`
|
||
|
||
**VO**: `List<GroupBatchStatusLogItemVO>`
|
||
|
||
#### 使用场景
|
||
|
||
团期详情「操作记录 / 时间线」。本次新增一个事件值：团期确认后逐户确认行程失败时每户一条。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | 不变 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| [].eventType | String | **新增取值** `BATCH_SUB_ORDER_CONFIRM_FAILED` |
|
||
| [].eventTypeName | String | 新值对应「子订单确认行程失败」 |
|
||
| [].changeType | String | 新事件为 `DATA`（团期状态不变，`fromStatus == toStatus`） |
|
||
| [].content | String | 「订单 {订单号} 随团期确认行程失败：{原因}（该户留在定制中，可在订单详情单户补确认）」，原因最长 300 字截断 |
|
||
| [].operatorType | String | 新事件为 `SYSTEM`，`operatorId` 为 null |
|
||
| [].extra | Object | 新事件带 `orderId` / `orderNo` / `reason` |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/2097250563497385985/status-logs HTTP/1.1
|
||
Host: api.test.1814.love:9443
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": [
|
||
{
|
||
"changeType": "DATA",
|
||
"eventType": "BATCH_SUB_ORDER_CONFIRM_FAILED",
|
||
"eventTypeName": "子订单确认行程失败",
|
||
"fromStatus": "MATERIAL_PREPARING",
|
||
"toStatus": "MATERIAL_PREPARING",
|
||
"content": "订单 HL2609240001 随团期确认行程失败：[581062] 请先指定本单主报账人（尾款代收人）（该户留在定制中，可在订单详情单户补确认）",
|
||
"operatorType": "SYSTEM",
|
||
"operatorId": null,
|
||
"extra": {
|
||
"orderId": "2103023889187799042",
|
||
"orderNo": "HL2609240001",
|
||
"reason": "[581062] 请先指定本单主报账人（尾款代收人）"
|
||
}
|
||
}
|
||
],
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
逐户全部成功时不写这类事件；无流水返回空数组（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": [], "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 589500,
|
||
"message": "团期不存在",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- `eventTypeName` 由后端给，前端直接显示即可（不变的约定）。
|
||
- `reason` 是原始失败信息：业务异常为「[错误码] 文案」，非业务异常为「异常类名: 消息」，可能含技术细节。
|
||
- 同一原因同时写入该户 `order_main.last_confirm_error`（最长 500 字），单户补确认成功后清空；该列当前**没有接口出参**。
|
||
- 同一户多次失败会各写一条，不去重。
|
||
|
||
---
|
||
|
||
### 5. 合同保险面板 `GET /v3/admin/order/group-batch/{groupBatchId}/contracts`
|
||
|
||
**VO**: `GroupBatchContractBoardVO`
|
||
|
||
#### 使用场景
|
||
|
||
「合同保险」页签首屏；`issuable` 决定出具按钮是否可点。本次只补 `TRIP_FINISHED`（出行完毕）为可出具。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | 不变 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| issuable | Boolean | **取值变化**：`TRIP_FINISHED` 由 false 改为 true；其余状态不变 |
|
||
| batchStatus | String | 团期状态存储值（不变） |
|
||
| 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": true,
|
||
"batchStatus": "TRIP_FINISHED",
|
||
"totalCount": 4,
|
||
"contractIssuedCount": 4,
|
||
"contractSignedCount": 3,
|
||
"insuranceIssuedCount": 4,
|
||
"items": []
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无活跃子订单时 `totalCount=0`、`items` 为空数组（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "issuable": true, "batchStatus": "TRIP_FINISHED", "totalCount": 0, "items": [] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 589500,
|
||
"message": "团期不存在",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 可出具状态集：`MATERIAL_PREPARING` / `PENDING_DEPARTURE` / `TRAVELLING` / **`TRIP_FINISHED`（新增）** / `REVIEWING` / `SETTLED`。
|
||
- 同一状态集也用于接口 2 / 3 的「团期已确认、放行补确认」判断，保证确认得了的户也出具得了。
|
||
|
||
---
|
||
|
||
### 6. 手动开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue`
|
||
|
||
**VO**: `GroupBatchContractIssueReqVO` → `GroupBatchIssueResultVO`
|
||
|
||
#### 使用场景
|
||
|
||
「合同保险」页签逐户开合同 / 保险。本次只放宽前置门：出行完毕的团（返团当天补签 / 补开）不再被 589548 挡住。入参出参结构不变。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | 团期主键 | 不变 |
|
||
| orderIds | Body | List<Long> | 否 | - | 为空 = 本期全部尚未出具的户（不变） |
|
||
| target | Body | String | ✅ | `CONTRACT` / `INSURANCE` / `BOTH` | 不变 |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalCount / successCount / failCount / skipCount | Integer | 不变 |
|
||
| results[].orderId / target / outcome / message | String | 不变 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{ "orderIds": ["2103023889187799042"], "target": "CONTRACT" }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 1,
|
||
"successCount": 1,
|
||
"failCount": 0,
|
||
"skipCount": 0,
|
||
"results": [
|
||
{ "orderId": "2103023889187799042", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
已出具的户逐项 `SKIPPED`（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "totalCount": 1, "successCount": 0, "failCount": 0, "skipCount": 1, "results": [] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期尚未确认（`RECRUITING` / `RESOURCE_PREPARING` 等，不变）：
|
||
|
||
```json
|
||
{
|
||
"code": 589548,
|
||
"message": "团期确认后才能出具合同与保险",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- `TRIP_FINISHED` 改前 589548，改后放行；其余状态口径不变。
|
||
- 自动出具只剩逐户确认链路；本接口仍是人工补出的通路（逐户确认失败户补确认后会自动出，一般无需手动）。
|
||
|
||
---
|
||
|
||
### 7. 作废重开合同 / 保险 `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": ["2103023889187799042"], "target": "CONTRACT", "reason": "方案选错" }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 1,
|
||
"successCount": 1,
|
||
"failCount": 0,
|
||
"skipCount": 0,
|
||
"results": [
|
||
{ "orderId": "2103023889187799042", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
作废失败的户记 `FAILED`，不影响其他户（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "totalCount": 1, "successCount": 0, "failCount": 1, "skipCount": 0, "results": [] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 589548,
|
||
"message": "团期确认后才能出具合同与保险",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 与手动开共用同一出具门；`TRIP_FINISHED` 放行。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
### ✅ 正确 / ❌ 错误调用对照
|
||
|
||
| 场景 | 调用 |
|
||
|------|------|
|
||
| ✅ 团期单确认行程 | 补齐各户资料 → 团期 `confirm` → 系统逐户确认，合同保险自动出 |
|
||
| ❌ 团期确认前逐户点确认行程 | `confirm-itinerary` → 581065 |
|
||
| ✅ 团期确认后某户失败 | 看时间线 `BATCH_SUB_ORDER_CONFIRM_FAILED` 的原因 → 补资料 → 订单详情 `confirm-itinerary` 补确认 |
|
||
| ❌ 确认后等「全团补发」合同 | 已下线；合同保险只随逐户确认自动出具 |
|
||
|
||
### 589556 的解析
|
||
|
||
message 冒号之后按「；」切段：不以「订单 」开头的是团期级（「、」分隔的五种之一），以「订单 {订单号}：」开头的是逐户段，冒号后按「、」切出未满足项。可直接逐段展示，无需解析。
|
||
|
||
### 581065 的处理
|
||
|
||
提示「请到团期详情点确认」，不要引导运营去补本单资料（那是 581036 的出路）。
|
||
|
||
---
|
||
|
||
## 五、数据库行为
|
||
|
||
| 前端动作 | 外部可观察的写入 |
|
||
|----------|------------------|
|
||
| `confirm` 被拒（589556 等） | 零写入（预检前的人员副本补齐随事务一并回滚） |
|
||
| `confirm` 成功（团期事务） | 团期状态 CAS 推进 + 时间线 `BATCH_CONFIRM`；各户团期人员副本（`order_staff_assignment`）按团期配置补齐 |
|
||
| `confirm` 成功（提交后逐户，每户独立事务） | 子订单 `CUSTOMIZING → PENDING_DEPARTURE`、写 `confirmed_at`、订单日志 CONFIRM「随团期确认行程」、应付台账推送；随后逐户生成合同 / 保单 |
|
||
| 逐户确认失败 | 该户不变；团期时间线 `BATCH_SUB_ORDER_CONFIRM_FAILED` + `order_main.last_confirm_error` |
|
||
| 单户补确认成功 | 同上逐户写入，并清空 `last_confirm_error` |
|
||
| `confirm-itinerary` / `transition` 被 581065 拒 | 零写入 |
|
||
|
||
无 schema 变更（`last_confirm_error` 为既有列）。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录 → 401（网关拦截）；团期不存在 → 589500。
|
||
- 待支付户、未付订金户会挡住整团确认：须先付订金或取消该户。
|
||
- 已是待出行 / 出行中的户在团期确认时跳过，不重复确认、不重复出具。
|
||
- 逐户确认使用系统身份，订单日志 / 合同创建人为 SYSTEM；确认人记在团期时间线 `BATCH_CONFIRM`。
|
||
- 定案前已单独确认但未出合同的存量户，需在「合同保险」页签手动补出。
|
||
- 建单时团期人员副本连同报账人等级一起抄（PR #8349），后挂团的户订单层主报账人不再停在 NONE。
|
||
|
||
---
|
||
|
||
## 六.5、枚举 / 数据字典
|
||
|
||
### 时间线事件（GroupBatchLogEventType，新增一值）
|
||
|
||
**所属字段**: 团期状态流水 `eventType` / `eventTypeName` | **类型**: `String`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `BATCH_SUB_ORDER_CONFIRM_FAILED` | 子订单确认行程失败 | 本次新增；`changeType=DATA`，`operatorType=SYSTEM`，extra 带 orderId / orderNo / reason |
|
||
|
||
### 错误码
|
||
|
||
| 码 | 文案 | 说明 |
|
||
|----|------|------|
|
||
| 581065 | 团期单随团期确认，不可单独确认 | 本次新增 |
|
||
| 589556 | 团期尚不满足确认条件：{0} | 码值不变，{0} 改为「；」分段、含逐户段 |
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 589556 message `{0}` | 团期级未满足项，「、」连接 | 「；」分段：团期级一段（有才出现）+ 每户一段「订单 {订单号}：{未满足项}」 |
|
||
| `confirm-itinerary` / `transition(CONFIRM)` 错误码 | 无 581065 | 团期单在团期确认前 581065 |
|
||
| 时间线 `eventType` | 无该值 | 新增 `BATCH_SUB_ORDER_CONFIRM_FAILED` |
|
||
| 合同保险面板 `issuable`（`TRIP_FINISHED`） | false | true |
|
||
| `contracts/issue` / `reissue`（`TRIP_FINISHED`） | 589548 | 放行 |
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 团期确认后子订单 | 仍在定制中，需逐户点确认行程 | 系统逐户确认 → 待出行 |
|
||
| 合同保险出具 | 确认后全团补发 + 逐户确认链路 | 只剩逐户确认链路 |
|
||
| 团期确认门 | 四项 ready + 物资 | 另加逐户预检（付订金即可） |
|
||
| 子订单 CONFIRM 落库 | 按主键更新 | 带原状态条件 CAS |
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **是否破坏向后兼容**: 是。按「、」切 589556 message 的前端会把逐户段切碎；团期单的「确认行程」在团期确认前会收到 581065。
|
||
- **前端是否必须同步上线**: 建议同步。后端不依赖前端即可工作（团期确认即完成子订单确认）；前端未改时只是提示不友好、按钮可点但报 581065。
|
||
- **前端 workaround 清理点**: 团期单订单详情「确认行程」按钮在团期确认前隐藏或置灰；589556 改按「；」分段展示；时间线对新事件无需映射（后端给中文名）。
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- **仅影响**: 团期确认门与确认后的子订单联动、团期单 CONFIRM 守卫、团期时间线新事件、合同保险出具门的状态集。
|
||
- **零影响**:
|
||
- 散客单的确认行程与 transition 各事件
|
||
- 团期确认的权限码、路径、入参、成功出参
|
||
- `GET /v3/admin/order/{id}/confirm-checklist` 的入参出参（逐户预检复用其判据，接口本身不变）
|
||
- 进入待出发的七项硬门
|
||
- 小程序端
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
部署：hl-order-service-v3 = dev-v3 @ f55840cb5（PR #8346，第一轮 2026-09-24 15:30–16:16），复验 dev-v3 @ 9ffb3c2de（PR #8349，2026-09-24）的 TEST 环境实测（证据见工单 #8339 验收评论）；工单 #8339 已验收关单。
|
||
|
||
| # | 场景 | 结果 |
|
||
|---|---|---|
|
||
| 1 | 全户满足，调团期 `confirm` | 200；子订单 定制中 → 待出行，写 `confirmed_at`，订单日志 CONFIRM「随团期确认行程」；合同 1 份 SIGNED、保险 2 条 INSURED / 户，无重复（两轮均验） |
|
||
| 2 | 某户仅付订金（DEPOSIT_PAID） | 视为满足付款项 |
|
||
| 3 | 待支付 / 户级房未完成 / 无主报账人（第一轮）；产品未配置合同方案 / 成人出行人无手机号 / 未提交用车需求（复验，SQL 构造已恢复） | 589556 整团拒，逐户列订单号 + 未满足项，团期与子订单状态不变 |
|
||
| 4 | 已待出行户 | 跳过，不重复确认、不重复出具 |
|
||
| 5 | CHECK 约束注入使一户逐户确认失败 | 团期确认不回滚、其他户正常；时间线 `BATCH_SUB_ORDER_CONFIRM_FAILED`（含订单号 + 原因），`last_confirm_error` 有值；删约束后单户补确认成功，`last_confirm_error` 清空 |
|
||
| 6 | 团期单 `confirm-itinerary` / `transition` CONFIRM（团期未确认） | 581065；散客单不受影响 |
|
||
| 7 | `TRIP_FINISHED`（附带 `REVIEWING`）调 `GET /contracts` | `issuable=true` |
|
||
| 8 | 先设 PRIMARY 后下单的户 / 存量 NONE 副本（PR #8349） | 建单即抄为 PRIMARY；确认预检前补齐，不再误报「未指定主报账人」 |
|
||
|
||
本地：788 例 + 合入后 606 例（含 6 个 Docker IT，唯一红为 dev-v3 既有基线 `ConfirmChecklistGuardIT` 581062）；PR #8349 相关 360 例（含 Docker IT）0 失败。
|
||
|
||
---
|
||
|
||
## 九、相关历史 PR
|
||
|
||
| PR | Issue | 说明 | 是否仍有效 |
|
||
|----|-------|------|------------|
|
||
| #8302 | #8268 | 团期人工确认端点；确认后全团补发合同保险 | ⚠️ 确认端点有效；「确认后全团补发」被本单下线 |
|
||
| **本 PR #8346** | **#8339** | 确认门逐户预检、子订单随团期确认、581065 | ✅ 最新 |
|
||
| **本 PR #8349** | **#8339** | 人员副本补齐、逐户确认失败留痕 | ✅ 最新 |
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#8339](https://git.1814.love/wx/HL/issues/8339)
|
||
- 关联 PR: [wx/HL#8346](https://git.1814.love/wx/HL/pulls/8346)、[wx/HL#8349](https://git.1814.love/wx/HL/pulls/8349)
|
||
- 定案文档：SRS §0.27.7（PR #8338）
|
||
- 同批条目：团期核单 / 结算 / 反结算同步子订单（#8341）；团期人工确认端点（#8268）
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8339](https://git.1814.love/wx/HL/issues/8339)
|
||
- **PR**: [#8346](https://git.1814.love/wx/HL/pulls/8346)、[#8349](https://git.1814.love/wx/HL/pulls/8349)
|
||
- **Merge commit**: [f55840cb5](https://git.1814.love/wx/HL/commit/f55840cb5dca1d2f3a81078548c7a50cc813ca7e)、[9ffb3c2de](https://git.1814.love/wx/HL/commit/9ffb3c2de31ccf2ba7b16c2922f6f493f2025269)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @jw
|