文件

T

changelog-filename-gate / validate (push) Failing after 2s

详情

feat(finance): 往来账财务调账5端点 changelog（#8699）

新增 /admin/finance/adjusts 5 端点：TZ调账单+页内审批+应收/应付入账联动。

2026-10-02 09:57:09 +08:00

10 KiB

原始文件 Blame 文件历史

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	8699	往来账·财务调账——调账单(TZ)+页内审批+应收/应付入账联动（#8699）	admin	yst(GIT)	新增接口	deployed	not_required	pending			v2.1	2026-10-02	往来账「财务调账」（SRS 3.6.2，原型 fin-adjust）后端落地，原标二期提前本期实现。新增 /admin/finance/adjusts 5 端点：新建调账单(TZ-单号)/分页/详情/批准/驳回。挂团+改单团利润的应收/应付跨团调整集中口，金额正=调增/负=红字冲减，批准后顺数据流写台账、全留痕不删原记录、不动账户结存。应付侧写 fin_payable_line 调账行（可继续走付款申请），应收侧改 order-v3 查询叠加让应收台账数字真实变化（B 方案）。审批=页内单步批准/驳回（企微多级后期统一接）；改单团利润只留痕标记；阈值 FINADJUST_APPROVE_MIN 从后端参数读取回传提示。部署测试服行为级验证全过：应收叠加 receivable 5360→5860(+500)精确、应付调增/调减、不挂团占位 UNGROUPED、驳回、596110/596103/596102 校验全对。	2026-10-02	dev-v3

finance：往来账·财务调账——调账单(TZ)+页内审批+应收/应付入账联动（管理后台）

✅ additive 纯新增接口组：新增 /admin/finance/adjusts 5 端点，旧前端不受影响。

1. 接口背景

往来账「财务调账」是挂团 + 改单团利润的应收/应付跨团调整集中口，调账单号 TZ 前缀。用于账对不上时的差异平账：金额正=调增 / 负=红字冲减，批准后顺数据流写入应付款 / 应收台账，全留痕不删原记录、不动账户结存。

此前仅有原型 + 设计稿（SRS 标二期），后端零实现。本期落地完整后端：调账单 CRUD + 页内审批 + 应收/应付入账联动。

2. 变更清单

#	接口	变更	类型
1	POST /admin/finance/adjusts	新建调账单（生成 TZ 单号，PENDING）	✅ 新增
2	GET /admin/finance/adjusts/page	调账单分页（kw/target/status 筛选）	✅ 新增
3	GET /admin/finance/adjusts/{id}	调账单详情（含审批留痕 + 多级提示标记）	✅ 新增
4	POST /admin/finance/adjusts/{id}/approve	批准 → 入账联动 → POSTED	✅ 新增
5	POST /admin/finance/adjusts/{id}/reject	驳回 → REJECTED	✅ 新增

3. 接口详情

统一前缀 POST/GET /admin/finance/adjusts/**（业务调用不带服务前缀，网关按 /admin/finance/** 路由到 order-v3）。

4. 入参

4.1 新建调账单（POST /）

参数	类型	必填	说明
adjustTarget	String	是	`RECEIVABLE` 应收 / `PAYABLE` 应付
partyId	Long	否	单位ID（应付=供应商ID / 应收=客户ID）
partyName	String	是	单位名称（快照）
teamNo	String	见说明	团号。应收：与 orderId 至少填一个（否则 596110）；应付：可空（空则入账占位 UNGROUPED）
orderId	Long	见说明	订单ID（应收订单级定位；应付可空）
amount	BigDecimal	是	调账金额（正=调增 / 负=红字冲减，禁 0 否则 596103）
accountPeriod	Date	是	插入账期（yyyy-MM-dd；批准时校验未封账否则 596104）
profitFlag	Boolean	是	是否改单团利润（true=修改 / false=不修改，只留痕标记，不跨域回写）
remark	String	是	备注（调账原因/依据）

4.2 分页（GET /page）

参数	说明
pageNo / pageSize	分页
kw	关键词（模糊调账单号/单位名/团号）
adjustTarget	`RECEIVABLE` / `PAYABLE` 精确筛选
status	`PENDING` / `POSTED` / `REJECTED` 精确筛选

4.3 批准 / 驳回（POST /{id}/approve | /{id}/reject）

参数	类型	必填	说明
opinion	String	驳回必填	审批意见（批准可空 / 驳回必填否则 596109）

5. 出参

5.1 调账单行（AdjustRowRespVO）/ 详情（AdjustDetailRespVO）

字段	类型	说明
id	Long(string)	调账单ID
adjustNo	String	调账单号（TZ-yyyyMMddNNNN）
adjustTarget	String	RECEIVABLE / PAYABLE
partyId / partyName	Long(string) / String	单位
teamNo	String	团号（可空）
orderId	Long(string)	订单ID（可空）
amount	BigDecimal	调账金额（带符号）
accountPeriod	Date	插入账期
profitFlag	Boolean	是否改单团利润
remark	String	备注
status	String	PENDING / POSTED / REJECTED
postedFlow	String	入账关联流水描述（批准后回填，如「应付款·某供应商·某团」「应收台账·26-2827」）
reviewByName / reviewTime / reviewRemark		审批最终态
createTime	LocalDateTime	创建时间

详情额外：

字段	说明
needMultiLevelApprove	Boolean：金额绝对值 ≥ 后端参数 `FINADJUST_APPROVE_MIN`（默认 5000）时为 true，前端据此提示「需多级审批」（本期后端仍单步批准，仅提示）
reviewLogs	审批留痕列表（action/operatorName/opinion/fromStatus/toStatus/createTime）

5.2 批准 / 驳回响应（AdjustReviewRespVO）

字段	说明
status	操作后状态（POSTED / REJECTED）
postedFlow	入账关联流水（批准时）
needMultiLevelApprove	多级审批提示标记（批准时）

6. 枚举/数据字典

adjustTarget（调整目标）

值	含义
RECEIVABLE	应收（客户侧）
PAYABLE	应付（供应商侧）

status（调账单状态）

值	含义
PENDING	待审批
POSTED	已入账（批准生效）
REJECTED	已驳回

7. 错误码

错误码	含义	触发
596101	调账单不存在	id 不存在/已软删
596102	调账单非待审批状态，不可操作	对已 POSTED/REJECTED 单再批准/驳回
596103	调账金额不允许为 0	amount=0
596104	插入账期已封账	accountPeriod 落已封账期/无开账期
596105	调整目标非法	adjustTarget 非 RECEIVABLE/PAYABLE
596106	单位缺失	partyName 空
596107	调账单号生成冲突	TZ 取号撞号重试耗尽（重试即可）
596109	驳回原因不能为空	驳回未填 opinion
596110	应收调账必须挂团或挂订单	RECEIVABLE 且 teamNo/orderId 双空

8. 示例

8.1 典型：新建应收调账单（挂订单 +500）→ 批准

POST /admin/finance/adjusts
{"adjustTarget":"RECEIVABLE","partyName":"宋家辉","teamNo":"26-2827","orderId":2105709330353520641,
 "amount":500,"accountPeriod":"2026-10-02","profitFlag":false,"remark":"尾款差额补差"}
→ 200 {"id":"2105837196957446145","adjustNo":"TZ-202610020001","status":"PENDING",...}

POST /admin/finance/adjusts/2105837196957446145/approve {"opinion":"同意"}
→ 200 {"status":"POSTED","postedFlow":"应收台账·26-2827","needMultiLevelApprove":false}
# 效果：该订单应收台账 receivableAmount 5360→5860（+500）、balanceAmount 0→500

8.2 应付调增（挂团 +300）

POST /admin/finance/adjusts
{"adjustTarget":"PAYABLE","partyName":"草原行车队","teamNo":"26-8875","amount":300,
 "accountPeriod":"2026-10-02","profitFlag":true,"remark":"包车加班费补差"}
→ 批准后 postedFlow="应付款·草原行车队·26-8875"
# 效果：fin_payable_line 追加调增行，可继续走付款申请/审批/出纳

8.3 应付调减不挂团（-100）→ 占位 UNGROUPED

POST /admin/finance/adjusts
{"adjustTarget":"PAYABLE","partyName":"某供应商","amount":-100,
 "accountPeriod":"2026-10-02","profitFlag":false,"remark":"多付红字冲减"}
→ 批准后 postedFlow="应付款·某供应商·UNGROUPED"
# 效果：fin_payable_line 追加 REDUCE 负向行；不挂团时团号占位 UNGROUPED

8.4 异常：应收双空

POST /admin/finance/adjusts
{"adjustTarget":"RECEIVABLE","partyName":"某客户","amount":50,
 "accountPeriod":"2026-10-02","profitFlag":false,"remark":"x"}
→ {"code":596110,"message":"应收调账必须挂团或挂订单","success":false}

9. 业务边界

应付侧：调账行写入 fin_payable_line（来源 FIN_ADJUST），进应付款「按团号/按供应商」列表，可继续走付款申请/审批/出纳支付；不挂团时团号占位 UNGROUPED，会在按团列表出现一个 UNGROUPED 行，前端可识别该值显示「不挂团」。
应收侧：调账不写新表行，由 order-v3 查询时实时叠加进应收台账数字（receivableAmount + balanceAmount）。挂订单按订单级叠加、挂团（order_id 空）按团维度叠加；负调账超额时 balanceAmount 可为负（负值即「冲多了」信号，前端原样展示，不兜底）。
改单团利润 profitFlag 仅留痕标记，后端不跨域回写订单/团利润。
阈值：needMultiLevelApprove 仅提示，本期后端仍单步批准；企微多级审批后期统一接。
全留痕不删原记录，审批轨迹进 reviewLogs。

10. 修改前后对比

新增接口组，无「修改前」。

11. 影响评估/回滚

additive 纯新增，旧前端零影响。
回滚：删除调账域代码 + DROP fin_adjust/fin_adjust_review_log 即可（涉 DDL 回滚需谨慎，建议保留表只回滚代码）。

12. 注意事项

Long 型 ID 全部是 string，前端勿按 number 解析。
应收调账必须挂团或挂订单（596110），否则静默不进台账——前端表单应引导填其一。
应付调账不挂团会出现 UNGROUPED 占位行，前端需做识别展示。
金额带符号：正=调增 / 负=红字冲减，禁 0。
驳回必须填驳回原因（596109）。

13. 关联/联系人

Issue：wx/HL#8699
PR：wx/HL#8710
merge commit：a65c53ebbc7dd0d5646a827dce8ea29f730055fb
后端负责人：腰苏图

10 KiB 原始文件 Blame 文件历史 Unescape Escape