docs(changelog): #8642 团期详情进度条导摄分支按名册显示已完成

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

changelogs-v2/2026-09/30_8642_团期详情进度条导摄分支按名册显示已完成-修改接口-管理后台.md

@@ -0,0 +1,235 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8642"
+title: "团期详情（A2）进度条导游 / 摄影分支改为看名册——本位配了人即「已完成」，招募中也一样；「无需」只留给不需要且没配人"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "A2 团期详情 progressStepper（#8478）配置节点下的「配导游」「配摄影」两条分支，改前只要团期 needs_guide / needs_photographer 不为 true 就显示 WAIVED「无需」，不看导摄名册。导摄 ready 一列两义（成团免闸置 1 = 不需要；配人保存置 1 = 已配人），产品没配领队的团期成团后再配导游，进度条一直是「配导游·无需」（TEST T26-3963 实例），与看板导/摄芯片「名册有人即完成」（#8469）口径分家。jw 2026-09-30 定案：导游位配了人 → 配导游 DONE「已完成」，摄影位配了人 → 配摄影 DONE「已完成」，招募中同样适用；「无需」只留给 needs 不为 true 且本位没人。标记为 false → UNMET「未配齐」仍排在最前，与确认预检逐项一致。路径、入参、出参字段名与结构零变化；变的是 GUIDE / PHOTOGRAPHER 两条分支 status / statusName / displayText 的取值口径，属「语义取值」变化，按 jw 2026-09-18 口径推送。已合并 dev-v3（PR #8652，merge commit 5b271055b）并部署测试服。前端按 status 渲染，DONE 本来就有样式，零改动，frontend_status 记 not_required。"
+updated_at: "2026-09-30"
+base: "dev-v3"
+---
+
+# 团期详情（A2）进度条导游 / 摄影分支改为看名册（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+
+## 一、接口背景
+
+团期详情（A2）的 `progressStepper`（#8478）在「配置」节点下有五条分支：配房、配车、配导游、配摄影、配物资。
+其中导游、摄影两条原先只看团期的 `needs_guide` / `needs_photographer`：不为 true 就显示 `WAIVED`「无需」，不看导摄名册里有没有人。
+
+`needs_*` 在创单时按产品人员配置冻结（产品配了领队才为 1），成团时抄到团期；成团事务会把不需要的导摄 ready 直接置 1（免闸）。
+所以产品没配领队的团期，成团后运营再去配导游，进度条仍然是「配导游·无需」，而同一页的看板导/摄芯片（#8469）按名册判定已经是完成。
+
+jw 2026-09-30 定案：
+
+1. 导游位配了人 → 配导游「已完成」；摄影位配了人 → 配摄影「已完成」。
+2. 招募阶段同样适用：招募中名册本位有人也显示「已完成」（其余情况仍是「待开始」）。
+
+本次修订 #8478 的两条定案：「不需要时显示无需、不要显示成已完成」收窄为「不需要且没配人才显示无需」；「招募阶段五条分支全部待开始」改为导游、摄影两条在本位有人时显示「已完成」。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | A2 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 修改接口 | 出参 `progressStepper[].subFlows[]` 中 GUIDE / PHOTOGRAPHER 两条分支的 `status` / `statusName` / `displayText` 改为看名册；字段名、结构与其余字段零变化 |
+
+## 三、接口详情
+
+### 1. A2 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
+
+**VO**: `GroupBatchDetailRespVO`（进度条节点 `GroupBatchProgressNodeVO`，分支 `GroupBatchProgressSubFlowVO`）
+
+#### 使用场景
+
+团期详情页页头的分叉进度条。本次只改「配置」节点下导游、摄影两条分支的取值，其余三条分支、六个主节点、其余出参都不变。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 正整数，团期聚合主键 | 团期 ID，不存在返 589501 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| progressStepper | List\<GroupBatchProgressNodeVO\> | 六个主节点，结构不变；只有 CONFIGURE 节点带 `subFlows` |
+| progressStepper[].subFlows[].code | String | HOTEL / VEHICLE / GUIDE / PHOTOGRAPHER / MATERIAL，顺序固定，未变 |
+| progressStepper[].subFlows[].status | String | **本次 GUIDE / PHOTOGRAPHER 两条改口径**，按下面「业务边界」的优先级判定：WAITING 待开始 / UNMET 未配齐 / WAIVED 无需 / DONE 已完成 |
+| progressStepper[].subFlows[].statusName | String | 与 status 对应的中文名：待开始 / 未配齐 / 无需 / 已完成 |
+| progressStepper[].subFlows[].displayText | String | `name + "·" + statusName`，如「配导游·已完成」 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2104839654727618562 HTTP/1.1
+Host: api.test.1814.love
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+T26-3963（已成团，needs_guide=0、needs_photographer=0；名册有导游李雪梅、领队巴特尔，没有摄影）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2104839654727618562",
+    "batchStatus": "RESOURCE_PREPARING",
+    "guideReady": true,
+    "photographerReady": true,
+    "progressStepper": [
+      { "step": 1, "code": "RECRUIT", "name": "招募", "status": "DONE", "isCurrent": false, "label": null, "subFlows": null },
+      { "step": 2, "code": "CONFIGURE", "name": "配置", "status": "PROCESSING", "isCurrent": true, "label": "配置中",
+        "subFlows": [
+          { "code": "HOTEL",        "name": "配房",   "status": "UNMET",  "statusName": "未配齐", "displayText": "配房·未配齐" },
+          { "code": "VEHICLE",      "name": "配车",   "status": "DONE",   "statusName": "已完成", "displayText": "配车·已完成" },
+          { "code": "GUIDE",        "name": "配导游", "status": "DONE",   "statusName": "已完成", "displayText": "配导游·已完成" },
+          { "code": "PHOTOGRAPHER", "name": "配摄影", "status": "WAIVED", "statusName": "无需",   "displayText": "配摄影·无需" },
+          { "code": "MATERIAL",     "name": "配物资", "status": "UNMET",  "statusName": "未确认", "displayText": "配物资·未确认" }
+        ] }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+- 已流团、`batchStatus` 为 null 或不在九态内：`progressStepper` 为空列表 `[]`（与 #8478 相同，本次未改）。
+- 名册没人：导摄分支按 `needs_*` 判——需要且标记 false 为「未配齐」，不需要为「无需」，与改前一致。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2105074297745866753",
+    "batchStatus": "CANCELLED",
+    "progressStepper": []
+  }
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589501,
+  "message": "团期不存在",
+  "data": null
+}
+```
+
+| 错误码 | 触发条件 |
+|---|---|
+| 589501 | groupBatchId 不存在或已软删 |
+| 589507 | 缺 `group-batch:view` 权限码 |
+
+#### 业务边界
+
+导游 / 摄影分支自上而下按优先级判定（房、车、物资三条规则不变）：
+
+| 条件 | status | statusName |
+|---|---|---|
+| 团期在招募阶段，名册本位有人 | DONE | 已完成 |
+| 团期在招募阶段，名册本位没人 | WAITING | 待开始 |
+| 已成团，就绪标记（`guideReady` / `photographerReady`）不为 true | UNMET | 未配齐 |
+| 已成团，标记 true 且名册本位有人 | DONE | 已完成 |
+| 已成团，标记 true、名册本位没人、`needs_*` 不为 true | WAIVED | 无需 |
+| 已成团，标记 true、`needs_*` 为 true | DONE | 已完成 |
+
+- 「本位有人」与看板导/摄芯片同一读口（`GroupBatchSlotStaffReadService#slotsWithStaffByProductBatchIds`）：导游位包含哪些人员类型由字典决定，默认 GUIDE + LEADER，所以只配了领队也算导游位有人；摄影位默认 PHOTOGRAPHER。
+- 已成团阶段「未配齐」排在名册前面：进度条的 UNMET 与确认预检 `confirm-check` 同一项 `passed=false` 仍逐项等价。
+- 已成团、不需要该项的团期，清空名册后 ready 保持 1（免闸不回落，既有行为），进度条回到「无需」。
+
+## 四、契约约束与正确调用方式
+
+- 进度条只供展示；业务判断（能不能确认、能不能出发）仍读 `batchStatus` 与五个就绪标记本身，不要读分支 `status`。
+- 招募阶段导摄分支可能是 DONE，而「配置」主节点仍是 WAITING——这是定案行为，前端按分支自身 `status` 渲染即可，不要用主节点状态覆盖分支。
+
+## 五、数据库行为
+
+零数据库变更，不新增表、列或索引，不写任何数据。
+进度条派生从 `assembleDetail`（`@Transactional(readOnly = true)`）挪到 `getDetail` 事务外：名册读口按字典把角色归位，字典回源是同步 Feign（`DictFeignClient`，5 分钟缓存），留在事务里会违反红线⑧。
+名册懒求值：只在「招募中」或「已成团、导摄标记 true 且 `needs_*` 不为 true」时查一次（只投影 `product_batch_id` / `staff_role`），导游、摄影两条分支共用；已成团且两项都需要的团期不多查。
+
+## 六、边界行为
+
+- 团期不存在 → 589501。
+- 已流团 / 脏状态 → `progressStepper=[]`。
+- 招募中名册没人 → 五条全「待开始」。
+- 已成团、需要导游但名册没人 → 「配导游·未配齐」（与改前一致）。
+
+## 六.6、修改前后对比
+
+| 场景 | 修改前 | 修改后 |
+|---|---|---|
+| 已成团、needs=0、本位有人 | 无需 | **已完成** |
+| 已成团、needs=0、本位没人 | 无需 | 无需 |
+| 已成团、needs=1、标记 true | 已完成 | 已完成 |
+| 已成团、标记 false | 未配齐 | 未配齐 |
+| 招募中、本位有人 | 待开始 | **已完成** |
+| 招募中、本位没人 | 待开始 | 待开始 |
+| 路径 / 入参 / 权限码 / 字段名 / 结构 | — | 逐字未变 |
+
+## 六.7、影响评估
+
+- **兼容性**：字段与结构不变，只有两条分支的取值在上表两种场景下从 WAIVED / WAITING 变成 DONE。前端按 `status` 渲染，DONE 已有样式，不用改。
+- **性能**：招募中或已成团免闸的团期，详情多一次本库只读查询（名册投影）+ 字典读取（5 分钟缓存）；在事务外执行，不占 DB 连接做远程调用。
+- **回滚**：撤销 PR #8652 的合并提交后重新部署 order-v3，无数据与配置残留。
+
+## 七、不影响范围
+
+- 确认预检 `confirm-check`、确认门、出发七项硬门、合同 / 预支 / 物资闸：仍只读五个就绪标记，零改动。
+- `guide_ready` / `photographer_ready` 的写法与成团免闸：零改动。
+- 房、车、物资三条分支与六个主节点：零改动。
+- 看板导/摄芯片（#8469）：本来就是按名册判定，本次与之对齐，未改动。
+- 网关：路径未变、无新增路由与权限码。
+
+## 八、测试环境已验证
+
+2026-09-30 13:01–14:10 测试服（`api.test.1814.love`），部署 `dev-v3 @ 5b271055b`（order-v3 双实例 8086/8186）。
+
+- 部署身份：T26-3963 改前（13:01）为「配导游·无需」；部署后经网关连打 6 次，6/6 为「配导游·已完成」「配摄影·无需」。
+- 自建两个团期、各一张真实订单：A 团（needs=0）、B 团（成团前把自造订单 needs 置 1）。每一步同时读 A2、确认预检和库里的就绪位。
+
+| 场景 | 名册 | 进度条导摄两条 | 库 ready（导/摄） |
+|---|---|---|---|
+| A 招募中，只配导游 | GUIDE | 配导游·已完成、配摄影·待开始（改前旧代码为 配导游·待开始） | 1 / 0 |
+| A 招募中，再配摄影 | GUIDE, PHOTOGRAPHER | 配导游·已完成、配摄影·已完成（房、车、物资仍待开始） | 1 / 1 |
+| A 成团后（needs 0/0） | GUIDE, PHOTOGRAPHER | 配导游·已完成、配摄影·已完成 | 1 / 1 |
+| A 清空导游位 | PHOTOGRAPHER | 配导游·无需 | 1 / 1（免闸不回落） |
+| A 导游位只配领队 | LEADER, PHOTOGRAPHER | 配导游·已完成 | 1 / 1 |
+| A 清空摄影位 | LEADER | 配摄影·无需 | 1 / 1 |
+| B 招募中 | 空 | 五条全待开始 | 0 / 0 |
+| B 成团后（needs 1/1） | 空 | 配导游·未配齐、配摄影·未配齐 | 0 / 0 |
+| B 配导游 | GUIDE | 配导游·已完成、配摄影·未配齐 | 1 / 0 |
+| B 清空导游位 | 空 | 配导游·未配齐 | 0 / 0 |
+
+- 已成团的每一步，进度条 UNMET 的项与确认预检同一项 `passed=false` 逐项一致。
+- 验收造数已全部回收（两团两单连带名册、扇出、行程、服务项、快照、流水共 12 张表按主键软删 / 物理删，产品侧班期经接口删除），回读零残留；他人团期 T26-3963 全程只读。
+
+单元测试：定向 4 类 189 例 0 失败（进度条穷举加名册维度共 69984 组合、确认门同源不变量加名册维度）；团期整包 + 全部 ArchTest 3302 例中 12 例红，基底 `8e00cc98b` 逐条复现，属既有失败，本单引入 0 个。
+
+## 十、相关文档
+
+- 工单 #8642、PR #8652（merge commit `5b271055b`）
+- 进度条首发：#8478
+- 看板导/摄芯片按名册计算：#8469
+- 招募中允许配导摄：#8231
+
+## 关联 / 联系人
+
+- 后端：jw
+- 前端：不涉及（`frontend_status: not_required`）