From 97056b0370201418fcde062864b9ab8dc03c4ca3 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Sun, 4 Oct 2026 10:22:06 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=208768=20=E8=B5=84=E9=87=91?=
 =?UTF-8?q?=E8=B4=A6=E6=88=B7=E7=9B=98=E7=9B=88=E7=9B=98=E4=BA=8F=E6=95=B4?=
 =?UTF-8?q?=E5=8A=9F=E8=83=BD=E4=B8=8B=E7=BA=BF=EF=BC=88inventory-adjust?=
 =?UTF-8?q?=20=E5=88=A0=E9=99=A4=20+=20INVENTORY=20=E6=9E=9A=E4=B8=BE?=
 =?UTF-8?q?=E5=88=A0=E9=99=A4=EF=BC=8C=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- POST /admin/finance/fund-accounts/{id}/inventory-adjust 已删，调用一律 404
- 资金流水 bizType 枚举删 INVENTORY（历史残留行 bizTypeName 返 null）
- 错误码 595106 废弃（码位保留不重发）
- 关联：Issue #8768 / PR #8773（代码）/ PR #8781（原型+文档）
---
 ..._资金账户盘盈盘亏下线-删除接口-管理后台.md | 331 ++++++++++++++++++
 1 file changed, 331 insertions(+)
 create mode 100644 changelogs-v2/2026-10/04_8768_资金账户盘盈盘亏下线-删除接口-管理后台.md

diff --git a/changelogs-v2/2026-10/04_8768_资金账户盘盈盘亏下线-删除接口-管理后台.md b/changelogs-v2/2026-10/04_8768_资金账户盘盈盘亏下线-删除接口-管理后台.md
new file mode 100644
index 00000000..08b1dcef
--- /dev/null
+++ b/changelogs-v2/2026-10/04_8768_资金账户盘盈盘亏下线-删除接口-管理后台.md
@@ -0,0 +1,331 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8768"
+title: "资金账户盘盈盘亏整功能下线（inventory-adjust 接口删除 + INVENTORY 业务类型枚举删除）"
+consumer: "admin"
+author: "yst"
+change_type: "删除接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "hl-admin"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-10-04"
+updated_at: "2026-10-04"
+base: "dev-v3"
+status_note: "后端已合 dev-v3（PR #8773 代码 + PR #8781 原型/文档）并部署测试服。盘盈盘亏属无审批直接轧平账户结存=资金挪用通道，整功能删除；账户差异改走对账补记具体业务流水。"
+---
+
+# 【删除接口·管理后台】资金账户盘盈盘亏整功能下线 (#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（路由不存在）。
+
+**请求**：
+```http
+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
+HTTP/1.1 404 Not Found
+```
+
+（网关 / 服务路由无该端点，返回 404，无业务响应体。）
+
+### 8.2 边界：bizType 传 INVENTORY 筛选 → 仅命中库中历史残留行
+
+**场景说明**：`bizType` 筛选为字符串等值匹配、不做枚举合法性校验。传 `INVENTORY` 不报错、不拒绝，仍按 biz_type 等值过滤，可捞出库中残留的历史盘盈盘亏流水；但不会再产生任何新 INVENTORY 流水。
+
+**请求**：
+```http
+GET /admin/finance/fund-flows/page?page=1&pageSize=20&bizType=INVENTORY HTTP/1.1
+Authorization: Bearer <管理后台JWT>
+```
+
+（无请求体）
+
+**响应**：
+```json
+{
+  "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。
+
+**请求**：
+```http
+POST /admin/finance/fund-accounts/1234567890/inventory-adjust HTTP/1.1
+Authorization: Bearer <管理后台JWT>
+Content-Type: application/json
+
+{
+  "direction": "INVALID",
+  "amount": -1,
+  "reason": ""
+}
+```
+
+**响应**：
+```http
+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](https://git.1814.love/wx/HL/issues/8768)
+- **PR（代码）**: [#8773](https://git.1814.love/wx/HL/pulls/8773)
+- **PR（原型+文档）**: [#8781](https://git.1814.love/wx/HL/pulls/8781)
+- **Merge commit（代码）**: [669f84bd3b](https://git.1814.love/wx/HL/commit/669f84bd3b5fdd532a1d7817dd69db8141119013)
+- **Merge commit（文档）**: [df99bfedfd](https://git.1814.love/wx/HL/commit/df99bfedfd)
+
+### 13.2 联系人
+
+- **后端负责人**: @yst（腰苏图）