文件

T

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): 补齐 17 条消费闭环 frontmatter 回写

11 条有业务交付改判 verified(#6397/6903/6904/6905/6950/6979/6986/7013/7029/7036/7066,owner=mmg+对应业务 commit ref+交付日 verified_at);
6 条实证零改动改判 not_required(#6014/6016/6140/6938/6842/7087,仅翻 frontend_status 不填 owner/ref)。
#5935 挂起待后端补字段,保持 pending 不动。sync-log 均已记账。

2026-09-06 10:43:20 +08:00

30 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	6903	团期看板六芯片逐户明细 GB-ADM-090~095	admin	wx(GIT)	新增接口	deployed	verified	verified	mmg	c91163fc		2026-09-01	2026-09-01 部署测试服 dev-v3@1159c8949，6 端点网关实测 200 全通过，团期不存在 589500 / 参数错误 400 已核验。前端评估(2026-09-01)：团期看板 src/views/order-v2/batch 当前为纯本地 mock 阶段(period 用 mock id，全仓无真实 group-batch 调用)，chips 端点需真实雪花 groupBatchId，下钻暂无真实落脚页。决策：先接真团期看板(需 GB-ADM-001 看板列表契约+真实 groupBatchId，不在本单)再接六芯片下钻，下钻形态已定=弹层明细。待看板列表契约后接入，跟踪见 hl-admin 任务 #104。	2026-09-01	dev-v3

团期看板：六芯片逐户明细（GB-ADM-090~095，房/车/导/摄/约/保）

存放目录: 二期（order-v3）→ changelogs-v2/2026-09/

服务: hl-order-service-v3 Issue: #6903 日期: 2026-09-01 影响范围: 管理后台团期看板行右侧六芯片（配房/配车/配导游/配摄影/合同/保险）点击后的逐户下钻

⚠️ 关键变化

新增能力，无破坏性变化：先前看板芯片只有整团聚合色块（GB-ADM-001 chips.X）、没有逐户下钻；本次把「点芯片看每户到哪一步」补成可调用接口。数据（order_main 六态列）早已落库并被房务/车队/地接等 Service 消费，本组接口只读透出，不改变任何业务状态。

一、背景（选填）

团期看板行右侧有「房/车/导/摄/约/保」六个芯片，点击后按需展开该项的逐户明细。逐户口径与整团聚合、看板芯片（GB-ADM-001 chips.X）同源同算法（共享地基 GroupBatchChipResolver，#6902/#6916）。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
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`	新增接口	车芯片逐户下钻
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，正文各自自包含。

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` 完全一致（整团待办/进行中/已完成/异常），与 GB-ADM-001 `chips.hotel` 同源同算法
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

请求示例

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

响应示例

{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "配房",
    "aggregateStatus": "DOING",
    "totalCount": 7,
    "doneCount": 5,
    "items": [
      { "orderId": "770152", "orderNo": "GT-26-0096", "contactName": "陈昊",
        "peopleCount": 2, "status": "DONE", "statusText": "配房完成",
        "needsIt": true, "updateTime": null },
      { "orderId": "770153", "orderNo": "GT-26-0097", "contactName": "林婉清",
        "peopleCount": 3, "status": null, "statusText": "无需",
        "needsIt": false, "updateTime": null }
    ]
  },
  "success": true
}

空数据 / 降级响应

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

错误响应

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

业务边界

授权码 group-batch:view；未配置权限 → 589507。
只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
免闸户（needsIt=false）：status=null、statusText=「无需」、前端置灰、不计入 totalCount/doneCount 分子分母。
已取消子订单不计入（活跃口径与共享地基一致）。
团期已流团（CANCELLED）→ aggregateStatus 恒整团待办（wire 值同看板 chips.X），但逐户明细仍如实返回（不造假计数）。

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

请求示例

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

响应示例

{
  "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
}

空数据 / 降级响应

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

错误响应

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

业务边界

授权码 group-batch:view；未配置权限 → 589507。
只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
免闸户（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

请求示例

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

响应示例

{
  "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
}

空数据 / 降级响应

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

错误响应

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

业务边界

授权码 group-batch:view；未配置权限 → 589507。
只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
免闸户（needsIt=false）status 为 NONE（非 null），与房/车（null）区分；前端按 NONE 置灰。
读侧只认 DONE，其余非免闸状态一律 PENDING；已取消子订单不计入；流团团期聚合恒整团待办。

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

请求示例

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

响应示例

{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "配摄影",
    "aggregateStatus": "整团待办",
    "totalCount": 1,
    "doneCount": 0,
    "items": [
      { "orderId": "770180", "orderNo": "GT-26-0104", "contactName": "郑浩",
        "peopleCount": 2, "status": "PENDING", "statusText": "待指派", "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}

空数据 / 降级响应

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

错误响应

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

业务边界

授权码 group-batch:view；未配置权限 → 589507。
只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
免闸户（needsIt=false）status 为 NONE（非 null），与导芯片一致。
读侧只认 DONE，其余非免闸状态一律 PENDING；已取消子订单不计入；流团团期聚合恒整团待办。

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` 完全一致（整团待办/进行中/已完成/异常）；房车导摄四项未全 DONE 前恒整团待办（硬规则；wire 值同看板 chips.X）
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` 8 值，见「六.5」；无合同为 null
items[].statusText	String	状态中文名（服务端给出，见「六.5」）
items[].needsIt	Boolean	恒 true（约/保无免闸）
items[].updateTime	String	合同最后变更时间；无独立时间戳时为 null

请求示例

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

响应示例

{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "合同",
    "aggregateStatus": "DOING",
    "totalCount": 2,
    "doneCount": 1,
    "items": [
      { "orderId": "770190", "orderNo": "GT-26-0105", "contactName": "钱进",
        "peopleCount": 2, "status": "SIGNED", "statusText": "已签署", "needsIt": true, "updateTime": null },
      { "orderId": "770191", "orderNo": "GT-26-0106", "contactName": "孙丽",
        "peopleCount": 2, "status": "PENDING", "statusText": "待出具", "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}

空数据 / 降级响应

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

错误响应

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

业务边界

授权码 group-batch:view；未配置权限 → 589507。
只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
needsIt 恒 true（约/保无免闸户）；doneCount 只按 SIGNED；作废中/已作废计入整团 ERROR。
约/保整团聚合在房车导摄四芯片未全部 DONE 前恒整团待办（硬规则）；已取消子订单不计入；流团团期聚合恒整团待办。

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` 完全一致（整团待办/进行中/已完成/异常）；房车导摄未全 DONE 前恒整团待办（硬规则；wire 值同看板 chips.X）
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	本户保险状态，4 值：`INSURING` 投保中 / `INSURED` 已出单 / `CANCELLED` 已取消 / `FAILED` 出单失败；无保险为 null
items[].statusText	String	状态中文名（服务端给出，见「六.5」）
items[].needsIt	Boolean	恒 true（约/保无免闸）
items[].updateTime	String	保险最后变更时间；无独立时间戳时为 null

请求示例

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

响应示例

{
  "code": 200,
  "data": {
    "batchId": "90211",
    "chipLabel": "保险",
    "aggregateStatus": "DOING",
    "totalCount": 2,
    "doneCount": 1,
    "items": [
      { "orderId": "770200", "orderNo": "GT-26-0107", "contactName": "李娜",
        "peopleCount": 2, "status": "INSURED", "statusText": "已出单", "needsIt": true, "updateTime": null },
      { "orderId": "770201", "orderNo": "GT-26-0108", "contactName": "赵敏",
        "peopleCount": 3, "status": "INSURING", "statusText": "出单中", "needsIt": true, "updateTime": null }
    ]
  },
  "success": true
}

空数据 / 降级响应

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

错误响应

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

业务边界

授权码 group-batch:view；未配置权限 → 589507。
只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
needsIt 恒 true；doneCount 只按 INSURED；已取消/出单失败计入整团 ERROR。
约/保整团聚合在房车导摄未全 DONE 前恒整团待办（硬规则）；已取消子订单不计入；流团团期聚合恒整团待办。

四、契约约束与正确调用方式（接口类必写）

本节只写后端接受/拒绝请求的规则，不写 UI 渲染建议。

✅ 正确 / ❌ 错误调用对照

场景	说明
✅ 网关已注入 X-Admin-Id，调任一芯片端点	返回 `Result<GroupBatchChipDetailVO>`，code=200
✅ 免闸户（needsIt=false）	房/车 status=null；导/摄 status=NONE；不计入 totalCount/doneCount
❌ 未配置 `group-batch:view` 权限	589507 无操作权限
❌ groupBatchId 不存在/非团期/已软删	589500 团期不存在
❌ 客户端自行传 X-Admin-Id	以网关注入值为准，客户端值一律忽略（不校验客户端值）

切换状态时的必要动作

无状态切换——六个端点均为只读 GET、无请求体；前端点击芯片即查询，请求方不需要携带任何业务状态字段，也不修改任何状态。

五、数据库行为（涉及写操作时必写）

本组接口无写操作（READ_ONLY 事务），无表变更、无字段变更、无数据迁移。数据来源即为现有 order_main 六态列（needs_hotel/needs_vehicle/needs_guide/needs_photographer/合同状态/保险状态），由共享地基读取投影。

六、边界行为

未登录/无有效 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），单次请求最多一次 listByProductBatchId 查询。

六.5、枚举 / 数据字典（接口出现枚举时必写）

items[].status（配房/配车，`com.hulalv.order.core.enums.RequirementStatus`）

所属字段: GroupBatchChipItemRespVO.status | 类型: String

值	中文（statusText）	说明
`PENDING`	待房务配（房）/ 待车务配（车）	待房务/车队配
`PROCESSING`	配房中（房）/ 配车中（车）	配置进行中
`DONE`	配房完成（房）/ 配车完成（车）	已完成（房/车分文案，#6921）
`PENDING_REVIEW`	待审核	待复核
`REJECTED_TO_CONSULTANT`	驳回给定制师	失败态（计入整团 ERROR）
`REJECTED_TO_ADMIN`	驳回给管理员	失败态（计入整团 ERROR）

items[].status（配导游/配摄影）

所属字段: GroupBatchChipItemRespVO.status | 类型: String

值	中文（statusText）	说明
`NONE`	无需	免闸户/未开始（免闸户恒 NONE）
`PENDING`	待指派	读侧非免闸非 DONE 一律 PENDING
`DONE`	已指派	已完成

items[].status（合同，`com.hulalv.order.*.ContractStatus`）

所属字段: GroupBatchChipItemRespVO.status | 类型: String

值	中文（statusText）	说明
`PENDING`	待出具	待生成
`GENERATED`	已生成	-
`REPORTED`	已报备	-
`UPLOADED`	已上传	-
`SIGNING`	签署中	-
`SIGNED`	已签署	doneCount 判定值
`VOIDING`	作废中	失败态（计入整团 ERROR）
`VOIDED`	已作废	失败态（计入整团 ERROR）

items[].status（保险）

所属字段: GroupBatchChipItemRespVO.status | 类型: String

值	中文（statusText）	说明
`INSURING`	出单中	投保中
`INSURED`	已出单	doneCount 判定值
`CANCELLED`	已取消	失败态（计入整团 ERROR）
`FAILED`	出单失败	失败态（计入整团 ERROR）

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

仅影响: 管理后台团期看板六芯片的逐户明细展示层接口（GB-ADM-090~095）。
零影响:
- 看板整团聚合接口（GB-ADM-001 chips.X 结构不变）
- 房务/车队/地接/合同/保险的任何写接口与业务流程（本组只读）
- 一期（v2）所有接口
- 数据库结构、网关路由、权限点（复用既有 group-batch:view）

八、测试环境已验证

JUnit 定向测试: GroupBatchChipServiceTest（12 用例）+ GroupBatchChipControllerTest（7 用例）+ 共享地基 GroupBatchChipResolverTest（18 用例）全绿，覆盖六端点、聚合态、免闸户、错误码 589500/589507、权限校验。

真实接口网关验证（2026-09-01 部署 dev-v3 @1159c8949 后实测）：

测试团期: groupBatchId=2089713777065832450（batch Q202610312089667212070612994，RESOURCE_PREPARING，含 1 活跃子订单）

聚合态 aggregateStatus wire 英文四态值与看板 GB-ADM-001 chips.X 完全一致（读侧同源同算法）；下表按中文态名展示实测结果。

GET /v3/admin/order/group-batch/2089713777065832450/chips/hotel     → 200 code=200  aggregateStatus=整团待办 total=1 done=0 items=1 ✓
GET /v3/admin/order/group-batch/2089713777065832450/chips/vehicle  → 200 code=200  aggregateStatus=整团待办 total=1 done=0 items=1 ✓
GET /v3/admin/order/group-batch/2089713777065832450/chips/guide    → 200 code=200  aggregateStatus=整团待办 total=0 items=1（needsIt=false 免闸不计 total，"无需"）✓
GET /v3/admin/order/group-batch/2089713777065832450/chips/photo    → 200 code=200  aggregateStatus=整团待办 total=0 items=1（免闸，"无需"）✓
GET /v3/admin/order/group-batch/2089713777065832450/chips/contract → 200 code=200  aggregateStatus=整团待办 total=1 items=1（无合同 → statusText="无合同"）✓
GET /v3/admin/order/group-batch/2089713777065832450/chips/insurance→ 200 code=200  aggregateStatus=整团待办 total=1 items=1（无保险 → statusText="无保险"）✓
GET /v3/admin/order/group-batch/999999999999999999/chips/hotel     → 200 code=589500 message="团期不存在" ✓
GET /v3/admin/order/group-batch/abc/chips/hotel                    → 200 code=400 message="参数 groupBatchId 格式错误，请检查后重试" ✓

验证通道: 统一网关 https://api.test.1814.love:9443，管理员登录 token + 网关注入 X-Admin-Id。

九、相关历史 PR（纠错 / 功能演进时必写）

PR	Issue	说明	是否仍有效
#6916	#6915	共享地基 statusText 契约文案修正 + 测试补齐（本单契约基础）	✅ 有效
本 PR（#6903 分支合并）	#6903	六芯片逐户明细接口交付	✅ 最新

十、相关文档

关联 Issue: wx/HL#6903
关联 PR: wx/HL#6918（squash 合并至 dev-v3 @1159c8949）
共享地基: #6902（Resolver/看板聚合）、#6916（statusText 契约修正）

30 KiB 原始文件 Blame 文件历史 Unescape Escape

团期看板：六芯片逐户明细（GB-ADM-090~095，房/车/导/摄/约/保）

⚠️ 关键变化

一、背景（选填）

二、变更接口清单

三、接口详情

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

使用场景

入参

出参 Result<GroupBatchChipDetailVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参 Result<GroupBatchChipDetailVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参 Result<GroupBatchChipDetailVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参 Result<GroupBatchChipDetailVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参 Result<GroupBatchChipDetailVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参 Result<GroupBatchChipDetailVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式（接口类必写）

✅ 正确 / ❌ 错误调用对照

切换状态时的必要动作

五、数据库行为（涉及写操作时必写）

六、边界行为

六.5、枚举 / 数据字典（接口出现枚举时必写）

items[].status（配房/配车，com.hulalv.order.core.enums.RequirementStatus）

items[].status（配导游/配摄影）

items[].status（合同，com.hulalv.order.*.ContractStatus）

items[].status（保险）

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

八、测试环境已验证

九、相关历史 PR（纠错 / 功能演进时必写）

十、相关文档

关联 / 联系人

链接

联系人

30 KiB

原始文件 Blame 文件历史

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

出参 `Result<GroupBatchChipDetailVO>`

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

出参 `Result<GroupBatchChipDetailVO>`

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

出参 `Result<GroupBatchChipDetailVO>`

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

出参 `Result<GroupBatchChipDetailVO>`

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

出参 `Result<GroupBatchChipDetailVO>`

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

出参 `Result<GroupBatchChipDetailVO>`

items[].status（配房/配车，`com.hulalv.order.core.enums.RequirementStatus`）

items[].status（合同，`com.hulalv.order.*.ContractStatus`）