新增核单其他收支确认状态与项目类别变更说明

2026-07-29 09:25:17 +08:00 · 2026-07-29 09:25:17 +08:00 · dbef2f3397
--- a/changelogs-v2/2026-07/29_5320_核单其他收支确认状态与项目类别-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/29_5320_核单其他收支确认状态与项目类别-修改接口-管理后台.md
--- a/changelogs/2026-07/29_5320_核单其他收入项目类别字典.md
+++ b/changelogs/2026-07/29_5320_核单其他收入项目类别字典.md
@ -0,0 +1,322 @@
+# 【✨ 新增字典·管理后台】核单其他收入项目类别字典（#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