---
schema: "hl-changelog/v2"
ticket: "8468"
title: "团期导领摄配置加服务日期与基础日薪，选人列表与名册显示占用状态，导摄芯片去掉逐户人员"
consumer: "admin"
author: "jw(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "838b80d69dd1ff5a96e6a95e886d979dac5f452c"
target_release: "v2.1"
verified_at: "2026-09-28"
status_note: "PR #8475（bf65803b7）与 #8476（623c932bd）已合入 dev-v3，TEST 的 hl-resource-service 与 hl-order-service-v3 均运行 dev-v3 623c932bd；经网关 api.test.1814.love 用真实 admin token 实测 AC-1、3、6~13、15、16 主路径全部通过，金额字段字符串形态已复验。前端需接：选人弹窗展示等级、服务区域、擅长、基础日薪与占用标签，占用明细弹层，保存弹窗编辑服务日期，服务人员管理基础日薪回显与列表列，导摄页签与看板芯片弹层去掉逐户人员表（见第四节交接清单），故 frontend_status 记 pending。前端已交付(人员画像/占用标签/服务日期三态+导摄芯片去逐户人员),详见 hl-admin v2.1 提交 838b80d6。"
updated_at: "2026-09-28"
base: "dev-v3"
---

# 团期人员配置：服务日期、基础日薪与占用状态（管理后台）

> **服务**: hl-order-service-v3（团期人员配置、导/摄芯片明细）、hl-resource-service（服务人员管理）
> **PR**: #8475（主体，合入 dev-v3 为 `bf65803b7`）、#8476（金额字段改字符串输出，合入 dev-v3 为 `623c932bd`）
> **Issue**: #8468
> **日期**: 2026-09-28
> **影响范围**: 团期详情「配导游」「配摄影」的选人弹窗、已配置人员名册与保存弹窗，看板导/摄芯片弹层，服务人员管理新建/编辑/详情/列表

---

## ⚠️ 关键变化

1. **名册与候选新增占用**：已配置人员名册（以及保存、更换、删除响应里的 `staffList[]`）和两个候选接口的每一项都新增 `occupancyStatus`（`FREE` 空闲 / `PARTIAL` 部分占用 / `FULL` 全程占用）、`occupiedDays`、`freeRanges`、`occupancies[]`。占用**只提示、不拦截**，有占用照样能保存。
2. **名册新增服务日期与基础日薪**：`serviceStartDate`、`serviceEndDate`、`serviceDateCustom`、`baseDailyWage`。保存接口每人可选传 `serviceStartDate` / `serviceEndDate`；日期不合法返回**新错误码 `582119`**（文案带人名，整批不写入）。
3. **候选新增人员画像并改为全局排序**：候选项新增 `level`、`serviceAreas`、`specialties`、`baseDailyWage`；排序改为「本团本位已选 → 空闲 → 部分占用 → 全程占用 → 等级从高到低 → `sortOrder` 升序 → `staffId` 升序」，分页版逐页翻完不重不漏。
4. **金额字段是 JSON 字符串**：order-v3 的 `baseDailyWage` 与服务人员管理的 `basePrice` 都以字符串输出（如 `"600.00"`）。做数值运算、比较大小或回填数字输入框前先 `Number()`。
5. **导/摄芯片不再逐户返回人员**：`GET .../chips/guide`、`GET .../chips/photo` 的 `items` 恒为 `[]`，只看 `staffList`（团期名册）。`aggregateStatus` / `totalCount` / `doneCount` 口径不变。
6. **修复：保存导游位后主报账人与备注被重置**。保留下来的人（即使请求只带 `staffId`、`staffRole`、`sortOrder`）沿用原来的报账人等级、备注、服务日期与日薪。随之 **`remark` 口径变化**：不传（`null`）= 沿用原备注；要清空请传空串 `""`。

---

## 一、背景

选人弹窗原来只有姓名、手机号、类型，看不到等级、服务区域、擅长和日薪，也看不出这个人同一时段是否已派到别的团或订单；导游/摄影页签下的逐户表把团期名册在每个子订单上重复列一遍；每保存一次导游位，主报账人被重置、备注被清空；服务人员管理的「基础日薪」输入框填了不保存。

jw 2026-09-28 定案口径：

| # | 口径 |
|---|---|
| D1 | 基础日薪在选人时从服务人员管理的「基础日薪」带出，团期里不能改。更换人员取新人的档案值。档案值为 0 或空时返回 null。快照为空时，下次保存补取一次档案当前值；已有值不刷新 |
| D2 | 服务日期不填就跟随团期：读的时候换算成团期出发日和结束日，团期改期后自动跟着变。提交的日期和团期起止相同也按跟随团期处理 |
| D3 | 招募中（还没成团）的团期里派了的人，也算占用 |
| D4 | 日期段两端都算：前一个团结束当天、后一个团出发，这种首尾相接也算占用 |
| D5 | 占用只提示，不拦截。有占用照样能保存，也不要求二次确认 |
| D6 | 保存时，保留下来的人员沿用原来那一行的报账人等级、备注、服务日期和日薪；请求里传了的以请求为准 |
| D7 | 占用有两个来源：①其他团期的人员配置；②普通订单（不属于任何团期）上定制师直接派的人。团期同步到子订单的人员副本不重复计算。已取消的订单不算，其余订单状态都算 |
| D8 | 占用分三档：被占 0 天为空闲，被占满整段为全程占用，其余为部分占用 |
| D9 | 本单不做「只看空闲」筛选 |
| D10 | 导游/摄影不再按子订单逐户展示配置人员，看团期整体名册即可 |

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 保存团期人员配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 修改：入参加字段、新错误码、出参加字段 | 每人可选 `serviceStartDate`、`serviceEndDate`；日薪由服务端带出；新错误码 582119；保留人员沿用原等级、备注、日期、日薪 |
| 2 | 查询团期人员名册 | GET | `/v3/admin/group-batch/{productBatchId}/staff` | 修改：出参加字段 | 每人加服务日期、是否自定义、基础日薪与四个占用字段 |
| 3 | 团期单人更换 | PUT | `/v3/admin/group-batch/{productBatchId}/staff/{staffId}/replace` | 修改：行为、新错误码、出参加字段 | 新人沿用原人服务日期，日薪取新人档案；可能返回 582119 |
| 4 | 团期单人删除 | DELETE | `/v3/admin/group-batch/{productBatchId}/staff/{staffId}` | 修改：出参加字段 | 响应 `staffList[]` 加字段 |
| 5 | 团期人员候选分页 | GET | `/v3/admin/group-batch/{productBatchId}/staff/candidates/page` | 修改：出参加字段、排序变化 | 加等级、区域、擅长、日薪与占用；全局排序后分页 |
| 6 | 团期人员候选列表 | GET | `/v3/admin/group-batch/{productBatchId}/staff/candidates` | 修改：出参加字段、排序变化 | 与 5 相同（全量版） |
| 7 | 配导游芯片明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/guide` | 修改：出参取值变化 | `items` 恒为 `[]`，只看 `staffList` |
| 8 | 配摄影芯片明细 | GET | `/v3/admin/order/group-batch/{groupBatchId}/chips/photo` | 修改：出参取值变化 | `items` 恒为 `[]`，只看 `staffList` |
| 9 | 新建服务人员 | POST | `/admin/staff` | 修改：入参加字段、出参加字段 | 可传 `basePrice`；响应 `basePrice` 为字符串 |
| 10 | 编辑服务人员 | PUT | `/admin/staff/{staffId}` | 修改：入参加字段、出参加字段 | `basePrice` 可改，不传不改；负数或超过 2 位小数返回 400 |
| 11 | 服务人员详情 | GET | `/admin/staff/{staffId}` | 修改：出参加字段 | 返回字符串 `basePrice` |
| 12 | 服务人员列表 | GET | `/admin/staff/list` | 修改：出参加字段 | 每条返回字符串 `basePrice` |

---

## 三、接口详情

### 1. 保存团期人员配置 `PUT /v3/admin/group-batch/{productBatchId}/staff`

**VO**: `BatchStaffConfigReqVO` → `BatchStaffConfigRespVO`

#### 使用场景

「配导游」「配摄影」保存弹窗点「保存」时调用。本单起弹窗里可以给每个人填服务开始 / 结束日期（不填 = 跟随团期）；基础日薪只读展示，不提交。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productBatchId | Path | Long | 是 | 产品侧排期 ID | 取 `detail.productBatchId`，不是团期 ID（既有） |
| scopeRoles | Body | String[] | 否 | 传了就不能是 `[]`；导游位必须同时含 `GUIDE` 与 `LEADER` | 本次覆盖的角色范围；不传 = 整期覆盖（既有） |
| staffList | Body | Object[] | 是 | 显式传 `[]` = 清空覆盖范围 | 覆盖范围内的最终名单（既有） |
| staffList[].staffId | Body | Long | 是 | - | 人员 ID（既有） |
| staffList[].staffRole | Body | String | 是 | 取值域不变 | 角色，如 `LEADER`、`GUIDE`、`PHOTOGRAPHER`（既有） |
| staffList[].sortOrder | Body | Integer | 否 | 缺省 0 | 展示排序（既有；不沿用原值） |
| staffList[].remark | Body | String | 否 | ≤500 字 | **口径变化**：不传（`null`）时，保留下来的人沿用原备注；传空串 `""` 才是清空；新选的人不传即无备注 |
| staffList[].serviceStartDate | Body | String(yyyy-MM-dd) | 否 | 有效开始日不晚于有效结束日，且在团期出发日到结束日之间，否则 582119 | **新增**。服务开始日。不传：保留下来的人沿用原值，新选的人跟随团期。与团期出发日相同按跟随团期处理。要把自定义日期改回跟随团期，传团期出发日本身 |
| staffList[].serviceEndDate | Body | String(yyyy-MM-dd) | 否 | 同上 | **新增**。服务结束日，口径同上，对照团期结束日 |
| staffList[].baseDailyWage | Body | - | 否 | 不接收 | 请求里带了会被忽略（不报错、不落库）；日薪一律由服务端从服务人员档案带出 |

#### 出参 `Result<BatchStaffConfigRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| productBatchId | String | 回显路径参数（既有） |
| groupBatchId | String | 运营团期 ID（既有） |
| affectedOrderCount | Integer | 同步到的活跃子订单数（既有） |
| staffList | Object[] | 保存后的整期名单（既有）。既有字段 `id`、`staffId`、`staffRole`、`staffRoleName`、`staffName`、`staffPhone`、`avatarUrl`、`sortOrder`、`remark`、`reporterRank`、`reporterRankName` 不变；`staffStatus`、`liveInfoDegraded` 在本接口为 null（既有） |
| staffList[].serviceStartDate | String(yyyy-MM-dd) | **新增**。有效服务开始日：没自定义 = 团期出发日（团期改期后跟着变）；自定义值原样显示；只有团期出发日为空时为 null |
| staffList[].serviceEndDate | String(yyyy-MM-dd) | **新增**。有效服务结束日，口径同上，对照团期结束日 |
| staffList[].serviceDateCustom | Boolean | **新增**。开始或结束任一自定义过为 `true`；都跟随团期为 `false`；恒非 null |
| staffList[].baseDailyWage | String | **新增**。基础日薪快照，字符串如 `"1000.00"`；档案未填或为 0 时为 null；前端运算前 `Number()` |
| staffList[].occupancyStatus | String | **新增**。`FREE` / `PARTIAL` / `FULL`，按这个人在本团的服务日期段比对；本团期未建或团期起止不全时为 null |
| staffList[].occupiedDays | Integer | **新增**。服务日期段内被占的天数（两端都算）；`occupancyStatus` 为 null 时为 0 |
| staffList[].freeRanges | String[] | **新增**。可派日期段，形如 `2026-10-28~2026-10-28`，按日期升序；全程占用或 `occupancyStatus` 为 null 时为 `[]` |
| staffList[].occupancies | Object[] | **新增**。占用明细，按 `startDate` 升序；空闲或 `occupancyStatus` 为 null 时为 `[]` |
| staffList[].occupancies[].sourceType | String | 来源：`GROUP_BATCH` 其他团期的人员配置 / `ORDER` 普通订单上定制师直派 |
| staffList[].occupancies[].sourceId | String | 来源 ID：`GROUP_BATCH` 为运营团期 ID，`ORDER` 为订单 ID |
| staffList[].occupancies[].refNo | String | 团期号 / 订单号；源数据为空时为 null |
| staffList[].occupancies[].title | String | 团期名称（为空时取产品名）/ 订单的产品名；都为空时为 null |
| staffList[].occupancies[].statusName | String | 来源当前状态中文名，如「招募中」「待出行」 |
| staffList[].occupancies[].staffRole / staffRoleName | String | 他在那边的角色及中文名（跨角色也计入占用） |
| staffList[].occupancies[].startDate / endDate | String(yyyy-MM-dd) | 他在那边的服务起止：团期为他在那个团的有效服务日期（自定义日期先夹进那个团当前起止）；订单为出发日到返回日（返回日为空按出发日当天） |
| staffList[].occupancies[].overlapStartDate / overlapEndDate | String(yyyy-MM-dd) | 与本团服务日期段重叠的起止，两端都算，恒在本团服务日期段内 |

#### 请求示例

```http
PUT /v3/admin/group-batch/2104455374549721090/staff
Authorization: Bearer <admin token>
Content-Type: application/json

{
  "scopeRoles": ["GUIDE", "LEADER"],
  "staffList": [
    {
      "staffId": 1005,
      "staffRole": "LEADER",
      "sortOrder": 1,
      "remark": "负责额尔古纳段",
      "serviceStartDate": "2026-10-27",
      "serviceEndDate": "2026-10-28"
    }
  ]
}
```

#### 响应示例

2026-09-28 测试服实测（班期 10-26 ~ 10-28，刘大山 10-27 已被一张普通订单派为领队；金额按当前契约写成字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "productBatchId": "2104455374549721090",
    "groupBatchId": "2104455377657724930",
    "staffList": [
      {
        "id": "2104456232708509698",
        "staffId": 1005,
        "staffRole": "LEADER",
        "staffRoleName": "领队",
        "staffName": "刘大山",
        "staffPhone": "138****1005",
        "avatarUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/26/45d9abebc569ca7b7ab13cac212ca38a.png",
        "sortOrder": 1,
        "remark": "负责额尔古纳段",
        "reporterRank": "NONE",
        "reporterRankName": "非报账人",
        "staffStatus": null,
        "liveInfoDegraded": null,
        "serviceStartDate": "2026-10-27",
        "serviceEndDate": "2026-10-28",
        "serviceDateCustom": true,
        "baseDailyWage": "1000.00",
        "occupancyStatus": "PARTIAL",
        "occupiedDays": 1,
        "freeRanges": ["2026-10-28~2026-10-28"],
        "occupancies": [
          {
            "sourceType": "ORDER",
            "sourceId": "2100743225424621570",
            "refNo": "HL20260918082629372",
            "title": "测试核心产品-单档-固定比例",
            "statusName": "待出行",
            "staffRole": "LEADER",
            "staffRoleName": "领队",
            "startDate": "2026-10-25",
            "endDate": "2026-10-27",
            "overlapStartDate": "2026-10-27",
            "overlapEndDate": "2026-10-27"
          }
        ]
      }
    ],
    "affectedOrderCount": 1
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

- `staffList: []`（清空覆盖范围）：照常 200，响应 `staffList` 是保存后的整期名单，范围内的人已移除（既有）。
- 团期起止任一端为空时：名册项 `serviceStartDate` / `serviceEndDate` 可能为 null，占用四字段为 `null` / `0` / `[]` / `[]`。
- 占用不影响保存结果：有占用、全程占用都照样 200。

#### 错误响应

```json
{
  "code": 582119,
  "message": "萨仁高娃 的服务日期（2026-11-16 至 2026-11-19）不合法：开始日期不能晚于结束日期，且须在团期日期（2026-11-17 至 2026-11-19）之内",
  "data": null,
  "traceId": null,
  "success": false
}
```

| code | 触发条件 |
|---|---|
| `582119` | **新增**。某人的有效服务开始日晚于结束日，或越出团期出发日到结束日；文案里是人名和他的有效起止、团期起止（团期日期不全时写「未定」）；整批不写入 |
| `582115` / `582116` | 角色超出 `scopeRoles` / 只声明了半个配置位（既有；同时触犯时先报这两个） |
| `589553` / `589598` | 团期尚未创建 / 团期已确认或已取消（既有） |
| `400` | 缺 `staffList`、`remark` 超 500 字、日期格式不对等参数校验（既有机制） |

#### 业务边界

- 判权未改：需要团期管理权限 `group-batch:manage`。
- 「保留下来的人」= 本次提交里、且在本次覆盖范围内原本就有记录的人（按 `staffId` 认）。他们的报账人等级一律沿用（本接口改不了等级，改等级走 `PUT .../staff/{staffId}/reporter-rank`）；备注、服务日期请求没传时沿用；日薪原快照非空时沿用。
- 日薪（D1）：新选的人取服务人员档案当前的基础日薪（0 或空 → null）；保留下来的人原快照非空不刷新，原快照为空时补取一次档案当前值；请求里的 `baseDailyWage` 一律忽略。
- 服务日期（D2）：与团期起止相同按跟随团期处理，名册 `serviceDateCustom=false`；自定义才算 `true`。开始、结束两端各自判断。
- 582119 校验的是本次所有要写入的人，**包括沿用来的旧日期**：团期改期后旧的自定义日期可能已落在新团期外，这时保存同样返回 582119，文案点名，先把那个人的日期改到团期内再保存。
- 返回 582119 时整批不写入：原名册一行不变。
- 占用只提示不拦截（D5）。

### 2. 查询团期人员名册 `GET /v3/admin/group-batch/{productBatchId}/staff`

**VO**: `List<BatchStaffConfigRespVO.BatchStaffItemVO>`

#### 使用场景

「配导游」「配摄影」页签打开时拉已配置人员，前端按 `staffRole` 分到导游位（`GUIDE` / `LEADER`）与摄影位（`PHOTOGRAPHER`）两张表。本单起每行可展示服务日期、基础日薪与占用标签。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productBatchId | Path | Long | 是 | 产品侧排期 ID | 取 `detail.productBatchId`，不是团期 ID（既有） |

#### 出参 `Result<List<BatchStaffItemVO>>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 团期人员记录 ID（既有；整位保存后会变，单人操作用 `staffId`） |
| staffId | Long | 人员 ID（既有） |
| staffRole / staffRoleName | String | 角色及中文名（既有） |
| staffName / staffPhone / avatarUrl | String | 姓名、脱敏手机号、头像（既有） |
| sortOrder | Integer | 排序（既有） |
| remark | String | 备注（既有） |
| reporterRank / reporterRankName | String | 报账人等级及中文名（既有） |
| staffStatus / liveInfoDegraded | String / Boolean | 人员在资源库的状态、是否降级为快照（既有，仅本接口填充） |
| serviceStartDate | String(yyyy-MM-dd) | **新增**。有效服务开始日：没自定义 = 团期出发日（团期改期后跟着变）；自定义值原样显示；只有团期出发日为空时为 null |
| serviceEndDate | String(yyyy-MM-dd) | **新增**。有效服务结束日，口径同上，对照团期结束日 |
| serviceDateCustom | Boolean | **新增**。开始或结束任一自定义过为 `true`；恒非 null |
| baseDailyWage | String | **新增**。基础日薪快照，字符串如 `"1000.00"`；档案未填或为 0 时为 null；前端运算前 `Number()` |
| occupancyStatus | String | **新增**。`FREE` / `PARTIAL` / `FULL`，按这个人在本团的服务日期段比对；本团期未建或团期起止不全时为 null |
| occupiedDays | Integer | **新增**。服务日期段内被占天数（两端都算）；`occupancyStatus` 为 null 时为 0 |
| freeRanges | String[] | **新增**。可派日期段 `yyyy-MM-dd~yyyy-MM-dd`，升序；全程占用或 `occupancyStatus` 为 null 时为 `[]` |
| occupancies | Object[] | **新增**。占用明细，按 `startDate` 升序；空闲或 `occupancyStatus` 为 null 时为 `[]` |
| occupancies[].sourceType | String | `GROUP_BATCH` 其他团期的人员配置 / `ORDER` 普通订单上定制师直派 |
| occupancies[].sourceId | String | `GROUP_BATCH` 为运营团期 ID，`ORDER` 为订单 ID |
| occupancies[].refNo | String | 团期号 / 订单号；源数据为空时为 null |
| occupancies[].title | String | 团期名称（为空时取产品名）/ 订单的产品名；都为空时为 null |
| occupancies[].statusName | String | 来源当前状态中文名，如「招募中」「待出行」 |
| occupancies[].staffRole / staffRoleName | String | 他在那边的角色及中文名（跨角色也计入占用） |
| occupancies[].startDate / endDate | String(yyyy-MM-dd) | 他在那边的服务起止：团期为他在那个团的有效服务日期（自定义日期先夹进那个团当前起止）；订单为出发日到返回日（返回日为空按出发日当天） |
| occupancies[].overlapStartDate / overlapEndDate | String(yyyy-MM-dd) | 与本团服务日期段重叠的起止，两端都算 |

#### 请求示例

```http
GET /v3/admin/group-batch/2104455359768993795/staff
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测（班期 11-17 ~ 11-19；白云飞跟随团期，萨仁高娃自定义为 11-18 单日；金额按当前契约写成字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "id": "2104455839127633921",
      "staffId": 1007,
      "staffRole": "LEADER",
      "staffRoleName": "领队",
      "staffName": "白云飞",
      "staffPhone": "139****1007",
      "avatarUrl": null,
      "sortOrder": 1,
      "remark": null,
      "reporterRank": "NONE",
      "reporterRankName": "非报账人",
      "staffStatus": "ON_SHELF",
      "liveInfoDegraded": false,
      "serviceStartDate": "2026-11-17",
      "serviceEndDate": "2026-11-19",
      "serviceDateCustom": false,
      "baseDailyWage": "800.00",
      "occupancyStatus": "FREE",
      "occupiedDays": 0,
      "freeRanges": ["2026-11-17~2026-11-19"],
      "occupancies": []
    },
    {
      "id": "2104455839131828226",
      "staffId": 1008,
      "staffRole": "LEADER",
      "staffRoleName": "领队",
      "staffName": "萨仁高娃",
      "staffPhone": "139****1008",
      "avatarUrl": null,
      "sortOrder": 2,
      "remark": null,
      "reporterRank": "NONE",
      "reporterRankName": "非报账人",
      "staffStatus": "ON_SHELF",
      "liveInfoDegraded": false,
      "serviceStartDate": "2026-11-18",
      "serviceEndDate": "2026-11-18",
      "serviceDateCustom": true,
      "baseDailyWage": null,
      "occupancyStatus": "FREE",
      "occupiedDays": 0,
      "freeRanges": ["2026-11-18~2026-11-18"],
      "occupancies": []
    }
  ],
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

- 未配置人员：`data: []`（测试服未建团期的班期实测即为 `[]`）。
- 本团期未建或团期起止不全：每行 `occupancyStatus=null`、`occupiedDays=0`、`freeRanges=[]`、`occupancies=[]`。
- 资源服务不可用：姓名手机回落快照、`liveInfoDegraded=true`（既有）；本单新增的服务日期、日薪、占用字段照常返回，不依赖资源服务。

#### 错误响应

判权未改动（`group-batch:view`）。

```json
{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "data": null,
  "success": false
}
```

#### 业务边界

- 名册项**不含**等级、服务区域、擅长（这几列只在两个候选接口返回）；名册要展示时从候选接口按 `staffId` 取。
- 占用比对用的日期段 = 这个人在本团的有效服务日期，先夹进本团当前起止；展示的 `serviceStartDate` / `serviceEndDate` 不夹。团期改期后旧的自定义日期越出团期时，名册照实显示越界日期，保存时会 582119。
- 占用来源口径见第六节；占用只提示不拦截。

### 3. 团期单人更换 `PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/replace`

**VO**: `BatchStaffReplaceReqVO` → `BatchStaffReplaceRespVO`

#### 使用场景

名册表格某一行点「更换」，从候选里选一个新人替换原人。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productBatchId | Path | Long | 是 | 产品侧排期 ID | 同名册接口（既有） |
| staffId | Path | Long | 是 | 须在本团名册中 | 被换下的人（既有） |
| newStaffId | Body | Long | 是 | 上架、类型符合原配置位、不在本团、不等于 `staffId` | 换上的人（既有） |

#### 出参 `Result<BatchStaffReplaceRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| productBatchId / groupBatchId | String | 回显 / 运营团期 ID（既有） |
| oldStaffId / newStaffId | Long | 被换下 / 换上的人员 ID（既有） |
| staffRole | String | 新人落库角色（既有） |
| reporterRank | String | 新人继承的报账人等级（既有） |
| primaryReporterTransferred | Boolean | 主报账人是否转给了新人（既有） |
| affectedOrderCount | Integer | 同步替换的活跃子订单数（既有） |
| staffList | Object[] | 更换后的整期名单（既有字段不变，`staffStatus`、`liveInfoDegraded` 为 null） |
| staffList[].serviceStartDate / serviceEndDate | String(yyyy-MM-dd) | **新增**。有效服务起止；新人沿用原人的服务日期 |
| staffList[].serviceDateCustom | Boolean | **新增**。是否自定义过服务日期 |
| staffList[].baseDailyWage | String | **新增**。基础日薪快照（新人取新人档案值），字符串；0 或空为 null |
| staffList[].occupancyStatus | String | **新增**。`FREE` / `PARTIAL` / `FULL`；本团期未建或团期起止不全时为 null |
| staffList[].occupiedDays | Integer | **新增**。被占天数 |
| staffList[].freeRanges | String[] | **新增**。可派日期段 `yyyy-MM-dd~yyyy-MM-dd` |
| staffList[].occupancies | Object[] | **新增**。占用明细，按 `startDate` 升序 |
| staffList[].occupancies[].sourceType / sourceId | String | `GROUP_BATCH` + 运营团期 ID，或 `ORDER` + 订单 ID |
| staffList[].occupancies[].refNo / title / statusName | String | 团期号或订单号 / 团期名称或产品名 / 来源状态中文名 |
| staffList[].occupancies[].staffRole / staffRoleName | String | 他在那边的角色及中文名 |
| staffList[].occupancies[].startDate / endDate | String(yyyy-MM-dd) | 他在那边的服务起止 |
| staffList[].occupancies[].overlapStartDate / overlapEndDate | String(yyyy-MM-dd) | 与本团服务日期段重叠的起止 |

#### 请求示例

```http
PUT /v3/admin/group-batch/2104455374549721090/staff/1005/replace
Authorization: Bearer <admin token>
Content-Type: application/json

{ "newStaffId": 1007 }
```

#### 响应示例

2026-09-28 测试服实测：原人刘大山（主报账人，服务日期 10-27 ~ 10-28，日薪 1000）换成白云飞（档案日薪 800）。等级、备注、服务日期随位置转给新人，日薪取新人档案：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "productBatchId": "2104455374549721090",
    "groupBatchId": "2104455377657724930",
    "oldStaffId": 1005,
    "newStaffId": 1007,
    "staffRole": "LEADER",
    "reporterRank": "PRIMARY",
    "primaryReporterTransferred": true,
    "affectedOrderCount": 1,
    "staffList": [
      {
        "id": "2104456292880023553",
        "staffId": 1007,
        "staffRole": "LEADER",
        "staffRoleName": "领队",
        "staffName": "白云飞",
        "staffPhone": "139****1007",
        "avatarUrl": null,
        "sortOrder": 1,
        "remark": "负责额尔古纳段",
        "reporterRank": "PRIMARY",
        "reporterRankName": "主报账人",
        "staffStatus": null,
        "liveInfoDegraded": null,
        "serviceStartDate": "2026-10-27",
        "serviceEndDate": "2026-10-28",
        "serviceDateCustom": true,
        "baseDailyWage": "800.00",
        "occupancyStatus": "FREE",
        "occupiedDays": 0,
        "freeRanges": ["2026-10-27~2026-10-28"],
        "occupancies": []
      }
    ]
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

写接口，无空数据形态；任何校验失败都不写入。新人档案日薪为 0 或空时，新行 `baseDailyWage` 为 null。

#### 错误响应

以下 582119 按源码文案模板拼出（示意，测试服未造「团期改期后旧日期越界再更换」的数据）：

```json
{
  "code": 582119,
  "message": "白云飞 的服务日期（2026-10-25 至 2026-10-28）不合法：开始日期不能晚于结束日期，且须在团期日期（2026-10-26 至 2026-10-28）之内",
  "data": null,
  "success": false
}
```

| code | 触发条件 |
|---|---|
| `582119` | **新增**。原人的自定义服务日期已不在团期起止内（团期改期后没重新保存）；文案里是**新人**的名字；不写入。先在保存弹窗把这个位置的日期改到团期内，再换人 |
| `100001` / `589508` / `589582` | 新旧相同 / 原人不在本团 / 新人已在本团（既有） |
| `582103` / `582118` / `582114` | 资源库取不到新人 / 新人已下架 / 新人类型不符合配置位（既有） |
| `589553` / `589598` | 未建团 / 团期已确认或已取消（既有） |

#### 业务边界

- 服务日期跟位置走：新人原样沿用原人的服务日期（包括「跟随团期」）。
- 日薪跟人走：取新人服务人员档案的基础日薪（D1），不沿用原人的日薪。
- 排序、备注、报账人等级转给新人（既有）。

### 4. 团期单人删除 `DELETE /v3/admin/group-batch/{productBatchId}/staff/{staffId}`

**VO**: `BatchStaffRemoveRespVO`

#### 使用场景

名册表格某一行点「删除」，只移除这一个人。本单只给响应的 `staffList[]` 加字段，删除行为不变。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productBatchId | Path | Long | 是 | 产品侧排期 ID | 同名册接口（既有） |
| staffId | Path | Long | 是 | 须在本团名册中 | 要删除的人（既有） |

#### 出参 `Result<BatchStaffRemoveRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| productBatchId / groupBatchId | String | 回显 / 运营团期 ID（既有） |
| removedStaffId | Long | 被删除的人员 ID（既有） |
| removedStaffRole | String | 被删除人员的角色（既有） |
| primaryReporterRemoved | Boolean | 删的是否是主报账人（既有） |
| affectedOrderCount | Integer | 同步删除副本的活跃子订单数（既有） |
| staffList | Object[] | 删除后的整期名单（既有字段不变，`staffStatus`、`liveInfoDegraded` 为 null） |
| staffList[].serviceStartDate / serviceEndDate | String(yyyy-MM-dd) | **新增**。有效服务起止（没自定义 = 团期起止） |
| staffList[].serviceDateCustom | Boolean | **新增**。是否自定义过服务日期 |
| staffList[].baseDailyWage | String | **新增**。基础日薪快照，字符串；0 或空为 null |
| staffList[].occupancyStatus | String | **新增**。`FREE` / `PARTIAL` / `FULL`；本团期未建或团期起止不全时为 null |
| staffList[].occupiedDays | Integer | **新增**。被占天数 |
| staffList[].freeRanges | String[] | **新增**。可派日期段 `yyyy-MM-dd~yyyy-MM-dd` |
| staffList[].occupancies | Object[] | **新增**。占用明细，按 `startDate` 升序 |
| staffList[].occupancies[].sourceType / sourceId | String | `GROUP_BATCH` + 运营团期 ID，或 `ORDER` + 订单 ID |
| staffList[].occupancies[].refNo / title / statusName | String | 团期号或订单号 / 团期名称或产品名 / 来源状态中文名 |
| staffList[].occupancies[].staffRole / staffRoleName | String | 他在那边的角色及中文名 |
| staffList[].occupancies[].startDate / endDate | String(yyyy-MM-dd) | 他在那边的服务起止 |
| staffList[].occupancies[].overlapStartDate / overlapEndDate | String(yyyy-MM-dd) | 与本团服务日期段重叠的起止 |

#### 请求示例

```http
DELETE /v3/admin/group-batch/2104455356057034754/staff/1009
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测节选（班期 11-16 ~ 11-18；`staffList` 只保留两行；金额按当前契约写成字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "productBatchId": "2104455356057034754",
    "groupBatchId": "2104455358355509249",
    "removedStaffId": 1009,
    "removedStaffRole": "LEADER",
    "primaryReporterRemoved": false,
    "affectedOrderCount": 1,
    "staffList": [
      {
        "id": "2104456120838062081",
        "staffId": 1005,
        "staffRole": "LEADER",
        "staffRoleName": "领队",
        "staffName": "刘大山",
        "staffPhone": "138****1005",
        "sortOrder": 1,
        "remark": "负责草原段带队",
        "reporterRank": "PRIMARY",
        "reporterRankName": "主报账人",
        "staffStatus": null,
        "liveInfoDegraded": null,
        "serviceStartDate": "2026-11-16",
        "serviceEndDate": "2026-11-16",
        "serviceDateCustom": true,
        "baseDailyWage": "1000.00",
        "occupancyStatus": "FREE",
        "occupiedDays": 0,
        "freeRanges": ["2026-11-16~2026-11-16"],
        "occupancies": []
      },
      {
        "id": "2104456120838062082",
        "staffId": 1002,
        "staffRole": "GUIDE",
        "staffRoleName": "导游",
        "staffName": "李雪梅",
        "staffPhone": "138****1002",
        "sortOrder": 2,
        "remark": null,
        "reporterRank": "NONE",
        "reporterRankName": "非报账人",
        "staffStatus": null,
        "liveInfoDegraded": null,
        "serviceStartDate": "2026-11-16",
        "serviceEndDate": "2026-11-18",
        "serviceDateCustom": false,
        "baseDailyWage": "600.00",
        "occupancyStatus": "PARTIAL",
        "occupiedDays": 1,
        "freeRanges": ["2026-11-16~2026-11-17"],
        "occupancies": [
          {
            "sourceType": "GROUP_BATCH",
            "sourceId": "2104455369311031298",
            "refNo": "Q202611182104455365389361153",
            "title": "11月18日海拉尔-额尔古纳3日团",
            "statusName": "招募中",
            "staffRole": "GUIDE",
            "staffRoleName": "导游",
            "startDate": "2026-11-18",
            "endDate": "2026-11-20",
            "overlapStartDate": "2026-11-18",
            "overlapEndDate": "2026-11-18"
          }
        ]
      }
    ]
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

删光后 `staffList` 为 `[]`（既有）。本团期未建或团期起止不全时，名单项占用四字段为 `null` / `0` / `[]` / `[]`。

#### 错误响应

错误码未改动。

```json
{
  "code": 589508,
  "message": "报账人不是该团期已派员工",
  "data": null,
  "success": false
}
```

#### 业务边界

- 删除行为、错误码与判权（`group-batch:manage`）都未改，只是响应 `staffList[]` 多了字段。
- 删掉的人在其他团的占用计算里立即消失（已删除的配置行不算占用）。

### 5. 团期人员候选分页 `GET /v3/admin/group-batch/{productBatchId}/staff/candidates/page`

**VO**: `PageResult<StaffCandidateRespVO>`

#### 使用场景

「配导游」「配摄影」选人弹窗的人员列表（带关键词搜索、分页）。本单起每行可展示等级、服务区域、擅长、基础日薪和占用标签，点占用标签看 `occupancies` 明细与 `freeRanges`。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productBatchId | Path | Long | 是 | 产品侧排期 ID | 取 `detail.productBatchId`（既有） |
| role | Query | String | 是 | `GUIDE` / `PHOTOGRAPHER` | 配置位；导游位并收导游与领队（既有） |
| keyword | Query | String | 否 | ≤50 字 | 姓名包含；纯数字另按手机号尾号匹配（既有） |
| page | Query | Integer | 否 | 缺省 1 | 页码（既有） |
| pageSize | Query | Integer | 否 | 缺省 20，最大 100 | 每页条数（既有） |

#### 出参 `Result<PageResult<StaffCandidateRespVO>>`

| 字段 | 类型 | 说明 |
|------|------|------|
| total / page / pageSize | Integer | 分页信息（既有） |
| records | Object[] | 候选项（既有字段 `productBatchId`、`groupBatchId`、`staffId`、`staffName`、`staffPhone`、`staffType`、`staffTypeName`、`avatarUrl`、`assigned`、`assignedRole`、`assignedRoleName`、`reporterRank`、`reporterRankName` 不变） |
| records[].level | String | **新增**。导游等级：`初级` / `中级` / `高级` / `特级`，档案里认不出的写法原样返回；未填为 null |
| records[].serviceAreas | String[] | **新增**。服务区域；未填为 `[]`，恒非 null |
| records[].specialties | String[] | **新增**。擅长；未填为 `[]`，恒非 null |
| records[].baseDailyWage | String | **新增**。服务人员档案的基础日薪，字符串如 `"600.00"`，仅供参考；未填或为 0 时为 null；前端运算前 `Number()` |
| records[].occupancyStatus | String | **新增**。`FREE` / `PARTIAL` / `FULL`，按**本团出发日到结束日**比对；本团期未建（`groupBatchId` 为 null）或团期起止不全时为 null |
| records[].occupiedDays | Integer | **新增**。本团日期段内被占天数（两端都算）；`occupancyStatus` 为 null 时为 0 |
| records[].freeRanges | String[] | **新增**。可派日期段 `yyyy-MM-dd~yyyy-MM-dd`，升序；全程占用或 `occupancyStatus` 为 null 时为 `[]` |
| records[].occupancies | Object[] | **新增**。占用明细，按 `startDate` 升序；空闲或 `occupancyStatus` 为 null 时为 `[]` |
| records[].occupancies[].sourceType | String | `GROUP_BATCH` 其他团期的人员配置 / `ORDER` 普通订单上定制师直派 |
| records[].occupancies[].sourceId | String | `GROUP_BATCH` 为运营团期 ID，`ORDER` 为订单 ID |
| records[].occupancies[].refNo | String | 团期号 / 订单号；源数据为空时为 null |
| records[].occupancies[].title | String | 团期名称（为空时取产品名）/ 订单的产品名；都为空时为 null |
| records[].occupancies[].statusName | String | 来源当前状态中文名，如「招募中」「待支付」 |
| records[].occupancies[].staffRole / staffRoleName | String | 他在那边的角色及中文名（跨角色也计入占用） |
| records[].occupancies[].startDate / endDate | String(yyyy-MM-dd) | 他在那边的服务起止：团期为他在那个团的有效服务日期（自定义日期先夹进那个团当前起止）；订单为出发日到返回日（返回日为空按出发日当天） |
| records[].occupancies[].overlapStartDate / overlapEndDate | String(yyyy-MM-dd) | 与本团日期段重叠的起止，两端都算，恒在本团日期段内 |

#### 请求示例

```http
GET /v3/admin/group-batch/2104455359768993795/staff/candidates/page?role=GUIDE&page=1&pageSize=20
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测节选（班期 11-17 ~ 11-19，共 7 人，只保留三行：本团已选 → 空闲 → 部分占用；金额按当前契约写成字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "productBatchId": "2104455359768993795",
        "groupBatchId": "2104455363380285441",
        "staffId": 1007,
        "staffName": "白云飞",
        "staffPhone": "139****1007",
        "staffType": "LEADER",
        "staffTypeName": "领队",
        "avatarUrl": null,
        "assigned": true,
        "assignedRole": "LEADER",
        "assignedRoleName": "领队",
        "reporterRank": "NONE",
        "reporterRankName": "非报账人",
        "level": null,
        "serviceAreas": ["内蒙古", "新疆"],
        "specialties": ["户外探险", "亲子活动", "草原穿越"],
        "baseDailyWage": "800.00",
        "occupancyStatus": "FREE",
        "occupiedDays": 0,
        "freeRanges": ["2026-11-17~2026-11-19"],
        "occupancies": []
      },
      {
        "productBatchId": "2104455359768993795",
        "groupBatchId": "2104455363380285441",
        "staffId": 1005,
        "staffName": "刘大山",
        "staffPhone": "138****1005",
        "staffType": "LEADER",
        "staffTypeName": "领队",
        "avatarUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/26/45d9abebc569ca7b7ab13cac212ca38a.png",
        "assigned": false,
        "assignedRole": null,
        "assignedRoleName": null,
        "reporterRank": null,
        "reporterRankName": null,
        "level": null,
        "serviceAreas": ["内蒙古", "新疆", "青海", "甘肃", "西藏"],
        "specialties": ["户外探险", "高原旅行", "沙漠旅行", "自驾越野"],
        "baseDailyWage": "1000.00",
        "occupancyStatus": "FREE",
        "occupiedDays": 0,
        "freeRanges": ["2026-11-17~2026-11-19"],
        "occupancies": []
      },
      {
        "productBatchId": "2104455359768993795",
        "groupBatchId": "2104455363380285441",
        "staffId": 1002,
        "staffName": "李雪梅",
        "staffPhone": "138****1002",
        "staffType": "GUIDE",
        "staffTypeName": "导游",
        "avatarUrl": null,
        "assigned": false,
        "assignedRole": null,
        "assignedRoleName": null,
        "reporterRank": null,
        "reporterRankName": null,
        "level": "中级",
        "serviceAreas": ["云南", "四川", "贵州"],
        "specialties": ["民俗风情", "美食体验", "自然风光"],
        "baseDailyWage": "600.00",
        "occupancyStatus": "PARTIAL",
        "occupiedDays": 2,
        "freeRanges": ["2026-11-19~2026-11-19"],
        "occupancies": [
          {
            "sourceType": "GROUP_BATCH",
            "sourceId": "2104455358355509249",
            "refNo": "Q202611162104455356057034753",
            "title": "11月16日海拉尔-额尔古纳3日团",
            "statusName": "招募中",
            "staffRole": "GUIDE",
            "staffRoleName": "导游",
            "startDate": "2026-11-16",
            "endDate": "2026-11-18",
            "overlapStartDate": "2026-11-17",
            "overlapEndDate": "2026-11-18"
          }
        ]
      }
    ],
    "total": 7,
    "page": 1,
    "pageSize": 20
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

本团期还没建（班期有、团期无）时，`groupBatchId` 为 null，占用四字段为空值（测试服班期 11-26 实测节选）：

```json
{
  "productBatchId": "2104455372507095042",
  "groupBatchId": null,
  "staffId": 1002,
  "staffName": "李雪梅",
  "level": "中级",
  "baseDailyWage": "600.00",
  "occupancyStatus": null,
  "occupiedDays": 0,
  "freeRanges": [],
  "occupancies": []
}
```

- 页码越界：`records` 为 `[]`，`total` 为真实总数（既有）。
- 资源服务不可用：返回 582103（见下）。

#### 错误响应

```json
{
  "code": 582103,
  "message": "员工信息查询失败，请稍后重试",
  "data": null,
  "success": false
}
```

| code | 触发条件 |
|---|---|
| `582103` | 资源服务查询候选失败（既有码，本单起候选分页经资源服务新的排序分页查询取数） |
| `582113` | `role` 不是 `GUIDE` / `PHOTOGRAPHER`（既有） |
| `589507` | 无团期查看权限（既有） |
| `400` | `keyword` 超 50 字（既有） |

#### 业务边界

- **全局排序**：本团本位已选（即 `assigned=true`）→ 空闲 → 部分占用 → 全程占用；同组内按等级从高到低（特级 → 高级 → 中级 → 初级 → 未填）→ 人员 `sortOrder` 升序 → `staffId` 升序。先按同一筛选条件（类型、关键词）取全体候选排好再切页，逐页翻完不重不漏，与第 6 个接口的顺序一致。
- 本团期未建时没有占用分组，只有「本团本位已选」排最前，其余人按等级 → `sortOrder` → `staffId` 排（改前只按 `sortOrder`、`staffId`）。
- 本团其他配置位上的人（例如在导游位看摄影师）不算占用（本团自己不算），`assigned=false`，照常用 `assignedRole` 提示「已在其他位」。
- 占用只提示不拦截；本单不提供「只看空闲」筛选参数（D9）。
- 保存仍以 `GET .../staff` 为已选名单来源，不能只凭当前页勾选拼保存请求（既有）。

### 6. 团期人员候选列表 `GET /v3/admin/group-batch/{productBatchId}/staff/candidates`

**VO**: `List<StaffCandidateRespVO>`

#### 使用场景

旧的全量候选接口（不分页）。条目结构、占用口径、排序规则与候选分页完全一致。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productBatchId | Path | Long | 是 | 产品侧排期 ID | 取 `detail.productBatchId`（既有） |
| role | Query | String | 是 | `GUIDE` / `PHOTOGRAPHER` | 配置位；导游位并收导游与领队（既有） |

#### 出参 `Result<List<StaffCandidateRespVO>>`

| 字段 | 类型 | 说明 |
|------|------|------|
| 既有字段 | - | `productBatchId`、`groupBatchId`、`staffId`、`staffName`、`staffPhone`、`staffType`、`staffTypeName`、`avatarUrl`、`assigned`、`assignedRole`、`assignedRoleName`、`reporterRank`、`reporterRankName` 不变 |
| level | String | **新增**。导游等级：`初级` / `中级` / `高级` / `特级`，认不出的写法原样返回；未填为 null |
| serviceAreas | String[] | **新增**。服务区域；未填为 `[]` |
| specialties | String[] | **新增**。擅长；未填为 `[]` |
| baseDailyWage | String | **新增**。档案基础日薪，字符串，仅供参考；未填或为 0 时为 null |
| occupancyStatus | String | **新增**。`FREE` / `PARTIAL` / `FULL`，按本团出发日到结束日比对；本团期未建或团期起止不全时为 null |
| occupiedDays | Integer | **新增**。被占天数；`occupancyStatus` 为 null 时为 0 |
| freeRanges | String[] | **新增**。可派日期段 `yyyy-MM-dd~yyyy-MM-dd`；全程占用或 null 状态时为 `[]` |
| occupancies | Object[] | **新增**。占用明细，按 `startDate` 升序 |
| occupancies[].sourceType / sourceId | String | `GROUP_BATCH` + 运营团期 ID，或 `ORDER` + 订单 ID |
| occupancies[].refNo / title / statusName | String | 团期号或订单号 / 团期名称或产品名 / 来源状态中文名 |
| occupancies[].staffRole / staffRoleName | String | 他在那边的角色及中文名 |
| occupancies[].startDate / endDate | String(yyyy-MM-dd) | 他在那边的服务起止 |
| occupancies[].overlapStartDate / overlapEndDate | String(yyyy-MM-dd) | 与本团日期段重叠的起止 |

#### 请求示例

```http
GET /v3/admin/group-batch/2104455359768993795/staff/candidates?role=GUIDE
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测节选（班期 11-17 ~ 11-19；陈志远只有 11-18 被占，可派日期被切成两段；李雪梅被两个招募中的团占满整段）：

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "productBatchId": "2104455359768993795",
      "groupBatchId": "2104455363380285441",
      "staffId": 1009,
      "staffName": "陈志远",
      "staffPhone": "139****1009",
      "staffType": "LEADER",
      "staffTypeName": "领队",
      "avatarUrl": null,
      "assigned": false,
      "assignedRole": null,
      "assignedRoleName": null,
      "reporterRank": null,
      "reporterRankName": null,
      "level": null,
      "serviceAreas": ["内蒙古", "黑龙江", "吉林"],
      "specialties": ["户外探险", "高原旅行", "冬季活动"],
      "baseDailyWage": null,
      "occupancyStatus": "PARTIAL",
      "occupiedDays": 1,
      "freeRanges": ["2026-11-17~2026-11-17", "2026-11-19~2026-11-19"],
      "occupancies": [
        {
          "sourceType": "GROUP_BATCH",
          "sourceId": "2104455358355509249",
          "refNo": "Q202611162104455356057034753",
          "title": "11月16日海拉尔-额尔古纳3日团",
          "statusName": "招募中",
          "staffRole": "LEADER",
          "staffRoleName": "领队",
          "startDate": "2026-11-18",
          "endDate": "2026-11-18",
          "overlapStartDate": "2026-11-18",
          "overlapEndDate": "2026-11-18"
        }
      ]
    },
    {
      "productBatchId": "2104455359768993795",
      "groupBatchId": "2104455363380285441",
      "staffId": 1002,
      "staffName": "李雪梅",
      "staffPhone": "138****1002",
      "staffType": "GUIDE",
      "staffTypeName": "导游",
      "avatarUrl": null,
      "assigned": false,
      "assignedRole": null,
      "assignedRoleName": null,
      "reporterRank": null,
      "reporterRankName": null,
      "level": "中级",
      "serviceAreas": ["云南", "四川", "贵州"],
      "specialties": ["民俗风情", "美食体验", "自然风光"],
      "baseDailyWage": "600.00",
      "occupancyStatus": "FULL",
      "occupiedDays": 3,
      "freeRanges": [],
      "occupancies": [
        {
          "sourceType": "GROUP_BATCH",
          "sourceId": "2104455358355509249",
          "refNo": "Q202611162104455356057034753",
          "title": "11月16日海拉尔-额尔古纳3日团",
          "statusName": "招募中",
          "staffRole": "GUIDE",
          "staffRoleName": "导游",
          "startDate": "2026-11-16",
          "endDate": "2026-11-18",
          "overlapStartDate": "2026-11-17",
          "overlapEndDate": "2026-11-18"
        },
        {
          "sourceType": "GROUP_BATCH",
          "sourceId": "2104455369311031298",
          "refNo": "Q202611182104455365389361153",
          "title": "11月18日海拉尔-额尔古纳3日团",
          "statusName": "招募中",
          "staffRole": "GUIDE",
          "staffRoleName": "导游",
          "startDate": "2026-11-18",
          "endDate": "2026-11-20",
          "overlapStartDate": "2026-11-18",
          "overlapEndDate": "2026-11-19"
        }
      ]
    }
  ],
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

- 资源库没有可用人员：`data: []`（既有）。
- 本团期未建：`groupBatchId` 为 null，每人 `occupancyStatus=null`、`occupiedDays=0`、`freeRanges=[]`、`occupancies=[]`。

#### 错误响应

```json
{
  "code": 582113,
  "message": "人员配置位不合法，请检查配置位标识",
  "data": null,
  "success": false
}
```

| code | 触发条件 |
|---|---|
| `582113` | `role` 不是 `GUIDE` / `PHOTOGRAPHER`（既有） |
| `582103` | 资源服务查询候选失败（既有） |
| `589507` | 无团期查看权限（既有） |

#### 业务边界

- 排序与候选分页同一规则：本团本位已选 → 空闲 → 部分占用 → 全程占用 → 等级从高到低 → `sortOrder` 升序 → `staffId` 升序。
- 同一来源（同一个团期或同一张订单）即使有多行也只出一条明细；`occupiedDays` 按实际被占的日子算，重叠部分只算一次。
- 占用只提示不拦截。

### 7. 配导游芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/guide`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期详情「配导游」页签、看板点导游芯片弹出的明细。本单起只看团期名册 `staffList`，不再有逐户人员表。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| groupBatchId | Path | Long | 是 | 运营团期 ID | 路由上的团期 ID（既有） |

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId / groupBatchId | String | 团期 ID（`batchId` 已废弃，同值；既有） |
| chipLabel | String | 芯片中文名（既有） |
| aggregateStatus / aggregateStatusName | String | 整团聚合态及中文名（既有，口径不变，仍按户计） |
| totalCount / doneCount | Integer | 计入统计的户数 / 已完成户数（既有，口径不变） |
| staffList | Object[] | 本团导游位（导游 + 领队）已配置人员（既有，内容不变）；元素字段 `staffId`、`staffRole`、`staffRoleName`、`staffName`、`staffPhone`、`reporterRank`、`reporterRankName`、`source`、`sourceName` |
| items | Object[] | **取值变化**：恒为 `[]`，不再逐户返回（改前每户一行并带 `items[].staffs`） |

#### 请求示例

```http
GET /v3/admin/order/group-batch/2104455358355509249/chips/guide
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "batchId": "2104455358355509249",
    "groupBatchId": "2104455358355509249",
    "chipLabel": "配导游",
    "aggregateStatus": "TODO",
    "aggregateStatusName": "待开始",
    "totalCount": 0,
    "doneCount": 0,
    "staffList": [
      {
        "staffId": "1005",
        "staffRole": "LEADER",
        "staffRoleName": "领队",
        "staffName": "刘大山",
        "staffPhone": "138****1005",
        "reporterRank": "PRIMARY",
        "reporterRankName": "主报账人",
        "source": null,
        "sourceName": null
      },
      {
        "staffId": "1002",
        "staffRole": "GUIDE",
        "staffRoleName": "导游",
        "staffName": "李雪梅",
        "staffPhone": "138****1002",
        "reporterRank": "NONE",
        "reporterRankName": "非报账人",
        "source": null,
        "sourceName": null
      }
    ],
    "items": []
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

未配置导游位人员时 `staffList: []`、`items: []`（改前 `items` 会列出每户，本单起恒为 `[]`）。

#### 错误响应

错误码未改动。

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

#### 业务边界

- 判权未改（`group-batch:view`，无权限 589507）。
- `staffList` 不带服务日期、日薪、占用；需要这些时调 `GET /v3/admin/group-batch/{productBatchId}/staff`。
- 芯片聚合态（`aggregateStatus`、`totalCount`、`doneCount`）仍按户计算，本单不改；改按团期名册计算的口径见 #8469。
- 配房、配车、合同、保险四个芯片完全不变。

### 8. 配摄影芯片明细 `GET /v3/admin/order/group-batch/{groupBatchId}/chips/photo`

**VO**: `GroupBatchChipDetailVO`

#### 使用场景

团期详情「配摄影」页签、看板点摄影芯片弹出的明细。本单起只看团期名册 `staffList`，不再有逐户人员表。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| groupBatchId | Path | Long | 是 | 运营团期 ID | 路由上的团期 ID（既有） |

#### 出参 `Result<GroupBatchChipDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| batchId / groupBatchId | String | 团期 ID（`batchId` 已废弃，同值；既有） |
| chipLabel | String | 芯片中文名（既有） |
| aggregateStatus / aggregateStatusName | String | 整团聚合态及中文名（既有，口径不变，仍按户计） |
| totalCount / doneCount | Integer | 计入统计的户数 / 已完成户数（既有，口径不变） |
| staffList | Object[] | 本团摄影位已配置人员（既有，内容不变）；元素字段 `staffId`、`staffRole`、`staffRoleName`、`staffName`、`staffPhone`、`reporterRank`、`reporterRankName`、`source`、`sourceName` |
| items | Object[] | **取值变化**：恒为 `[]`，不再逐户返回（改前每户一行并带 `items[].staffs`） |

#### 请求示例

```http
GET /v3/admin/order/group-batch/2104455358355509249/chips/photo
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "batchId": "2104455358355509249",
    "groupBatchId": "2104455358355509249",
    "chipLabel": "配摄影",
    "aggregateStatus": "TODO",
    "aggregateStatusName": "待开始",
    "totalCount": 0,
    "doneCount": 0,
    "staffList": [
      {
        "staffId": "1003",
        "staffRole": "PHOTOGRAPHER",
        "staffRoleName": "摄影",
        "staffName": "王强",
        "staffPhone": "138****1003",
        "reporterRank": "NONE",
        "reporterRankName": "非报账人",
        "source": null,
        "sourceName": null
      }
    ],
    "items": []
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

未配置摄影位人员时 `staffList: []`、`items: []`（改前 `items` 会列出每户，本单起恒为 `[]`）。

#### 错误响应

错误码未改动。

```json
{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "data": null,
  "success": false
}
```

#### 业务边界

- 判权未改（`group-batch:view`）；团期不存在 589500（既有）。
- `staffList` 不带服务日期、日薪、占用；需要这些时调 `GET /v3/admin/group-batch/{productBatchId}/staff`。
- 芯片聚合态仍按户计算，本单不改；改按团期名册计算的口径见 #8469。

### 9. 新建服务人员 `POST /admin/staff`

**VO**: `StaffCreateRequest` → `StaffVO`

#### 使用场景

服务人员管理「新建」弹窗保存。本单起「基础日薪」输入框的值会保存（改前填了不保存）。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| name | Body | String | 是 | ≤100 字 | 姓名（既有） |
| staffType | Body | String | 是 | 人员类型字典 | 人员类型（既有） |
| basePrice | Body | Number | 否 | ≥0；最多 8 位整数、2 位小数 | **新增**。基础日薪（元/天）；不传按 0 保存（= 没填） |

其余字段与改前一致。

#### 出参 `Result<StaffVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| basePrice | String | **新增**。基础日薪，按库值原样返回的字符串，如 `"650.00"`；没填为 `"0.00"`（不是 null）。回填数字输入框用 `Number(basePrice)` |
| 其余字段 | - | 与改前一致 |

#### 请求示例

```json
{
  "name": "孟和巴雅尔",
  "staffType": "LEADER",
  "gender": 1,
  "serviceAreas": ["内蒙古"],
  "specialties": ["草原穿越"],
  "basePrice": 650,
  "description": "熟悉呼伦贝尔草原线路，常带亲子团"
}
```

#### 响应示例

2026-09-28 测试服实测节选（验收后已软删；金额按当前契约写成字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "staffId": "2104454928988823553",
    "name": "孟和巴雅尔",
    "staffType": "LEADER",
    "specialties": ["草原穿越"],
    "serviceAreas": ["内蒙古"],
    "basePrice": "650.00",
    "sortOrder": 0,
    "status": 0
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

写接口，无空数据形态。不传 `basePrice` 时按 0 保存，详情与列表返回 `"0.00"`。

#### 错误响应

与编辑接口同一组校验（测试服在编辑接口实测）：

```json
{
  "code": 400,
  "message": "基础日薪不能为负数",
  "data": null,
  "traceId": null,
  "success": false
}
```

| code | 触发条件 |
|---|---|
| `400` | `basePrice` 为负数（「基础日薪不能为负数」）；超过 8 位整数或 2 位小数（「基础日薪最多8位整数、2位小数」） |

#### 业务边界

- 判权与审批上架流程未改。
- 校验失败不写入。
- 团期选人时取的就是这里保存的基础日薪（0 视为没填，团期侧显示 null）。

### 10. 编辑服务人员 `PUT /admin/staff/{staffId}`

**VO**: `StaffUpdateRequest` → `StaffVO`

#### 使用场景

服务人员管理「编辑」弹窗保存。弹窗打开时用详情接口回显 `Number(basePrice)`，保存时把数值传回。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| staffId | Path | Long | 是 | - | 人员 ID（既有） |
| basePrice | Body | Number | 否 | ≥0；最多 8 位整数、2 位小数 | **新增**。基础日薪（元/天）；**不传不改**原值；传 0 = 清成没填 |

其余字段与改前一致（均为不传不改）。

#### 出参 `Result<StaffVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| basePrice | String | **新增**。保存后的基础日薪字符串，如 `"800.00"`；没填为 `"0.00"` |
| 其余字段 | - | 与改前一致 |

#### 请求示例

```json
{ "basePrice": 800 }
```

#### 响应示例

2026-09-28 测试服实测节选（金额按当前契约写成字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "staffId": "1007",
    "name": "白云飞",
    "phone": "139****1007",
    "staffType": "LEADER",
    "basePrice": "800.00",
    "sortOrder": 90,
    "status": 1
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

写接口，无空数据形态。请求不带 `basePrice`（如 `{ "sortOrder": 90 }`）时原值不变，测试服实测保持 800。

#### 错误响应

测试服实测：

```json
{
  "code": 400,
  "message": "基础日薪最多8位整数、2位小数",
  "data": null,
  "traceId": null,
  "success": false
}
```

| code | 触发条件 |
|---|---|
| `400` | `basePrice=-1` →「基础日薪不能为负数」；`basePrice=12.345` →「基础日薪最多8位整数、2位小数」；均不写入 |

#### 业务边界

- 不传不改：只提交部分字段的调用方不会把日薪清掉。
- 改了档案日薪后，已经选进团期的人日薪快照**不刷新**；之后新选、或更换进来的人才取新值（D1）。
- 判权未改。

### 11. 服务人员详情 `GET /admin/staff/{staffId}`

**VO**: `StaffVO`

#### 使用场景

服务人员详情页、编辑弹窗回显。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| staffId | Path | Long | 是 | - | 人员 ID（既有） |

#### 出参 `Result<StaffVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| basePrice | String | **新增**。基础日薪字符串，按库值原样返回，如 `"600.00"`；没填为 `"0.00"`（不是 null） |
| 其余字段 | - | 与改前一致 |

#### 请求示例

```http
GET /admin/staff/1007
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

测试服实测节选（1007 验收后已恢复为没填；金额为字符串）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "staffId": "1007",
    "name": "白云飞",
    "phone": "139****1007",
    "staffType": "LEADER",
    "guideLevel": null,
    "serviceAreas": ["内蒙古", "新疆"],
    "specialties": ["户外探险", "亲子活动", "草原穿越"],
    "basePrice": "0.00",
    "sortOrder": 90,
    "status": 1
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

没填日薪的人 `basePrice` 为 `"0.00"`，前端按「未填」展示即可。

#### 错误响应

错误码未改动（人员不存在时 HTTP 200 + 业务码 404）：

```json
{
  "code": 404,
  "message": "服务人员不存在",
  "data": null,
  "success": false
}
```

#### 业务边界

- 详情返回库里的原值（0 就是 `"0.00"`）；团期侧把 0 视为没填、返回 null，两处口径不同是有意的。
- 判权未改。

### 12. 服务人员列表 `GET /admin/staff/list`

**VO**: `PageResult<StaffAdminListVO>`

#### 使用场景

服务人员管理列表页。本单起每条记录带 `basePrice`，列表可恢复「基础日薪」列。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| keyword | Query | String | 否 | - | 姓名 / 描述模糊匹配（既有） |
| staffType | Query | String | 否 | - | 人员类型筛选（既有） |
| status | Query | Integer | 否 | 0 / 1 | 下架 / 上架（既有） |
| page | Query | Integer | 否 | ≥1，缺省 1 | 页码（既有） |
| pageSize | Query | Integer | 否 | 1~100，缺省 20 | 每页条数（既有） |

#### 出参 `Result<PageResult<StaffAdminListVO>>`

| 字段 | 类型 | 说明 |
|------|------|------|
| records[].basePrice | String | **新增**。基础日薪字符串，按库值原样返回，如 `"1000.00"`；没填为 `"0.00"` |
| records[] 其余字段 | - | 与改前一致 |

#### 请求示例

```http
GET /admin/staff/list?staffType=LEADER&page=1&pageSize=20
Authorization: Bearer <admin token>
```

无请求体。

#### 响应示例

2026-09-28 测试服实测节选：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "staffId": "1005",
        "name": "刘大山",
        "staffType": "LEADER",
        "phone": "138****1005",
        "basePrice": "1000.00",
        "sortOrder": 95,
        "status": 1,
        "supplierFullName": "陈巴尔虎旗天下草原旅游服务有限"
      },
      {
        "staffId": "1007",
        "name": "白云飞",
        "staffType": "LEADER",
        "phone": "139****1007",
        "basePrice": "0.00",
        "sortOrder": 90,
        "status": 1
      }
    ]
  },
  "traceId": null,
  "success": true
}
```

#### 空数据 / 降级响应

无匹配记录时 `records: []`（既有）。没填日薪的人 `basePrice` 为 `"0.00"`。

#### 错误响应

参数校验错误码未改动：

```json
{
  "code": 400,
  "message": "页码不能小于1",
  "data": null,
  "success": false
}
```

#### 业务边界

- 列表排序、筛选、判权都未改，只多了 `basePrice`。
- `basePrice` 是字符串，排序或求和前先 `Number()`。

---

## 四、契约约束与正确调用方式

### ✅ 正确 / ❌ 错误 payload 对照（保存团期人员配置）

| 场景 | payload（`staffList[]` 单项） | 结果 |
|------|---------|------|
| ✅ 前端现有写法，保留的人只传三项 | `{ "staffId": 1005, "staffRole": "LEADER", "sortOrder": 1 }` | 沿用原报账人等级、备注、服务日期、日薪 |
| ✅ 自定义服务日期 | `{ "staffId": 1008, "staffRole": "LEADER", "sortOrder": 2, "serviceStartDate": "2026-11-18", "serviceEndDate": "2026-11-18" }` | 落为自定义，`serviceDateCustom=true` |
| ✅ 改回跟随团期 | 传团期起止本身，如团期 11-17 ~ 11-19 时 `"serviceStartDate": "2026-11-17", "serviceEndDate": "2026-11-19"` | 按跟随团期处理，`serviceDateCustom=false` |
| ✅ 清空备注 | `{ ..., "remark": "" }` | 备注清空 |
| ⚠️ 想清空备注却传 null 或不传 | `{ ..., "remark": null }` | 保留下来的人**沿用原备注**（不会清空） |
| ⚠️ 想改回跟随团期却不传日期 | `{ "staffId": 1008, "staffRole": "LEADER" }` | 保留下来的人**沿用原自定义日期** |
| ❌ 开始晚于结束 | `"serviceStartDate": "2026-11-19", "serviceEndDate": "2026-11-18"` | 582119，整批不写入 |
| ❌ 越出团期 | 团期 11-17 ~ 11-19 时 `"serviceStartDate": "2026-11-16"` | 582119，整批不写入 |
| ➖ 带日薪 | `{ ..., "baseDailyWage": 9999 }` | 不报错，但被忽略；日薪取档案值 |

### 金额字段

- `baseDailyWage`（团期名册、候选）与 `basePrice`（服务人员管理详情、列表、新建与编辑响应）都是 JSON 字符串，如 `"600.00"`。展示可直接用；运算、比较、回填数字输入框前 `Number()`。
- 团期侧 `baseDailyWage` 为 null 表示「档案没填日薪」；服务人员管理侧 `basePrice` 为 `"0.00"` 表示同一件事。
- 服务人员新建 / 编辑的请求体里 `basePrice` 传数字即可（如 `800`）。

### 前端交接清单

1. **选人弹窗（候选分页 / 候选列表）**：每行展示等级 `level`、服务区域 `serviceAreas`、擅长 `specialties`、基础日薪 `baseDailyWage`（标「参考」），以及占用标签（`FREE` 空闲 / `PARTIAL` 部分占用 / `FULL` 全程占用）和被占天数 `occupiedDays`；`occupancyStatus` 为 null（团期未建）时不显示占用标签。列表顺序直接用接口顺序，不要在前端重排。
2. **占用明细弹层**：点占用标签弹出 `occupancies[]`（来源类型 `sourceType`、团期号或订单号 `refNo`、名称 `title`、状态 `statusName`、角色 `staffRoleName`、他那边的服务起止 `startDate`~`endDate`、与本团重叠的起止 `overlapStartDate`~`overlapEndDate`）和可派日期段 `freeRanges`。
3. **保存弹窗**：每个人可编辑服务开始 / 结束日期（不填 = 跟随团期），基础日薪只读展示。回显用名册的 `serviceStartDate` / `serviceEndDate` / `serviceDateCustom`；把自定义日期改回跟随团期时提交团期起止本身（不传会沿用原值）；收到 582119 直接展示接口文案（带人名）。有占用不需要二次确认（D5）。
4. **已配置人员名册**：可加服务日期、基础日薪、占用标签三列（字段见接口 2）。
5. **服务人员管理**：编辑框回显用 `Number(row.basePrice)`（出参是字符串）；列表恢复「基础日薪」列，`"0.00"` 按未填展示。
6. **团期详情导游 / 摄影页签、看板导 / 摄芯片弹层**：去掉逐户人员表（`items` 恒为 `[]`）及其「共 N 户计入」汇总行，只展示团期名册 `staffList`。
7. **本单不做**：「只看空闲」筛选（D9）；导 / 摄芯片状态颜色口径另见 #8469，本单不改。

### 服务间内部接口（前端不可调）

资源服务的 `/internal/staff/...` 系列接口也随本单加了字段，并新增 `POST /internal/staff/page-available`（候选分页的全局排序由它完成）。这些接口不经网关，前端无需关注；候选分页在资源服务不可用时返回 582103。

---

## 五、数据库行为

| 前端动作 | 可观察到的存储结果 |
|----------|---------------------|
| 保存时服务日期不传 / 与团期起止相同 | 按「跟随团期」存，名册返回团期起止，`serviceDateCustom=false`，团期改期后跟着变 |
| 保存时服务日期自定义 | 原样保存，`serviceDateCustom=true`，团期改期后不变 |
| 保存 / 更换选人 | 基础日薪快照在选人那一刻从服务人员档案带出并保存；档案之后再改，快照不变 |
| 保存返回 582119 | 整批不写入，名册前后一致（测试服前后比对） |
| 服务人员新建 / 编辑带 `basePrice` | 档案基础日薪保存；编辑不传不改；新建不传为 0 |

- 存量团期人员配置：服务日期全部视为「跟随团期」，基础日薪快照为 null；下次保存这些人时会补取一次档案当前日薪。
- 查询接口只读。

---

## 六、边界行为

- **占用来源（D3 / D7）**：
  - 计入：其他团期里这个人的有效配置（含招募中团期；在那个团当任何角色都算）；普通订单（不属于任何团期）上定制师直接派的人（未取消的订单，任何订单状态都算）。
  - 不计：本团自己；已取消的团期（含流团）；出发日或结束日为空的团期；已删除的配置；团期同步到子订单的人员副本；车务派车的司机；已取消的订单；没有出发日的订单。
- **日期段**：候选接口用本团出发日到结束日；名册（及保存、更换、删除响应）用这个人在本团的有效服务日期，先夹进本团当前起止。其他团的自定义服务日期同样先夹进那个团当前起止，完全越界时按那个团整段算。订单用出发日到返回日，返回日为空按出发日一天。
- **两端都算（D4）**：首尾相接那一天算占用。测试服实测：本团 11-18 ~ 11-20，另一团 11-16 ~ 11-18，重叠 1 天（11-18）。
- **三档（D8）**：被占 0 天 → `FREE`；被占满整段 → `FULL`；其余 → `PARTIAL`。守恒：`FREE` ⇔ `occupiedDays=0` ⇔ `occupancies` 为空；`FULL` ⇔ `freeRanges` 为空；`occupiedDays` + 可派天数 = 日期段天数。
- **多段**：多条占用重叠部分只算一次；被占日子在中间时可派日期切成两段。
- **只提示不拦截（D5）**：有占用照样能保存。
- **未建团期**：候选能查、团期还没有是正常态，占用四字段为 `null` / `0` / `[]` / `[]`。
- **未登录**：网关拦截返回 401（既有）。
- **向后兼容**：团期侧全部为新增字段，旧前端不读也不报错；例外见六.6 的 `items` 与 `remark` 两处行为变化。

---

## 六.5、枚举 / 数据字典

### occupancyStatus（常量定义于 `com.hulalv.order.assignment.helper.StaffOccupancyCalculator`）

**所属字段**: `BatchStaffItemVO.occupancyStatus`、`StaffCandidateRespVO.occupancyStatus` | **类型**: `String`

| 值 | 中文 | 说明 |
|----|------|------|
| `FREE` | 空闲 | 日期段内被占 0 天 |
| `PARTIAL` | 部分占用 | 被占天数大于 0 且小于日期段天数 |
| `FULL` | 全程占用 | 日期段每一天都被占 |
| `null` | - | 本团期未建或团期起止不全，算不出 |

### occupancies[].sourceType（常量定义于 `com.hulalv.order.assignment.helper.StaffOccupancyCalculator`）

**所属字段**: `StaffOccupancyItemVO.sourceType` | **类型**: `String`

| 值 | 中文 | 说明 |
|----|------|------|
| `GROUP_BATCH` | 团期 | 其他团期的人员配置；`sourceId` 为运营团期 ID，`refNo` 为团期号 |
| `ORDER` | 订单 | 普通订单上定制师直派；`sourceId` 为订单 ID，`refNo` 为订单号 |

### level（`com.hulalv.resource.staff.constant.StaffGuideLevel`）

**所属字段**: `StaffCandidateRespVO.level` | **类型**: `String`

| 值 | 中文 | 说明 |
|----|------|------|
| `特级` | 特级 | 排序最高 |
| `高级` | 高级 | - |
| `中级` | 中级 | - |
| `初级` | 初级 | 已知等级中排最后 |
| 其他原样值 / null | - | 档案写法认不出时原样返回；未填为 null；都排在已知等级之后 |

### occupancies[].statusName

**所属字段**: `StaffOccupancyItemVO.statusName` | **类型**: `String`（中文名，不是编码）

| 值 | 中文 | 说明 |
|----|------|------|
| 团期来源 | 招募中 / 资源准备中 / 物料准备中 / 待出发 / 出行中 / 出行完毕 / 核单中 / 已结算 | 团期当前状态（已取消的团期不计入，不会出现） |
| 订单来源 | 待支付 / 定制中 / 待出行 / 出行中 / 已完成 | 订单当前状态（已取消的订单不计入，不会出现） |

---

## 六.6、修改前后对比

### 字段级对比

| 字段 | 改前 | 改后 |
|------|------|------|
| 名册 / 保存 / 更换 / 删除响应的人员项 | 无服务日期、日薪、占用 | 新增 `serviceStartDate`、`serviceEndDate`、`serviceDateCustom`、`baseDailyWage`、`occupancyStatus`、`occupiedDays`、`freeRanges`、`occupancies` |
| 保存请求 `staffList[]` | 无日期字段 | 新增可选 `serviceStartDate`、`serviceEndDate` |
| 候选项 | 只有姓名、手机、类型等 | 新增 `level`、`serviceAreas`、`specialties`、`baseDailyWage` 与四个占用字段 |
| 导 / 摄芯片 `items` | 每户一行，带 `items[].staffs` | 恒为 `[]` |
| 服务人员 `basePrice` | 请求传了不保存，响应不返回 | 可保存；详情、列表、新建与编辑响应返回字符串 |

### 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 保存导游位（前端只传三项） | 主报账人被打回非报账人、备注被清空 | 沿用原等级、备注、服务日期、日薪 |
| 保存时 `remark` 不传 | 清空备注 | 保留下来的人沿用原备注；要清空传 `""` |
| 候选排序 | 资源库原顺序（`sortOrder`、`staffId`） | 本团本位已选 → 空闲 → 部分占用 → 全程占用 → 等级 → `sortOrder` → `staffId` |
| 服务日期不合法 | 无此校验 | 582119，整批不写入 |
| 更换人员 | 新人不带服务日期、日薪 | 新人沿用原人服务日期，日薪取新人档案 |
| 导 / 摄页签逐户表 | 每户显示分到的人 | 不再提供，只看团期名册 |

---

## 六.7、影响评估

- **是否破坏向后兼容**: 部分。团期侧与服务人员管理都是新增字段；有两处行为变化：①导 / 摄芯片 `items` 恒为 `[]`，旧页面的逐户人员表会变空；②保存时 `remark` 不传不再清空备注。候选顺序也变了（接口顺序即展示顺序）。
- **前端是否必须同步上线**: 否。新字段不读不会报错；逐户表变空只影响展示，按交接清单第 6 项去掉即可。
- **前端 workaround 清理点**: 如果前端为规避「保存后主报账人丢失」在保存后补调过设置报账人接口，可以删掉；导 / 摄页签里按 `items[].staffs` 渲染的「人员」列与「共 N 户计入」汇总行可以删掉。

---

## 七、不影响范围

- **仅影响**: 团期人员配置的保存 / 名册 / 更换 / 删除 / 两个候选接口，导 / 摄两个芯片明细，服务人员管理新建 / 编辑 / 详情 / 列表。
- **零影响**:
  - 设置报账人等级 `PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank`
  - 配房、配车、合同、保险四个芯片明细与看板聚合
  - 订单侧人员接口（`/v3/admin/order/{orderId}/staff`）与团期同步到子订单的人员副本
  - 出团通知书里的人员默认值
  - 核团费用（本单不用「日薪 × 服务天数」预填）
  - 服务人员价格日历

---

## 八、测试环境已验证

- **环境**：TEST，`hl-resource-service` 与 `hl-order-service-v3` 均为 dev-v3 `623c932bd`（含 `bf65803b7` 与 `623c932bd` 两次合入；resource 14:28、order-v3 14:31 双实例滚动完成，先 resource 后 order-v3）。
- **方式**：经网关 `https://api.test.1814.love`，真实 admin token；每批取证前做构建身份探针（候选响应含 `occupancyStatus` 等新键），5 次全部命中。手机号均为接口脱敏值。
- **造数**：五个班期（A 11-16、B 11-17、C 11-18、D 11-26 未建团期、E 10-26）与两张普通订单；验收后配置清空、团期流团、订单取消，新建人员已软删，1007 基础日薪已恢复为 0。

| AC | 检验点 | 结果 | 证据 |
|----|--------|------|------|
| 1 | `basePrice` 编辑 800 后详情 / 列表都为 800；再次编辑不带 `basePrice` 仍 800；-1、12.345 返回 400 且库值不变；新建带 650 → 650 | ✅ | 会话证据 accept/AC-1.json |
| 3 | 候选带等级、服务区域、擅长、日薪；档案为 0 返回 null，1005 为 1000 | ✅ | accept/AC-3.json |
| 6 | 新选 1007 日薪 800、1008 为 null；请求夹 `baseDailyWage=9999` 不生效；档案改回 0 后再保存，已有 800 快照不刷新 | ✅ | accept/AC-6.json |
| 7 | 1005 设为主报账人、备注「负责草原段带队」，用前端现有请求体（只含 `staffId`/`staffRole`/`sortOrder`）重存导游位：仍为主报账人，备注、日薪、1009 的自定义日期都保留 | ✅ | accept/AC-7.json |
| 8 | 不传存为跟随团期且名册返回团期起止、`serviceDateCustom=false`；与团期起止相同同样跟随；自定义 → `true`；开始晚于结束 / 早于团期 / 晚于团期 → 582119，文案含「萨仁高娃」，名册前后一致 | ✅ | accept/AC-8.json |
| 9 | E 团 1005 → 1007：沿用 10-27 ~ 10-28，日薪 800，等级与备注随之转移 | ✅ | accept/AC-9.json |
| 10 | 产品侧把 C 改期到 11-19 后，团期变为 11-19 ~ 11-21，1002 名册日期随之变化 | ✅ | accept/AC-10.json |
| 11 | 名册与两个候选接口字段齐全，占用明细 11 个字段齐全；未建团期的班期 D 候选占用为 null / 0 / [] / [] | ✅ | accept/AC-11.json |
| 12 | 重叠 2 天、首尾相接 1 天、招募中算、本团不算、缩短日期后不算、删除后不算、流团后不算、多段合并、中间切两段、普通订单直派算、取消订单后不算、跨角色（订单上当摄影）算、团期副本不重复算 | ✅ | accept/AC-12.json |
| 13 | E 团派已被普通订单占用的 1005，保存成功，名册显示部分占用 | ✅ | accept/AC-13.json |
| 15 | A / B / C / E 四团每页 2 条翻完：本团已选 → 空闲 → 部分 → 全程 → 等级 → `sortOrder`，与全量接口一致，`total` 不变 | ✅ | accept/AC-15.json |
| 16 | A 团导游 / 摄影芯片 `items=[]`、`staffList` 有人；配房、配车芯片照常逐户返回 | ✅ | accept/AC-16.json |
| 18 | #8476 合入后复验：候选 `baseDailyWage` 为 `"600.00"` / `"1000.00"`；人员详情与列表 `basePrice` 为 `"600.00"` / `"0.00"`（字符串） | ✅ | accept/AC-18-wage-string.json |

说明：本文各响应示例取自 AC-6 ~ AC-16 的实测响应（取证时金额字段仍为数字），示例里的金额已按 AC-18 复验过的字符串形态书写，其余字段为原值。「司机行不算」在测试服造不出司机来源数据，由真库单测覆盖。

---

## 九、相关历史 PR

| PR | Issue | 说明 | 是否仍有效 |
|----|-------|------|------------|
| #7831 | #7827 | 团期人员候选分页与模糊搜索 | ✅ 有效（本单改了排序与条目字段） |
| #7856 | #7853 | 导 / 摄芯片带出 `staffList` 与逐户 `items[].staffs` | ⚠️ `staffList` 有效；逐户人员已被本单撤掉 |
| #8357 | #8354 | 名册实时姓名手机、单人删除 / 更换 | ✅ 有效（本单给响应加字段、更换沿用服务日期） |
| **#8475** | **#8468** | 本单主体 | ✅ 最新 |
| **#8476** | **#8468** | 金额字段改字符串输出 | ✅ 最新 |

---

## 十、相关文档

- 工单 #8468: https://git.1814.love/wx/HL/issues/8468
- 导 / 摄芯片状态改按团期名册计算：https://git.1814.love/wx/HL/issues/8469
- 团期人员配置二期改表：https://git.1814.love/wx/HL/issues/8258

---

## 关联 / 联系人

### 链接

- **Issue**: [#8468](https://git.1814.love/wx/HL/issues/8468)
- **PR**: [#8475](https://git.1814.love/wx/HL/pulls/8475)、[#8476](https://git.1814.love/wx/HL/pulls/8476)
- **Merge commit**: [bf65803b7](https://git.1814.love/wx/HL/commit/bf65803b7)、[623c932bd](https://git.1814.love/wx/HL/commit/623c932bd)

### 联系人

- **后端负责人**: @jw