From b224d430a46216e173cba15ef7a814426c94f868 Mon Sep 17 00:00:00 2001
From: jw <jinwei@1814.love>
Date: Mon, 28 Sep 2026 18:54:00 +0800
Subject: [PATCH] =?UTF-8?q?docs(order-v3):=20=E5=9B=A2=E6=9C=9F=E5=AF=BC/?=
 =?UTF-8?q?=E6=91=84=E8=8A=AF=E7=89=87=E7=8A=B6=E6=80=81=E6=94=B9=E6=8C=89?=
 =?UTF-8?q?=E5=9B=A2=E6=9C=9F=E5=90=8D=E5=86=8C=E8=AE=A1=E7=AE=97=E4=BA=A4?=
 =?UTF-8?q?=E6=8E=A5=E4=BB=B6=EF=BC=88#8469=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...„芯片状æ€�改按团期å��册计算-修改接å�£-管ç�†å�Žå�°.md | 1123 +++++++++++++++++
 1 file changed, 1123 insertions(+)
 create mode 100644 changelogs-v2/2026-09/28_8469_团期导摄芯片状�改按团期�册计算-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/28_8469_团期导摄芯片状�改按团期�册计算-修改接�-管���.md b/changelogs-v2/2026-09/28_8469_团期导摄芯片状�改按团期�册计算-修改接�-管���.md
new file mode 100644
index 00000000..2056a770
--- /dev/null
+++ b/changelogs-v2/2026-09/28_8469_团期导摄芯片状�改按团期�册计算-修改接�-管���.md
@@ -0,0 +1,1123 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8469"
+title: "团期看�导/摄芯片状�改按团期�册计算，��/�险芯片门控�之�化"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8489 已�入 dev-v3（2c87b0618），TEST 的 hl-order-service-v3 �行 dev-v3 2c87b0618；�网关 api.test.1814.love 用真实 admin token 实测 AC-1~AC-6�AC-9 通过（验收脚本 22/22）。5 个接�结构�字段��枚举值集��，颜色渲染逻辑�用改；导/摄计数��由户�为�册�，看�悬� 0/0 与导/摄页签�芯片弹层的按户文案需�端核对（�第四节交接清�），故 frontend_status 记 pending。"
+updated_at: "2026-09-28"
+base: "dev-v3"
+---
+
+# 团期看�：导/摄芯片状�改按团期�册计算（管���）
+
+> **�务**: hl-order-service-v3（团期看�列表�团期芯片明细）
+> **PR**: #8489（�入 dev-v3 为 `2c87b0618`）
+> **Issue**: #8469
+> **日期**: 2026-09-28
+> **影�范围**: 团期看��行「导 / 摄�芯片颜色与悬�计数�「�� / �险�芯片颜色；团期详情「�导游�「�摄影�页签的状�标签与计数；看�点导 / 摄 / �� / �险芯片弹出的明细
+
+---
+
+## ⚠� 关键�化
+
+1. **导 / 摄芯片改按团期�册算，��按户**：看�列表的 `records[].chips.guide` / `chips.photo` 与芯片明细 `GET .../chips/guide`�`GET .../chips/photo` 的 `aggregateStatus` �一�径——团期�册里这一�有人就是 `DONE`；�册没人时，�有「团期已�团�未返团�且团期标记为整团�需���是 `DONE`，其余都是 `TODO`。�团� `TODO`�已返团� `DONE` 两�硬规则��。完整判定表�六.5。
+2. **导 / 摄��出现 `DOING`**（改�「部分户已指派�是 `DOING`），也�会出现 `ERROR`；`chipStats.guide.error` / `chipStats.photo.error` �为 0。
+3. **导 / 摄计数���了：从「户���「�册的这一��**。`chipStats.guide/photo` 的 `total/done` 与明细的 `totalCount/doneCount` �有三��值：�册有人 `total=1, done=1`；�团�整团�需�且�册没人 `total=0, done=0`；其余 `total=1, done=0`。���按户数展示，也��与 `orderCount` 比较。
+4. **�� / �险芯片的起点�之�化**：「房 / 车 / 导 / 摄四项全部 `DONE` �，�� / �险� `TODO`�这�规则现在�新的导 / 摄结果。整团�需�导摄�或�册已��的团��被导 / 摄��；�� / �险自身的 `totalCount`�`doneCount`�`chipStats` 与�户 `items` ��。
+5. **接�结构�字段��枚举值集全部��**，颜色映射（`TODO` � / `DOING` 橙 / `DONE` 绿 / `ERROR` 红）照旧。�端�核对的�有按户文案与 0/0 悬�（�第四节「�端交接清��）。
+
+---
+
+## 一�背景
+
+团期详情导游 / 摄影页签的状�标签�看�导 / 摄芯片颜色和悬�「已完� done/total�原�都按户算：�统计需�导游 / 摄影的�订�（户），�看�户有没有指派。�订�都「无需�时计入户数为 0，状�就一直是「待开始�，�使团期�册里已�派了人；����险芯片��等房车导摄四项�了�开始，于是一起��。
+
+测试�实例：团期 `2101506167098511362`（jw测试1期，物料准备中，12 户都无需�导游，�册导游� 2 �领队�摄影� 1 人），改�导游页签显示「待开始 · 共 0 户计入 · 已完� 0 户�，��芯片 `TODO`（10/12 已签署）��险芯片 `TODO`（12/12 已出�）。
+
+jw 2026-09-28 定案�径（出自工� D1~D8，按��最终实现表述）：
+
+| # | �径 |
+|---|---|
+| D1 | 团期�册本�（导游� / 摄影�）有人 → 完�；没人 → 待开始（�团��的细分� D5�D6） |
+| D2 | 两�硬规则��：团期已�团 → 待开始；已返团（出行完毕 / 核�中 / 已结算）→ 完� |
+| D3 | 看�列表�团期详情页签�芯片明细接�三处�一�径��一�值 |
+| D4 | �� / �险「房车导摄四项全部完���待开始�，导 / 摄两项改� D1 的结果 |
+| D5 | 招募中�看�册：有人 → 完�，没人 → 待开始；团期上的「需�导游 / 需�摄影�标记在招募中还没写入（�团时�由�订�汇总写入），��与判断 |
+| D6 | 已�团未返团（资�准备中 / 物料准备中 / 待出� / 出行中）：�册有人 → 完�；�册没人时，团期标记为「�需��→ 完�，「需��→ 待开始 |
+| D7 | 计数：�册有人 1/1，没人 0/1（done/total）；�团�整团�需�且�册没人 → 0/0 |
+| D8 | 导游�默认 = 导游 `GUIDE` + 领队 `LEADER`，摄影� = 摄影 `PHOTOGRAPHER`（与团期人员�置�芯片明细 `staffList` �一�径）；导 / 摄��有「进行中�，失败数� 0 |
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期分页列表（看�，GB-ADM-001） | GET | `/v3/admin/order/group-batch` | 修改：出��值语义�化 | `records[].chips.guide/photo`�`records[].chipStats.guide/photo` 改按团期�册；`chips.contract/insurance` 门控�之�化；带与�带 `productId` 两�路一致 |
+| 2 | �导游芯片明细（GB-ADM-092） | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/guide` | 修改：出��值语义�化 | `aggregateStatus`�`totalCount`�`doneCount` 改按团期�册；`items` �� `[]`，`staffList` �� |
+| 3 | �摄影芯片明细（GB-ADM-093） | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/photo` | 修改：出��值语义�化 | � 2 |
+| 4 | ��芯片明细（GB-ADM-094） | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/contract` | 修改：出��值语义�化 | `aggregateStatus` �新导 / 摄结果门控；`totalCount`�`doneCount`�`items` �� |
+| 5 | �险芯片明细（GB-ADM-095） | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/insurance` | 修改：出��值语义�化 | � 4 |
+
+---
+
+## 三�接�详情
+
+### 1. 团期分页列表（看�） `GET /v3/admin/order/group-batch`
+
+**VO**: `GroupBatchPageItemRespVO`（`records[]` 元素；芯片字段在内嵌的 `Chips` 与 `ChipStatsMap` / `ChipStats`）
+
+#### 使用场景
+
+团期看��行的六芯片：颜色� `records[].chips.X`，悬�「已完� done/total�� `records[].chipStats.X`。本��改其中 `guide`�`photo` 两项的�值，以� `contract`�`insurance` 两项何时离开 `TODO`。�带 `productId`（全部团期，按建团时间分页）与带 `productId`（产�全�期基底，�未建团的�期行）两�路�一�径。
+
+#### 入�
+
+全部为既有�数，本�未改。
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| productId | Query | Long | � | - | 按产�筛选；有值时以产�全�期为基底，�未建团的�期行（`groupBatchId` 为 `null`） |
+| batchStatus | Query | String | � | 团期��之一（�六.5） | 团期状�精确筛选 |
+| opsStage | Query | String | � | `RECRUIT` / `CONFIGURE` / `CONFIRM` / `TRIP` / `REVIEW` / `SETTLE` / `DISBANDED`；�法值忽略 | 看�桶筛选 |
+| scope | Query | String | � | `ONGOING` / `FINISHED` / `ALL`；�法值忽略 | �期范围；带 `productId` 时缺� `ONGOING`，�带时缺� `ALL` |
+| month | Query | String | � | `yyyy-MM` | 出�月份 |
+| departFrom / departTo | Query | String | � | `yyyy-MM-dd`，�当日；�法值忽略 | 出团日期区间 |
+| deadlineFrom / deadlineTo | Query | String | � | `yyyy-MM-dd` | 报�截止日区间 |
+| keyword | Query | String | � | - | �期编� / �期�称模糊匹� |
+| sortBy / sortOrder | Query | String | � | `departDate` / `enrollDeadline` / `createTime`；`asc` / `desc` | 排�；�白��值回�默认排�，�报错 |
+| pageNo | Query | Integer | � | 缺�或�于 1 时按 1 | 页� |
+| pageSize | Query | Integer | � | 缺� 20，最大 100（超出截断） | �页�数 |
+
+#### 出� `Result<PageResult<GroupBatchPageItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.records[].chips.guide / chips.photo | String | **�值�化**：�会是 `TODO` 或 `DONE`，按团期�册判定（判定表�六.5）；��出现 `DOING`�`ERROR` |
+| data.records[].chipStats.guide / chipStats.photo | Object | **�值�化**：`{ total, done, error }`，��是「�册的这一��：�册有人 `total=1, done=1`；�团�整团�需�且�册没人 `total=0, done=0`；其余 `total=1, done=0`；`error` � 0 |
+| data.records[].chips.contract / chips.insurance | String | **门控�化**：房 / 车 / 导 / 摄四项全部 `DONE` �� `TODO`，其中导 / 摄�上�的新结果；四项��按�户�� / �险状�汇总，汇总规则�� |
+| data.records[].chipStats.contract / chipStats.insurance | Object | ��：户数，按真实数�统计，��门控影� |
+| data.records[].chips.hotel / vehicle�chipStats.hotel / vehicle | - | �� |
+| data.records[] 其余字段�data.total / page / pageSize | - | �� |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch?scope=ALL&pageNo=1&pageSize=100
+Authorization: Bearer <admin token>
+```
+
+无请求体。按产�看�：`GET /v3/admin/order/group-batch?productId=2101499109901778946&scope=ALL&pageNo=1&pageSize=100`。
+
+#### �应示例
+
+2026-09-28 18:34 测试�实测（�带 `productId`；本页共 13 行，这里��留实例团期一行，字段�为原值）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "records": [
+      {
+        "groupBatchId": "2101506167098511362",
+        "productBatchId": "2101502082564407299",
+        "productId": "2101499109901778946",
+        "productName": "jw测试产�",
+        "batchNo": "Q202609272101502082564407298",
+        "batchName": "jw测试1期",
+        "batchLabel": "1",
+        "batchStatus": "MATERIAL_PREPARING",
+        "batchStatusName": "物料准备中",
+        "stage": "CONFIRM",
+        "stageName": "确认",
+        "tripSubStatus": null,
+        "tripSubStatusName": null,
+        "opsStage": "CONFIRM",
+        "opsStageName": "确认",
+        "minGroupPeople": 6,
+        "minToForm": 6,
+        "maxRooms": 12,
+        "maxParticipants": 24,
+        "enrolledPeople": 24,
+        "enrolledRooms": 12,
+        "remainRooms": 0,
+        "remainParticipants": 0,
+        "orderCount": 12,
+        "enrollDeadline": "2026-09-26",
+        "departDate": "2026-09-27",
+        "endDate": "2026-10-03",
+        "daysToDepart": -1,
+        "receivableAmount": "156760.00",
+        "receivedAmount": "47940.00",
+        "unpaidAmount": "108820.00",
+        "chips": {
+          "hotel": "DONE",
+          "vehicle": "DONE",
+          "guide": "DONE",
+          "photo": "DONE",
+          "contract": "DOING",
+          "insurance": "DONE"
+        },
+        "chipStats": {
+          "hotel": {
+            "total": 12,
+            "done": 12,
+            "error": 0
+          },
+          "vehicle": {
+            "total": 12,
+            "done": 12,
+            "error": 0
+          },
+          "guide": {
+            "total": 1,
+            "done": 1,
+            "error": 0
+          },
+          "photo": {
+            "total": 1,
+            "done": 1,
+            "error": 0
+          },
+          "contract": {
+            "total": 12,
+            "done": 10,
+            "error": 0
+          },
+          "insurance": {
+            "total": 12,
+            "done": 12,
+            "error": 0
+          }
+        },
+        "productBatchStatus": null,
+        "productBatchStatusLabel": null,
+        "productBatchStatusName": null,
+        "productBatchRemoved": null
+      }
+    ],
+    "total": 13,
+    "page": 1,
+    "pageSize": 100
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+改�（�一请求，18:00 实测）这一行的芯片部分：
+
+```json
+{
+  "groupBatchId": "2101506167098511362",
+  "batchStatus": "MATERIAL_PREPARING",
+  "chips": {
+    "hotel": "DONE",
+    "vehicle": "DONE",
+    "guide": "TODO",
+    "photo": "TODO",
+    "contract": "TODO",
+    "insurance": "TODO"
+  },
+  "chipStats": {
+    "hotel": {
+      "total": 12,
+      "done": 12,
+      "error": 0
+    },
+    "vehicle": {
+      "total": 12,
+      "done": 12,
+      "error": 0
+    },
+    "guide": {
+      "total": 0,
+      "done": 0,
+      "error": 0
+    },
+    "photo": {
+      "total": 0,
+      "done": 0,
+      "error": 0
+    },
+    "contract": {
+      "total": 12,
+      "done": 10,
+      "error": 0
+    },
+    "insurance": {
+      "total": 12,
+      "done": 12,
+      "error": 0
+    }
+  }
+}
+```
+
+#### 空数� / �级�应
+
+- 本页没有团期时 `records: []`，��芯片计算。
+- 带 `productId` 时，未建团的�期行（`groupBatchId` 为 `null`）导 / 摄� `TODO`�`total=1, done=0`（改�为 `total=0, done=0`）；房 / 车 / �� / �险计数�为 0。实测片段（�一产��一期）：
+
+```json
+{
+  "groupBatchId": null,
+  "productBatchId": "2101502082795143171",
+  "batchName": "jw测试2期",
+  "batchStatus": "RECRUITING",
+  "orderCount": 0,
+  "chips": {
+    "hotel": "TODO",
+    "vehicle": "TODO",
+    "guide": "TODO",
+    "photo": "TODO",
+    "contract": "TODO",
+    "insurance": "TODO"
+  },
+  "chipStats": {
+    "hotel": {
+      "total": 0,
+      "done": 0,
+      "error": 0
+    },
+    "vehicle": {
+      "total": 0,
+      "done": 0,
+      "error": 0
+    },
+    "guide": {
+      "total": 1,
+      "done": 0,
+      "error": 0
+    },
+    "photo": {
+      "total": 1,
+      "done": 0,
+      "error": 0
+    },
+    "contract": {
+      "total": 0,
+      "done": 0,
+      "error": 0
+    },
+    "insurance": {
+      "total": 0,
+      "done": 0,
+      "error": 0
+    }
+  }
+}
+```
+
+- 团期里没有活跃�订�时：房 / 车 / �� / �险计数为 0（��）；导 / 摄�按�册与团期标记判定，例如�团�整团�需�且�册没人为 `DONE`�`total=0, done=0`。
+
+#### 错误�应
+
+错误�未改动。角色未授予 `group-batch:list`：
+
+```json
+{
+  "code": 589507,
+  "message": "无�作��（当�角色未授予团期��，或该团期�在您�下）",
+  "data": null,
+  "success": false
+}
+```
+
+未登录由网关拦截，HTTP 200�业务� 401（测试�实测文案「缺少有效的 Authorization 头�）。
+
+#### 业务边界
+
+- 判�未改：`group-batch:list`，无�� 589507。
+- 导 / 摄�看团期�册�团期状�与团期「需�导游 / 需�摄影�标记，�看任何一户�订�的需�标记或指派情况。
+- �团（`batchStatus=CANCELLED`）：六芯片� `TODO`；导 / 摄计数照实，�册有人时会出现 `chips.guide=TODO` 而 `chipStats.guide` 为 `total=1, done=1`，属正常。
+- 已返团（`TRIP_FINISHED` / `REVIEWING` / `SETTLED`）：导 / 摄� `DONE`；�册没人且团期需�时计数为 `total=1, done=0`，属正常。
+- 颜色一律以 `chips.X` 为准，`chipStats` �用�解释（与 #7250 �径相�）。
+- �册增删人员�，下一次请求�按新�册计算。
+- 本接��读。
+
+### 2. �导游芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/guide`
+
+**VO**: `GroupBatchChipDetailVO`
+
+#### 使用场景
+
+团期详情「�导游�页签的状�标签与计数�看�点导游芯片弹出的明细。本接� `aggregateStatus` 与看��一行 `chips.guide` �值，`doneCount` / `totalCount` 与 `chipStats.guide.done` / `chipStats.guide.total` �值。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | 是 | ��团期 ID | 路由上的团期 ID（既有，未改） |
+
+#### 出� `Result<GroupBatchChipDetailVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| batchId / groupBatchId | String | 团期 ID（`batchId` 已废弃，�值；��） |
+| chipLabel | String | 「�导游�（��） |
+| aggregateStatus / aggregateStatusName | String | **�值�化**：�会是 `TODO`「待开始�或 `DONE`「已完��，按团期�册判定（判定表�六.5）；改�按户，�为 `DOING`「进行中� |
+| totalCount | Integer | **�值�化**：�册导游�有人为 1；没人时，�团�整团�需�为 0，其余为 1。改�是需�导游的户数 |
+| doneCount | Integer | **�值�化**：�册导游�有人为 1，�则 0。改�是已指派导游的户数 |
+| staffList | Object[] | ��：本团导游�已�置人员；元素字段 `staffId`�`staffRole`�`staffRoleName`�`staffName`�`staffPhone`（脱�）�`reporterRank`�`reporterRankName`�`source`�`sourceName`；未�置为 `[]` |
+| items | Object[] | ��：�为 `[]`（#8468 起） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101506167098511362/chips/guide
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### �应示例
+
+2026-09-28 18:34 测试�实测，实例团期（12 户都无需�导游，�册导游� 2 �领队）。改��一请求 `aggregateStatus` 为 `TODO`「待开始��`totalCount=0`�`doneCount=0`，其余字段相�。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2101506167098511362",
+    "groupBatchId": "2101506167098511362",
+    "chipLabel": "�导游",
+    "aggregateStatus": "DONE",
+    "aggregateStatusName": "已完�",
+    "totalCount": 1,
+    "doneCount": 1,
+    "staffList": [
+      {
+        "staffId": "1011",
+        "staffRole": "LEADER",
+        "staffRoleName": "领队",
+        "staffName": "巴特尔",
+        "staffPhone": "139****1011",
+        "reporterRank": "PRIMARY",
+        "reporterRankName": "主报账人",
+        "source": null,
+        "sourceName": null
+      },
+      {
+        "staffId": "1008",
+        "staffRole": "LEADER",
+        "staffRoleName": "领队",
+        "staffName": "��高娃",
+        "staffPhone": "139****1008",
+        "reporterRank": "NONE",
+        "reporterRankName": "�报账人",
+        "source": null,
+        "sourceName": null
+      }
+    ],
+    "items": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+�册导游�没人时 `staffList: []`�`items: []`，状�与计数看团期状�和团期标记。三�实测：
+
+�团�整团�需���册没人（团期 `2100856430494973953`，资�准备中）→ `DONE`，`totalCount=0`�`doneCount=0`：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2100856430494973953",
+    "groupBatchId": "2100856430494973953",
+    "chipLabel": "�导游",
+    "aggregateStatus": "DONE",
+    "aggregateStatusName": "已完�",
+    "totalCount": 0,
+    "doneCount": 0,
+    "staffList": [],
+    "items": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+�团�团期需�导游��册没人（造数团期 H，资�准备中）→ `TODO`，`totalCount=1`�`doneCount=0`（`data` 部分）：
+
+```json
+{
+  "batchId": "2104511888882868226",
+  "groupBatchId": "2104511888882868226",
+  "chipLabel": "�导游",
+  "aggregateStatus": "TODO",
+  "aggregateStatusName": "待开始",
+  "totalCount": 1,
+  "doneCount": 0,
+  "staffList": [],
+  "items": []
+}
+```
+
+�团��册�有人（�一团期 H �团�）→ � `TODO`，计数照实 `totalCount=1`�`doneCount=1`（`data` 部分）：
+
+```json
+{
+  "batchId": "2104511888882868226",
+  "groupBatchId": "2104511888882868226",
+  "chipLabel": "�导游",
+  "aggregateStatus": "TODO",
+  "aggregateStatusName": "待开始",
+  "totalCount": 1,
+  "doneCount": 1,
+  "staffList": [
+    {
+      "staffId": "1002",
+      "staffRole": "GUIDE",
+      "staffRoleName": "导游",
+      "staffName": "�雪梅",
+      "staffPhone": "138****1002",
+      "reporterRank": "NONE",
+      "reporterRankName": "�报账人",
+      "source": null,
+      "sourceName": null
+    }
+  ],
+  "items": []
+}
+```
+
+#### 错误�应
+
+错误�未改动：团期�存在 589500，无�� 589507。未登录（测试�实测，网关返回 HTTP 200�业务� 401）：
+
+```json
+{
+  "code": 401,
+  "message": "缺少有效的 Authorization 头",
+  "data": null,
+  "traceId": "8f16889e7bc64740",
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 判�未改：`group-batch:view`，无�� 589507；团期�存在 589500。
+- 导游�收哪些角色以�置�字典为准，默认导游 `GUIDE` + 领队 `LEADER`；与 `staffList` �一�径，所以 `staffList` �空 ⇔ `doneCount=1`。
+- 招募中�看团期标记：�册没人一律 `TODO`�`totalCount=1`�`doneCount=0`。
+- �团� `TODO`（计数照实，�能 1/1）；已返团� `DONE`（计数照实，�能 0/1 或 0/0）；�团���团的团期�册没人时计数为 `totalCount=1`�`doneCount=0`，�是 0/0。
+- `items` � `[]`，��用�户数�推导本芯片状�。
+- 本接��读。
+
+### 3. �摄影芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/photo`
+
+**VO**: `GroupBatchChipDetailVO`
+
+#### 使用场景
+
+团期详情「�摄影�页签的状�标签与计数�看�点摄影芯片弹出的明细。本接� `aggregateStatus` 与看��一行 `chips.photo` �值，`doneCount` / `totalCount` 与 `chipStats.photo.done` / `chipStats.photo.total` �值。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | 是 | ��团期 ID | 路由上的团期 ID（既有，未改） |
+
+#### 出� `Result<GroupBatchChipDetailVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| batchId / groupBatchId | String | 团期 ID（`batchId` 已废弃，�值；��） |
+| chipLabel | String | 「�摄影�（��） |
+| aggregateStatus / aggregateStatusName | String | **�值�化**：�会是 `TODO`「待开始�或 `DONE`「已完��，按团期�册判定（判定表�六.5）；改�按户，�为 `DOING`「进行中� |
+| totalCount | Integer | **�值�化**：�册摄影�有人为 1；没人时，�团�整团�需�为 0，其余为 1。改�是需�摄影的户数 |
+| doneCount | Integer | **�值�化**：�册摄影�有人为 1，�则 0。改�是已指派摄影的户数 |
+| staffList | Object[] | ��：本团摄影�已�置人员；元素字段�接� 2（`staffId`�`staffRole`�`staffRoleName`�`staffName`�`staffPhone`（脱�）�`reporterRank`�`reporterRankName`�`source`�`sourceName`）；未�置为 `[]` |
+| items | Object[] | ��：�为 `[]`（#8468 起） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101506167098511362/chips/photo
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### �应示例
+
+2026-09-28 18:34 测试�实测，实例团期（12 户都无需�摄影，�册摄影� 1 人）。改��一请求 `aggregateStatus` 为 `TODO`「待开始��`totalCount=0`�`doneCount=0`，其余字段相�。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2101506167098511362",
+    "groupBatchId": "2101506167098511362",
+    "chipLabel": "�摄影",
+    "aggregateStatus": "DONE",
+    "aggregateStatusName": "已完�",
+    "totalCount": 1,
+    "doneCount": 1,
+    "staffList": [
+      {
+        "staffId": "1003",
+        "staffRole": "PHOTOGRAPHER",
+        "staffRoleName": "æ‘„å½±",
+        "staffName": "王强",
+        "staffPhone": "138****1003",
+        "reporterRank": "NONE",
+        "reporterRankName": "�报账人",
+        "source": null,
+        "sourceName": null
+      }
+    ],
+    "items": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+�册摄影�没人时 `staffList: []`�`items: []`。招募中团期摄影�没人（团期 `2104491315645538305`，团期标记在招募中为 0，也�算「�需��）→ `TODO`，`totalCount=1`�`doneCount=0`：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2104491315645538305",
+    "groupBatchId": "2104491315645538305",
+    "chipLabel": "�摄影",
+    "aggregateStatus": "TODO",
+    "aggregateStatusName": "待开始",
+    "totalCount": 1,
+    "doneCount": 0,
+    "staffList": [],
+    "items": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+�团�整团�需�且�册没人时为 `DONE`�`totalCount=0`�`doneCount=0`（与接� 2 �形）。
+
+#### 错误�应
+
+错误�未改动：团期�存在 589500，无�� 589507。
+
+```json
+{
+  "code": 589500,
+  "message": "团期�存在",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 判�未改：`group-batch:view`，无�� 589507；未登录由网关返回业务� 401。
+- 摄影�收哪些角色以�置�字典为准，默认�收摄影 `PHOTOGRAPHER`；与 `staffList` �一�径，所以 `staffList` �空 ⇔ `doneCount=1`。
+- 招募中�看团期标记：�册没人一律 `TODO`�`totalCount=1`�`doneCount=0`。
+- �团� `TODO`（计数照实）；已返团� `DONE`（计数照实）。
+- `items` � `[]`，��用�户数�推导本芯片状�。
+- 本接��读。
+
+### 4. ��芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/contract`
+
+**VO**: `GroupBatchChipDetailVO`（�户项 `GroupBatchChipItemRespVO`）
+
+#### 使用场景
+
+看�点��芯片弹出的�户��明细，以�团期详情里的��芯片��。本接� `aggregateStatus` 与看��一行 `chips.contract` �值。本��改「何时离开 `TODO`�，�户内容与计数��。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | 是 | ��团期 ID | 路由上的团期 ID（既有，未改） |
+
+#### 出� `Result<GroupBatchChipDetailVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| batchId / groupBatchId | String | 团期 ID（`batchId` 已废弃，�值；��） |
+| chipLabel | String | 「���（��） |
+| aggregateStatus / aggregateStatusName | String | **门控�化**：房 / 车 / 导 / 摄四项未全部 `DONE` 时� `TODO`「待开始�，其中导 / 摄改用团期�册结果；四项��按�户��状�汇总（汇总规则��）：有作废中 / 已作废 → `ERROR`；全部已签署 → `DONE`；有待出具 / 已生� / 已上报 / 已上传 / 签署中 → `DOING`；�则 `TODO` |
+| totalCount | Integer | ��：活跃�订�数（���户都计入） |
+| doneCount | Integer | ��：已签署户数 |
+| staffList | - | ��：� `null` |
+| items | Object[] | ��：�户��状�；元素字段 `orderId`�`orderNo`�`teamNo`�`contactName`（已废弃）/ `customerName`�`peopleCount`�`status`�`statusText`（已废弃）/ `statusName`�`needsIt`（� true）�`updateTime`�`claimerId`�`claimerName`�`claimerSource`�`staffs`（� `null`） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101506167098511362/chips/contract
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### �应示例
+
+2026-09-28 18:34 测试�实测，实例团期（房 / 车 12/12 已完�，导 / 摄按�册已完�，四项�；10/12 已签署）。`items` 共 12 户，这里��留� 2 户，其余字段原值。改��一请求 `aggregateStatus` 为 `TODO`「待开始�（被按户的导 / 摄��），计数与 `items` 相�。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2101506167098511362",
+    "groupBatchId": "2101506167098511362",
+    "chipLabel": "��",
+    "aggregateStatus": "DOING",
+    "aggregateStatusName": "进行中",
+    "totalCount": 12,
+    "doneCount": 10,
+    "staffList": null,
+    "items": [
+      {
+        "orderId": "2101506167043985410",
+        "orderNo": "HL20260920105808925",
+        "teamNo": "26-3627",
+        "contactName": "张建国",
+        "customerName": "张建国",
+        "peopleCount": 6,
+        "status": "SIGNED",
+        "statusText": "已签署",
+        "statusName": "已签署",
+        "needsIt": true,
+        "updateTime": null,
+        "claimerId": "1001",
+        "claimerName": "admin",
+        "claimerSource": "BATCH",
+        "staffs": null
+      },
+      {
+        "orderId": "2101507276118626306",
+        "orderNo": "HL20260920110233355",
+        "teamNo": "26-0750",
+        "contactName": "王志强",
+        "customerName": "王志强",
+        "peopleCount": 2,
+        "status": "SIGNED",
+        "statusText": "已签署",
+        "statusName": "已签署",
+        "needsIt": true,
+        "updateTime": null,
+        "claimerId": "1001",
+        "claimerName": "admin",
+        "claimerSource": "BATCH",
+        "staffs": null
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+- 团期没有活跃�订�：`totalCount=0`�`doneCount=0`�`items: []`�`aggregateStatus` 为 `TODO`（��）。
+- 导 / 摄�未�时� `TODO`。实测：造数团期 H 已�导游�未�摄影，��芯片 `TODO`：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2104511888882868226",
+    "groupBatchId": "2104511888882868226",
+    "chipLabel": "��",
+    "aggregateStatus": "TODO",
+    "aggregateStatusName": "待开始",
+    "totalCount": 1,
+    "doneCount": 0,
+    "staffList": null,
+    "items": [
+      {
+        "orderId": "2104511888652181506",
+        "orderNo": "HL20260928180148673",
+        "teamNo": null,
+        "contactName": "巴图孟和",
+        "customerName": "巴图孟和",
+        "peopleCount": 2,
+        "status": null,
+        "statusText": "无��",
+        "statusName": "无��",
+        "needsIt": true,
+        "updateTime": null,
+        "claimerId": null,
+        "claimerName": null,
+        "claimerSource": null,
+        "staffs": null
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误�应
+
+错误�未改动：团期�存在 589500，无�� 589507。
+
+```json
+{
+  "code": 589507,
+  "message": "无�作��（当�角色未授予团期��，或该团期�在您�下）",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 判�未改：`group-batch:view`，无�� 589507；团期�存在 589500；未登录由网关返回业务� 401。
+- 门控�影� `aggregateStatus`：门控期间 `totalCount`�`doneCount`�`items` 照实，�能出现 `doneCount=totalCount` 而 `aggregateStatus=TODO`，属正常。
+- �团� `TODO`；已返团时房 / 车 / 导 / 摄� `DONE`，��按�户汇总（��）。
+- 整团�需�导摄的团（�团���册没人�团期标记为�需�）��因导 / 摄�在 `TODO`，��房 / 车也已 `DONE` �按�户��状�显示。
+- 本接��读。
+
+### 5. �险芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/insurance`
+
+**VO**: `GroupBatchChipDetailVO`（�户项 `GroupBatchChipItemRespVO`）
+
+#### 使用场景
+
+看�点�险芯片弹出的�户�险明细，以�团期详情里的�险芯片��。本接� `aggregateStatus` 与看��一行 `chips.insurance` �值。本��改「何时离开 `TODO`�，�户内容与计数��。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | 是 | ��团期 ID | 路由上的团期 ID（既有，未改） |
+
+#### 出� `Result<GroupBatchChipDetailVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| batchId / groupBatchId | String | 团期 ID（`batchId` 已废弃，�值；��） |
+| chipLabel | String | 「�险�（��） |
+| aggregateStatus / aggregateStatusName | String | **门控�化**：房 / 车 / 导 / 摄四项未全部 `DONE` 时� `TODO`「待开始�，其中导 / 摄改用团期�册结果；四项��按�户�险状�汇总（汇总规则��）：有已�消 / 出�失败 → `ERROR`；全部已出� → `DONE`；有出�中 → `DOING`；�则 `TODO` |
+| totalCount | Integer | ��：活跃�订�数（�险�户都计入） |
+| doneCount | Integer | ��：已出�户数 |
+| staffList | - | ��：� `null` |
+| items | Object[] | ��：�户�险状�；元素字段�接� 4 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101506167098511362/chips/insurance
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### �应示例
+
+2026-09-28 18:34 测试�实测，实例团期（四项�，12/12 已出�）。`items` 共 12 户，这里��留� 2 户，其余字段原值。改��一请求 `aggregateStatus` 为 `TODO`「待开始�，计数与 `items` 相�。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "batchId": "2101506167098511362",
+    "groupBatchId": "2101506167098511362",
+    "chipLabel": "�险",
+    "aggregateStatus": "DONE",
+    "aggregateStatusName": "已完�",
+    "totalCount": 12,
+    "doneCount": 12,
+    "staffList": null,
+    "items": [
+      {
+        "orderId": "2101506167043985410",
+        "orderNo": "HL20260920105808925",
+        "teamNo": "26-3627",
+        "contactName": "张建国",
+        "customerName": "张建国",
+        "peopleCount": 6,
+        "status": "INSURED",
+        "statusText": "已出�",
+        "statusName": "已出�",
+        "needsIt": true,
+        "updateTime": null,
+        "claimerId": "1001",
+        "claimerName": "admin",
+        "claimerSource": "BATCH",
+        "staffs": null
+      },
+      {
+        "orderId": "2101507276118626306",
+        "orderNo": "HL20260920110233355",
+        "teamNo": "26-0750",
+        "contactName": "王志强",
+        "customerName": "王志强",
+        "peopleCount": 2,
+        "status": "INSURED",
+        "statusText": "已出�",
+        "statusName": "已出�",
+        "needsIt": true,
+        "updateTime": null,
+        "claimerId": "1001",
+        "claimerName": "admin",
+        "claimerSource": "BATCH",
+        "staffs": null
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+- 团期没有活跃�订�：`totalCount=0`�`doneCount=0`�`items: []`�`aggregateStatus` 为 `TODO`（��）。
+- 房 / 车 / 导 / 摄未�时� `TODO`，计数照实（与接� 4 �形）。
+
+#### 错误�应
+
+错误�未改动：团期�存在 589500，无�� 589507。
+
+```json
+{
+  "code": 589500,
+  "message": "团期�存在",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 判�未改：`group-batch:view`，无�� 589507；团期�存在 589500；未登录由网关返回业务� 401。
+- 门控�影� `aggregateStatus`：门控期间计数与 `items` 照实，�能出现 `doneCount=totalCount` 而 `aggregateStatus=TODO`，属正常（实例团期改�� 12/12 � `TODO`）。
+- �团� `TODO`；已返团时按�户汇总（��）。
+- 本接��读。
+
+---
+
+## 四�契约约�与正确调用方�
+
+> 5 个接��为 GET�入�未改；本节写�值的正确读法。
+
+### ✅ 正确 / � 错误读法对照
+
+| 场景 | 读法 |
+|------|------|
+| ✅ 芯片颜色 | 列表� `chips.X`，明细� `aggregateStatus`；四值映射�� |
+| ✅ 导 / 摄「�册有没有人� | 明细 `staffList` 是��空，或 `doneCount=1` / `chipStats.X.done=1`（三者�一致） |
+| ✅ 识别「整团�需�� | 导 / 摄 `total=0`（明细 `totalCount=0`）：此时状�必为 `DONE`，�义是已�团（�已返团）�团期标记为�需���册没人 |
+| � 把导 / 摄计数当户数 | 「共 N 户计入 · 已完� N 户�对导 / 摄��立，两个数�会是 0 或 1 |
+| � 用�户数�推导导 / 摄状� | 导 / 摄 `items` � `[]`；�订�上的需�导游 / 摄影标记��与判定 |
+| � 用 `chipStats` 推颜色 | �团时 `TODO` �与 1/1 并存，已返团时 `DONE` �与 0/1 并存，�� / �险门控期间 `TODO` �与 12/12 并存 |
+
+### �端交接清�
+
+1. **颜色**：�用改。`chips.guide/photo` �会出现 `TODO` / `DONE`，�� / �险�是四值。
+2. **看�悬�**（hl-ui `src/views/order-v2/batch/_shared/batchLifecycle.js` 的 `chipStatsTip`）：导 / 摄会显示「已完� 1/1�「已完� 0/1�「已完� 0/0�，数字是�册这一�，�是户数。0/0 时芯片为绿色（整团�需�），当�会原样显示「已完� 0/0�——这是本契约的正常�值；若�更直观，�对导 / 摄 `total=0`（此时必为 `DONE`）改显示「无需�。
+3. **导 / 摄页签与芯片弹层汇总行**（hl-ui `src/views/order-v2/batch/detail/components/ChipItemsPanel.vue`�`src/views/order-v2/batch/components/ChipDetailModal.vue` 的「共 {totalCount} 户计入 · 已完� {doneCount} 户�）：对导 / 摄这两个数��是户数。若按 #8468 交接清�第 6 项已对导 / 摄去掉该行，无需�动；若�在，请对导 / 摄��该行或改为按�册展示（如「已�置 N 人�� `staffList.length`，`totalCount=0` 显示「无需�）。状�标签照用 `aggregateStatus`。房 / 车 / �� / �险的汇总行��。
+4. **�� / �险**：�用改。整团�需�导摄或�册已��的团，�� / �险芯片会比改�更早离开 `TODO`，属预期。
+5. �需�新增请求或字段。
+
+---
+
+## 五�数�库行为
+
+本� 5 个接��为�读查询，零写入；��数��移，�改存�数�。
+
+---
+
+## 六�边界行为
+
+- 未登录 → 网关拦截，HTTP 200�业务� 401（既有，测试�实测）。
+- 无�� → 589507（列表 `group-batch:list`，明细 `group-batch:view`，既有）。
+- 团期�存在 → 589500（芯片明细，既有）。
+- 未建团的�期行（仅带 `productId` 的列表）→ 导 / 摄 `TODO`�`total=1, done=0`；该行没有 `groupBatchId`，调�到芯片明细。
+- 团期状�缺失（历��数�）→ 导 / 摄�册有人 `DONE`（1/1），�则 `TODO`（0/1）。
+- �团���团 → � `TODO`；�册没人时计数 0/1，�是 0/0。
+- 导 / 摄从�出现 `DOING`�`ERROR`；`chipStats.guide/photo.error` � 0。
+- ��兼容：结构��，旧�端�改也能按新值正确�色；�是导 / 摄的按户文案��准确（�第四节）。
+
+---
+
+## 六.5�枚举 / 数�字典
+
+### 芯片���（常�定义于 `com.hulalv.order.groupbatch.helper.GroupBatchChipResolver`）
+
+**所属字段**: `GroupBatchPageItemRespVO.Chips.*`�`GroupBatchChipDetailVO.aggregateStatus` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `TODO` | 待开始 | 导 / 摄：�下方判定表；�� / �险：四项未�时�为此值 |
+| `DOING` | 进行中 | 导 / 摄本�起��出现；房 / 车 / �� / �险规则�� |
+| `DONE` | 已完� | 导 / 摄：�下方判定表 |
+| `ERROR` | 异常 | 导 / 摄从�出现；房 / 车 / �� / �险规则�� |
+
+### 导 / 摄判定表（按优先级从上往下，命中�止；计数写作 done/total）
+
+| 团期状� | �册本� | 团期「需��标记 | 状� | 计数 |
+|----------|----------|------------------|------|------|
+| �团 `CANCELLED` | 有人 | �看 | `TODO` | 1/1 |
+| �团 `CANCELLED` | 没人 | �看 | `TODO` | 0/1 |
+| 已返团 `TRIP_FINISHED` / `REVIEWING` / `SETTLED` | 有人 | �看 | `DONE` | 1/1 |
+| 已返团 | 没人 | 需� | `DONE` | 0/1 |
+| 已返团 | 没人 | �需� | `DONE` | 0/0 |
+| 任�其他状�（�招募中） | 有人 | �看 | `DONE` | 1/1 |
+| 已�团未返团 `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE` / `TRAVELLING` | 没人 | �需� | `DONE` | 0/0 |
+| 已�团未返团 | 没人 | 需� | `TODO` | 0/1 |
+| 招募中 `RECRUITING` | 没人 | �看 | `TODO` | 0/1 |
+| 未建团的�期行（仅带 `productId` 的列表） | 没人 | 无 | `TODO` | 0/1 |
+
+### batchStatus（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）
+
+**所属字段**: `GroupBatchPageItemRespVO.batchStatus` | **类型**: `String`
+
+| 值 | 中文 | 导 / 摄判定分组 |
+|----|------|------|
+| `RECRUITING` | 招募中 | 招募中：�看�册 |
+| `RESOURCE_PREPARING` | 资�准备中 | 已�团未返团 |
+| `MATERIAL_PREPARING` | 物料准备中 | 已�团未返团 |
+| `PENDING_DEPARTURE` | 待出� | 已�团未返团 |
+| `TRAVELLING` | 出行中 | 已�团未返团 |
+| `TRIP_FINISHED` | 出行完毕 | 已返团 |
+| `REVIEWING` | 核�中 | 已返团 |
+| `SETTLED` | 已结算 | 已返团 |
+| `CANCELLED` | 已�消（�团） | �团 |
+
+### �置��员（`com.hulalv.order.assignment.constants.GroupBatchStaffSlot`）
+
+**所属字段**: 决定 `staffList` 与导 / 摄「�册本�有没有人� | **类型**: `String`（`staffRole`）
+
+| �置� | 默认�员 | 说明 |
+|--------|----------|------|
+| 导游� | `GUIDE` 导游�`LEADER` 领队 | 以�置�字典为准，字典读�到时用默认�员 |
+| 摄影� | `PHOTOGRAPHER` 摄影 | �上 |
+| - | �机�其他 | �属于任何�置�，�算导 / 摄有人 |
+
+---
+
+## 六.6�修改��对比
+
+### 字段级对比
+
+| 字段 | 改� | 改� |
+|------|------|------|
+| `chips.guide` / `chips.photo`，导 / 摄明细 `aggregateStatus` | 按户（#7204）：无计入户 `TODO`；计入户零指派 `TODO`；部分指派 `DOING`；全部指派 `DONE` | 按团期�册：�有 `TODO` / `DONE`，判定�六.5 |
+| `chipStats.guide/photo.total`，导 / 摄明细 `totalCount` | 需�导游 / 摄影的户数 | �册这一�：1；�团�整团�需�且�册没人时为 0 |
+| `chipStats.guide/photo.done`，导 / 摄明细 `doneCount` | 已指派的户数 | �册有人 1，�则 0 |
+| `chipStats.guide/photo.error` | � 0 | � 0（��） |
+| `chips.contract/insurance`，�� / �险明细 `aggregateStatus` | 四项�判定用按户的导 / 摄结果 | 用按�册的导 / 摄结果 |
+
+### 行为级对比（测试�部署���一批�读请求；计数写作 done/total）
+
+| 场景 | 改� | 改� |
+|------|------|------|
+| 实例团期 `2101506167098511362`（物料准备中，12 户都无需导摄，�册导游� 2 人�摄影� 1 人）导 / 摄 | `TODO` 0/0 | `DONE` 1/1 |
+| �上 · �� | `TODO` 10/12 | `DOING` 10/12 |
+| �上 · �险 | `TODO` 12/12 | `DONE` 12/12 |
+| 招募中团期 `2104491315645538305`（导游�有人�摄影�没人） | 导 / 摄 `TODO` 0/0 | 导游 `DONE` 1/1，摄影 `TODO` 0/1 |
+| �团�整团�需���册空的团期（部署��都在列表里的 8 个） | 导 / 摄 `TODO` 0/0 | 导 / 摄 `DONE` 0/0 |
+| 带 `productId` 的未建团�期行（实例产�下 15 行） | 导 / 摄 `TODO` 0/0 | 导 / 摄 `TODO` 0/1 |
+| 团期 `2104490621953794050`（2 户都需�导摄且已指派，�册导游��摄影�� 1 人） | 导 / 摄 `DONE` 2/2（户） | 导 / 摄 `DONE` 1/1（�册�） |
+| 部分户已指派 | 导 / 摄 `DOING` | ��出现；�册有人� `DONE` |
+| 房 / 车芯片（看� 11 行） | - | 部署���字段一致 |
+
+---
+
+## 六.7�影�评估
+
+- **是�破���兼容**: �。结构�字段��枚举值集��；但导 / 摄计数的�义由户数�为�册�，按户展示的文案会�准确（�第四节交接清�第 2�3 项）。
+- **�端是�必须�步上线**: �。颜色�新值自然�化；文案核对�影�功能。
+- **�端 workaround 清�点**: 若�端为导 / 摄 `DOING`「部分户已指派�写过专门的图例或�示，�删；导 / 摄汇总行里的「户�字样�删。
+
+---
+
+## 七��影�范围
+
+- **仅影�**: 看�列表 `chips` / `chipStats` 的导�摄两项�值与����险两项的门控；导�摄�����险四个芯片明细的 `aggregateStatus` 与导 / 摄计数。
+- **零影�**:
+  - �房��车芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/hotel`�`GET /v3/admin/order/group-batch/{groupBatchId}/chips/vehicle`，以�看� `chips.hotel/vehicle`�`chipStats.hotel/vehicle`（测试�部署���字段一致）
+  - �� / �险芯片的 `totalCount`�`doneCount`�`chipStats`��户 `items`
+  - 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}` 的进度� `progressStepper`（#8478，按确认门就绪标记计算）�其余字段
+  - �并层看� `GET /v3/admin/order/group-batch/board`
+  - 团期人员�置（�存 / �册 / 更� / 删除 / 候选）接�
+  - �订�上的需�导游 / 摄影标记与订�侧人员指派数�（���与芯片判定，数�本身��）
+
+---
+
+## 八�测试环境已验�
+
+- **环境**：TEST，`hl-order-service-v3` �行 dev-v3 `2c87b0618`（PR #8489 �入，2026-09-28 18:33 �实例滚动完�）。
+- **方�**：�网关 `https://api.test.1814.love`，真实 admin token；构建身份探针命中（实例团期导游芯片由 `TODO` 0/0 �为 `DONE` 1/1）。手机��为接�脱�值。
+- **部署��对照**：�一批�读请求，��为会��� accept8469/PROBE-before.json 与 accept8469/PROBE-after.json，结果�六.6 行为级对比。
+- **造数**：团期 H「11月20日海拉尔-满洲里3日团�（团期 ID `2104511888882868226`，1 张订�，�团��对这张�置需�导游 / 摄影），验收�已�团�订�已�消；其余团期�读。
+
+| AC | 检验点 | 结果 | �� |
+|----|--------|------|------|
+| 1 | 实例团期导 / 摄：明细 `DONE` 1/1；看��带 `productId`�带 `productId` 两�路�为 `DONE` 1/1，三处一致 | ✅ | 会��� accept8469/AC-1.json |
+| 2 | 招募中团期：导游�有人 `DONE` 1/1�摄影�没人 `TODO` 0/1（团期标记为 0 也�算�需�），看�与明细一致；实例产�下 15 个未建团行导 / 摄� `TODO` 0/1 | ✅ | 会��� accept8469/AC-2.json�accept8469/PROBE-after.json |
+| 3 | �团�整团�需���册空的 9 个团期看�导 / 摄� `DONE` 0/0，抽样明细一致；团期 H（资�准备中，团期需�导摄��册空）导 / 摄 `TODO` 0/1，看�与明细一致 | ✅ | 会��� accept8469/AC-3.json |
+| 4 | 团期 H �团��册�有 2 人，导 / 摄� `TODO`（计数 1/1 照实）；测试�没有已返团团期���，已返团三�由�测矩阵覆盖（出行完毕 / 核�中 / 已结算 × 有人 / 没人需� / 没人�需�） | ✅ | 会��� accept8469/AC-4.json |
+| 5 | 团期 H �导游�导游 `DONE` 1/1�摄影� `TODO` 0/1��� `TODO`；��摄影�摄影 `DONE` 1/1；实例团期四项���� `TODO` → `DOING` 10/12��险 `TODO` → `DONE` 12/12 | ✅ | 会��� accept8469/AC-5.json |
+| 6 | 看� 11 行房 / 车 `chips` 与 `chipStats` 部署���字段一致 | ✅ | 会��� accept8469/PROBE-before.json�accept8469/PROBE-after.json |
+| 9 | 无 token 调导游芯片明细 → HTTP 200�业务� 401 | ✅ | 会��� accept8469/AC-9.json |
+
+验收脚本 22/22 通过（会��� accept8469/VERIFY-summary.json）。
+
+---
+
+## ��相关历� PR
+
+| PR | Issue | 说明 | 是��有效 |
+|----|-------|------|------------|
+| #7207 | #7204 | 导 / 摄芯片按户：零指派 `TODO`�部分指派 `DOING`�全部指派 `DONE` | � 已被本��代 |
+| #7254 | #7250 | 六芯片�出 `chipStats` 计数 | ✅ 字段有效；导 / 摄计数��本�改为�册� |
+| #7856 | #7853 | 导 / 摄芯片明细带出 `staffList` | ✅ 有效（内容��） |
+| #8475 | #8468 | 导 / 摄明细 `items` � `[]`；该文所写「导 / 摄���与计数�按户�一�已被本��代 | ⚠� `items` �径有效，���径以本文为准 |
+| #8480 | #8478 | 团期详情进度� `progressStepper` | ✅ 有效，本��改 |
+| **#8489** | **#8469** | 本�：导 / 摄芯片改按团期�册，�� / �险门控�之�化 | ✅ 最新 |
+
+---
+
+## ��相关文档
+
+- 工� #8469: https://git.1814.love/wx/HL/issues/8469
+- 拆出本�的 #8468（导 / 摄明细去掉�户人员）: https://git.1814.love/wx/HL/issues/8468
+- 改��径 #7204: https://git.1814.love/wx/HL/issues/7204
+
+---
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#8469](https://git.1814.love/wx/HL/issues/8469)
+- **PR**: [#8489](https://git.1814.love/wx/HL/pulls/8489)
+- **Merge commit**: [2c87b0618](https://git.1814.love/wx/HL/commit/2c87b0618)
+
+### �系人
+
+- **�端负责人**: @jw