wx/hl-api-changelog

派生 0

yaosutu d3d21efceb

changelog-filename-gate / validate (push) Successful in 1s

详情

更新核单资源下拉可选范围与中文字段契约

2026-08-05 11:29:19 +08:00

12 KiB

原始文件 Blame 文件历史

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

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

1. 接口背景

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

2. 变更清单

#	接口名	方法	路径	变更类型	说明
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 仍为符合条件的启用资源总数。

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 保存和传递。

12 KiB

原始文件 Blame 文件历史

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

1. 接口背景

2. 变更清单

3. 接口详情

4. 接口入参

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

4.2 已删除的 Query 参数

4.3 请求体字段

5. 出参字段

5.1 统一响应与分页字段

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

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

6. 枚举 / 数据字典

6.1 `resourceType` / `resourceTypeName`

6.2 `settleType` / `settleTypeName`

6.3 价格字段关系

7. 错误码

8. 示例

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

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

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

9. 业务边界

10. 修改前后对比

10.1 字段级对比

10.2 行为级对比

11. 影响评估 / 回滚

12. 前端迁移清单

13. 关联 / 联系人

13.1 链接

13.2 联系人

12 KiB 原始文件 Blame 文件历史 Unescape Escape

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

1. 接口背景

2. 变更清单

3. 接口详情

4. 接口入参

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

4.2 已删除的 Query 参数

4.3 请求体字段

5. 出参字段

5.1 统一响应与分页字段

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

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

6. 枚举 / 数据字典

6.1 resourceType / resourceTypeName

6.2 settleType / settleTypeName

6.3 价格字段关系

7. 错误码

8. 示例

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

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

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

9. 业务边界

10. 修改前后对比

10.1 字段级对比

10.2 行为级对比

11. 影响评估 / 回滚

12. 前端迁移清单

13. 关联 / 联系人

13.1 链接

13.2 联系人

12 KiB

原始文件 Blame 文件历史

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

6.1 `resourceType` / `resourceTypeName`

6.2 `settleType` / `settleTypeName`