hl-api-changelog/changelogs-v2/2026-09/29_8501_应收往来对象分类与应收性质下拉字典化-新增接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

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

八、示例

典型：

GET /admin/finance/receipt/options
Authorization: Bearer <admin-token>

{
  "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
}

边界（字典某组全部停用 / 加载失败）：对应组返回空数组，前端按空下拉处理：

{ "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：wx/HL#8501
• PR：wx/HL#8503
• 合并 commit：8f278ec574
• 负责人：yst（后端）

前端配套动作：应收页两组写死常量（CUSTOMER_PTYPE_OPTIONS / RECV_NATURE_OPTIONS）改为调用 GET /admin/finance/receipt/options 动态渲染，码值从中文迁到英文码。