---
schema: "hl-changelog/v2"
ticket: "6921"
title: "六芯片读端接入专用投影 + 车芯片车务文案修正"
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: "复审返工：#6903 六芯片读端由 order_main 整行实体查询改为 18 列专用投影（不再触发 customerPhone/emergencyContactPhone 解密），车芯片 statusText 由房务文案改为车务文案；2026-09-01 部署测试服 dev-v3，6 端点网关实测 200 全通过、团期不存在 589500，文案由单测锁定"
updated_at: "2026-09-01"
base: "dev-v3"
---

# 六芯片读端接入专用投影 + 车芯片车务文案修正

> **服务**: hl-order-service-v3
> **PR**: #6924（squash 合并落地 dev-v3 `35b7f2ed`）
> **Issue**: #6921（#6903 复审返工）
> **日期**: 2026-09-01
> **影响范围**: 管理后台团期看板行右侧六芯片（配房/配车/配导游/配摄影/合同/保险）逐户下钻接口（GB-ADM-090~095）

---

## ⚠️ 关键变化

- **读端投影化（实现层，对外契约不变）**：六芯片逐户明细改为从 `order_main` 的 **18 列专用投影**读取，不再整行加载实体，因此**不再触发 `customerPhone` / `emergencyContactPhone` 解密逻辑**；返回体、字段名、枚举、免闸计数口径全部不变。
- **车芯片文案修正（对外可观察）**：`items[].statusText` 车务文案为 `待车务配 / 配车中 / 配车完成`（房务文案 `待房务配 / 配房中 / 配房完成` 不变）。前版 #6903 文档误写"与房同文案"，#6921 按车务实际口径修正。
- 对外响应结构、错误码、聚合态、免闸口径与 #6903 完全一致，**无任何字段新增/删除/改名**，前端无需改动。

---

## 一、背景

#6903 交付的六芯片接口在代码走查中发现读端直接加载 `OrderInfo` 实体并触发手机号解密，存在无关数据暴露与无效解密开销；同时车芯片文案错误沿用房务文案。本单为复审返工：#6901/#6903 接口契约不变，仅修正读端实现与车芯片文案。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | GB-ADM-090 配房逐户明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/hotel` | 修改接口 | 读端改专用投影，对外不变 |
| 2 | GB-ADM-091 配车逐户明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/vehicle` | 修改接口 | 读端改专用投影 + statusText 车务文案 |
| 3 | GB-ADM-092 配导游逐户明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/guide` | 修改接口 | 读端改专用投影，对外不变 |
| 4 | GB-ADM-093 配摄影逐户明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/photo` | 修改接口 | 读端改专用投影，对外不变 |
| 5 | GB-ADM-094 合同逐户明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/contract` | 修改接口 | 读端改专用投影，对外不变 |
| 6 | GB-ADM-095 保险逐户明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/insurance` | 修改接口 | 读端改专用投影，对外不变 |

---

## 三、接口详情

六个接口共用 `GroupBatchChipDetailVO` / `GroupBatchChipItemRespVO`，本单为复审返工：仅读端实现与车芯片文案变化，契约字段与 #6903 完全一致，正文各自自包含。

### 1. GB-ADM-090 配房逐户明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/hotel`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期看板行右侧「房」芯片点击展开：返回该团期每户的配房进度（哪一户到哪一步），前端展开列表展示。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| groupBatchId | Path | String | ✅ | 团期 ID（Snowflake） | 不存在/非团期/已软删 → 589500 |

无查询参数、无请求体。

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId | String | 团期 ID |
| chipLabel | String | 固定「配房」 |
| aggregateStatus | String | 整团聚合态 四态取值与看板 GB-ADM-001 `chips.X` 的 `aggregateStatus` 完全一致（整团待办/进行中/已完成/异常） |
| totalCount | Integer | 计入统计的子订单数（免闸户不计入） |
| doneCount | Integer | 已完成户数（`status==DONE`） |
| items[].orderId | String | 子订单 ID（JSON String 化） |
| items[].orderNo | String | 子订单编号 |
| items[].contactName | String | 联系人/客户姓名 |
| items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby |
| items[].status | String | 本户配房状态，`RequirementStatus` 6 值，见「六.5」；无需/未开始为 null |
| items[].statusText | String | 状态中文名（服务端给出，房务文案，见「六.5」） |
| items[].needsIt | Boolean | 本户是否需要配房（`order_main.needs_hotel`）；false=免闸户，status=null、置灰、不计入计数 |
| items[].updateTime | String | 配房最后变更时间；无独立时间戳时为 null |

#### 请求示例

```http
GET /v3/admin/order/group-batch/90211/chips/hotel
Authorization: Bearer ****
X-Admin-Id: 3301
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "配房",
    "aggregateStatus": "DONE",
    "totalCount": 3,
    "doneCount": 3,
    "items": [
      { "orderId": "770153", "orderNo": "GT-26-0097", "contactName": "林婉清",
        "peopleCount": 3, "status": "DONE", "statusText": "配房完成",
        "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}
```

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

```json
{ "code": 200, "data": { "batchId": "90211", "chipLabel": "配房",
  "aggregateStatus": "整团待办", "totalCount": 0, "doneCount": 0, "items": [] },
  "success": true }
```

#### 错误响应

```json
{ "code": 589500, "message": "团期不存在", "success": false, "data": null }
```

#### 业务边界

- 授权码 `group-batch:view`；未配置权限 → 589507。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- 本单读端改为专用投影，返回体与 #6903 完全一致（契约不变）。

### 2. GB-ADM-091 配车逐户明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/vehicle`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期看板行右侧「车」芯片点击展开：返回该团期每户的配车进度，前端展开列表展示。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| groupBatchId | Path | String | ✅ | 团期 ID（Snowflake） | 不存在/非团期/已软删 → 589500 |

无查询参数、无请求体。

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId | String | 团期 ID |
| chipLabel | String | 固定「配车」 |
| aggregateStatus | String | 整团聚合态 四态取值与看板 GB-ADM-001 `chips.X` 的 `aggregateStatus` 完全一致（整团待办/进行中/已完成/异常），与 GB-ADM-001 `chips.vehicle` 同源 |
| totalCount | Integer | 计入统计的子订单数（免闸户不计入） |
| doneCount | Integer | 已完成户数（`status==DONE`） |
| items[].orderId | String | 子订单 ID（JSON String 化） |
| items[].orderNo | String | 子订单编号 |
| items[].contactName | String | 联系人/客户姓名 |
| items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby |
| items[].status | String | 本户配车状态，`RequirementStatus` 6 值，见「六.5」；无需/未开始为 null |
| items[].statusText | String | 状态中文名（服务端给出，**车务文案**，见「六.5」） |
| items[].needsIt | Boolean | 本户是否需要配车（`order_main.needs_vehicle`）；false=免闸户置灰不计入 |
| items[].updateTime | String | 配车最后变更时间；无独立时间戳时为 null |

#### 请求示例

```http
GET /v3/admin/order/group-batch/90211/chips/vehicle
Authorization: Bearer ****
X-Admin-Id: 3301
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "配车",
    "aggregateStatus": "DONE",
    "totalCount": 3,
    "doneCount": 3,
    "items": [
      { "orderId": "770160", "orderNo": "GT-26-0101", "contactName": "王强",
        "peopleCount": 2, "status": "DONE", "statusText": "配车完成",
        "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}
```

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

```json
{ "code": 200, "data": { "batchId": "90211", "chipLabel": "配车",
  "aggregateStatus": "整团待办", "totalCount": 0, "doneCount": 0, "items": [] },
  "success": true }
```

#### 错误响应

```json
{ "code": 589500, "message": "团期不存在", "success": false, "data": null }
```

#### 业务边界

- 授权码 `group-batch:view`；未配置权限 → 589507。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- **本单唯一文案变化**：statusText 使用车务文案（待车务配/配车中/配车完成），不再与房同文案。
- 免闸户（`needsIt=false`）：status=null、statusText=「无需」、置灰、不计入计数。

### 3. GB-ADM-092 配导游逐户明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/guide`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期看板行右侧「导」芯片点击展开：返回每户配导游进度。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| groupBatchId | Path | String | ✅ | 团期 ID（Snowflake） | 不存在/非团期/已软删 → 589500 |

无查询参数、无请求体。

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId | String | 团期 ID |
| chipLabel | String | 固定「配导游」 |
| aggregateStatus | String | 整团聚合态 四态取值与看板 GB-ADM-001 `chips.X` 的 `aggregateStatus` 完全一致（整团待办/进行中/已完成/异常） |
| totalCount | Integer | 计入统计的子订单数（免闸户不计入） |
| doneCount | Integer | 已完成户数（`status==DONE`） |
| items[].orderId | String | 子订单 ID（JSON String 化） |
| items[].orderNo | String | 子订单编号 |
| items[].contactName | String | 联系人/客户姓名 |
| items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby |
| items[].status | String | 本户配导游状态，3 值：`NONE` 无需/未开始 / `PENDING` 待指派 / `DONE` 已指派，见「六.5」 |
| items[].statusText | String | 状态中文名（服务端给出，见「六.5」） |
| items[].needsIt | Boolean | 本户是否需要配导游（`order_main.needs_guide`）；false=免闸户 status 恒 `NONE`、不计入计数 |
| items[].updateTime | String | 配导游最后变更时间；无独立时间戳时为 null |

#### 请求示例

```http
GET /v3/admin/order/group-batch/90211/chips/guide
Authorization: Bearer ****
X-Admin-Id: 3301
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "配导游",
    "aggregateStatus": "DOING",
    "totalCount": 4,
    "doneCount": 2,
    "items": [
      { "orderId": "770170", "orderNo": "GT-26-0102", "contactName": "周磊",
        "peopleCount": 2, "status": "DONE", "statusText": "已指派", "needsIt": true, "updateTime": null },
      { "orderId": "770171", "orderNo": "GT-26-0103", "contactName": "吴芳",
        "peopleCount": 1, "status": "NONE", "statusText": "无需", "needsIt": false, "updateTime": null }
    ]
  },
  "success": true
}
```

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

```json
{ "code": 200, "data": { "batchId": "90211", "chipLabel": "配导游",
  "aggregateStatus": "整团待办", "totalCount": 0, "doneCount": 0, "items": [] },
  "success": true }
```

#### 错误响应

```json
{ "code": 589500, "message": "团期不存在", "success": false, "data": null }
```

#### 业务边界

- 授权码 `group-batch:view`；未配置权限 → 589507。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- 免闸户（needsIt=false）status 为 `NONE`（非 null），与房/车（null）区分；前端按 NONE 置灰。

### 4. GB-ADM-093 配摄影逐户明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/photo`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期看板行右侧「摄」芯片点击展开：返回每户配摄影进度。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| groupBatchId | Path | String | ✅ | 团期 ID（Snowflake） | 不存在/非团期/已软删 → 589500 |

无查询参数、无请求体。

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId | String | 团期 ID |
| chipLabel | String | 固定「配摄影」 |
| aggregateStatus | String | 整团聚合态 四态取值与看板 GB-ADM-001 `chips.X` 的 `aggregateStatus` 完全一致（整团待办/进行中/已完成/异常） |
| totalCount | Integer | 计入统计的子订单数（免闸户不计入） |
| doneCount | Integer | 已完成户数（`status==DONE`） |
| items[].orderId | String | 子订单 ID（JSON String 化） |
| items[].orderNo | String | 子订单编号 |
| items[].contactName | String | 联系人/客户姓名 |
| items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby |
| items[].status | String | 本户配摄影状态，3 值：`NONE` 无需/未开始 / `PENDING` 待指派 / `DONE` 已指派，见「六.5」 |
| items[].statusText | String | 状态中文名（服务端给出，见「六.5」） |
| items[].needsIt | Boolean | 本户是否需要配摄影（`order_main.needs_photographer`）；false=免闸户 status 恒 `NONE`、不计入计数 |
| items[].updateTime | String | 配摄影最后变更时间；无独立时间戳时为 null |

#### 请求示例

```http
GET /v3/admin/order/group-batch/90211/chips/photo
Authorization: Bearer ****
X-Admin-Id: 3301
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "配摄影",
    "aggregateStatus": "DOING",
    "totalCount": 3,
    "doneCount": 1,
    "items": [
      { "orderId": "770180", "orderNo": "GT-26-0104", "contactName": "郑涛",
        "peopleCount": 2, "status": "DONE", "statusText": "已指派", "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}
```

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

```json
{ "code": 200, "data": { "batchId": "90211", "chipLabel": "配摄影",
  "aggregateStatus": "整团待办", "totalCount": 0, "doneCount": 0, "items": [] },
  "success": true }
```

#### 错误响应

```json
{ "code": 589500, "message": "团期不存在", "success": false, "data": null }
```

#### 业务边界

- 授权码 `group-batch:view`；未配置权限 → 589507。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- 免闸户（needsIt=false）status 为 `NONE`（非 null），前端按 NONE 置灰。

### 5. GB-ADM-094 合同逐户明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/contract`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期看板行右侧「约」芯片点击展开：返回每户合同（团约）进度。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| groupBatchId | Path | String | ✅ | 团期 ID（Snowflake） | 不存在/非团期/已软删 → 589500 |

无查询参数、无请求体。

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId | String | 团期 ID |
| chipLabel | String | 固定「合同」 |
| aggregateStatus | String | 整团聚合态 四态取值与看板 GB-ADM-001 `chips.X` 的 `aggregateStatus` 完全一致（整团待办/进行中/已完成/异常） |
| totalCount | Integer | 计入统计的子订单数（免闸户不计入） |
| doneCount | Integer | 已完成户数（`status==SIGNED`） |
| items[].orderId | String | 子订单 ID（JSON String 化） |
| items[].orderNo | String | 子订单编号 |
| items[].contactName | String | 联系人/客户姓名 |
| items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby |
| items[].status | String | 本户合同状态（`ContractStatus`），见「六.5」；无合同记录为 null |
| items[].statusText | String | 状态中文名（服务端给出，见「六.5」）；无合同为「无合同」 |
| items[].needsIt | Boolean | 本户是否需要合同（`order_main.needs_contract`）；false=免闸户不计入 |
| items[].updateTime | String | 合同最后变更时间；无独立时间戳时为 null |

#### 请求示例

```http
GET /v3/admin/order/group-batch/90211/chips/contract
Authorization: Bearer ****
X-Admin-Id: 3301
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "合同",
    "aggregateStatus": "整团待办",
    "totalCount": 1,
    "doneCount": 0,
    "items": [
      { "orderId": "770190", "orderNo": "GT-26-0105", "contactName": "钱进",
        "peopleCount": 2, "status": "SIGNED", "statusText": "已签署", "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}
```

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

```json
{ "code": 200, "data": { "batchId": "90211", "chipLabel": "合同",
  "aggregateStatus": "整团待办", "totalCount": 0, "doneCount": 0, "items": [] },
  "success": true }
```

#### 错误响应

```json
{ "code": 589500, "message": "团期不存在", "success": false, "data": null }
```

#### 业务边界

- 授权码 `group-batch:view`；未配置权限 → 589507。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- 老数据无合同记录：status=null、statusText=「无合同」，不异常不计入。

### 6. GB-ADM-095 保险逐户明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/insurance`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期看板行右侧「保」芯片点击展开：返回每户保险进度。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| groupBatchId | Path | String | ✅ | 团期 ID（Snowflake） | 不存在/非团期/已软删 → 589500 |

无查询参数、无请求体。

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId | String | 团期 ID |
| chipLabel | String | 固定「保险」 |
| aggregateStatus | String | 整团聚合态 四态取值与看板 GB-ADM-001 `chips.X` 的 `aggregateStatus` 完全一致（整团待办/进行中/已完成/异常） |
| totalCount | Integer | 计入统计的子订单数（免闸户不计入） |
| doneCount | Integer | 已完成户数（`status==INSURED`） |
| items[].orderId | String | 子订单 ID（JSON String 化） |
| items[].orderNo | String | 子订单编号 |
| items[].contactName | String | 联系人/客户姓名 |
| items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby |
| items[].status | String | 本户保险状态，见「六.5」；无保险记录为 null |
| items[].statusText | String | 状态中文名（服务端给出，见「六.5」）；无保险为「无保险」 |
| items[].needsIt | Boolean | 本户是否需要保险（`order_main.needs_insurance`）；false=免闸户不计入 |
| items[].updateTime | String | 保险最后变更时间；无独立时间戳时为 null |

#### 请求示例

```http
GET /v3/admin/order/group-batch/90211/chips/insurance
Authorization: Bearer ****
X-Admin-Id: 3301
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "保险",
    "aggregateStatus": "整团待办",
    "totalCount": 1,
    "doneCount": 0,
    "items": [
      { "orderId": "770200", "orderNo": "GT-26-0106", "contactName": "孙丽",
        "peopleCount": 2, "status": "INSURED", "statusText": "已出单", "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}
```

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

```json
{ "code": 200, "data": { "batchId": "90211", "chipLabel": "保险",
  "aggregateStatus": "整团待办", "totalCount": 0, "doneCount": 0, "items": [] },
  "success": true }
```

#### 错误响应

```json
{ "code": 589500, "message": "团期不存在", "success": false, "data": null }
```

#### 业务边界

- 授权码 `group-batch:view`；未配置权限 → 589507。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- 老数据无保险记录：status=null、statusText=「无保险」，不异常不计入。

---

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

- **只读**：六端点全部为 GET 查询，READ_ONLY 事务，不产生任何写操作；重复调用结果一致（无副作用）。
- **授权**：必须携带管理端登录令牌，网关校验 `group-batch:view` 权限；未配置权限 → 589507。
- **入参**：仅 Path 参数 `groupBatchId`（Snowflake 团期 ID），无查询参数、无请求体。
- **安全**：读端 18 列专用投影不含任何手机号/证件列，**不会返回也不解密 `customerPhone` / `emergencyContactPhone`**；前端不得依赖此类字段。
- **免闸口径**：`needsIt=false` 户不计入 totalCount/doneCount；房/车/约/保 status=null+「无需」/「无合同」/「无保险」，导/摄 status=`NONE`+「无需」。
- **聚合态**：`aggregateStatus` 与看板 GB-ADM-001 `chips.X` 同源同算法（共享 `GroupBatchChipResolver`）。

---

## 六、边界行为

- 未登录/无有效 token → 401（网关拦截，本组接口不允许匿名访问）。
- 未配置 `group-batch:view` 权限 → 589507 无操作权限。
- 团期不存在/非团期/已软删 → 589500 团期不存在。
- 任意芯片端点输入非法（groupBatchId 非数字）→ 400 参数错误（框架级）。
- 空团期/无活跃子订单 → data 正常返回：totalCount=0、doneCount=0、items=[]，不 500 不降级。
- 下游数据缺失（老数据无对应需求/合同/保险记录）→ 对应 status 为 null（房/车/约/保）或 NONE（导/摄），不异常。
- 团期流团（CANCELLED）→ aggregateStatus 恒整团待办（wire 值同看板 chips.X），明细仍如实返回。
- 已返团（审核/结算）→ 房车导摄恒 DONE 聚合。
- 列表查询与整团伙计数一次性内存聚合（防 N+1），单次请求最多一次投影查询。

---

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

| 维度 | 修改前（#6903） | 修改后（#6921） |
|------|------|------|
| 读端数据源 | 加载 `OrderInfo` 整行实体再取字段 | `order_main` **18 列专用投影**（`listChipProjectionByProductBatchIds`），不再整行加载 |
| 手机号解密 | 读端会触发 `customerPhone` / `emergencyContactPhone` 解密（本单实测从未返回，但存在触发路径） | 投影列不含手机号列，**编译期零手机列、运行时零解密** |
| 车芯片 statusText | 与房同文案（待房务配/配房中/配房完成） | **车务文案**：待车务配/配车中/配车完成（驳回文案与房一致） |
| 对外响应结构 | `GroupBatchChipDetailVO` | 完全一致（无字段新增/删除/改名） |
| 错误码/聚合/免闸口径 | 同 #6903 | 完全一致 |

## 六.7、影响评估

- **调用方影响**：无。响应结构、字段名、枚举、错误码、聚合态、免闸计数口径全部不变，管理后台前端无需改动。
- **性能**：读端从整行实体 + 可能触发解密，改为 18 列投影 + 内存聚合，减少列宽与解密开销（本单不涉及额外查询次数）。
- **安全**：消除读端手机号解密触发路径，减少无关敏感字段暴露面。
- **回归范围**：六芯片端点 + 共享 `GroupBatchChipResolver` 文案；已用模块全量 7874 用例回归，仅 3 个 dev-v3 既有 refund 401 基线用例失败（与本单无关）。
- **其他服务**：不涉及 Feign/域事件/表结构变更，未触碰 #6905 GroupBatchQueryService 与 OrderInfoMapper 契约。

---

## 七、不影响范围

- 写操作（配房/配车/配导/配摄/合同/保险状态流转）
- 下单/支付/退款链路
- 数据库表结构（零迁移）
- #6905 团期看板 4 接口（GB-ADM-000/001/002/003，本单未改）
- OrderInfoMapper 既有查询契约（仅新增只读投影方法，未改任何既有方法）
- 前端展示逻辑（本次为纯后端返工，前端无需改动）

## 八、测试环境已验证

网关: `https://api.test.1814.love:9443`（`/v3/admin/**` → hl-order-service-v3，dev-v3 @ `0d5f8c568`，双实例 8086/8186 UP）

- 6 端点对真实团期 `2089713777065832450` 网关实测全通过：hotel/vehicle/guide/photo/contract/insurance → 200 code=200，chipLabel 正确，items 在位 ✓
- 团期不存在 `999999999999999999` → 589500 团期不存在 ✓
- 测试数据无 PROCESSING/DONE 态订单（status 全空或无需/无合同/无保险），车务文案（待车务配/配车中/配车完成）由 `GroupBatchChipResolverTest` 单测锁定 ✓
- 本地：chip 定向 229 用例全绿；模块全量 7874 用例仅 3 个 dev-v3 refund 401 基线失败（与本单无关）✓

## 九、相关历史 PR

| PR | Issue | 说明 | 是否仍有效 |
|----|-------|------|------------|
| #6902 | #6902 | 共享件（chip/stats/buckets） | ✅ 依赖 |
| #6903 | #6903 | 六芯片逐户明细新增接口（本单返工对象） | ✅ 有效 |
| #6916 | #6915 | 共享地基 statusText 契约文案修正 + 测试补齐 | ✅ 依赖 |
| #6924 | #6921 | 本单复审返工（读端投影 + 车务文案）squash 合并 `35b7f2ed` | ✅ 最新 |

## 十、相关文档

- 关联 Issue: [wx/HL#6921](https://git.1814.love:8443/wx/HL/issues/6921)
- 关联 PR: [wx/HL#6924](https://git.1814.love:8443/wx/HL/pulls/6924)
- 合并落点: [wx/HL commit 35b7f2ed](https://git.1814.love:8443/wx/HL/commit/35b7f2ed)（dev-v3）
- 原接口文档: #6903 `01_6903_团期看板六芯片逐户明细-GB-ADM-090~095-新增接口-管理后台.md`（本单已同步其车务文案描述）

## 关联 / 联系人

### 链接

- **Issue**: [#6921](https://git.1814.love:8443/wx/HL/issues/6921)
- **PR**: [#6924](https://git.1814.love:8443/wx/HL/pulls/6924)（squash 合并）
- **Merge commit**: [35b7f2ed](https://git.1814.love:8443/wx/HL/commit/35b7f2ed)（dev-v3 落点）

### 联系人

- 后端: wx(GIT)
- 前端: 待定（本次无前端改动）