d39345076e
新增 GET/PUT /v3/admin/group-batch/{groupBatchId}/staff（团期配置+扇出）；
order/{id}/staff 出参加 source，团期共享行订单侧只读（582109）。管理后台 v3。
168 行
7.6 KiB
Markdown
168 行
7.6 KiB
Markdown
# 团期级 staff 两级配置（团期共享 + 订单专属）
|
||
|
||
> 端类型：**管理后台**（v3）｜变更类型：**新增接口 + 修改接口**｜服务：hl-order-service-v3
|
||
> Issue #3560 ｜ PR #3567 ｜日期：2026-06-07
|
||
|
||
## ① 接口背景
|
||
|
||
团期产品（小蒙马等）同一团期（groupBatchId）下多个订单**共享同一批出团团队**（领队/摄影/司导）。原先 staff 只能逐订单配置（`order_staff_assignment`），同团期 N 个订单要重复配 N 次。
|
||
|
||
本次新增**团期级**配置：按团期配一次，后端自动扇出到团内所有订单；同时保留**订单级专属**配置，两级叠加。前端形成两个配置入口：
|
||
- 独立的「团期 staff 配置页」（按 groupBatchId 配，本次新增接口）
|
||
- 订单详情「staff 配置」（订单专属，沿用原接口，出参新增 source 字段区分来源）
|
||
|
||
## ② 变更清单
|
||
|
||
| 接口 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `GET /v3/admin/group-batch/{groupBatchId}/staff` | 新增 | 查团期 staff 配置列表 |
|
||
| `PUT /v3/admin/group-batch/{groupBatchId}/staff` | 新增 | 全量保存团期配置 + 扇出团内订单 |
|
||
| `GET /v3/admin/order/{id}/staff` | 修改 | 出参新增 `source` 字段（GROUP_BATCH/ORDER） |
|
||
| `DELETE /v3/admin/order/{id}/staff/{staffAssignmentId}` | 行为变更 | 团期来源行（source=GROUP_BATCH）禁止在订单侧删除（582109） |
|
||
| `PUT /v3/admin/order/{id}/staff/{staffAssignmentId}` | 行为变更 | 团期来源行禁止在订单侧编辑（582109） |
|
||
|
||
## ③ 接口详情
|
||
|
||
### 接口 A：查询团期 staff 配置
|
||
`GET /v3/admin/group-batch/{groupBatchId}/staff`
|
||
打开「团期 staff 配置页」时调用，回填当前团期已配的共享 staff。
|
||
|
||
### 接口 B：保存团期 staff 配置（全量 + 扇出）
|
||
`PUT /v3/admin/group-batch/{groupBatchId}/staff`
|
||
**全量覆盖语义**：传入列表即为最终状态，后端软删旧配置后插入新配置。保存成功后**异步**扇出到团内所有活跃订单的 `order_staff_assignment`（source=GROUP_BATCH），订单专属行（source=ORDER）不受影响。
|
||
|
||
### 接口 C：订单 staff 列表（出参加字段）
|
||
`GET /v3/admin/order/{id}/staff` 出参每项新增 `source`，前端据此区分「团期共享」（置灰、不可在订单侧增删改）与「订单专属」（可增删改）。
|
||
|
||
## ④ 入参
|
||
|
||
### 接口 A（GET）
|
||
| 参数 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| groupBatchId | path | Long | 是 | 团期批次 ID |
|
||
|
||
### 接口 B（PUT）
|
||
路径参数：`groupBatchId`（Long，必填）
|
||
|
||
请求体 `BatchStaffConfigReqVO`：
|
||
| 字段 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|
|
||
| staffList | List\<Item\> | 是 | staff 配置**全集**（全量覆盖，传空数组=清空团期配置） |
|
||
|
||
`Item`：
|
||
| 字段 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|
|
||
| staffId | Long | 是 | 用户域员工 ID |
|
||
| staffRole | String | 是 | 员工角色（见枚举） |
|
||
| sortOrder | Integer | 否 | 展示排序（默认 0） |
|
||
| remark | String | 否 | 备注（≤500） |
|
||
|
||
> 注：`staffName` / `staffPhone` / `avatarUrl` 由后端 Feign 反查冻结快照，**前端不传**。
|
||
|
||
**入参示例**
|
||
```json
|
||
{
|
||
"staffList": [
|
||
{"staffId": 40001, "staffRole": "LEADER", "sortOrder": 0, "remark": "首席领队"},
|
||
{"staffId": 40002, "staffRole": "PHOTOGRAPHER", "sortOrder": 1, "remark": "跟拍摄影"}
|
||
]
|
||
}
|
||
```
|
||
|
||
## ⑤ 出参
|
||
|
||
### 接口 A：`Result<List<BatchStaffItemVO>>`
|
||
### 接口 B：`Result<BatchStaffConfigRespVO>`
|
||
|
||
`BatchStaffConfigRespVO`：
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| staffList | List\<BatchStaffItemVO\> | 保存后当前团期配置快照 |
|
||
| affectedOrderCount | int | 扇出影响的活跃订单数（已触发异步写入） |
|
||
|
||
`BatchStaffItemVO`：
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | Long | 记录 ID（batch_staff_id） |
|
||
| staffId | Long | 用户域员工 ID |
|
||
| staffRole | String | 员工角色 |
|
||
| staffName | String | 员工姓名（快照） |
|
||
| staffPhone | String | 员工手机（脱敏前 3 后 4） |
|
||
| avatarUrl | String | 头像 URL（快照） |
|
||
| sortOrder | Integer | 展示排序 |
|
||
| remark | String | 备注 |
|
||
|
||
### 接口 C：`GET /order/{id}/staff` 出参 `StaffAssignmentVO` 新增字段
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| source | String | **新增**。GROUP_BATCH=团期共享（不可在订单侧改） / ORDER=订单专属 |
|
||
|
||
**接口 B 出参示例**
|
||
```json
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"staffList": [
|
||
{"id": 770001, "staffId": 40001, "staffRole": "LEADER", "staffName": "刘领队",
|
||
"staffPhone": "138****6677", "avatarUrl": "https://oss/40001.jpg", "sortOrder": 0, "remark": "首席领队"}
|
||
],
|
||
"affectedOrderCount": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
## ⑥ 枚举 / 数据字典
|
||
|
||
| 枚举 | 取值 | 含义 |
|
||
|---|---|---|
|
||
| staffRole | LEADER / DRIVER / PHOTOGRAPHER / OTHER | 领队 / 司机 / 摄影师 / 其他 |
|
||
| source | GROUP_BATCH / ORDER | 团期共享 / 订单专属 |
|
||
|
||
## ⑦ 错误码
|
||
|
||
| code | message | 触发 |
|
||
|---|---|---|
|
||
| 582109 | 团期共享 staff 不可在订单侧增删改，请到团期配置页操作 | 对 source=GROUP_BATCH 的行调订单侧 DELETE/PUT staff |
|
||
| 400 | 参数校验失败 | staffId/staffRole 缺失等 |
|
||
| 401 | 缺少有效的 Authorization 头 | 未携带 token |
|
||
|
||
## ⑧ 示例（典型 / 边界 / 异常）
|
||
|
||
- **典型**：团期配「领队+摄影」→ 保存返回 affectedOrderCount=3（团内 3 个活跃订单已扇出）。
|
||
- **边界**：staffList 传 `[]` → 清空该团期配置，并扇出删除团内订单的所有 GROUP_BATCH 行（订单专属行保留）。
|
||
- **异常**：在订单详情对一个「团期共享」的领队点删除 → 返回 582109，前端应禁用团期行的删除/编辑按钮。
|
||
|
||
## ⑨ 业务边界
|
||
|
||
- **全量覆盖**：保存即最终状态，未在列表中的旧团期 staff 会被软删并从团内订单移除。
|
||
- **扇出范围**：仅团内**活跃**订单（已完成 / 已取消订单不被扇出刷新，保留历史团队记录）。
|
||
- **两级叠加**：订单详情 staff = 团期共享（GROUP_BATCH） + 订单专属（ORDER），同一员工去重。
|
||
- **下单自动写入**：团期已配 staff 后新下单的订单，创建时自动带上团期 staff。
|
||
- **异步最终一致**：扇出为异步，保存接口返回后团内订单的更新可能有秒级延迟（affectedOrderCount 表示已触发的订单数）。
|
||
|
||
## ⑩ 修改前后对比
|
||
|
||
| | 修改前 | 修改后 |
|
||
|---|---|---|
|
||
| 团期共享配置 | 无，同团期逐单重复配 | 团期配一次自动扇出团内 |
|
||
| order/{id}/staff 出参 | 无 source | 每项带 source（GROUP_BATCH/ORDER） |
|
||
| 订单侧删/改团期行 | 可删（会造成与团期不一致） | 禁止（582109），引导去团期页 |
|
||
|
||
## ⑪ 影响评估 / 回滚
|
||
|
||
- **存量兼容**：`order_staff_assignment` 加 source 列默认 ORDER，存量行全部视为订单专属，原订单 staff 展示不变。
|
||
- **前端必改**：订单 staff 列表需按 source 渲染（团期行置灰禁操作）；新增团期配置页对接 A/B 接口。
|
||
- **回滚**：接口为新增 + 加字段，回滚后前端忽略 source 字段即可，无破坏性。
|
||
|
||
## ⑫ 注意事项
|
||
|
||
- 团期配置页的「团期信息」（团期号/出发日期/产品）由**产品服务 admin 接口**提供，本接口只管 staff。
|
||
- 保存后 affectedOrderCount 是「已触发异步写入」数，非「已写完」数；前端如需精确状态可重查订单。
|
||
- staffPhone 出参已脱敏（前 3 后 4），列表展示直接用即可。
|
||
|
||
## ⑬ 关联 / 联系人
|
||
|
||
- Issue：https://git.1814.love:8443/wx/HL/issues/3560
|
||
- PR：https://git.1814.love:8443/wx/HL/pulls/3567
|
||
- 后端负责人：腰苏图（订单 v3）
|