# 【✨ 新增字典·管理后台】核单其他收入项目类别字典（#5320）

> **PR**: #5330 | **服务**: hl-user-service | **更新时间**: 2026-07-29 09:19

## 1. 接口背景

核单「其他收入」的项目类别改为统一字典值。管理后台通过现有字典查询接口加载 7 个启用项，展示 `dictLabel`，保存其他收入时提交对应的 `dictValue`。

票种/规格不使用本字典，仍通过 `settlement_ticket_spec` 字典加载并提交。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 按类型查询字典数据 | GET | `/admin/dict/data/settlement_other_income_project_category` | 修改接口 | 新增 7 个核单其他收入项目类别启用项 |

## 3. 接口详情

### 3.1 按类型查询核单其他收入项目类别

- **方法 + 路径**：`GET /admin/dict/data/settlement_other_income_project_category`
- **接口名**：按类型查询字典数据
- **使用场景**：加载核单其他收入的项目类别选项。
- **认证**：需要管理后台 JWT。
- **幂等性**：是，只读查询。
- **限流**：无接口专属限流约定。
- **排序**：按 `sortOrder` 升序，同一排序号再按 `dictDataId` 升序。
- **过滤**：只返回 `status=ACTIVE` 的字典项。

## 4. 接口入参

### 4.1 路径参数

| 字段 | 类型 | 必填 | 固定值 | 说明 |
|------|------|------|--------|------|
| `dictType` | String | 是 | `settlement_other_income_project_category` | 核单其他收入项目类别字典类型编码 |

### 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_other_income_project_category` |
| `dictLabel` | String | 否 | 展示文案 |
| `dictValue` | String | 否 | 保存其他收入时提交到 `projectCategory` 的值 |
| `icon` | String | 是 | 图标，本字典当前为 `null` |
| `color` | String | 是 | 展示色值，本字典当前为 `null` |
| `sortOrder` | Integer | 否 | 排序号，越小越靠前 |
| `status` | String | 否 | 字典项状态，本接口返回项为 `ACTIVE` |
| `remark` | String | 是 | 字典项说明 |
| `createdAt` | String | 是 | 创建时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `updatedAt` | String | 是 | 更新时间，格式 `yyyy-MM-dd HH:mm:ss` |

## 6. 枚举 / 数据字典

### 6.1 `settlement_other_income_project_category`

**展示字段**：`dictLabel` | **提交字段**：`dictValue` | **提交目标**：其他收入保存接口的 `projectCategory`

| `dictValue` | `dictLabel` | `sortOrder` | `status` | 说明 |
|-------------|-------------|-------------|----------|------|
| `HOTEL` | 住宿 | `10` | `ACTIVE` | 住宿类其他收入 |
| `TICKET` | 门票/游玩项目 | `20` | `ACTIVE` | 门票或游玩项目类其他收入 |
| `MEAL` | 餐食 | `30` | `ACTIVE` | 餐食类其他收入 |
| `VEHICLE` | 车辆 | `40` | `ACTIVE` | 车辆类其他收入 |
| `GUIDE` | 导游 | `50` | `ACTIVE` | 导游类其他收入 |
| `PHOTOGRAPHER` | 摄影 | `60` | `ACTIVE` | 摄影类其他收入 |
| `OTHER` | 其他 | `70` | `ACTIVE` | 以上类别以外的其他收入 |

### 6.2 `status`

| 值 | 中文 | 是否由本接口返回 |
|----|------|------------------|
| `ACTIVE` | 启用 | 是 |
| `INACTIVE` | 禁用 | 否；查询接口过滤禁用项 |

### 6.3 票种/规格字典（独立）

其他收入保存接口的 `specification` 不使用项目类别字典；其选项来自：

`GET /admin/dict/data/settlement_ticket_spec`

当前启用项为：

| `dictValue` | `dictLabel` | 提交目标 |
|-------------|-------------|----------|
| `成人票` | 成人票 | 其他收入保存接口的 `specification` |

## 7. 错误码

| code | 含义 | 触发场景 |
|------|------|----------|
| `200` | 成功 | 查询成功；没有匹配项时 `data=[]` |
| `401` | 未认证或认证失效 | 未携带有效管理后台 JWT |
| `500` | 系统异常 | 查询过程发生未预期异常 |

## 8. 示例

### 8.1 典型成功

**请求**：

```http
GET /admin/dict/data/settlement_other_income_project_category
Authorization: Bearer <admin-token>
```

无请求体。

**响应**：

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "dictDataId": 101421,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "住宿",
      "dictValue": "HOTEL",
      "icon": null,
      "color": null,
      "sortOrder": 10,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09:00:00"
    },
    {
      "dictDataId": 101422,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "门票/游玩项目",
      "dictValue": "TICKET",
      "icon": null,
      "color": null,
      "sortOrder": 20,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09:00:00"
    },
    {
      "dictDataId": 101423,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "餐食",
      "dictValue": "MEAL",
      "icon": null,
      "color": null,
      "sortOrder": 30,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09:00:00"
    },
    {
      "dictDataId": 101424,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "车辆",
      "dictValue": "VEHICLE",
      "icon": null,
      "color": null,
      "sortOrder": 40,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09:00:00"
    },
    {
      "dictDataId": 101425,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "导游",
      "dictValue": "GUIDE",
      "icon": null,
      "color": null,
      "sortOrder": 50,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09:00:00"
    },
    {
      "dictDataId": 101426,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "摄影",
      "dictValue": "PHOTOGRAPHER",
      "icon": null,
      "color": null,
      "sortOrder": 60,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09:00:00"
    },
    {
      "dictDataId": 101427,
      "dictType": "settlement_other_income_project_category",
      "dictLabel": "其他",
      "dictValue": "OTHER",
      "icon": null,
      "color": null,
      "sortOrder": 70,
      "status": "ACTIVE",
      "remark": "核单其他收入项目类别",
      "createdAt": "2026-07-29 09:00:00",
      "updatedAt": "2026-07-29 09: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_other_income_project_category
```

无请求体，且未携带 `Authorization`。

**响应**：

```json
{
  "code": 401,
  "message": "未认证或登录已失效",
  "data": null,
  "traceId": "c3d4e5f6-a7b8-9012",
  "success": false
}
```

## 9. 业务边界

- 查询接口只返回启用项，禁用项不进入 `data`。
- 前端展示 `dictLabel`，保存时提交 `dictValue`；不要提交 `dictDataId` 或中文标签。
- `projectCategory` 只接受上述 7 个启用值。
- `specification` 是独立字段，非空时必须使用 `settlement_ticket_spec` 的启用 `dictValue`。
- 字典为单层平铺列表，不包含父子层级。

## 10. 修改前后对比

### 10.1 字段级对比

| 项目 | 改前 | 改后 |
|------|------|------|
| 字典接口响应结构 | `Result<List<SysDictDataRespVO>>` | 不变 |
| 其他收入项目类别字典 | 无专用字典 | 新增 `settlement_other_income_project_category` |
| 可提交值 | 前端可能提交自由文本 | 固定为 7 个 `dictValue` |

### 10.2 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 加载项目类别 | 前端自行维护 | 调用本接口动态加载 |
| 保存项目类别 | 提交自由文本 | 提交选中项的 `dictValue` |
| 票种/规格 | 与项目类别未明确区分 | 继续独立读取 `settlement_ticket_spec` |

## 11. 影响评估

- **是否破坏向后兼容**：字典查询接口本身兼容；其他收入保存接口开始校验项目类别启用值。
- **前端是否必须同步上线**：是。保存其他收入前必须把 `projectCategory` 切换为本字典的 `dictValue`。

## 12. 注意事项

- 不要把 7 个项目类别写死为中文值；展示中文，提交英文 `dictValue`。
- `projectCategory=TICKET` 时，`specification` 仍从 `settlement_ticket_spec` 选择。
- 旧记录若存的是非字典值，编辑保存时需要改成上述 7 个值之一。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5320](https://git.1814.love:8443/wx/HL/issues/5320)
- **PR**: [#5330](https://git.1814.love:8443/wx/HL/pulls/5330)
- **Merge commit**: [7477b03963](https://git.1814.love:8443/wx/HL/commit/7477b0396352e7591e78a5d5ab9b080a640187d7)

### 13.2 联系人

- **后端负责人**: @yst