---
schema: "hl-changelog/v2"
ticket: "7142"
title: "订单详情/列表/创单响应透出 groupBatchId·productBatchId·groupOrder 判团字段"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: ""
updated_at: "2026-09-06"
base: "dev-v3"
---

# 订单模块：判团字段透出（详情·列表·创单）

三个订单读接口响应透出判团字段 `groupBatchId` / `productBatchId` / `groupOrder`，供前端判断订单是否为团订单。关键口径：**判团只读 `groupBatchId`（非空=团订单）或 `groupOrder`**；`productBatchId` 仅供溯源，不参与判团。

## ⚠️ 关键变化

- **判团唯一口径** `groupBatchId` 非空或 `groupOrder = true` → 团订单；为空/false → 普通订单。
- **不要拿 `productBatchId` 反推团单**，该字段仅供产品侧班期溯源展示，产品侧可能有多个班期映射同一团期。
- 前一版 #7083 仅涉及订单主表冻结，本次全量透出给前端消费，与主表字段同源。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 订单详情 - 主单数据 | GET | `/v3/admin/order/{id}` | 响应新增字段 | data.main 新增 4 字段 |
| 2 | 订单分页列表 | GET | `/v3/admin/order` | 响应新增字段 | data.list[] 新增 2 字段 |
| 3 | 创建订单 | POST | `/v3/admin/order` | 响应新增字段 | data 新增 3 字段 |

---

## 三、接口详情

### 1. 订单详情 - 主单数据 `GET /v3/admin/order/{id}`

**VO**: `OrderMainVO`（响应位置：`data.main`）

#### 使用场景

打开订单详情页面时，读取订单主单数据及其判团标记，供前端决定显示团期相关内容（如「团期编号」、「团期名称」等）。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `id` | Path | String | 是 | 正整数 ID | 订单 ID |

#### 出参 `Result<OrderDetailRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.main.groupBatchId` | String/null | 运营团期主键（order_group_batch.group_batch_id）；非空=团订单，为空=普通订单 |
| `data.main.productBatchId` | String/null | 产品侧班期 ID（product_v2.group_tour_batch.batch_id）；仅供溯源，不参与判团 |
| `data.main.groupOrder` | Boolean | 派生值，= groupBatchId != null；直接用于前端判团 |
| `data.main.batchNo` | String/null | 团期编号（order_group_batch.batch_no）；普通单为 null，团期软删也为 null |
| `data.main.batchName` | String/null | 团期名称（order_group_batch.batch_name）；普通单为 null，团期软删也为 null |

#### 请求示例

```http
GET /v3/admin/order/2096414445365338113
Authorization: Bearer <token>
```

无请求体。

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "main": {
      "id": "2096414445365338113",
      "orderNo": "HL20260906094527867",
      "orderStatus": "PENDING_PAY",
      "orderStatusName": "待支付",
      "flowStatus": "AWAITING_PAY",
      "flowStatusName": "待补全信息",
      "flowStep": 0,
      "flowStepTotal": 6,
      "totalAmount": "5850.00",
      "depositAmount": "1000.00",
      "departureDate": "2026-10-01",
      "returnDate": "2026-10-03",
      "groupBatchId": "2096412454643802114",
      "productBatchId": "2052935476557328386",
      "groupOrder": true,
      "batchNo": "Q202610012052935476548939777",
      "batchName": "10月1日长白山亲子团",
      "progressStepper": []
    },
    "profile": {},
    "resource": {},
    "contract": {},
    "insurance": {},
    "refund": {},
    "aftersale": {},
    "financial": {}
  }
}
```

#### 空数据 / 降级响应

普通订单时，`groupBatchId`、`productBatchId`、`batchNo`、`batchName` 均为 null；`groupOrder` 为 false。

#### 错误响应

```json
{
  "code": 581007,
  "message": "订单不存在",
  "success": false,
  "data": null
}
```

示例错误码：
- 581007：订单不存在
- 581045：房务角色无权查看订单详情（HTTP 200 code）

#### 业务边界

- 沿用订单详情权限校验；业务失败仍为 HTTP 200，需检查 code。
- 普通订单与团单在出参结构上无区别，仅字段值不同（null vs 有值）。
- 团期已软删时，`groupBatchId` 存在但对应记录不可查，`batchNo` / `batchName` 回退为 null。
- `productBatchId` 与 `groupBatchId` 无必然对应，前端不做交叉校验。

---

### 2. 订单分页列表 `GET /v3/admin/order`

别名接口：`GET /v3/admin/order/list`

**VO**: `OrderListItemRespVO`（响应位置：`data.list[]`）

#### 使用场景

订单列表页加载数据时，带上新增的判团标记，供前端快速判断每行是否为团订单，可用于条件展示「团期信息」列或其他团期特化功能。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `orderStatus` | Query | String | 否 | 枚举多值（逗号分隔） | 粗状态过滤（PENDING_PAY、CUSTOMIZING 等） |
| `flowStatus` | Query | String | 否 | 枚举多值（逗号分隔） | 细状态过滤（AWAITING_PAY、RESOURCE_PREPARING 等） |
| `tagNames` | Query | Array | 否 | - | 按标签过滤（多标签 OR 关系） |
| `keyword` | Query | String | 否 | - | 搜索关键字（团号/客户姓名/产品名/订单号 LIKE） |
| `departureDateFrom` | Query | String | 否 | yyyy-MM-dd | 出发日期范围起始 |
| `departureDateTo` | Query | String | 否 | yyyy-MM-dd | 出发日期范围结束 |
| `createSource` | Query | String | 否 | - | 来源过滤（CONSULTANT/MP/...） |
| `cancelled` | Query | Boolean | 否 | - | 是否含已取消订单（默认 false） |
| `consultantName` | Query | String | 否 | - | 定制师姓名 LIKE 模糊匹配 |
| `statusGroup` | Query | String | 否 | 枚举单值 | 按 Tab 分组（ALL/BEFORE_TRIP/ON_TRIP/SETTLEMENT/ABNORMAL/AFTERSALE） |
| `page` | Query | Integer | 是 | ≥1 | 页码 |
| `pageSize` | Query | Integer | 是 | ≤100 | 每页条数 |

#### 出参 `Result<Page<OrderListItemRespVO>>`

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.list[].groupBatchId` | String/null | 运营团期主键（order_group_batch.group_batch_id）；非空=团订单 |
| `data.list[].groupOrder` | Boolean | 派生值，= groupBatchId != null；直接用于前端判团 |

其他字段详见现有订单列表接口文档。

#### 请求示例

```http
GET /v3/admin/order?page=1&pageSize=20
Authorization: Bearer <token>
```

无请求体。

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "total": 150,
    "list": [
      {
        "id": "2096414445365338113",
        "orderNo": "HL20260906094527867",
        "productName": "冻干粉发短信给",
        "customerName": "张三",
        "departureDate": "2026-10-01",
        "orderStatus": "PENDING_PAY",
        "flowStatus": "AWAITING_PAY",
        "totalAmount": "5850.00",
        "groupBatchId": "2096412454643802114",
        "groupOrder": true
      },
      {
        "id": "2096414445365338114",
        "orderNo": "HL20260906094527868",
        "productName": "其他产品",
        "customerName": "李四",
        "departureDate": "2026-10-02",
        "orderStatus": "PENDING_DEPARTURE",
        "flowStatus": "PENDING_DEPARTURE",
        "totalAmount": "8000.00",
        "groupBatchId": null,
        "groupOrder": false
      }
    ]
  }
}
```

#### 空数据 / 降级响应

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "total": 0,
    "list": []
  }
}
```

#### 错误响应

```json
{
  "code": 401,
  "message": "未登录或登录已过期",
  "success": false,
  "data": null
}
```

#### 业务边界

- 分页字段 `page` / `pageSize` 沿用现有约束。
- 列表返回最新 50 条或 100 条时，两个新增字段保证同时返回，不存在部分返回的情况。
- `groupOrder` 是 `groupBatchId != null` 的派生布尔值，前端可二选一使用。
- 普通订单与团单混合返回，字段值直接对标订单属性。

---

### 3. 创建订单 `POST /v3/admin/order`

**VO**: `OrderCreateRespVO`（响应位置：`data`）

#### 使用场景

创建订单后，管理端「订单已创建」弹窗或后续流程需判断该单是否为团单，及时显示团期相关信息（如「团期编号」、「出发日期」等）。

#### 入参

沿用现有 `OrderCreateReqVO`，**请求体不变**（本单只改响应）。字段表：

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `productId` | Body | String（Long） | ✅ | 正整数 | 产品 ID |
| `tierSeq` | Body | Integer | ✅ | ≥1 | 档位序号 |
| `departureDate` | Body | String(yyyy-MM-dd) | ✅ | 不早于今天 | 出发日期 |
| `adultCount` | Body | Integer | ✅ | ≥1 | 成人数 |
| `childCount` | Body | Integer | 否 | ≥0，默认 0 | 儿童数 |
| `youngChildCount` | Body | Integer | 否 | ≥0，默认 0 | 小童数 |
| `babyCount` | Body | Integer | 否 | ≥0，默认 0 | 婴儿数 |
| `customerName` | Body | String | ✅ | @NotBlank | 客户姓名 |
| `customerPhone` | Body | String | ✅ | ^1[3-9]\d{9}$ | 客户手机号 |
| `customerRemark` | Body | String | 否 | ≤500 | 备注 |
| `createSource` | Body | String | 否 | 默认 CONSULTANT | 创建来源 |
| `productBatchId` | Body | String（Long） | 否 | GROUP 必传、非 GROUP 禁传 | 团期 ID（见 #7135） |
| `roomCount` | Body | Integer | 否 | ≥1 | 房间数 |
| `tags` | Body | Array&lt;String&gt; | 否 | — | 订单标签 |

#### 出参 `Result<OrderCreateRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.id` | String | 订单主键 |
| `data.orderNo` | String | 订单号 |
| `data.orderStatus` | String | 粗状态（创单后为 PENDING_PAY） |
| `data.flowStatus` | String | 细状态（创单后为 AWAITING_PAY） |
| `data.flowStep` | Integer | 线性步序（创单初态为 0） |
| `data.flowStepTotal` | Integer | 总步数（固定 6） |
| `data.productName` | String | 产品名 |
| `data.tierName` | String | 档位名 |
| `data.departureDate` | String | 出发日期 |
| `data.returnDate` | String | 返团日期 |
| `data.totalAmount` | String | 订单总价 |
| `data.depositAmount` | String | 建议定金金额 |
| `data.depositRatio` | Integer/null | 定金比例百分比 |
| `data.depositMode` | String | 定金计算模式（FIXED/RATIO/FULL） |
| `data.paymentMode` | String | 支付模式（DEPOSIT/FULL） |
| `data.groupBatchId` | String/null | 运营团期 ID（创单同事务回写）；非空=团订单 |
| `data.productBatchId` | String/null | 产品侧班期 ID（创单入参原样固化）；仅供溯源 |
| `data.groupOrder` | Boolean | 派生值，= groupBatchId != null；直接用于判团 |

#### 请求示例

```json
{
  "productId": 2044306857534636034,
  "tierSeq": 1,
  "departureDate": "2026-10-01",
  "adultCount": 2,
  "childCount": 1,
  "customerName": "张三",
  "customerPhone": "13800138000",
  "productBatchId": 2052935476557328386,
  "createSource": "CONSULTANT"
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "id": "2096414445365338113",
    "orderNo": "HL20260906094527867",
    "orderStatus": "PENDING_PAY",
    "orderStatusName": "待支付",
    "flowStatus": "AWAITING_PAY",
    "flowStatusName": "待补全信息",
    "flowStep": 0,
    "flowStepTotal": 6,
    "flowStepName": "待支付",
    "productName": "冻干粉发短信给",
    "tierName": "经典档",
    "departureDate": "2026-10-01",
    "returnDate": "2026-10-03",
    "totalAmount": "5850.00",
    "depositAmount": "1000.00",
    "depositRatio": null,
    "depositMode": "FIXED",
    "paymentMode": "DEPOSIT",
    "expiryMinutes": 1440,
    "payUrl": "https://pay.hulalv.com/pay/HL20260906094527867",
    "customerName": "张三",
    "groupBatchId": "2096412454643802114",
    "productBatchId": "2052935476557328386",
    "groupOrder": true
  }
}
```

实测数据示例（2026-09-06 测试服）：
- 产品「冻干粉发短信给」productId=2044306857534636034
- 班期 2026-10-01 productBatchId=2052935476557328386
- 团期主键 groupBatchId=2096412454643802114
- 团期编号 batchNo=Q202610012052935476548939777

#### 空数据 / 降级响应

创建订单成功后无空数据响应。

#### 错误响应

```json
{
  "code": 400,
  "message": "产品 ID 非法或产品已下架",
  "success": false,
  "data": null
}
```

#### 业务边界

- 创建普通订单时，`groupBatchId` / `productBatchId` 为 null，`groupOrder` 为 false。
- 创建 GROUP 产品订单时（必须提交 `productBatchId`），后端在同事务内懒创建或命中已有团期，回写 `groupBatchId`。
- `groupBatchName` 字段当前恒为 null（仅为兼容既有前端契约），**前端不要读它**。
- 响应中 `groupBatchId` / `productBatchId` 为字符串（JSON 序列化后，避免 JS 精度丢失）；前端若需数值运算应转换为字符串存储。

---

## 四、契约约束与正确调用方式

| 场景 | 正确做法 |
|------|---------|
| 判断订单是否团单 | 读 `groupBatchId` 非空 或 `groupOrder == true`，两者等价 |
| 不要用 productBatchId 判团 | `productBatchId` 仅供溯源，可能 null（普通单）或有值（团单/非团单均可能） |
| 团单需显示团期名 | `groupBatchName` 恒为 null，读 `batchName`；团期软删时也为 null |
| 普通单与团单混合渲染 | 按 `groupOrder` 条件渲染，普通单该字段为 false；两类订单出参结构一致，仅值不同 |

---

## 五、数据库行为

| 订单类型 | groupBatchId | productBatchId | groupOrder | batchNo | batchName |
|---------|-------------|----------------|-----------|---------|-----------|
| 普通订单 | null | null | false | null | null |
| 团单（命中或懒建） | 非空 | 非空 | true | 有值 | 有值 |
| 团期已软删 | 非空 | 非空 | true | null | null |

---

## 六、边界行为

- 业务失败可能仍为 HTTP 200，必须同时检查 `code`、`success` 和 `message`。
- 详情接口 404/权限 403 时直接返回对应 HTTP 状态码；业务类失败（如订单状态不符）返回 HTTP 200 + code。
- 列表空结果返回 `total=0, list=[]`，分页参数超界时返回空列表（无 5XX）。
- 创单失败不落库，响应 HTTP 200 + code，data 为 null。
- 新增判团字段与现有字段同源、同时刷新，无时间差。

---

## 六.6、修改前后对比

### 字段级对比

| 字段 | 改前 | 改后 |
|------|------|------|
| `groupBatchId` | 无此字段 | 新增；运营团期主键 |
| `productBatchId` | 无此字段 | 新增；产品班期 ID（仅溯源） |
| `groupOrder` | 无此字段 | 新增；派生布尔，= groupBatchId != null |
| `batchNo` | 无此字段 | 新增；团期编号（详情/列表） |
| `batchName` | 无此字段 | 新增；团期名称（详情/列表） |

### 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 前端判团依据 | 无判团字段，无法直接判别 | 读 groupBatchId 非空 或 groupOrder = true |
| 团单信息展示 | 依赖联查或额外接口 | 直接在订单响应中获得 |
| 产品班期溯源 | 不支持 | 新增 productBatchId（仅溯源展示） |

---

## 六.7、影响评估

- **是否破坏向后兼容**: 否。新增字段对旧客户端透明，非必需字段缺失时前端框架可靠 null 处理。
- **前端是否必须同步上线**: 是。前端需接入新增四个字段至详情/列表/创建成功弹窗模板，判团逻辑改用 groupBatchId 或 groupOrder。
- **前端 workaround 清理点**: 
  - 删除旧的"通过产品 ID 推断团单"逻辑，改用 groupBatchId 判别
  - 不要硬编码团期编号/名称，改用响应中的 batchNo / batchName
  - groupBatchName 恒为 null，勿读之；用 batchName 替代

---

## 七、不影响范围

- **仅影响**: 管理后台订单详情、列表和创建流程的前端渲染
- **零影响**:
  - 订单创建/编辑/取消接口
  - 小程序端（MpOrderDetailVO 不变）
  - 数据库结构（新字段冻结在 order_main 表，无表改动）
  - 订单写操作和业务流程

---

## 八、测试环境已验证

- **单测**: 559 条测试用例绿✓（新增判团字段相关的 UT 已覆盖普通单/团单双路径）
- **ArchTest**: 45 条架构测试绿✓
- **测试服网关实测**: 单测 + CR 通过；测试服网关实测见管理者补充

实测产品: `productId=2044306857534636034`（冻干粉发短信给），班期 `2026-10-01`（productBatchId=2052935476557328386），团期主键 `groupBatchId=2096412454643802114`，批号 `batchNo=Q202610012052935476548939777`。

---

## 九、相关历史 PR（功能演进）

| PR | Issue | 说明 | 是否仍有效 |
|----|-------|------|------------|
| #7083 | - | order_group_batch 一跳直连，订单主表冻结 groupBatchId/productBatchId | ✅ 有效 |
| #7135 | - | GROUP 产品创单校验与重整 | ✅ 有效 |
| #7143 | - | 团期看板 VO 补 productId（配合本 PR） | ✅ 有效 |
| **本 PR #7155** | **#7142** | **订单详情/列表/创单响应透出判团字段** | ✅ 最新 |

---

## 十、相关文档

- 关联 Issue: [wx/HL#7142](https://git.1814.love:8443/wx/HL/issues/7142)
- 关联 PR: [wx/HL#7155](https://git.1814.love:8443/wx/HL/pulls/7155)
- 团期接口文档: `docs/ARCHITECTURE.md` §0A.2.2（团单冻结口径）
- 团单业务规范: 见 #7135 changelog 中的团期创建规则

## 关联 / 联系人

### 链接

- **Issue**: [#7142](https://git.1814.love:8443/wx/HL/issues/7142)
- **PR**: [#7155](https://git.1814.love:8443/wx/HL/pulls/7155)
- **Merge commit**: [21d3d00de](https://git.1814.love:8443/wx/HL/commit/21d3d00de)

### 联系人

- **后端负责人**: @wx