feat(finance): 应收往来对象分类/应收性质下拉字典化 + 新增 /receipt/options 接口 changelog（#8501）

管理后台 changelogs-v2；PR #8503，测试服已部署+网关实测验证
2026-09-29 11:00:46 +08:00
@@ -0,0 +1,171 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8501"
+title: "应收往来对象分类/应收性质两组下拉字典化，新增 /receipt/options 接口供前端动态读取"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "应收页「往来对象分类」「应收性质」两组下拉此前前端写死常量、后端无字典无接口，加值须改前端发版。本次纯字典化（不落库不加列）：新增 2 个财务字典 + GET /admin/finance/receipt/options 接口，测试环境网关已实测返回两组 ACTIVE 下拉。前端需把两组写死常量改读本接口，码值从中文 value 迁英文码。"
+updated_at: "2026-09-29"
+base: "dev-v3"
+---
+
+# finance：应收往来对象分类 / 应收性质两组下拉字典化 + 新增 /receipt/options（管理后台）
+
+**服务**: hl-order-service-v3（finance 模块，同进程）
+**PR**: #8503
+**Issue**: #8501
+
+---
+
+## 一、接口背景
+
+财务应收页（应收台账等）有两组下拉：
+
+- **往来对象分类**：个人客户 / 企业客户 / 同行客户
+- **应收性质**：押金退还 / 赔偿款 / 口车费 / 其他应收
+
+此前这两组**前端写死常量**，后端没有对应数据字典、也没有下拉接口，运营要加值必须改前端代码发版。本次排查三方支付渠道字典化问题（前端写死导致新渠道 `webchat` 取不到）时，顺势把应收这两组也拉齐为「字典事实源 + 下拉接口」的统一做法，与资金账户三字段（#7141 accountType/nature/channel）一致。
+
+**拍板方案**：纯字典化，**不落库、不在应收/往来表加列**——仅作前端展示/筛选下拉的事实源。
+
+## 二、变更清单
+
+| 项 | 变更 |
+|---|---|
+| 数据字典 | 新增 2 个：`fin_recv_customer_ptype`、`fin_recv_nature` |
+| 接口 | 新增 `GET /admin/finance/receipt/options` |
+| 数据库表 | 零 DDL、零加列（纯字典化） |
+
+## 三、接口详情
+
+- **路径**：`GET /admin/finance/receipt/options`
+- **认证**：网关 JWT（admin）
+- **数据源**：平台字典 `fin_recv_customer_ptype` / `fin_recv_nature`，仅下放 **ACTIVE** 行、按 `sortOrder` 升序
+- **缓存**：后端 5 分钟本地缓存，运营改字典最多 5 分钟生效
+- **降级**：字典服务不可用时对应组返回空 List，**不报错**
+
+## 四、入参
+
+无（Query / Body 均无参数）。
+
+## 五、出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `customerPTypes` | `List<OptionItem>` | 应收往来对象分类下拉（字典 `fin_recv_customer_ptype`） |
+| `recvNatures` | `List<OptionItem>` | 应收性质下拉（字典 `fin_recv_nature`） |
+
+`OptionItem`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `value` | String | 字典值（英文码，如 `PERSONAL` / `DEPOSIT_REFUND`） |
+| `label` | String | 中文标签（如 `个人客户` / `押金退还`） |
+| `sortOrder` | Integer | 排序（越小越靠前） |
+
+## 六、枚举 / 数据字典
+
+`fin_recv_customer_ptype`（应收往来对象分类）：
+
+| dict_value | label | sortOrder |
+|---|---|---|
+| `PERSONAL` | 个人客户 | 10 |
+| `COMPANY` | 企业客户 | 20 |
+| `PEER` | 同行客户 | 30 |
+
+`fin_recv_nature`（应收性质）：
+
+| dict_value | label | sortOrder |
+|---|---|---|
+| `DEPOSIT_REFUND` | 押金退还 | 10 |
+| `COMPENSATION` | 赔偿款 | 20 |
+| `CAR_FEE` | 口车费 | 30 |
+| `OTHER` | 其他应收 | 40 |
+
+> 字典加值（如新增一种应收性质）零发版生效，前端读接口即可拿到。
+
+## 七、错误码
+
+无业务错误码。字典加载失败降级为空 List（HTTP 200，对应组 `[]`），不抛错。
+
+## 八、示例
+
+**典型**：
+
+```http
+GET /admin/finance/receipt/options
+Authorization: Bearer <admin-token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "customerPTypes": [
+      { "value": "PERSONAL", "label": "个人客户", "sortOrder": 10 },
+      { "value": "COMPANY", "label": "企业客户", "sortOrder": 20 },
+      { "value": "PEER", "label": "同行客户", "sortOrder": 30 }
+    ],
+    "recvNatures": [
+      { "value": "DEPOSIT_REFUND", "label": "押金退还", "sortOrder": 10 },
+      { "value": "COMPENSATION", "label": "赔偿款", "sortOrder": 20 },
+      { "value": "CAR_FEE", "label": "口车费", "sortOrder": 30 },
+      { "value": "OTHER", "label": "其他应收", "sortOrder": 40 }
+    ]
+  },
+  "success": true
+}
+```
+
+**边界（字典某组全部停用 / 加载失败）**：对应组返回空数组，前端按空下拉处理：
+
+```json
+{ "code": 200, "data": { "customerPTypes": [], "recvNatures": [] }, "success": true }
+```
+
+**异常（未带 / 过期 token）**：网关 401。
+
+## 九、业务边界
+
+- 本接口**只提供下拉选项**，不涉及应收数据的落库、查询、统计——两组值当前不存任何表字段。
+- 仅 ACTIVE 字典行下放；停用行不出现，但历史若有引用不受影响（本期无落库引用）。
+- 后端 5 分钟缓存：运营改字典后最多 5 分钟各实例口径一致。
+
+## 十、修改前后对比
+
+本接口为**新增**，无旧版本。前端的对应变化：
+
+| 项 | 改前（前端写死） | 改后（读接口） |
+|---|---|---|
+| 往来对象分类 | `CUSTOMER_PTYPE_OPTIONS` 中文 value（`'个人客户'`…） | 读 `customerPTypes`，英文码 value（`PERSONAL`…） |
+| 应收性质 | `RECV_NATURE_OPTIONS` 中文 value（`'押金退还'`…） | 读 `recvNatures`，英文码 value（`DEPOSIT_REFUND`…） |
+
+## 十一、影响评估 / 回滚
+
+- **影响面**：纯新增接口 + 新增字典，零存量接口改动、零 DDL、零数据迁移。旧逻辑不受影响。
+- **前端**：本次接口新增不破坏现有页面；但下拉要动态化需前端配套改（见下）。
+- **回滚**：回退 PR #8503 即可；新增字典行可保留（无引用不碍事）或由 DBA 清理。
+
+## 十二、注意事项
+
+- ⚠️ **码值是英文码**（`PERSONAL`/`DEPOSIT_REFUND`…），不是中文。前端若沿用旧写死常量的中文 value 需迁移。
+- ⚠️ 部署后需清字典缓存（迁移脚本注释已含 redis-cli DEL 命令），否则可能读到旧缓存。
+- 字典缓存 5 分钟：前端联调时若刚改字典没看到新值，先等缓存过期或重启服务。
+
+## 十三、关联 / 联系人
+
+- Issue：https://git.1814.love/wx/HL/issues/8501
+- PR：https://git.1814.love/wx/HL/pulls/8503
+- 合并 commit：https://git.1814.love/wx/HL/commit/8f278ec57485f896bf89372cb084fc165a7ac302
+- 负责人：yst（后端）
+
+**前端配套动作**：应收页两组写死常量（`CUSTOMER_PTYPE_OPTIONS` / `RECV_NATURE_OPTIONS`）改为调用 `GET /admin/finance/receipt/options` 动态渲染，码值从中文迁到英文码。