hl-api-changelog/changelogs-v2/2026-08/06_5581_核算餐厅导游摄影资源下拉选项-新增接口-管理后台.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	5581	核算餐厅/导游/摄影资源下拉选项接口	admin	yst	新增接口	deployed	verified	implemented	mmg	hl-admin@479c44ce399995782504887e0f3aa68274a24e19		2026-08-06	hl-resource-service；PR #5583 已合并 dev-v3 并部署测试服，Gateway 实调验证通过（3 接口 + 必填/关键词/鉴权边界全绿）；等待管理后台接入。	2026-08-07	dev-v3

核算餐厅 / 导游 / 摄影资源下拉选项接口（新增 3 个）

• 变更类型：新增接口
• 端类型：管理后台
• 日期：2026-08-06
• 服务：hl-resource-service（资源服务）
• 关联 Issue：#5581 新增核算餐厅导游摄影资源下拉接口

---

1. 接口背景

管理后台核单（settlement）场景在录入餐厅 / 导游 / 摄影的实际费用时，需要下拉选择对应的资源（餐厅资源、导游人员、摄影人员），并直接看到该资源的默认单价用于预填费用。

本次在资源服务新增 3 个统一前缀的资源下拉选项查询接口，供管理后台核单页消费。接口只返回"识别资源 + 展示名 + 价格"所需的最小字段集合，与订单侧的人员分配（staffAssignment）无任何关联。

---

2. 变更清单

#	方法	路径	说明
1	GET	/admin/resource-options/restaurants	分页查询餐厅资源选项
2	GET	/admin/resource-options/guides	分页查询导游资源选项（固定 STAFF_TYPE=GUIDE）
3	GET	/admin/resource-options/photographers	分页查询摄影资源选项（固定 STAFF_TYPE=PHOTOGRAPHER）

三个接口均为新增，无既有接口被修改或删除。

---

3. 接口详情

项	说明
使用场景	管理后台核单录入费用时，下拉选择餐厅 / 导游 / 摄影资源
认证	需要登录态，请求头携带 Authorization: Bearer <token>，未携带返回 401
幂等性	GET 查询接口，天然幂等，可安全重试
限流	无业务级限流，受网关通用限流约束
分页	三个接口均为分页查询，返回统一分页结构 PageResult

---

4. 接口入参

4.1 GET /admin/resource-options/restaurants

全部为 Query 参数：

参数	类型	必填	说明
pageNo	Integer	是	页码，从 1 开始
pageSize	Integer	是	每页条数
keyword	String	否	餐厅名称关键词，模糊匹配；服务端自动 trim，纯空白等价于不传
city	String	否	城市，精确匹配

4.2 GET /admin/resource-options/guides

全部为 Query 参数：

参数	类型	必填	说明
pageNo	Integer	是	页码，从 1 开始
pageSize	Integer	是	每页条数
serviceDate	LocalDate	是	服务日期，格式 yyyy-MM-dd；用于匹配当日人员价格，缺失返回 400
keyword	String	否	人员姓名关键词，模糊匹配；服务端自动 trim，纯空白等价于不传

注：服务端固定按 STAFF_TYPE=GUIDE 过滤，不含助理导游，调用方无需也不支持传 staffType。

4.3 GET /admin/resource-options/photographers

入参与 guides 完全一致（serviceDate 必填），服务端固定按 STAFF_TYPE=PHOTOGRAPHER 过滤。

---

5. 出参字段

统一响应包装：Result<PageResult<T>>，code=200 表示成功。

实测响应顶层字段：{ code, message, data, traceId, success }（注意是 message 不是 msg）；其中分页数据在 data 内，字段为 { records, total, page, pageSize }（注意列表字段是 records 不是 list）。

5.1 餐厅资源选项 RestaurantResourceOptionRespVO

字段	类型	说明
resourceId	String	餐厅资源 ID，雪花 ID 序列化为字符串（防 JS 精度丢失）。仅用于识别资源，不是订单侧人员分配 ID
resourceName	String	餐厅名称
city	String | null	城市。取值规则：cityName 优先、city 回退，两者均空白时为 null
settleType	null	固定 null（餐厅无结算方式概念）
settleTypeName	null	固定 null
pricePerPerson	BigDecimal	餐厅人均价。餐厅唯一的价格来源（不是日期价）
defaultUnitPrice	BigDecimal | null	默认单价，恒等于人均价；未配置人均价时为 null
priceConfigured	Boolean	是否已配置人均价

5.2 人员资源选项 StaffResourceOptionRespVO（guides / photographers 共用）

字段	类型	说明
resourceId	String	staff 表 staff_id，雪花 ID 序列化为字符串（防 JS 精度丢失）。仅用于识别资源，明确不是 staffAssignmentId
resourceName	String	人员姓名
staffType	String	人员类型编码：GUIDE / PHOTOGRAPHER
staffTypeName	String	人员类型名称：导游 / 摄影师
settleType	String | null	结算方式编码：cash / sign / company；空白时为 null；未知编码原样保留返回
settleTypeName	String | null	结算方式名称：现付 / 签单 / 公司付款；编码为空或未知时为 null
serviceDate	LocalDate	服务日期，即入参 serviceDate，是共享人员类型价格的匹配日期
protocolPrice	BigDecimal | null	当日共享协议价
settlementPrice	BigDecimal | null	当日共享结算价
defaultUnitPrice	BigDecimal | null	默认单价：结算价优先、协议价回退，两者均空时为 null
priceConfigured	Boolean	是否至少配置了一种当日价格

注：响应不暴露 calendarStatus 字段。

---

6. 枚举 / 数据字典

6.1 staffType（人员类型，仅本接口出现的两个值）

编码	名称（staffTypeName）
GUIDE	导游
PHOTOGRAPHER	摄影师

6.2 settleType（结算方式）

编码	名称（settleTypeName）
cash	现付
sign	签单
company	公司付款

说明：编码为空时 settleType / settleTypeName 均为 null；出现上表之外的未知编码时，settleType 原样返回、settleTypeName 为 null。

---

7. 错误码

HTTP / code	触发条件	返回 message
400	guides / photographers 未传 serviceDate	服务日期不能为空
401	未携带有效的 Authorization 头（未登录 / token 失效）	缺少有效的 Authorization 头

---

8. 示例

8.1 典型成功

请求（餐厅）：

GET /admin/resource-options/restaurants?pageNo=1&pageSize=10&keyword=七间房&city=海拉尔

响应（实测）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "resourceId": "2023382108491247617",
        "resourceName": "七间房全羊馆",
        "city": "海拉尔",
        "settleType": null,
        "settleTypeName": null,
        "pricePerPerson": 120.00,
        "defaultUnitPrice": 120.00,
        "priceConfigured": true
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "traceId": null,
  "success": true
}

请求（导游）：

GET /admin/resource-options/guides?pageNo=1&pageSize=10&serviceDate=2026-08-06&keyword=李雪梅

响应（实测）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "resourceId": "1002",
        "resourceName": "李雪梅",
        "staffType": "GUIDE",
        "staffTypeName": "导游",
        "settleType": "cash",
        "settleTypeName": "现付",
        "serviceDate": "2026-08-06",
        "protocolPrice": 300.00,
        "settlementPrice": 299.00,
        "defaultUnitPrice": 299.00,
        "priceConfigured": true
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "traceId": null,
  "success": true
}

请求（摄影）：

GET /admin/resource-options/photographers?pageNo=1&pageSize=10&serviceDate=2026-08-06

响应结构与导游一致，staffType 为 PHOTOGRAPHER、staffTypeName 为 摄影师。

8.2 边界情况

keyword 为纯空白（自动 trim 后等价于不传，按全量分页返回）：

GET /admin/resource-options/restaurants?pageNo=1&pageSize=10&keyword=%20%20

响应：正常 200，keyword 不生效，返回全量分页数据。

无任何匹配结果（空数组，注意 total=0、records 为空数组而非 null）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  },
  "traceId": null,
  "success": true
}

人员当日未配置任何价格（defaultUnitPrice 为 null、priceConfigured 为 false）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "resourceId": "1003",
        "resourceName": "张三",
        "staffType": "GUIDE",
        "staffTypeName": "导游",
        "settleType": null,
        "settleTypeName": null,
        "serviceDate": "2026-08-06",
        "protocolPrice": null,
        "settlementPrice": null,
        "defaultUnitPrice": null,
        "priceConfigured": false
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "traceId": null,
  "success": true
}

8.3 业务失败

guides / photographers 缺失必填的 serviceDate：

GET /admin/resource-options/guides?pageNo=1&pageSize=10

响应：

{
  "code": 400,
  "message": "服务日期不能为空",
  "data": null,
  "traceId": null,
  "success": false
}

未登录调用：

GET /admin/resource-options/restaurants?pageNo=1&pageSize=10
（不携带 Authorization 头）

响应：

{
  "code": 401,
  "message": "缺少有效的 Authorization 头",
  "data": null,
  "traceId": "00fef1580108417f",
  "success": false
}

---

9. 业务边界

适用：

• 管理后台核单录入费用时，下拉选择餐厅 / 导游 / 摄影资源。

不适用 / 特殊边界：

• resourceId 仅用于识别资源：餐厅接口的 resourceId 是餐厅资源 ID；人员接口的 resourceId 是 staff 表 staff_id，明确不是订单侧的 staffAssignmentId，不能拿它去调订单人员分配相关接口。
• 餐厅价格只有"人均价"一个来源，不存在按日期变化的价格；defaultUnitPrice 恒等于 pricePerPerson。
• 人员价格是"共享人员类型价格"，按 serviceDate 匹配当日协议价 / 结算价；当日两种价格均未配置时 defaultUnitPrice 为 null、priceConfigured 为 false。
• defaultUnitPrice 取值规则固定为"结算价优先、协议价回退"，调用方不需要自行二选一。
• guides 接口固定只返回 GUIDE 类型人员，不含助理导游；photographers 固定只返回 PHOTOGRAPHER 类型。
• 餐厅的 settleType / settleTypeName 固定为 null，不是数据缺失。

---

10. 修改前后对比

新增接口，无修改前后对比。

---

11. 影响评估 / 回滚

新增接口，无回滚影响：

• 不破坏任何既有接口与字段，无兼容性问题。
• 不要求前端同步上线；前端未接入时接口存在但不影响任何现有功能。
• 如需回滚，下线 3 个新端点即可，无数据 / 状态残留。

---

12. 注意事项

• 三个接口的资源 ID 均为雪花 ID 序列化后的 String 类型，前端请勿按 Number 处理，避免精度丢失。
• guides / photographers 的 serviceDate 是必填项（格式 yyyy-MM-dd），缺失直接 400；restaurants 无此参数。
• keyword 服务端自动 trim，前端无需预处理空白。
• 人员 settleType 可能出现上表之外的未知编码，此时 settleType 原样返回、settleTypeName 为 null，需按未知编码兜底处理。
• 响应不暴露 calendarStatus 字段。

---

13. 关联 / 联系人

• Issue：wx/HL#5581
• PR：wx/HL#5583
• Commit：258a7d9485
• 后端负责人：腰苏图
• 接口已在测试服（web.test.1814.love:9443）实调验证通过。