---
schema: "hl-changelog/v2"
ticket: "7164"
title: "往来期初建账（客户应收 / 供应商应付 / 员工往来 三本账）"
consumer: "admin"
author: "yst"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "60ca7002"
target_release: ""
verified_at: "2026-09-10"
status_note: "verified 2026-09-10 mmg: 推翻 fin-init 预埋替换为真实契约三端点。opening.js 重写(getOpeningBalancePage/createOpeningBalance/adjustOpeningBalance)+纯函数;fin-init/index.vue 整页重写 segment 三账套页签(切签注入必填 ledgerType),INIT 新建(refId 字符串透传/应收应付至少填一项/FileUpload 佐证必填),ADJUST 调整仅 INIT 行触发存全量值非差额(evidenceUrl+reason 必填);移除现金银行预埋。opening-balance.spec 锁端点/至少填一项/调整全量。checkpoint 全绿含 Vitest 全量+生产构建。"
updated_at: "2026-09-06"
base: "dev-v3"
---

# 往来期初建账

## 1. 接口背景
财务域「期初建账」：系统启用财务模块时，对客户应收、供应商应付、员工往来三本账做期初余额的一次性录入与后续调整。期初金额必须附佐证材料（影像 URL），期初基准日由后端取当前未封账账期的起始日，前端无需传。

- 路径前缀：`/admin/finance/opening-balances`（3 个新端点）
- 服务：hl-finance（财务服务）

## 2. 变更清单
| 类型 | 接口 | 说明 |
|---|---|---|
| 新增 | GET `/admin/finance/opening-balances/page` | 往来期初分页（按账套过滤，支持类别/往来对象名筛选） |
| 新增 | POST `/admin/finance/opening-balances` | 往来期初一次录入（同往来对象仅可录入一次初始期初） |
| 新增 | POST `/admin/finance/opening-balances/adjust` | 往来期初调整单（须已录入初始期初；存调整全量值非差额） |

## 3. 接口详情

### 3.1 期初分页 GET /page
- 使用场景：管理后台「期初建账」三个页签（客户应收 / 供应商应付 / 员工往来）的列表查询，页签切换 = 换 `ledgerType`。
- 认证：管理后台管理员 Token（`Authorization: Bearer <admin-token>`），未登录返 401。
- 幂等性：查询接口，天然幂等。
- 限流：网关默认限流，无特殊配置。

### 3.2 期初一次录入 POST /
- 使用场景：首次为某往来对象建立期初余额（INIT 行）。同一 `(ledgerType, refId)` 仅允许一条 INIT，重复录入报 598401。
- 认证：同上。幂等性：非幂等（重复提交报 598401 不会产生重复 INIT 行，前端提交后应禁用按钮）。
- 限流：网关默认。

### 3.3 期初调整单 POST /adjust
- 使用场景：已录入 INIT 后修正期初金额。**存的是调整后全量值（非差额）**，每次调整落一行 `kind=ADJUST`，当前净额 = INIT + ΣADJUST 由后端现算。
- 认证：同上。幂等性：非幂等（每次提交落一行调整记录）。
- 限流：网关默认。

## 4. 接口入参

### 4.1 分页 Query（OpeningBalancePageReqVO）

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---:|---|---|
| `ledgerType` | String | 是 | `CUSTOMER`/`SUPPLIER`/`STAFF` | 账套：CUSTOMER 客户应收 / SUPPLIER 供应商应付 / STAFF 员工往来 |
| `kind` | String | 否 | `INIT`/`ADJUST` | 类别：INIT 初始 / ADJUST 期初调整；空=全部 |
| `refName` | String | 否 | 模糊匹配 | 往来对象名筛选；空=不限 |
| `page` | Number | 否 | ≥1，默认 1 | 页码 |
| `pageSize` | Number | 否 | 默认 20 | 每页条数 |

### 4.2 一次录入 Body（OpeningBalanceCreateReqVO）

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---:|---|---|
| `ledgerType` | String | 是 | 同上枚举 | 账套 |
| `refId` | Number | 是 | — | 往来对象 ID（客户/供应商/员工主键，按账套对应） |
| `refName` | String | 是 | ≤128 字 | 往来对象名称（冗余快照，落库后不随主数据改名） |
| `openingPayable` | Number | 条件 | >0 | 期初应付（我欠他）；与 openingReceivable 至少填一项 |
| `openingReceivable` | Number | 条件 | >0 | 期初应收（他欠我们）；与 openingPayable 至少填一项 |
| `evidenceUrl` | String | 是 | — | 佐证材料影像 URL（必传，缺失抛 598402） |
| `remark` | String | 否 | ≤200 字 | 备注 |

### 4.3 调整单 Body（OpeningBalanceAdjustReqVO）

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---:|---|---|
| `ledgerType` | String | 是 | 同上枚举 | 账套 |
| `refId` | Number | 是 | — | 往来对象 ID（须已存在 INIT 行，否则 598404） |
| `openingPayable` | Number | 否 | >0 | 调整后**全量**期初应付（不调整传 null） |
| `openingReceivable` | Number | 否 | >0 | 调整后**全量**期初应收（不调整传 null） |
| `evidenceUrl` | String | 是 | — | 佐证材料影像 URL（必传，缺失抛 598402） |
| `reason` | String | 是 | ≤200 字 | 调整原因（必填留痕） |

## 5. 出参字段

### 5.1 分页行（OpeningBalanceRowRespVO）

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | String | 期初行 ID（雪花 ID，Long 序列化为字符串防 JS 精度丢失） |
| `ledgerType` | String | 账套码（CUSTOMER/SUPPLIER/STAFF） |
| `refId` | String | 往来对象 ID（雪花字符串） |
| `refName` | String | 往来对象名称快照 |
| `openingDate` | String | 期初基准日（yyyy-MM-dd，= 当前未封账账期起始日，后端带入） |
| `kind` | String | 类别：INIT 初始 / ADJUST 期初调整 |
| `openingPayable` | Number | 期初应付（无 = null） |
| `openingReceivable` | Number | 期初应收（无 = null） |
| `evidenceUrl` | String | 佐证材料影像 URL |
| `recordedByName` | String | 录入人姓名快照 |
| `createTime` | String | 创建时间（yyyy-MM-dd HH:mm:ss） |

分页包裹：`data.records[]` / `data.total` / `data.page` / `data.pageSize`。

### 5.2 录入 / 调整响应（OpeningBalanceIdRespVO）

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | String | 新落库期初行 ID（雪花字符串） |

## 6. 枚举 / 数据字典

### `ledgerType`（账套，代码枚举）
| 值 | 中文 | 说明 |
|---|---|---|
| `CUSTOMER` | 客户应收 | 客户欠我们的期初 |
| `SUPPLIER` | 供应商应付 | 我们欠供应商的期初 |
| `STAFF` | 员工往来 | 员工借款/备用金期初 |

### `kind`（期初行类别，代码枚举）
| 值 | 中文 | 说明 |
|---|---|---|
| `INIT` | 初始期初 | 首次录入，同往来对象唯一 |
| `ADJUST` | 期初调整 | 调整单，存调整后全量值，可多条 |

## 7. 错误码（段位 598400-598499）

| 错误码 | 含义 | 触发场景 |
|---|---|---|
| 598401 | 该往来对象期初已录入 | 同 `(ledgerType, refId)` 重复 POST 录入 INIT |
| 598402 | 佐证材料必传 | `evidenceUrl` 为空 |
| 598403 | 账期已封账，不允许录入或调整期初 | 当前账期已封账 / 无未封账账期（视同未开账） |
| 598404 | 该往来对象尚未录入初始期初，不可调整 | POST /adjust 时无 INIT 行 |
| 598405 | 期初应付/应收须至少填一项 | 两项均空或均 ≤0 |
| 598406 | 账套类型非法，须为 SUPPLIER、CUSTOMER 或 STAFF | `ledgerType` 传其他值 |

## 8. 示例

### 8.1 典型成功（供应商应付期初录入）
```http
POST /admin/finance/opening-balances
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "ledgerType": "SUPPLIER",
  "refId": 2094123456789012345,
  "refName": "云山景区管理有限公司",
  "openingPayable": 50000.00,
  "openingReceivable": null,
  "evidenceUrl": "https://oss.example.com/evidence/abc.jpg",
  "remark": "2026 年 8 月对账单确认"
}
```
```json
{"code":200,"message":"成功","success":true,"data":{"id":"2094300011122233445"}}
```

分页查询：
```http
GET /admin/finance/opening-balances/page?ledgerType=SUPPLIER&page=1&pageSize=20
```
```json
{"code":200,"success":true,"data":{"records":[{"id":"2094300011122233445","ledgerType":"SUPPLIER","refId":"2094123456789012345","refName":"云山景区管理有限公司","openingDate":"2026-09-01","kind":"INIT","openingPayable":50000.00,"openingReceivable":null,"evidenceUrl":"https://oss.example.com/evidence/abc.jpg","recordedByName":"腰苏图","createTime":"2026-09-06 10:00:00"}],"total":1,"page":1,"pageSize":20}}
```

### 8.2 边界情况（期初调整为零 / 双项同调）
调整单传全量值，可把某项调成新值、另一项保持 null 不动：
```json
{
  "ledgerType": "SUPPLIER",
  "refId": 2094123456789012345,
  "openingPayable": 48000.00,
  "openingReceivable": null,
  "evidenceUrl": "https://oss.example.com/evidence/def.jpg",
  "reason": "对方减免 2000 元尾款"
}
```
```json
{"code":200,"success":true,"data":{"id":"2094300099988877766"}}
```
空分页：无数据时 `records=[]`、`total=0`，HTTP 200，前端正常渲染空列表。

### 8.3 业务失败（重复录入 / 未录初始就调整）
```http
POST /admin/finance/opening-balances   # 同一 refId 再次录入
```
```json
{"code":598401,"message":"该往来对象期初已录入","success":false,"data":null}
```
```http
POST /admin/finance/opening-balances/adjust   # 该对象从未录入 INIT
```
```json
{"code":598404,"message":"该往来对象尚未录入初始期初，不可调整","success":false,"data":null}
```
缺佐证材料：`{"code":598402,"message":"佐证材料必传"}`；两项金额均空：`{"code":598405,"message":"期初应付/应收须至少填一项"}`。

## 9. 业务边界

**适用**：
- 财务模块上线初始化时，批量为三本账建立期初基准。
- 期初金额有误时，通过调整单修正（保留全部调整留痕）。

**不适用 / 限制**：
- 同往来对象只能录入一次 INIT，后续一律走调整单。
- 账期封账后禁止录入与调整（598403）；未开账（无未封账账期）同样拦截。
- 期初基准日不可指定，由后端取当前未封账账期的 `start_date`。
- 期初数据**暂未回流勾稽到往来账**（方案 A，留 TODO 接缝），本期仅作独立台账。

**特殊边界**：
- `refName` 是冗余快照，主数据改名不影响历史期初行显示。
- 调整单存**全量值**不是差额，前端表单应展示「调整后金额」而非「调增/调减」。

## 10. 注意事项
- 所有雪花 ID（`id` / `refId`）均已序列化为字符串，前端按 String 处理，勿转 Number。
- `openingDate` 由后端带入，入参里没有该字段。
- 前端三个页签（客户应收 / 供应商应付 / 员工往来）对应 `ledgerType` 三值，建议页签切换即重置筛选条件重新查询。
- 新表 `fin_opening_balance`（Flyway `V20260906_101`），部署时自动执行，无需前端动作。

## 11. 关联 / 联系人
- Issue：https://git.1814.love:8443/wx/HL/issues/7164
- PR：https://git.1814.love:8443/wx/HL/pulls/7166
- Commit：https://git.1814.love:8443/wx/HL/commit/d0f06fa2e8
- Epic：https://git.1814.love:8443/wx/HL/issues/7163
- 负责人：腰苏图（yst）