diff --git a/changelogs-v2/2026-09/01_6903_团期看板六芯片逐户明细-GB-ADM-090~095-新增接口-管理后台.md b/changelogs-v2/2026-09/01_6903_团期看板六芯片逐户明细-GB-ADM-090~095-新增接口-管理后台.md index f48f4cd1..0f429e28 100644 --- a/changelogs-v2/2026-09/01_6903_团期看板六芯片逐户明细-GB-ADM-090~095-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/01_6903_团期看板六芯片逐户明细-GB-ADM-090~095-新增接口-管理后台.md @@ -181,7 +181,7 @@ X-Admin-Id: 3301 | items[].contactName | String | 联系人/客户姓名 | | items[].peopleCount | Integer | 本户人数 = adult+child+youngChild+baby | | items[].status | String | 本户配车状态，`RequirementStatus` 6 值，见「六.5」；无需/未开始为 null | -| items[].statusText | String | 状态中文名（服务端给出，与房同文案，见「六.5」） | +| items[].statusText | String | 状态中文名（服务端给出，车务文案：待车务配/配车中/配车完成/待审核/驳回给定制师/驳回给管理员，见「六.5」） | | items[].needsIt | Boolean | 本户是否需要配车（`order_main.needs_vehicle`）；false=免闸户置灰不计入 | | items[].updateTime | String | 配车最后变更时间；无独立时间戳时为 null | @@ -206,7 +206,7 @@ X-Admin-Id: 3301 "doneCount": 3, "items": [ { "orderId": "770160", "orderNo": "GT-26-0101", "contactName": "王强", - "peopleCount": 2, "status": "DONE", "statusText": "配房完成", + "peopleCount": 2, "status": "DONE", "statusText": "配车完成", "needsIt": true, "updateTime": null } ] }, @@ -639,9 +639,9 @@ X-Admin-Id: 3301 | 值 | 中文（statusText） | 说明 | |----|------|------| -| `PENDING` | 待房务配 | 待房务/车队配 | -| `PROCESSING` | 配房中 | 配置进行中 | -| `DONE` | 配房完成 | 已完成（房/车同文案） | +| `PENDING` | 待房务配（房）/ 待车务配（车） | 待房务/车队配 | +| `PROCESSING` | 配房中（房）/ 配车中（车） | 配置进行中 | +| `DONE` | 配房完成（房）/ 配车完成（车） | 已完成（房/车分文案，#6921） | | `PENDING_REVIEW` | 待审核 | 待复核 | | `REJECTED_TO_CONSULTANT` | 驳回给定制师 | 失败态（计入整团 ERROR） | | `REJECTED_TO_ADMIN` | 驳回给管理员 | 失败态（计入整团 ERROR） | diff --git a/changelogs-v2/2026-09/01_6921_六芯片读端接入专用投影车芯片车务文案修正-修改接口-管理后台.md b/changelogs-v2/2026-09/01_6921_六芯片读端接入专用投影车芯片车务文案修正-修改接口-管理后台.md new file mode 100644 index 00000000..caf4b55e --- /dev/null +++ b/changelogs-v2/2026-09/01_6921_六芯片读端接入专用投影车芯片车务文案修正-修改接口-管理后台.md @@ -0,0 +1,662 @@ +--- +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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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) +- 前端: 待定（本次无前端改动）