hl-api-changelog/changelogs-v2/2026-10/04_8768_资金账户盘盈盘亏下线-删除接口-管理后台.md

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

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	updated_at	base	status_note
hl-changelog/v2	8768	资金账户盘盈盘亏整功能下线（inventory-adjust 接口删除 + INVENTORY 业务类型枚举删除）	admin	yst	删除接口	deployed	verified	implemented	mmg	837eb9659e1e1dabc187ef76adac5e79e65d71d3	v2.1	2026-10-04	2026-10-04	dev-v3	后端已合 dev-v3（PR #8773 代码 + PR #8781 原型/文档）并部署测试服。盘盈盘亏属无审批直接轧平账户结存=资金挪用通道，整功能删除；账户差异改走对账补记具体业务流水。前端已交付(2026-10-04):删盘盈盘亏弹窗与 API 封装、账户页去操作按钮、业务类型筛选下拉排除 INVENTORY(流水页与日明细抽屉两处),历史残留行 bizTypeName=null 回退本地 map 显「盘盈盘亏」,提交 837eb9659。

【删除接口·管理后台】资金账户盘盈盘亏整功能下线 (#8768)

PR: #8773（代码）/ #8781（原型+文档） | 服务: hl-order-service-v3（finance 域同进程） | 更新时间: 2026-10-04

1. 接口背景

「盘盈盘亏」功能允许在资金账户上无审批直接提交一笔差额流水轧平账户结存（盘盈补收 IN / 盘亏补付 OUT），属于资金挪用通道：任何人都可以一句话把账面结存改成任意值，不留业务依据。同时银行账户 / 现金账本的差异本不该用库存盘点语义处理。

因此整功能下线删除：账户差异改走「对账找原因 → 补记具体业务流水」路径，不允许直接轧平。删除范围 = 1 个写接口 + 1 个业务类型枚举值 + 1 个错误码 + 2 个请求/响应 VO + 1 个方向枚举。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	盘盈盘亏	POST	/admin/finance/fund-accounts/{id}/inventory-adjust	⚠️ 删除	接口已删，调用一律 404
2	资金明细分页	GET	/admin/finance/fund-flows/page	🔧 行为变更	bizType 筛选项删除 INVENTORY（业务类型枚举删该值），不再会产生新的 INVENTORY 流水
3	错误码 595106	—	—	⚠️ 废弃	INVENTORY_DIRECTION_INVALID 随功能删除，码位保留不重发

配套删除（前端不可见但供完整性说明）：请求 VO InventoryAdjustReqVO、响应 VO InventoryAdjustRespVO、方向枚举 InventoryDirectionEnum（SURPLUS/DEFICIT）、业务类型枚举值 FundFlowBizTypeEnum.INVENTORY。

3. 接口详情

3.1 盘盈盘亏（已删除）

• 方法 + 路径：POST /admin/finance/fund-accounts/{id}/inventory-adjust
• 接口描述（删除前）：盘盈盘亏（提交即记一笔资金流水轧平该账户结存：盘盈补收 IN / 盘亏补付 OUT）
• 认证：管理后台 JWT
• 幂等性（删除前）：有幂等键（账户ID + direction + amount，5 秒窗口）；删除后无意义
• 现状：接口已删除，任何调用一律返回 404

3.2 资金明细分页（bizType 筛选项变化）

• 方法 + 路径：GET /admin/finance/fund-flows/page
• 接口描述：资金流水分页查询（账户台账 / 资金明细页数据源）
• 认证：管理后台 JWT
• 变化点：query 参数 bizType 的业务类型可选值集合中删除 INVENTORY（盘盈盘亏）。该筛选为字符串等值匹配，不做枚举合法性校验——传 INVENTORY 不报错，仍可捞出库中残留的历史 INVENTORY 流水；但不会再有任何新 INVENTORY 流水产生

4. 接口入参

4.1 盘盈盘亏请求体（已随接口删除，仅存档备查）

POST /admin/finance/fund-accounts/{id}/inventory-adjust

路径参数：

字段	类型	必填	说明
id	Long	✅	账户 ID

请求体字段（InventoryAdjustReqVO，已删除）：

字段	类型	必填	说明	校验规则
direction	String	✅	方向：SURPLUS 盘盈（补收）/ DEFICIT 盘亏（补付）	仅 SURPLUS/DEFICIT，否则 595106
amount	BigDecimal	✅	差额金额	须 > 0，否则 595102
reason	String	✅	原因（进留痕）	长度 ≤ 200
voucherUrl	String	❌	佐证影像	长度 ≤ 500

4.2 资金明细分页 query 参数（bizType 说明变化）

GET /admin/finance/fund-flows/page

字段	类型	必填	说明
bizType	String	❌	业务类型筛选。变更后可选值：PAYMENT / PREPAY / EXPENSE / REIMBURSE / RECEIPT / STAFF_LOAN / COMPANY_LOAN / NONBIZ / ADVANCE / TRANSFER / ORDER_PAY / ORDER_REFUND / OPENING。INVENTORY 已从可选值中删除

其余 query 参数（page / pageSize / fundAccountId / accountType / direction / bizId / flowNo / flowAtStart / flowAtEnd）无变化。

5. 出参（响应）

5.1 盘盈盘亏响应（已随接口删除，仅存档备查）

InventoryAdjustRespVO（已删除）：

字段	类型	说明
fundFlowId	String（Long 序列化为字符串）	生成的资金流水 ID
balanceAfter	BigDecimal	调后结存

5.2 资金明细分页行（历史 INVENTORY 行的展示变化）

FundFlowRowRespVO 字段结构无增删，仅历史残留数据的取值变化：

字段	类型	说明	本次变化
id	String	流水 ID	—
flowNo	String	流水号	—
fundAccountId	String	账户 ID	—
accountName	String	账户名称	—
accountType	String	账户类型：BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL	—
direction	String	方向：OUT / IN	—
amount	BigDecimal	金额	—
bizType	String	业务类型码值	⚠️ 历史残留行可能为 INVENTORY（不会再有新行）
bizTypeName	String 或 null	业务类型中文名	⚠️ 历史 INVENTORY 行该字段为 null（枚举值已删，解析不到）；其余业务类型正常返回中文名
bizId	String 或 null	关联业务单据 ID	—
bizNo	String 或 null	业务单据号	—
balanceAfter	BigDecimal	本笔记完后账户结存快照	—
transferGroupId	String 或 null	互转成对组号（仅 TRANSFER）	—
fee	BigDecimal 或 null	手续费（仅 TRANSFER，挂转出行）	—
counterparty	String 或 null	对方户名（展示层脱敏）	—
flowAt	String	收付时间	—
voucherUrl	String 或 null	回单凭证影像	—
remark	String 或 null	备注（互转备注 / 期初调整原因）	—

流水详情接口 GET /admin/finance/fund-flows/{flowId} 的 bizTypeName 口径同列表：历史 INVENTORY 行返回 null。

6. 枚举 / 数据字典

6.1 direction（InventoryDirectionEnum，已删除）

所属字段：InventoryAdjustReqVO.direction | 类型：String | 必填：✅（删除前）

值	中文	说明
SURPLUS	盘盈	实存多于账面 → 记 IN 流水增结存（补收）
DEFICIT	盘亏	实存少于账面 → 记 OUT 流水减结存（补付）

枚举已随功能整体删除，无任何现存接口使用。

6.2 bizType（FundFlowBizTypeEnum）

所属字段：FundFlowPageReqVO.bizType（入参筛选）/ FundFlowRowRespVO.bizType + bizTypeName（出参） | 类型：String

变更后值表（INVENTORY 已删除）：

值	中文	说明
PAYMENT	应付款付款	—
PREPAY	预付款	—
EXPENSE	费用报销	—
REIMBURSE	报账	—
RECEIPT	收款	—
STAFF_LOAN	员工借款	—
COMPANY_LOAN	公司借款	—
NONBIZ	非业务收支	—
ADVANCE	订单预支	—
TRANSFER	账户互转	成对记，不算对外收支
ORDER_PAY	对公收款	订单支付自动生成，不经出纳
ORDER_REFUND	订单退款	自动生成，不经出纳
OPENING	期初调整	仅审计留痕，不计净影响

已删除值：INVENTORY（盘盈盘亏，#8768 下线）。库中历史残留行 bizType 仍为该值，bizTypeName 返回 null。

7. 错误码

code	含义	触发场景	本次变化
595106	盘盈盘亏方向无效（须 SURPLUS/DEFICIT）	删除前 inventory-adjust 的 direction 非法	⚠️ 已废弃（码位保留不重发，防码值复用歧义；不会再有任何接口返回该码）
595102	金额无效（须大于0）	互转金额 ≤ 0	语义不变（不再覆盖盘盈盘亏场景）

8. 示例（3 组：典型 / 边界 / 异常）

8.1 典型：调旧 inventory-adjust 路径 → 404

场景说明：旧路径已删除，任何调用一律 404（路由不存在）。

请求：

POST /admin/finance/fund-accounts/1234567890/inventory-adjust HTTP/1.1
Authorization: Bearer <管理后台JWT>
Content-Type: application/json

{
  "direction": "SURPLUS",
  "amount": 100.00,
  "reason": "月末现金盘点多出100元",
  "voucherUrl": "https://oss.example.com/voucher/xxx.jpg"
}

响应：

HTTP/1.1 404 Not Found

（网关 / 服务路由无该端点，返回 404，无业务响应体。）

8.2 边界：bizType 传 INVENTORY 筛选 → 仅命中库中历史残留行

场景说明：bizType 筛选为字符串等值匹配、不做枚举合法性校验。传 INVENTORY 不报错、不拒绝，仍按 biz_type 等值过滤，可捞出库中残留的历史盘盈盘亏流水；但不会再产生任何新 INVENTORY 流水。

请求：

GET /admin/finance/fund-flows/page?page=1&pageSize=20&bizType=INVENTORY HTTP/1.1
Authorization: Bearer <管理后台JWT>

（无请求体）

响应：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": "9876543210987654321",
        "flowNo": "LS20260915000042",
        "fundAccountId": "1234567890",
        "accountName": "基本户-工行",
        "accountType": "BANK",
        "direction": "IN",
        "amount": 100.00,
        "bizType": "INVENTORY",
        "bizTypeName": null,
        "bizId": null,
        "bizNo": null,
        "balanceAfter": 50100.00,
        "transferGroupId": null,
        "fee": null,
        "counterparty": null,
        "flowAt": "2026-09-15 10:30:00",
        "voucherUrl": "https://oss.example.com/voucher/xxx.jpg",
        "remark": "月末现金盘点多出100元"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "message": "ok",
  "success": true
}

注意示例中 bizTypeName 为 null（历史行枚举值已删，解析不到中文名）。

8.3 业务失败：本功能已删除，无业务错误码场景

场景说明：盘盈盘亏功能整体删除后，原 595106 INVENTORY_DIRECTION_INVALID 错误码不会再由任何接口返回。对该功能的唯一「失败」表现就是 8.1 的 404。

请求：

POST /admin/finance/fund-accounts/1234567890/inventory-adjust HTTP/1.1
Authorization: Bearer <管理后台JWT>
Content-Type: application/json

{
  "direction": "INVALID",
  "amount": -1,
  "reason": ""
}

响应：

HTTP/1.1 404 Not Found

（不再进入参数校验，直接 404。）

9. 业务边界

• ❌ 不再适用：资金账户上的任何「盘点轧平」操作——该入口已彻底移除
• ✅ 替代路径：账户账面与实际有差异时，走对账定位差异原因，再补记具体业务类型的流水（收款 / 费用 / 非业务收支等），不允许无业务依据直接轧平
• ⚠️ 历史数据：库中存量 INVENTORY 流水保留不删，流水列表 / 详情仍可查到；这些历史行的 bizTypeName 为 null，流水列表对该字段做判空展示即可
• ⚠️ 筛选兼容：bizType=INVENTORY 作为 query 筛选传入不报错（字符串等值匹配），但属于已废弃值，筛选下拉中应移除该选项

10. 修改前后对比

10.1 字段级对比

字段	改前	改后
FundFlowPageReqVO.bizType 可选值	13 个值（含 INVENTORY）	12 个值（删 INVENTORY）
FundFlowRowRespVO.bizTypeName（历史 INVENTORY 行）	盘盈盘亏	null（枚举已删，解析不到）
FundFlowDetailRespVO.bizTypeName（历史 INVENTORY 行）	盘盈盘亏	null（同上）
错误码 595106	有效（direction 非法时返回）	废弃，不再返回（码位保留不重发）

10.2 行为级对比

行为	改前	改后
POST /admin/finance/fund-accounts/{id}/inventory-adjust	正常受理：记一笔 INVENTORY 流水轧平结存，返回 fundFlowId + balanceAfter	接口已删，调用一律 404
账户差异处理	可直接盘盈盘亏轧平	只能对账找原因 → 补记具体业务流水
流水列表 bizType 筛选下拉	含「盘盈盘亏」选项	应移除「盘盈盘亏」选项（传值不报错但仅命中历史残留）

11. 影响评估 / 回滚

11.1 影响评估

• 是否破坏向后兼容：是。写接口直接删除（404），属破坏性变更
• 前端是否必须同步上线：是。资金账户页「盘盈盘亏」入口（按钮 + 弹窗）与资金明细筛选下拉的「盘盈盘亏」选项已失去对应接口，必须随本变更移除；流水列表 bizTypeName 需判空展示（历史 INVENTORY 行为 null）
• 影响已有数据：库中历史 INVENTORY 流水保留，无需数据迁移

11.2 回滚方案

• 回滚方式：revert PR #8773（后端代码）可恢复接口
• 回滚后清理：无脏数据（下线期间不可能产生新 INVENTORY 流水，接口已 404）
• 前后端同步：若后端回滚而前端已删入口，需前端同步恢复；建议前后端同批上线 / 回滚

12. 注意事项

• 旧路径已删，调用一律 404：前端如仍残留 inventory-adjust 调用点必须全部移除，否则用户操作直接报 404
• bizTypeName 判空：流水列表 / 详情渲染 bizTypeName 时，历史 INVENTORY 行该字段为 null，请判空展示（如显示空白或「-」），不要按非空字符串处理
• bizType 筛选不做枚举校验：后端按字符串等值匹配，传 INVENTORY 不报错，仅命中历史残留行；筛选下拉请以后端现行 12 个值为准
• 原盘盈盘亏弹窗里的「佐证影像上传」「方向选择 SURPLUS/DEFICIT」相关逻辑已失去对应接口
• 如前端曾对 595106 错误码做过特判提示，该特判分支已不会触发（该码不会再返回）

13. 关联 / 联系人

13.1 链接

• Issue: #8768
• PR（代码）: #8773
• PR（原型+文档）: #8781
• Merge commit（代码）: 669f84bd3b
• Merge commit（文档）: df99bfedfd

13.2 联系人

• 后端负责人: @yst（腰苏图）