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

业务外收入 IN 建单去掉入账账户/收付方式/凭证字段（修改接口）

服务: hl-order-service-v3（hl-finance 模块，同进程部署） PR: #7664 Issue: #7662 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 收入单（不再传账户/凭证）

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": "代收工资"
}

响应：

{ "code": 200, "message": "成功", "data": { "id": "2099329937876934657" }, "success": true }

建单后详情（4 字段恒 null）：

{
  "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 边界：仍传已删字段（被忽略，不报错也不落库）

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 异常：缺必填

POST /admin/finance/nonbiz-flows
{ "direction":"IN","category":"AGENT_SALARY","amount":500,"occurDate":"2026-09-14" }

{ "code": 400, "message": "请求数据格式错误，请检查参数是否正确", "success": false }

（缺 unitId/operatorId 等 @NotNull 字段）

8.4 资金确认入口（不变，供前端对齐）：出纳确认收款

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
• PR（后端）: #7664 · commit 7fcea4c029
• PR（原型同步）: #7665
• 关联 Issue（OUT 手续费，原型侧）: #7663
• 负责人: 腰苏图（yst）