From b41e3df62dc36b3e8986a2df29132b83b7eb3c3a Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Fri, 2 Oct 2026 09:57:07 +0800
Subject: [PATCH] =?UTF-8?q?feat(finance):=20=E5=BE=80=E6=9D=A5=E8=B4=A6?=
 =?UTF-8?q?=E8=B4=A2=E5=8A=A1=E8=B0=83=E8=B4=A65=E7=AB=AF=E7=82=B9=20chang?=
 =?UTF-8?q?elog=EF=BC=88#8699=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 /admin/finance/adjusts 5 端点：TZ调账单+页内审批+应收/应付入账联动。
---
 ...9_往来账财务调账5端点-新增接口-管理后台.md | 203 ++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 changelogs-v2/2026-10/02_8699_往来账财务调账5端点-新增接口-管理后台.md

diff --git a/changelogs-v2/2026-10/02_8699_往来账财务调账5端点-新增接口-管理后台.md b/changelogs-v2/2026-10/02_8699_往来账财务调账5端点-新增接口-管理后台.md
new file mode 100644
index 00000000..594852d1
--- /dev/null
+++ b/changelogs-v2/2026-10/02_8699_往来账财务调账5端点-新增接口-管理后台.md
@@ -0,0 +1,203 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8699"
+title: "往来账·财务调账——调账单(TZ)+页内审批+应收/应付入账联动（#8699）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: "v2.1"
+verified_at: "2026-10-02"
+status_note: "往来账「财务调账」（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 校验全对。"
+updated_at: "2026-10-02"
+base: "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）→ 批准
+```http
+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）
+```http
+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
+```http
+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 异常：应收双空
+```http
+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：https://git.1814.love/wx/HL/issues/8699
+- PR：https://git.1814.love/wx/HL/pulls/8710
+- merge commit：a65c53ebbc7dd0d5646a827dce8ea29f730055fb
+- 后端负责人：腰苏图