docs(changelog): 财务域账期/费用分类/业务外分类/收款账户/资金流水/资金互转/资金日报 7 篇入 changelogs-v2

- 09_6951_财务账期设置：page/开新账期/封账 3 端点 - 09_7129_费用分类：tree/增/改/停用/启用 5 端点（DISABLED 统一+幂等） - 09_7052_业务外收支分类：查询/增/改/停用/启用 5 端点（自动生码 NONBIZ_） - 09_7003_收款账户：page/增/改/设默认/停用 5 端点 - 09_7003_资金流水：page/详情 2 端点（只读，含 remark） - 09_7003_资金互转：page/发起 2 端点（双边成对记账+幂等） - 09_7003_资金日报：daily 1 端点（closing=opening+收入−支出勾稽） Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-09 16:25:37 +08:00
@@ -0,0 +1,120 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7003"
+title: "资金互转（发起 + 分页，双边成对记账）"
+consumer: "admin"
+author: "yst"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "hl-admin"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-09"
+status_note: "后端已合 dev-v3（account 资金账户域）并部署测试服。双边成对记账（一转出一入账）；幂等键防重复提交；不收转入金额（转出净减 amount+fee、转入净加 amount）。"
+updated_at: "2026-09-09"
+base: "dev-v3"
+---
+
+# 资金互转
+
+## 1. 接口背景
+财务域「资金互转」：公司各资金账户间划转（银行取现、现金存银行、三方提现、账户互转等）。一次互转双边成对记账（转出户一笔 OUT、转入户一笔 IN，共享 transferGroupId）。
+
+## 2. 变更清单
+| 类型 | 接口 | 说明 |
+|---|---|---|
+| 新增 | GET `/admin/finance/fund-transfers/page` | 互转记录分页（按 transferGroupId 成对聚合） |
+| 新增 | POST `/admin/finance/fund-transfers` | 发起互转（幂等） |
+
+## 3. 接口详情
+
+### 3.1 分页 GET /page
+入参（Query + 分页，均可选）：`fromAccountId` / `toAccountId` / `mode` / `operatorName`（精确）/ `flowAtStart` / `flowAtEnd`（按 transferDate 过滤）/ pageNo / pageSize。
+
+出参行（FundTransferRowRespVO，一转出一入账聚合成一行，Long ID 序列化为 String）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| transferGroupId | String | 互转组ID |
+| mode | String | 存取方式 |
+| fromAccountId / fromAccountName | String | 转出账户 |
+| toAccountId / toAccountName | String | 转入账户 |
+| transferDate | String | 业务日期（yyyy-MM-dd，可回溯补录） |
+| amount | BigDecimal | 转出金额（转入实收同额） |
+| fee | BigDecimal | 手续费（挂转出行） |
+| outFlowId / inFlowId | String | 转出/入账流水ID |
+| voucherUrl | String | 佐证影像 |
+| flowAt | String | 落账时刻 |
+| handlerName / operatorName | String | 经手人 / 经办人 |
+| status | String | 恒 COMPLETED（本期无审批/撤销） |
+
+### 3.2 发起互转 POST /
+**幂等**：`@Idempotent`，key=`fromAccountId:toAccountId:amount`，5 秒内重复提交返回「互转提交处理中，请勿重复提交」。
+
+入参（FundTransferReqVO）：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| mode | 是 | 存取方式（见枚举） |
+| fromAccountId | 是 | 转出账户ID |
+| toAccountId | 是 | 转入账户ID（不得与转出相同） |
+| amount | 是 | 转出金额（>0） |
+| fee | 否 | 手续费（≥0，默认 0，挂转出行） |
+| transferDate | 是 | 业务日期（可回溯补录） |
+| handlerName | 否 | 经手人（≤50） |
+| voucherUrl | 否 | 佐证影像（≤500） |
+| remark | 否 | 备注（≤200） |
+
+**口径**：不收转入金额——转出户净减 `amount+fee`、转入户净加 `amount`。
+
+出参（FundTransferRespVO）：`transferGroupId` / `outFlowId` / `inFlowId` / `fromBalanceAfter` / `toBalanceAfter`。
+
+## 4. 枚举 / 数据字典
+| 字段 | 取值 |
+|---|---|
+| mode | BANK2CASH 银行取现金 / CASH2BANK 现金存银行 / THIRD2BANK 三方提现到银行 / BANK2THIRD 银行转三方 / BANK2BANK 银行转银行 / CASH2CASH 现金转现金 |
+| status | COMPLETED（恒值，本期无审批/撤销） |
+
+## 5. 错误码
+| 码 | 含义 |
+|---|---|
+| 595001 | 账户不存在 |
+| 595004 | 互转两方账户不能相同 |
+| 595006 | 账户已停用 |
+| 595008 | 取现出账账户须为基本户 |
+| 595009 | 存取方式无效 |
+| 595010 | 存取方式与转出/转入账户类型不匹配 |
+| 595102 | 金额无效（须大于0） |
+| 595103 | 余额不足且不允许透支 |
+| 595104 | 资金写入并发冲突，请重试 |
+
+## 6. 示例
+**银行取现**
+```
+POST /admin/finance/fund-transfers
+{"mode":"BANK2CASH","fromAccountId":"2097...","toAccountId":"2098...","amount":5000.00,"transferDate":"2026-09-09","handlerName":"李四"}
+→ 200 {"transferGroupId":"...","outFlowId":"...","inFlowId":"...","fromBalanceAfter":...,"toBalanceAfter":...}
+```
+**两方同账户（异常）**
+```
+POST /admin/finance/fund-transfers  {"mode":"BANK2BANK","fromAccountId":"X","toAccountId":"X","amount":100,"transferDate":"2026-09-09"}
+→ 595004 互转两方账户不能相同
+```
+**5 秒内重复提交（幂等拦截）**
+```
+（同 fromAccountId:toAccountId:amount 再次 POST）
+→ 互转提交处理中，请勿重复提交
+```
+
+## 7. 注意事项
+- 互转即付即完成（status 恒 COMPLETED），无审批/撤销。
+- 银行取现（BANK2CASH）出账账户须为基本户（595008）。
+- 手续费 fee 只挂转出行，转入户实收=amount。
+- 长整型 ID 序列化为字符串。
+
+## 8. 关联 / 联系人
+- Issue：https://git.1814.love:8443/wx/HL/issues/7003
+- Commit：https://git.1814.love:8443/wx/HL/commit/b46269a4d4
+- 负责人：腰苏图（yst）