wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs/2026-07/29_5320_核单其他收入项目类别字典.md
yaosutu dbef2f3397
所有检测均成功
changelog-filename-gate / validate (push) Successful in 1s
详情
新增核单其他收支确认状态与项目类别变更说明
2026-07-29 09:26:47 +08:00

10 KiB
原始文件 Blame 文件历史

【✨ 新增字典·管理后台】核单其他收入项目类别字典（#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 典型成功

请求：

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

无请求体。

响应：

{
  "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 边界情况：不存在的字典类型

请求：

GET /admin/dict/data/not_exists
Authorization: Bearer <admin-token>

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": [],
  "traceId": "b2c3d4e5-f6a7-8901",
  "success": true
}

8.3 业务失败：未认证

请求：

GET /admin/dict/data/settlement_other_income_project_category

无请求体，且未携带 Authorization。

响应：

{
  "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 链接

13.2 联系人

  • 后端负责人: @yst