220 行
6.3 KiB
Markdown
220 行
6.3 KiB
Markdown
# 【🔧 修改接口·管理后台】Step2 票种规格字典（#5185）
|
||
|
||
> **PR**: #5191 | **更新时间**: 2026-07-23
|
||
|
||
## 1. 接口背景
|
||
|
||
Step2 门票/游玩项目需要统一的票种/规格选项。管理后台现在可以按字典类型加载启用选项，首个可用选项为“成人票”，避免前端写死选项文案。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 按类型查询字典数据 | GET | `/admin/dict/data/settlement_ticket_spec` | 修改接口 | 新增 `settlement_ticket_spec` 字典类型及启用项“成人票” |
|
||
|
||
## 3. 接口详情
|
||
|
||
### 3.1 按类型查询 Step2 票种规格
|
||
|
||
- **使用场景**：加载 Step2 门票/游玩项目的票种/规格下拉选项。
|
||
- **认证**：需要管理后台 JWT。
|
||
- **幂等性**：是，只读查询。
|
||
- **限流**：无接口专属限流约定。
|
||
- **排序**：按 `sortOrder` 升序，同一排序号再按 `dictDataId` 升序。
|
||
- **过滤**：仅返回 `status=ACTIVE` 的字典项。
|
||
|
||
## 4. 接口入参
|
||
|
||
### 4.1 路径参数
|
||
|
||
| 字段 | 类型 | 必填 | 固定值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `dictType` | String | 是 | `settlement_ticket_spec` | Step2 票种/规格字典类型编码 |
|
||
|
||
### 4.2 Query 参数与请求体
|
||
|
||
无 Query 参数，无请求体。
|
||
|
||
## 5. 出参（响应）
|
||
|
||
### 5.1 统一响应字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `code` | Integer | 业务状态码，成功为 `200` |
|
||
| `message` | String | 响应消息，成功为“成功” |
|
||
| `data` | Array | 启用的字典项列表；无匹配项时为 `[]` |
|
||
| `traceId` | String / null | 链路追踪 ID |
|
||
| `success` | Boolean | `code=200` 时为 `true` |
|
||
|
||
### 5.2 `data[]` 字典项字段
|
||
|
||
| 字段 | 类型 | 可为空 | 说明 |
|
||
|------|------|--------|------|
|
||
| `dictDataId` | Long | 否 | 字典数据 ID |
|
||
| `dictType` | String | 否 | 字典类型编码，本接口固定为 `settlement_ticket_spec` |
|
||
| `dictLabel` | String | 否 | 展示文案 |
|
||
| `dictValue` | String | 否 | 提交值；选择后写入 Step2 `items[].specName` |
|
||
| `icon` | String | 是 | 图标，本字典项当前为 `null` |
|
||
| `color` | String | 是 | 展示色值，本字典项当前为 `null` |
|
||
| `sortOrder` | Integer | 否 | 排序号，越小越靠前 |
|
||
| `status` | String | 否 | 字典项状态 |
|
||
| `remark` | String | 是 | 字典项说明 |
|
||
| `createdAt` | String | 是 | 创建时间，格式为 `yyyy-MM-dd HH:mm:ss` |
|
||
| `updatedAt` | String | 是 | 更新时间，格式为 `yyyy-MM-dd HH:mm:ss` |
|
||
|
||
## 6. 枚举 / 数据字典
|
||
|
||
### 6.1 `settlement_ticket_spec`
|
||
|
||
**展示字段**：`dictLabel` | **提交字段**：`dictValue` | **提交目标**：Step2 `items[].specName`
|
||
|
||
| `dictValue` | `dictLabel` | `sortOrder` | `status` | 说明 |
|
||
|-------------|-------------|-------------|----------|------|
|
||
| `成人票` | 成人票 | `10` | `ACTIVE` | Step2 默认票种/规格 |
|
||
|
||
### 6.2 `status`
|
||
|
||
| 值 | 中文 | 是否由本接口返回 |
|
||
|----|------|------------------|
|
||
| `ACTIVE` | 启用 | 是 |
|
||
| `INACTIVE` | 禁用 | 否；查询接口会过滤禁用项 |
|
||
|
||
## 7. 错误码
|
||
|
||
| code | 含义 | 触发场景 |
|
||
|------|------|----------|
|
||
| `200` | 成功 | 查询成功；没有匹配项时 `data=[]` |
|
||
| `401` | 未认证或认证失效 | 未携带有效管理后台 JWT |
|
||
| `500` | 系统异常 | 查询过程发生未预期异常 |
|
||
|
||
## 8. 示例
|
||
|
||
### 8.1 典型成功
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /admin/dict/data/settlement_ticket_spec
|
||
Authorization: Bearer <admin-token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": [
|
||
{
|
||
"dictDataId": 101411,
|
||
"dictType": "settlement_ticket_spec",
|
||
"dictLabel": "成人票",
|
||
"dictValue": "成人票",
|
||
"icon": null,
|
||
"color": null,
|
||
"sortOrder": 10,
|
||
"status": "ACTIVE",
|
||
"remark": "Step2 默认票种/规格",
|
||
"createdAt": "2026-07-23 10:00:00",
|
||
"updatedAt": "2026-07-23 10:00:00"
|
||
}
|
||
],
|
||
"traceId": "a1b2c3d4-e5f6-7890",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 8.2 边界情况：不存在的字典类型
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /admin/dict/data/not_exists
|
||
Authorization: Bearer <admin-token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": [],
|
||
"traceId": "b2c3d4e5-f6a7-8901",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 8.3 业务失败：未认证
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /admin/dict/data/settlement_ticket_spec
|
||
```
|
||
|
||
无请求体，且未携带 `Authorization`。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"message": "未认证或登录已失效",
|
||
"data": null,
|
||
"traceId": "c3d4e5f6-a7b8-9012",
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
## 9. 业务边界
|
||
|
||
- 字典接口只返回启用项；禁用项不会出现在下拉列表中。
|
||
- 前端展示 `dictLabel`，并将选中项的 `dictValue` 原样提交到 Step2 `items[].specName`。
|
||
- 当前首个字典值为“成人票”；后续新增启用项时，接口会按排序规则一并返回。
|
||
- 字典为单层平铺列表，不包含父子层级。
|
||
|
||
## 10. 修改前后对比
|
||
|
||
### 10.1 字段级对比
|
||
|
||
| 项目 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 响应结构 | `Result<List<SysDictDataRespVO>>` | 不变 |
|
||
| Step2 票种规格字典类型 | 无 `settlement_ticket_spec` 可用项 | 返回启用项“成人票” |
|
||
|
||
### 10.2 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 加载 Step2 票种/规格选项 | 无专用字典数据 | 可查询 `settlement_ticket_spec` |
|
||
| 前端选项值 | 需要自行维护 | 使用接口返回的 `dictValue` |
|
||
|
||
## 11. 影响评估
|
||
|
||
- **是否破坏向后兼容**：否，接口路径和响应结构未改变。
|
||
- **前端是否必须同步上线**：否；接入后可使用动态字典，旧逻辑不会因本次新增字典项而报错。
|
||
|
||
## 12. 注意事项
|
||
|
||
- 不要把“成人票”选项数组硬编码在前端；应按需调用本接口。
|
||
- 展示使用 `dictLabel`，保存使用 `dictValue`，不要提交 `dictDataId`。
|
||
- Step2 仍使用原有 `specName` 字段，没有新增 `specCode`。
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
### 13.1 链接
|
||
|
||
- **Issue**: [#5185](https://git.1814.love:8443/wx/HL/issues/5185)
|
||
- **PR**: [#5191](https://git.1814.love:8443/wx/HL/pulls/5191)
|
||
- **Merge commit**: [03ab19b46](https://git.1814.love:8443/wx/HL/commit/03ab19b463be4b00f92848cb348ce6158918e041)
|
||
|
||
### 13.2 联系人
|
||
|
||
- **后端负责人**: @yst
|