hl-api-changelog/changelogs/2026-07/23_5185_Step2票种规格字典-修改接口-管理后台.md

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

请求：

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

无请求体。

响应：

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

请求：

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_ticket_spec

无请求体，且未携带 Authorization。

响应：

{
  "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
• PR: #5191
• Merge commit: 03ab19b46

13.2 联系人

• 后端负责人: @yst