---
schema: "hl-changelog/v2"
ticket: "8501"
title: "应收往来对象分类/应收性质两组下拉字典化，新增 /receipt/options 接口供前端动态读取"
consumer: "admin"
author: "yst(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "49a3bb6c5c92e405aee7c4a4ceb275d10b2f6d63"
target_release: "v2.1"
verified_at: "2026-09-29"
status_note: "应收页「往来对象分类」「应收性质」两组下拉此前前端写死常量、后端无字典无接口，加值须改前端发版。本次纯字典化（不落库不加列）：新增 2 个财务字典 + GET /admin/finance/receipt/options 接口，测试环境网关已实测返回两组 ACTIVE 下拉。前端需把两组写死常量改读本接口，码值从中文 value 迁英文码。；前端 2026-09-29 已交付：grep 实证两写死中文常量零消费点(应收新增表单尚未建)，删死常量留防回加注释，新增 getReceiptOptions 客户端(英文码 value/ACTIVE 升序/5 分钟缓存/字典失败降级空数组)，receipt api spec 3 例全绿"
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` 动态渲染，码值从中文迁到英文码。