257 行
11 KiB
Markdown
257 行
11 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7662"
|
||
title: "业务外收入 IN 建单去掉入账账户/收付方式/凭证字段，对齐两步资金流程"
|
||
consumer: "admin"
|
||
author: "yst(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "c9588762"
|
||
target_release: ""
|
||
verified_at: "2026-09-14"
|
||
status_note: "入参删字段（fundAccountId/payMethod/voucherNo/voucherUrl），建单不再采集；这 4 个值由出纳「确认收款」confirm-in 采集并回写。前端需把这 4 个字段从「添加收入」表单挪到「确认收款」弹窗。出参（列表 Row/详情 Detail）字段不变。；前端已交付(c9588762):建单/编辑表单删账户凭证 4 字段,确认收款弹窗 5 字段 #7217 已就绪,checkpoint 13 项全绿"
|
||
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）
|