docs(finance): 业务外收入建单去掉账户/凭证字段对齐两步资金流程 changelog（#7662）

入参删 fundAccountId/payMethod/voucherNo/voucherUrl，由出纳 confirm-in 采集；出参不变、零 DDL；前端需把字段从申请页挪到确认收款弹窗。
2026-09-14 12:40:23 +08:00
@@ -0,0 +1,256 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7662"
+title: "业务外收入 IN 建单去掉入账账户/收付方式/凭证字段，对齐两步资金流程"
+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: "入参删字段（fundAccountId/payMethod/voucherNo/voucherUrl），建单不再采集；这 4 个值由出纳「确认收款」confirm-in 采集并回写。前端需把这 4 个字段从「添加收入」表单挪到「确认收款」弹窗。出参（列表 Row/详情 Detail）字段不变。"
+updated_at: "2026-09-14"
+base: "dev-v3"
+---
+
+# 业务外收入 IN 建单去掉入账账户/收付方式/凭证字段（修改接口）
+
+> **服务**: hl-order-service-v3（hl-finance 模块，同进程部署）
+> **PR**: [#7664](https://git.1814.love:8443/wx/HL/pulls/7664)
+> **Issue**: [#7662](https://git.1814.love:8443/wx/HL/issues/7662)
+> **commit**: [7fcea4c029](https://git.1814.love:8443/wx/HL/commit/7fcea4c029)
+> **日期**: 2026-09-14
+> **影响范围**: 业务外收支申请/编辑两个端点的**入参字段集合**（删 4 个）；不涉及路由、出参结构、错误码集合、数据库 DDL
+
+---
+
+## ⚠️ 关键变化
+
+🔴 **建单/编辑不再接收这 4 个字段**（前端须从申请表单移除，挪到出纳确认收款弹窗）：
+
+| 被删入参字段 | 原含义 | 现在的去向 |
+|---|---|---|
+| `fundAccountId` | 入/出账公司账户ID | 出纳确认收款时由 `payAccountId` 采集（写入 `pay_account_id` 列） |
+| `payMethod` | 收付方式 | 出纳确认收款时采集（`CashierConfirmInReqVO.payMethod`） |
+| `voucherNo` | 凭证号 | 出纳确认收款时采集 |
+| `voucherUrl` | 凭证影像 URL | 出纳确认收款时采集 |
+
+🟢 **出参不变**：列表 Row / 详情 Detail 仍透出 `payMethod(+payMethodName)`、`voucherNo`、`voucherUrl`、`fundAccountId`，单据走到 PAID 后由 confirm-in 回写正常显示。**对未确认收款的草稿/待审批单，这 4 个出参字段改后恒为 null**（此前可能带建单时的预填值）。
+
+🟢 **零 DDL**：`fin_nonbiz_flow` 表结构不动，历史 `fund_account_id` 列保留。
+
+---
+
+## 一、背景（前因后果）
+
+业务外收入（IN）原先在**申请建单步**就要求填「入账账户/收付方式/凭证」，但核实发现这是**冗余且语义错位**的：
+
+- **资金只在出纳「确认收款」才动**：建单与批准均不碰资金；只有出纳 `POST /admin/finance/cashier/confirm-in` 才记 `fin_fund_flow` IN + 重算结存 + 回写 PAID。
+- **建单填的入账账户无人读**：建单仅 `setFundAccountId` 存库，全模块无任何读取方；真正动资金用的是 confirm-in 请求里的 `payAccountId`（必填），写入**另一列** `pay_account_id`。建单选 A 账户、出纳确认选 B 账户，系统不校验、不拦。
+- 这导致建单字段沦为纯展示，且与「审批后单独确认收款」的既有流程自相矛盾。
+
+本次把 IN 统一为「申请 → 审批 → **出纳确认收款（动钱）**」两步资金语义，与业务外支出（OUT）的「申请 → 审批 → 出纳付款（动钱）」对称。
+
+## 二、变更清单
+
+| 接口 | 方法+路径 | 变更 |
+|---|---|---|
+| 业务外收支申请（建单） | `POST /admin/finance/nonbiz-flows` | 入参删 `fundAccountId`/`payMethod`/`voucherNo`/`voucherUrl` |
+| 业务外收支编辑 | `PUT /admin/finance/nonbiz-flows/{id}` | 入参删同上 4 字段 |
+
+> 两个端点对 IN / OUT 两个方向同接口；本次删字段对两个方向同时生效（OUT 方向本就不采集这 4 个，删除后契约一致）。
+
+## 三、接口详情
+
+### 3.1 业务外收支申请（建单）
+
+- **方法/路径**：`POST /admin/finance/nonbiz-flows`
+- **权限**：管理后台已登录（网关鉴权）
+- **说明**：创建业务外收入/支出草稿（status=PENDING）
+
+### 3.2 业务外收支编辑
+
+- **方法/路径**：`PUT /admin/finance/nonbiz-flows/{id}`
+- **说明**：编辑草稿单（direction 不可改），入参字段同建单（除无 direction）
+
+## 四、入参
+
+### 修改后（本次生效）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `direction` | string | ✅ 仅建单 | `IN` 业务外收入 / `OUT` 业务外支出 |
+| `category` | string | ✅ | 收支类别码（fin_nonbiz_category 同方向组正常项），≤64 |
+| `unitId` | long | ✅ | 外部单位ID（可付款供应商），JSON 传 number |
+| `operatorId` | long | ✅ | 经办人ID（所选部门下员工），JSON 传 number |
+| `amount` | number | ✅ | 收支金额（>0） |
+| `feeRate` | number | 否 | 手续费率（‰，默认 0；收入页改动自动重算 fee） |
+| `fee` | number | 否 | 手续费（收入缺省按费率算、可手改；支出手填） |
+| `occurDate` | string | ✅ | 发生日期 `yyyy-MM-dd` |
+| `deptId` | long | 否 | 归属部门ID（用户域部门树） |
+| `remark` | string | 否 | 备注，≤200 |
+
+### 已删除（前端勿再传）
+
+| 字段 | 类型 | 原必填 | 删除说明 |
+|---|---|---|---|
+| ~~`fundAccountId`~~ | long | 否 | 改由出纳 confirm-in 的 `payAccountId` 采集 |
+| ~~`payMethod`~~ | string | 否 | 改由出纳 confirm-in 采集 |
+| ~~`voucherNo`~~ | string | 否 | 改由出纳 confirm-in 采集 |
+| ~~`voucherUrl`~~ | string | 否 | 改由出纳 confirm-in 采集 |
+
+> ⚠️ 当前服务对未知 JSON 字段为**忽略**（不报错）：旧前端若仍传这 4 个字段不会 400，但**值会被丢弃、不落库**。请以前端移除字段为准。
+
+## 五、出参
+
+不变。建单/编辑返回 `data.id`（新建单 ID）。
+
+列表 `GET /admin/finance/nonbiz-flows/page` 与详情 `GET /admin/finance/nonbiz-flows/{id}` 仍含 `payMethod`/`payMethodName`/`voucherNo`/`voucherUrl`/`fundAccountId`——单据 PAID 后由 confirm-in 回写正常显示；草稿/待审批态这 4 个字段恒为 null。
+
+## 六、枚举 / 数据字典
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| `direction` | `IN` / `OUT` | 业务外收入 / 业务外支出 |
+| 单据 `status` | `PENDING` / `SUBMITTED` / `APPROVED` / `PAID` / ... | 本次不变；IN 仅经 confirm-in 到 PAID |
+| `payMethod`（confirm-in 时） | 字典 `fin_pay_way`：`CASH`/`BANK_TRANSFER`/`WECHAT`/`ALIPAY` | 出纳确认收款时采集 |
+
+## 七、错误码
+
+| 码 | 含义 | 触发 |
+|---|---|---|
+| 598501 | 金额有效性 | amount≤0 / fee<0 / actualAmount<0 |
+| 598502 | 类别归属方向组且正常 | category 非法 |
+| 598506 | 方向合法 | direction 非 IN/OUT |
+| 598510 | 单号撞号重试耗尽 | 极端并发 |
+
+（本次未新增/变更错误码）
+
+## 八、示例
+
+### 8.1 典型：建 IN 收入单（不再传账户/凭证）
+
+```http
+POST /admin/finance/nonbiz-flows
+Content-Type: application/json
+
+{
+  "direction": "IN",
+  "category": "AGENT_SALARY",
+  "unitId": 2097974318146146305,
+  "operatorId": 1001,
+  "amount": 500,
+  "feeRate": 0,
+  "occurDate": "2026-09-14",
+  "deptId": 33,
+  "remark": "代收工资"
+}
+```
+
+响应：
+
+```json
+{ "code": 200, "message": "成功", "data": { "id": "2099329937876934657" }, "success": true }
+```
+
+建单后详情（4 字段恒 null）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": "2099329937876934657", "flowNo": "WS-20260914-0001",
+    "direction": "IN", "status": "PENDING",
+    "amount": 500.0, "fee": 0.0, "actualAmount": 500.0,
+    "fundAccountId": null, "payMethod": null, "voucherNo": null, "voucherUrl": null
+  },
+  "success": true
+}
+```
+
+### 8.2 边界：仍传已删字段（被忽略，不报错也不落库）
+
+```http
+POST /admin/finance/nonbiz-flows
+{ "direction":"IN","category":"AGENT_SALARY","unitId":2097974318146146305,"operatorId":1001,
+  "amount":500,"occurDate":"2026-09-14",
+  "fundAccountId":999999,"payMethod":"WECHAT","voucherNo":"V001","voucherUrl":"http://x/y.png" }
+```
+
+响应 200 正常建单，但详情里这 4 字段**仍为 null**（值被丢弃）。
+
+### 8.3 异常：缺必填
+
+```http
+POST /admin/finance/nonbiz-flows
+{ "direction":"IN","category":"AGENT_SALARY","amount":500,"occurDate":"2026-09-14" }
+```
+
+```json
+{ "code": 400, "message": "请求数据格式错误，请检查参数是否正确", "success": false }
+```
+
+（缺 `unitId`/`operatorId` 等 @NotNull 字段）
+
+### 8.4 资金确认入口（不变，供前端对齐）：出纳确认收款
+
+```http
+POST /admin/finance/cashier/confirm-in
+Content-Type: application/json
+
+{
+  "bizId": 2099329937876934657,
+  "payAccountId": 123,
+  "payMethod": "BANK_TRANSFER",
+  "voucherNo": "V2026-0914-01",
+  "voucherUrl": "https://oss/...png",
+  "payDate": "2026-09-14"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `bizId` | long | ✅ | 业务单据ID（direction=IN 且 status=APPROVED） |
+| `payAccountId` | long | ✅ | 入账公司账户ID（fin_fund_account，须 ACTIVE） |
+| `payMethod` | string | 否 | 收款方式（fin_pay_way 码值） |
+| `voucherNo` | string | 否 | 收款凭证号 |
+| `voucherUrl` | string | 否 | 收款凭证影像 URL |
+| `payDate` | string | ✅ | 收款日期 `yyyy-MM-dd` |
+
+## 九、业务边界
+
+- IN 单据只能在 status=APPROVED 后经 confirm-in 到 PAID（唯一资金确认入口），批准本身不动资金。
+- 建单/编辑阶段不再采集账户与凭证；账户/方式/凭证由出纳在 confirm-in 一次性采集并回写。
+- OUT 方向本就由出纳「登记付款」采集，本次删字段后 IN/OUT 建单侧契约一致。
+
+## 十、修改前后对比
+
+| 维度 | 修改前 | 修改后 |
+|---|---|---|
+| 建单入参字段数 | 14（含 4 个无效字段） | 10 |
+| 建单是否采集账户/凭证 | 采集（但无人读） | 不采集 |
+| 资金动作时机 | 建单填账户但不动钱、confirm-in 再选账户（重复） | 仅 confirm-in 选账户并动钱 |
+| 草稿态 4 字段出参 | 可能带建单预填值 | 恒 null，PAID 后由 confirm-in 回写 |
+
+## 十一、影响评估 / 回滚
+
+- **影响**：前端「添加收入」「编辑收入」表单需删除 收款账号/凭证号/收款凭证 3 项；「确认收款」弹窗需补 入账账户*/收款方式/凭证号/凭证/收款日期*（confirm-in 入参）。原型已同步（PR #7665）。
+- **兼容性**：旧前端仍传 4 字段不会报错（被忽略），但语义已变，请尽快移除。
+- **回滚**：回滚本 PR 即恢复旧入参；无 DDL、无数据迁移，回滚安全。
+
+## 十二、注意事项
+
+- JSON 中 `unitId`/`operatorId`/`deptId`/`payAccountId`/`bizId` 等 Long 字段**传 number**（不要加引号传字符串），否则 400「请求数据格式错误」。
+- 出参中 Long 已序列化为字符串（防 JS 精度丢失），前端按 string 读。
+
+## 十三、关联 / 联系人
+
+- Issue: [#7662](https://git.1814.love:8443/wx/HL/issues/7662)
+- PR（后端）: [#7664](https://git.1814.love:8443/wx/HL/pulls/7664) · commit [7fcea4c029](https://git.1814.love:8443/wx/HL/commit/7fcea4c029)
+- PR（原型同步）: [#7665](https://git.1814.love:8443/wx/HL/pulls/7665)
+- 关联 Issue（OUT 手续费，原型侧）: [#7663](https://git.1814.love:8443/wx/HL/issues/7663)
+- 负责人: 腰苏图（yst）