财务初始化三tab对齐原型：纠偏前端4tab为3tab（应收初始化/应付初始化/现金银行初始化），删员工往来tab（#8507 #8511）

2026-09-30 10:32:47 +08:00
@@ -0,0 +1,303 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8507"
+title: "财务初始化页面 tab 结构纠偏：应为 3 tab（应收初始化/应付初始化/现金银行初始化），删「员工往来」tab，应收初始化内按往来对象选 CUSTOMER/SUPPLIER_RECV（#8507 #8511）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-30"
+status_note: "财务初始化（菜单：参数设置/财务初始化）前端页面 tab 结构与原型不符的纠偏单。原型只有 3 个 tab（应收初始化/应付初始化/现金银行初始化），按「初始化场景」划分，初始化里**没有「员工往来」期初**（员工借款/备用金属付款管理业务流程，不在初始化）。当前前端做成了 4 个 tab（客户应收/供应商应付/供应商应收/员工往来），按「往来对象类型」划分，需重构。后端接口零改动、已全部部署测试服并验证通过：应收/应付走 /admin/finance/opening-balances（按 ledgerType 区分 CUSTOMER/SUPPLIER_RECV/SUPPLIER），现金银行走 /admin/finance/fund-accounts（账户期初结存），两套接口互相独立。本文自包含全部入参/出参/枚举/错误码/示例。"
+updated_at: "2026-09-30"
+base: "dev-v3"
+---
+
+# finance：财务初始化三 tab 对齐原型（管理后台）
+
+> **性质**：前端实现纠偏。后端接口无新增/无变更，已在测试服就绪。本文告诉前端「正确的 tab 结构 + 每个 tab 怎么调既有接口」。
+
+## 1. 接口背景
+
+财务初始化是账套启用前录入期初数据的入口（菜单：**参数设置 / 财务初始化**）。
+
+原型 `finance-prototype.html`（页面 id `cfg-fininit`）规定财务初始化**只有 3 个 tab**，按「初始化场景」划分：
+
+```
+财务初始化
+├─ 应收初始化      启用前欠我们的款（客户欠款 + 供应商杂项应收）
+├─ 应付初始化      启用前我们欠供应商的款
+└─ 现金银行初始化  各资金账户启用前已有结存
+```
+
+**当前前端实现错误**：做成了 4 个 tab（客户应收 / 供应商应付 / 供应商应收 / 员工往来），按「往来对象类型」划分。两处偏差：
+1. tab 划分维度错了——应按「初始化场景」（应收/应付/现金银行），不是按「往来对象类型」（客户/供应商/员工）。
+2. 多出了「员工往来」tab——原型财务初始化**没有员工往来期初**。员工借款/备用金是「付款管理 / 员工借款」的业务单据流（页面 `loan-stf` / `payex-stfloan`），不属于财务初始化。
+
+**「供应商应收」不是独立 tab**：它是「应收初始化」tab 内部、往来对象选「供应商」时的一种（供应商欠我们的杂项应收：押金退还/赔偿款/口车费/其他应收）。
+
+## 2. 变更清单（前端 tab 结构改动）
+
+| # | 改动 | 说明 |
+|---|------|------|
+| 1 | 删除「员工往来」tab | 初始化无此场景 |
+| 2 | tab 改 3 个并改名 | `应收初始化` / `应付初始化` / `现金银行初始化` |
+| 3 | 「客户应收」+「供应商应收」合并进「应收初始化」一个 tab | tab 内用「往来对象」下拉（客户/供应商）切换 ledgerType |
+| 4 | 「供应商应付」改名「应付初始化」 | 固定 ledgerType=SUPPLIER，去掉对象细分字段 |
+| 5 | 新增「现金银行初始化」tab | 接 `/admin/finance/fund-accounts` 系列接口（账户期初结存） |
+
+## 3. tab ↔ 接口 / 账套映射（核心）
+
+| 前端 tab | tab 内「往来对象」 | 调接口 | 传 `ledgerType` |
+|---|---|---|---|
+| 应收初始化 | 客户 | `POST /admin/finance/opening-balances` 等 | `CUSTOMER` |
+| 应收初始化 | 供应商 | 同上 | `SUPPLIER_RECV` |
+| 应付初始化 | （固定供应商，无此下拉） | 同上 | `SUPPLIER` |
+| 现金银行初始化 | — | `/admin/finance/fund-accounts` 系列 | —（无 ledgerType 概念） |
+
+> 应收初始化一个 tab 对应两个 ledgerType，按用户选的「往来对象」决定传哪个；金额字段填 `openingReceivable`。应付初始化固定 `SUPPLIER`，金额填 `openingPayable`。
+
+---
+
+## 4. 应收初始化 tab（ledgerType = CUSTOMER / SUPPLIER_RECV）
+
+### 4.1 列表（分页）
+
+`GET /admin/finance/opening-balances/page`
+
+**入参（query）**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| pageNo | int | 是 | 页码 |
+| pageSize | int | 是 | 每页 |
+| ledgerType | string | 是 | `CUSTOMER` 或 `SUPPLIER_RECV` |
+| kind | string | 否 | `INIT` 初始 / `ADJUST` 期初调整；空=全部 |
+| refName | string | 否 | 往来对象名模糊搜索 |
+
+> 应收初始化 tab 顶部建议加「往来对象」筛选（全部/客户/供应商）：客户→`CUSTOMER`、供应商→`SUPPLIER_RECV`、全部→两个 ledgerType 各查一次合并。
+
+**出参（`data.records[]`）**：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | string | 期初行 ID |
+| ledgerType | string | 账套回显 |
+| refId | string | 往来对象 ID |
+| refName | string | 往来对象名称 |
+| customerCategory | string | 对象细分编码（CUSTOMER=客户分类 / SUPPLIER_RECV=应收性质；SUPPLIER 为 null） |
+| customerCategoryName | string | **对象细分中文名**（列表直接显示这个；字典不可用为 null） |
+| companyId | string | 所属公司主体 ID |
+| companyName | string | 所属公司主体名 |
+| openingDate | string | 期初基准日（=当前未封账账期起始日），只读 |
+| kind | string | `INIT` / `ADJUST` |
+| openingPayable | number | 期初应付（应收 tab 恒 null，忽略） |
+| openingReceivable | number | **期初应收（本 tab 显示这个金额）** |
+| evidenceUrl | string | 佐证材料影像 URL（可空） |
+| recordedByName | string | 录入人姓名 |
+| createTime | string | 创建时间 |
+
+### 4.2 新建期初
+
+`POST /admin/finance/opening-balances`
+
+**表单（按原型应收表单三段递进）**：
+
+1. **往来对象**（下拉必填）：`客户` / `供应商`
+2. **对象细分**（下拉必填，标签随往来对象变）：
+   - 客户 → 标签「客户分类」，选项 = 字典 `fin_customer_category`
+   - 供应商 → 标签「应收性质」，选项 = 字典 `fin_recv_nature`
+3. **往来对象名称**（下拉必填）：
+   - 供应商 → `GET /admin/supplier/items/list?status=ACTIVE`（取 `supplierId` + `shortName`/`fullName`）
+   - 客户 → 客户列表（按所选客户分类过滤）
+4. **应收欠款**（数字必填，>0）
+5. **所属公司**（下拉单选必填）：`GET /v3/admin/travel-agency/enabled`（取 `agencyId`+`agencyName`）
+6. **记账日期**（只读）：前端不传，后端落 `openingDate`=当前账期起始日
+7. **备注**（文本域选填，≤200 字）
+
+**请求体**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ledgerType | string | 是 | `CUSTOMER`（选了客户）/ `SUPPLIER_RECV`（选了供应商） |
+| refId | Long | 是 | 往来对象 ID |
+| refName | string | 是 | 往来对象名称（≤128） |
+| customerCategory | string | 条件必填 | 对象细分编码：CUSTOMER→fin_customer_category 编码；SUPPLIER_RECV→fin_recv_nature 编码。**两账套均必填** |
+| companyId | Long | 是 | 所属公司主体 ID |
+| openingReceivable | number | 是 | 期初应收金额，>0 |
+| openingPayable | — | 否 | 应收 tab 不传（传了后端也忽略不落库） |
+| evidenceUrl | string | 否 | 佐证材料影像 URL |
+| remark | string | 否 | 备注（≤200） |
+
+**响应**：`data.id` = 新建期初行 ID。
+
+**请求示例（供应商应收）**：
+```json
+{
+  "ledgerType": "SUPPLIER_RECV",
+  "refId": 2104918057506041857,
+  "refName": "柴河星悦酒店",
+  "customerCategory": "DEPOSIT_REFUND",
+  "companyId": 2051922156798779394,
+  "openingReceivable": 1.01,
+  "remark": "押金退还期初"
+}
+```
+
+**响应示例**：
+```json
+{ "code": 200, "message": "成功", "data": { "id": "2105077077235662849" }, "success": true }
+```
+
+### 4.3 期初调整
+
+`POST /admin/finance/opening-balances/adjust`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ledgerType | string | 是 | 同新建 |
+| refId | Long | 是 | 往来对象 ID（须已有 INIT 行，否则 598404） |
+| openingReceivable | number | 条件 | **调整后期初应收（全量值非差额）**；CUSTOMER/SUPPLIER_RECV 落库 |
+| openingPayable | number | 条件 | 调整后期初应付；仅 SUPPLIER 落库 |
+| evidenceUrl | string | 否 | 佐证影像 |
+| reason | string | **是** | 调整原因（≤200） |
+
+> 分类/性质/公司沿用 INIT 行快照，调整单不开放改。
+
+---
+
+## 5. 应付初始化 tab（ledgerType = SUPPLIER）
+
+接口同应收（`/admin/finance/opening-balances` 一套），差异：
+
+| 项 | 应付初始化 |
+|---|---|
+| ledgerType | 固定 `SUPPLIER` |
+| 往来对象 | 固定「供应商」，无客户/供应商下拉；直接供应商列表 `GET /admin/supplier/items/list?status=ACTIVE` |
+| customerCategory | **不传**（SUPPLIER 忽略，供应商类别随供应商档案带出不手选） |
+| 金额字段 | 传 `openingPayable`（期初应付，>0），**不传** `openingReceivable` |
+
+列表看 `openingPayable`（`openingReceivable` 恒 null）。
+
+---
+
+## 6. 现金银行初始化 tab（走资金账户接口，独立）
+
+此 tab 是**资金账户的期初结存**，与应收/应付的 opening-balances **完全独立**，接 `/admin/finance/fund-accounts`：
+
+| 操作 | 接口 | 说明 |
+|---|---|---|
+| 列表 | `GET /admin/finance/fund-accounts/page` | 本 tab 列表（列：账户名称/类型/期初结存/操作） |
+| 新建账户（录期初结存） | `POST /admin/finance/fund-accounts` | 建户时录账户信息+期初结存 |
+| 期初调整 | `POST /admin/finance/fund-accounts/{id}/opening-adjust` | 唯一改期初途径，落 OPENING 留痕流水 |
+| 建户表单三组下拉 | `GET /admin/finance/fund-accounts/options` | accountType/nature/channel（字典 fin_fund_account_*） |
+
+> ⚠️ `opening-adjust` 差额为 0 时返 `595105`（不落流水），**非 200 幂等**——前端需区分「200 调整成功」vs「595105 无需调整」，不要把 595105 当失败弹错。
+
+---
+
+## 7. 枚举 / 数据字典
+
+### 7.1 ledgerType（账套，OpeningLedgerTypeEnum）
+
+**所属字段**：`ledgerType` | **类型**：`String` | **必填**：✅
+
+| 值 | 中文 | 金额字段 | 用于 tab |
+|----|------|------|------|
+| `SUPPLIER` | 供应商应付（我欠他） | openingPayable | 应付初始化 |
+| `CUSTOMER` | 客户应收（他欠我们） | openingReceivable | 应收初始化（往来对象=客户） |
+| `SUPPLIER_RECV` | 供应商应收（他欠我们：押金退还/赔偿款/口车费/其他应收） | openingReceivable | 应收初始化（往来对象=供应商） |
+
+### 7.2 kind（类别）
+
+**所属字段**：`kind` | **类型**：`String` | **必填**：❌（查询过滤用）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `INIT` | 初始 | 首次录入（同对象仅一次） |
+| `ADJUST` | 期初调整 | 对已有 INIT 的调整留痕 |
+
+### 7.3 应收性质（字典 fin_recv_nature，SUPPLIER_RECV 的 customerCategory）
+
+| 值 | 中文 |
+|----|------|
+| `DEPOSIT_REFUND` | 押金退还 |
+| `COMPENSATION` | 赔偿款 |
+| `CAR_FEE` | 口车费 |
+| `OTHER` | 其他应收 |
+
+### 7.4 客户分类（字典 fin_customer_category，CUSTOMER 的 customerCategory）
+
+经 `GET /admin/dict/all` 或字典接口取 `fin_customer_category` 当前生效值。
+
+---
+
+## 8. 下拉数据源汇总
+
+| 下拉 | 接口 / 字典 |
+|---|---|
+| 供应商列表 | `GET /admin/supplier/items/list?status=ACTIVE` |
+| 公司主体 | `GET /v3/admin/travel-agency/enabled` |
+| 客户分类（应收-客户） | 字典 `fin_customer_category` |
+| 应收性质（应收-供应商） | 字典 `fin_recv_nature`（押金退还/赔偿款/口车费/其他应收） |
+| 资金账户类型/性质/渠道 | `GET /admin/finance/fund-accounts/options` |
+
+---
+
+## 9. 错误码
+
+| code | 含义 | 触发场景 |
+|------|------|----------|
+| 598401 | 同往来对象 INIT 已录过 | 重复新建初始期初 |
+| 598403 | 账期已封账 | 封账后新建/调整 |
+| 598404 | 须先录初始期初 | 调整时无 INIT 行 |
+| 598405 | 期初金额须大于0 | 金额 ≤0 |
+| 598407 | 公司主体非法 | companyId 无效 |
+| 598408 | 客户分类必填 | CUSTOMER 缺 customerCategory |
+| 598409 | 供应商应收性质必填 | SUPPLIER_RECV 缺 customerCategory |
+| 598410 | 对象细分取值非法 | customerCategory 不在字典内 |
+| 595105 | 期初调整差额为 0 | 现金银行 opening-adjust 无需调整（非错误） |
+
+---
+
+## 10. 修改前后对比
+
+| 项 | 改前（当前前端错误） | 改后（对齐原型） |
+|---|---|---|
+| tab 数 | 4 个 | **3 个** |
+| tab 名 | 客户应收/供应商应付/供应商应收/员工往来 | **应收初始化/应付初始化/现金银行初始化** |
+| 划分维度 | 往来对象类型 | **初始化场景** |
+| 员工往来 tab | 有（多出） | **删除** |
+| 供应商应收 | 独立 tab | **并入应收初始化**（往来对象=供应商，ledgerType=SUPPLIER_RECV） |
+| 现金银行初始化 | 缺 | **新增**（接 fund-accounts 期初） |
+
+---
+
+## 11. 影响评估 / 回滚
+
+- **后端接口变更**：无（零改动，已 deployed）
+- **是否破坏向后兼容**：前端页面重构，接口契约不变
+- **前端是否必须同步上线**：是（当前 4 tab 结构与后端账套语义不符，「员工往来」tab 调任何接口都会失败——后端无员工往来账套）
+
+## 12. 注意事项
+
+- 金额字段二选一：应收 tab 填 `openingReceivable`、应付 tab 填 `openingPayable`，**不要同传两个**（后端按 ledgerType 只落对应方向，另一方向忽略）。
+- 记账日期只读、前端不传，后端落当前账期起始日。
+- 同一往来对象 INIT 仅可录一次；要改走「期初调整」。
+- 「现金银行初始化」与「应收/应付初始化」是两套独立接口（fund-accounts vs opening-balances），不要混用。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#8507](https://git.1814.love/wx/HL/issues/8507) / [#8511](https://git.1814.love/wx/HL/issues/8511)
+- **PR**: [#8509](https://git.1814.love/wx/HL/pulls/8509) / [#8513](https://git.1814.love/wx/HL/pulls/8513)
+
+### 13.2 联系人
+
+- **后端负责人**: @yst
+- **前端对接（管理后台）**: 待认领