# 【🔧 修改接口·管理后台】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