yaosutu
父节点
95b2b5a155
当前提交
d3d21efceb
@ -0,0 +1,316 @@
|
|||||||
|
# 【⚠️ 修改接口·管理后台】核单资源下拉可选范围与中文字段契约（#5539）
|
||||||
|
|
||||||
|
> **PR**: [#5540](https://git.1814.love:8443/wx/HL/pulls/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 典型成功：启用景区与游玩项目
|
||||||
|
|
||||||
|
**请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /admin/resource-options/ticket-items?dayDate=2026-08-03&keyword=体验&page=1&pageSize=20
|
||||||
|
Authorization: Bearer <admin-token>
|
||||||
|
```
|
||||||
|
|
||||||
|
无请求体。
|
||||||
|
|
||||||
|
**响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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 边界情况：空白城市、未知结算编码且当天无价格
|
||||||
|
|
||||||
|
**请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /admin/resource-options/ticket-items?dayDate=2026-12-31&resourceType=ACTIVITY&page=1&pageSize=20
|
||||||
|
Authorization: Bearer <admin-token>
|
||||||
|
```
|
||||||
|
|
||||||
|
无请求体。
|
||||||
|
|
||||||
|
**响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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 业务失败：缺少游玩日期
|
||||||
|
|
||||||
|
**请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /admin/resource-options/ticket-items?page=1&pageSize=20
|
||||||
|
Authorization: Bearer <admin-token>
|
||||||
|
```
|
||||||
|
|
||||||
|
无请求体。
|
||||||
|
|
||||||
|
**响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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 保存和传递。
|
||||||
|
|
||||||
|
## 13. 关联 / 联系人
|
||||||
|
|
||||||
|
### 13.1 链接
|
||||||
|
|
||||||
|
- **Issue**: [#5539](https://git.1814.love:8443/wx/HL/issues/5539)
|
||||||
|
- **PR**: [#5540](https://git.1814.love:8443/wx/HL/pulls/5540)
|
||||||
|
- **Merge commit**: [7edbb6026](https://git.1814.love:8443/wx/HL/commit/7edbb6026d7f0d3551ed8c43ca57ea1698ebfeff)
|
||||||
|
- **前置 Issue**: [#5429](https://git.1814.love:8443/wx/HL/issues/5429)
|
||||||
|
|
||||||
|
### 13.2 联系人
|
||||||
|
|
||||||
|
- **后端负责人**: @yst
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户