hl-api-changelog/changelogs-v2/2026-08/05_5539_核单资源下拉可选范围与中文字段契约-修改接口-管理后台.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	5539	核单资源下拉可选范围与中文字段契约	admin	yst	修改接口	deployed	verified	implemented	pi-main-session	hl-admin@0a8a72ed6a978a9f14187679188f4c8308e354cd			hl-resource-service；PR #5540 已合并并部署测试服，Gateway 真实验收通过；等待管理后台完成破坏性契约迁移。	2026-08-05	dev-v3

【⚠️ 修改接口·管理后台】核单资源下拉可选范围与中文字段契约（#5539）

PR: #5540 服务: hl-resource-service 更新时间: 2026-08-05

1. 接口背景

核单门票/游玩统一资源下拉首版会返回下架资源，且资源类型、结算方式只有编码，默认核算价字段名也不够明确。本次收紧为只返回启用资源，并调整请求与响应字段。删除字段和字段改名属于破坏性契约变化，接入方需要按第 12 节迁移。

变更接口

#	接口名	方法	路径	变更类型	说明
1	分页查询门票/游玩资源选项	GET	/admin/resource-options/ticket-items	修改接口	仅返回启用资源，删除状态字段，增加中文名称字段并重命名默认核算价

3. 接口详情

• 使用场景：核单 Step 2 新增或搜索可选的门票/游玩项目。
• 认证：需要有效的管理后台 JWT，使用 Authorization: Bearer <token>。
• 幂等性：幂等，只读查询。
• 限流：无接口专属限流约定。
• 响应类型：Result<PageResult<TicketResourceOptionRespVO>>。
• 请求体：无。

4. 接口入参

4.1 Query 参数（修改后完整字段）

字段	类型	必填	默认值	校验规则	说明
dayDate	String	是	无	ISO 日期 yyyy-MM-dd	实际游玩日期；价格字段只匹配这一天的资源价格
keyword	String	否	null	最长 100 个字符	资源名称模糊搜索；自动去除首尾空格；去除后为空等同未传
resourceType	String	否	null	SCENIC 或 ACTIVITY	不传时同时查询景区和游玩项目
page	Integer	否	1	最小值 1	当前页码
pageSize	Integer	否	20	1～100	每页条数

4.2 已删除的 Query 参数

字段	修改前	修改后
status	可选，0 已下架、1 已启用；不传查询全部	已删除；接口固定只返回启用资源

4.3 请求体字段

无请求体。

5. 出参字段

5.1 统一响应与分页字段

字段	类型	可空	说明
code	Integer	否	业务状态码；成功为 200
message	String	否	响应消息；成功为 成功
success	Boolean	否	code == 200 时为 true
traceId	String	是	链路追踪 ID
data	Object	否	分页结果
data.records	Array	否	本页启用资源列表；无匹配资源时为 []
data.total	Integer	否	符合条件的启用资源总数
data.page	Integer	否	当前页码
data.pageSize	Integer	否	每页条数

5.2 data.records[] 资源字段（修改后完整 13 项）

字段	类型	可空	说明
resourceType	String	否	资源类型编码：SCENIC 或 ACTIVITY
resourceTypeName	String	否	资源类型中文名：景区 或 游玩项目
resourceId	String	否	资源 ID；固定按 JSON String 返回，不要转换为 JavaScript Number
resourceName	String	否	资源名称；名称为 null、空字符串或纯空白的资源不会返回
city	String	是	城市；景区优先返回城市名称；原值为 null、空字符串或纯空白时统一返回 null
settleType	String	是	结算方式编码；空值/空白统一为 null；未知非空编码去除首尾空格后原值返回
settleTypeName	String	是	结算方式中文名；cash/sign/company 分别为现付/签单/公司付款；编码为空或未知时为 null
dayDate	String	否	本次查询的实际游玩日期，格式 yyyy-MM-dd
protocolPrice	Decimal	是	该日期的协议价；未配置时为 null
settlementPrice	Decimal	是	该日期的结算价；未配置时为 null
defaultUnitPrice	Decimal	是	默认核算单价：优先取结算价，结算价为空时回退协议价；两者都为空时为 null
priceConfigured	Boolean	否	defaultUnitPrice 非空时为 true，否则为 false
specName	String	否	固定返回 成人票

5.3 已删除或改名的响应字段

修改前字段	修改后	迁移说明
status	已删除	接口已固定过滤为启用资源，不再返回状态值
statusName	已删除	接口已固定过滤为启用资源，不再返回状态文案
ticketUnitPrice	改名为 defaultUnitPrice	价格优先级不变：结算价优先、协议价回退

6. 枚举 / 数据字典

6.1 resourceType / resourceTypeName

resourceType	resourceTypeName	说明
SCENIC	景区	景区资源
ACTIVITY	游玩项目	活动/游玩项目资源

6.2 settleType / settleTypeName

settleType	settleTypeName	说明
cash	现付	资源结算方式为现付
sign	签单	资源结算方式为签单
company	公司付款	资源结算方式为公司付款
null	null	原编码为空或空白
其他非空编码	null	编码去除首尾空格后原值返回，中文名为空

6.3 价格字段关系

条件	defaultUnitPrice	priceConfigured
settlementPrice 非空	取 settlementPrice	true
settlementPrice 为空、protocolPrice 非空	取 protocolPrice	true
两个价格都为空	null	false

7. 错误码

code	含义	触发场景
200	成功	查询完成；没有匹配资源时仍为成功，records=[]
400	参数校验失败	缺少/无法解析 dayDate，keyword 超过 100 字符，resourceType 非法，或分页参数越界
401	未认证或认证失效	未携带有效的管理后台 JWT
500	系统异常	查询过程发生未预期异常

8. 示例

8.1 典型成功：启用景区与游玩项目

请求：

GET /admin/resource-options/ticket-items?dayDate=2026-08-03&keyword=体验&page=1&pageSize=20
Authorization: Bearer <admin-token>

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "resourceType": "SCENIC",
        "resourceTypeName": "景区",
        "resourceId": "2079454953641836546",
        "resourceName": "草原景区体验区",
        "city": "呼伦贝尔市",
        "settleType": "sign",
        "settleTypeName": "签单",
        "dayDate": "2026-08-03",
        "protocolPrice": 100.00,
        "settlementPrice": 88.00,
        "defaultUnitPrice": 88.00,
        "priceConfigured": true,
        "specName": "成人票"
      },
      {
        "resourceType": "ACTIVITY",
        "resourceTypeName": "游玩项目",
        "resourceId": "2079454953641836550",
        "resourceName": "骑马体验",
        "city": "海拉尔区",
        "settleType": "cash",
        "settleTypeName": "现付",
        "dayDate": "2026-08-03",
        "protocolPrice": 66.00,
        "settlementPrice": null,
        "defaultUnitPrice": 66.00,
        "priceConfigured": true,
        "specName": "成人票"
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 20
  },
  "traceId": "a1b2c3d4-e5f6-7890",
  "success": true
}

8.2 边界情况：空白城市、未知结算编码且当天无价格

请求：

GET /admin/resource-options/ticket-items?dayDate=2026-12-31&resourceType=ACTIVITY&page=1&pageSize=20
Authorization: Bearer <admin-token>

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "resourceType": "ACTIVITY",
        "resourceTypeName": "游玩项目",
        "resourceId": "2079454953641836558",
        "resourceName": "特色体验",
        "city": null,
        "settleType": "other",
        "settleTypeName": null,
        "dayDate": "2026-12-31",
        "protocolPrice": null,
        "settlementPrice": null,
        "defaultUnitPrice": null,
        "priceConfigured": false,
        "specName": "成人票"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "traceId": "b2c3d4e5-f6a7-8901",
  "success": true
}

8.3 业务失败：缺少游玩日期

请求：

GET /admin/resource-options/ticket-items?page=1&pageSize=20
Authorization: Bearer <admin-token>

无请求体。

响应：

{
  "code": 400,
  "message": "游玩日期不能为空",
  "data": null,
  "traceId": "c3d4e5f6-a7b8-9012",
  "success": false
}

9. 业务边界

• 无论是否携带旧版 status 参数，接口都固定只返回已启用资源；调用方不应继续传该参数。
• 下架资源、软删除资源、名称为 null/空字符串/纯空白的资源均不返回，也不计入 total。
• 默认统一查询 SCENIC 与 ACTIVITY；结果按“名称升序 → 资源类型升序 → 资源 ID 升序”稳定排序。
• keyword 只匹配资源名称；不会匹配城市或资源 ID。
• 当天没有价格不会排除资源，defaultUnitPrice=null、priceConfigured=false。
• city 或 settleType 为空不影响资源是否返回；空白值会被规范为 null。
• 未知非空结算编码保留在 settleType，但 settleTypeName=null。
• 页码超过最后一页时，返回 code=200、records=[]，total 仍为符合条件的启用资源总数。

验证证据

• PR #5540 已合并到 dev-v3，hl-resource-service 已部署测试服。
• Gateway 真实 HTTP 验收确认仅启用过滤、新旧字段、String ID、结算方式映射、价格优先级、双价缺失、筛选与鉴权均按本文契约生效。

10. 修改前后对比

10.1 字段级对比

位置	修改前	修改后
Query	dayDate/keyword/resourceType/status/page/pageSize	dayDate/keyword/resourceType/page/pageSize
资源状态	status/statusName	两个字段均删除
资源类型中文名	无	新增 resourceTypeName
结算方式中文名	无	新增 settleTypeName
默认核算价	ticketUnitPrice	改名为 defaultUnitPrice
城市空白值	可能返回空字符串/纯空白	统一返回 null
结算编码空白值	可能返回空字符串/纯空白	统一返回 null

10.2 行为级对比

行为	修改前	修改后
可选资源范围	默认包含启用和下架，可通过 status 筛选	固定只返回启用资源
默认核算价优先级	结算价优先，协议价回退	不变，仅字段改名
未知结算编码	只有原始编码	保留原始编码，中文名为 null
排序	启用优先，再按名称/类型/ID	全部为启用资源，按名称/类型/ID

11. 影响评估 / 回滚

• 是否破坏向后兼容：是；请求删除 status，响应删除和改名字段。
• 前端是否必须同步上线：已接入首版接口的前端必须同步迁移；尚未接入的前端直接按新契约实现。
• 回滚影响：若后端回滚到首版，resourceTypeName/settleTypeName/defaultUnitPrice 将消失，旧字段和下架资源会重新出现；前后端需保持同一契约版本。

12. 前端迁移清单

• 删除请求中的 status 参数和相关状态筛选逻辑。
• 删除对响应 status、statusName 的读取、展示与过滤。
• 将所有 ticketUnitPrice 读取改为 defaultUnitPrice。
• 展示资源类型时读取 resourceTypeName；编码判断仍使用 resourceType。
• 展示结算方式时读取 settleTypeName，并允许该字段为 null。
• 允许 city、settleType、settleTypeName、三个价格字段为 null。
• 不再在前端筛除下架资源；接口结果已经只包含启用资源。
• resourceId 继续按 String 保存和传递。

13. 关联 / 联系人

13.1 链接

• Issue: #5539
• PR: #5540
• Merge commit: 7edbb6026
• 前置 Issue: #5429

13.2 联系人

• 后端负责人: @yst

关联/联系人

链接

• 后端工单 #5539
• 后端 PR #5540
• Merge commit: 7edbb6026d

联系人

• 后端负责人: @yst