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

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	8642	团期详情（A2）进度条导游 / 摄影分支改为看名册——本位配了人即「已完成」，招募中也一样；「无需」只留给不需要且没配人	admin	jw(GIT)	修改接口	deployed	verified	not_required					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。	2026-09-30	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，如「配导游·已完成」

请求示例

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；名册有导游李雪梅、领队巴特尔，没有摄影）：

{
  "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 为「未配齐」，不需要为「无需」，与改前一致。

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2105074297745866753",
    "batchStatus": "CANCELLED",
    "progressStepper": []
  }
}

错误响应

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