docs(changelog): 资源退费说明 changelog 追加 settleScope 字典化用法说明 (PR #3291)

对应后端 PR #3291 (Issue #3290): settleScope 字段补字典化, 出参补 settleScopeLabel。

在原 30_3272_资源退费说明CRUD模块_PR3273.md 的 settleScope 枚举说明后追加:

- 用法 A: 直接用出参 settleScopeLabel (展示场景)
- 用法 B: 调字典接口 GET /internal/dict/data?dictType=order_refund_settle_scope
         拉下拉框选项 (编辑场景)
- 容错说明 + 字典元信息

前端零代码改动也能用 (用法 A); 编辑场景拉一个统一字典接口即可。
这个提交包含在:
yaosutu 2026-06-01 10:14:39 +08:00
父节点 1d608857a7
当前提交 1c6b38f548

查看文件

@ -74,6 +74,64 @@ GET /admin/refund-note?resourceType=SCENIC&resourceId=12345
- 卡丁车场景:`unitLabel="/人"`(给客户看是 120/人)+ `settleScope=PER_VEHICLE`(引擎按车辆数乘单价)
- 两个字段独立维护,前端展示用 `unitLabel`,未来规则引擎用 `settleScope`
---
### ⚡ 更新2026-06-01 PR #3291settleScope 字典化 + 出参补 settleScopeLabel 中文
后端**已落字典 + 接口出参直接返中文**,前端**不用自己维护英文→中文映射**。两种用法二选一:
#### 用法 A直接用出参的 `settleScopeLabel`(展示场景推荐)
`GET /admin/refund-note` 返回的 `items[]` 每条**新增 `settleScopeLabel` 字段**
```jsonc
"items": [
{
"title": "成人未参加",
"settleScope": "PER_PERSON",
"settleScopeLabel": "按人", // 🆕 后端字典拼装,直接展示
...
}
]
```
**列表 / 详情 UI 直接 `{{ item.settleScopeLabel }}` 渲染**即可,无需自己映射。
#### 用法 B调字典接口拉下拉框选项编辑场景推荐
管理后台编辑退费规则时,需要下拉框让运营选"按人/按团/按车"。调统一字典接口:
```http
GET /internal/dict/data?dictType=order_refund_settle_scope
Authorization: Bearer <admin-token>
→ Result<List<SysDictDataDTO>>:
[
{ "dictValue": "PER_PERSON", "dictLabel": "按人", "sortOrder": 10 },
{ "dictValue": "PER_TEAM", "dictLabel": "按团", "sortOrder": 20 },
{ "dictValue": "PER_VEHICLE", "dictLabel": "按车", "sortOrder": 30 }
]
```
- 下拉框 `option.label = dictLabel``option.value = dictValue`
- 提交时 `req.items[].settleScope = dictValue`(提交 `settleScopeLabel` 后端会忽略,label 由后端拼)
- 建议前端**全局缓存字典 5-10 分钟**避免高频请求;如果有统一字典组件直接复用
#### 容错(前端可忽略)
- 字典服务异常 / 字典数据缺失 → `settleScopeLabel = null`,前端展示 fallback 用 `settleScope` 英文原值即可
- 字典文案后续改了(如"按人" → "按人头")→ **运维改 sys_dict_data + 清 Redis 缓存即生效**,后端无需重启,前端无需发版
#### 字典元信息
| 项 | 值 |
|---|---|
| `dict_type` | `order_refund_settle_scope` |
| `dict_name` | 退费明细结算粒度 |
| 字典数据 | PER_PERSON→按人 / PER_TEAM→按团 / PER_VEHICLE→按车 |
| 字典存储 | `hl_user_service.sys_dict_data` |
| 缓存 key | `cache:dict:data:order_refund_settle_scope` |
### 2. 保存upsert 整块)
```