---
schema: "hl-changelog/v2"
ticket: "8719"
title: "应收侧往来台账放开——ledgerType 取值域扩为 SUPPLIER/SUPPLIER_RECV/CUSTOMER（#8719）"
consumer: "admin"
author: "yst"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "b7bca8502a898be1e8f3d95ae0817bcdd2006cc0"
target_release: ""
verified_at: "2026-10-02"
status_note: "应收初始化录入的应收期初（客户应收/供应商应收）原在往来台账看不到，本期放开应收侧台账：/admin/finance/statements/page 与 /entries/page 两接口 ledgerType 取值域由仅 SUPPLIER 扩为 SUPPLIER/SUPPLIER_RECV/CUSTOMER（STAFF 仍未开放，传了报 596005）。应收账套本期无业务流水，increaseTotal/decreaseTotal 恒 0、entries 空页属正常；netAmount/openingAmount 符号方向按账套不同，详见正文对照表。前端 2026-10-02 已交付：台账页三账套页签切换+净额语义按账套分化（应收正=应收/负=多收标红，SUPPLIER 口径不变）+entries 随行账套上送。"
updated_at: "2026-10-02"
base: "dev-v3"
---

# finance：应收侧往来台账放开——ledgerType 扩域（管理后台）

> ⚠️ **修改接口（入参取值域扩大 + 出参符号语义按账套分化）**：`ledgerType` 新增 `SUPPLIER_RECV` / `CUSTOMER` 两个合法值；出参 `netAmount` / `openingAmount` 的正负方向随账套不同，前端展示层必须按账套区分正负含义并标红负值。

## 1. 接口背景

应收初始化录入的**应收期初**（客户应收 / 供应商应收）原先在往来台账页**完全看不到**——因为台账接口的 `ledgerType` 只开放 `SUPPLIER`（供应商应付）一个账套，应收侧的期初挂账没有查询入口。

本期放开应收侧台账，让期初挂账可见：
- 供应商应收（`SUPPLIER_RECV`）：我们预付/多付给供应商、应向他收回的钱
- 客户应收（`CUSTOMER`）：客户欠我们的钱（该收未收）

注意本期**只放开期初可见性**，应收账套暂无业务流水（后续版本接），所以应收账套下 `increaseTotal` / `decreaseTotal` 恒为 0、明细接口返回空页属于**正常行为**，不是接口坏了。

## 2. 变更清单

| # | 接口 | 变更点 | 类型 |
|---|------|--------|------|
| 1 | `GET /admin/finance/statements/page` | 入参 `ledgerType` 取值域扩大：`SUPPLIER` → `SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER` | ⚠️ 修改 |
| 2 | `GET /admin/finance/statements/page` | 出参 `netAmount` / `openingAmount` 符号方向按账套分化（详见 §5 对照表） | 🔧 语义扩展 |
| 3 | `GET /admin/finance/statements/page` | 出参 `ledgerType` 可能出现新值 `SUPPLIER_RECV` / `CUSTOMER` | ✨ 枚举扩域 |
| 4 | `GET /admin/finance/statements/entries/page` | 入参 `ledgerType` 取值域同步扩大 | ⚠️ 修改 |
| 5 | 两接口 | `STAFF` 账套仍未开放，传 `STAFF` 报 596005 | 📝 行为不变 |

## 3. 接口详情

| 项 | statements/page | entries/page |
|---|---|---|
| 方法 + 路径 | `GET /admin/finance/statements/page` | `GET /admin/finance/statements/entries/page` |
| 接口名 | 往来台账分页（按往来单位汇总） | 台账明细分页（按往来单位看流水） |
| 使用场景 | 管理后台 → 财务 → 往来台账列表页 | 台账页点某往来单位后的明细流水 |
| 认证 | 管理后台登录态（JWT） | 同左 |
| 幂等性 | 只读查询，天然幂等 | 只读查询，天然幂等 |
| 限流 | 无特殊限流 | 无特殊限流 |

## 4. 接口入参

### 4.1 `GET /admin/finance/statements/page`（Query 参数）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ledgerType | string | **必填** | 账套：`SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER`（本期新增后两个值）；传 `STAFF` 报 596005 |
| refName | string | 可空 | 往来单位名称，模糊匹配 |
| negativeOnly | boolean | 可空 | 只看净额为负（多付/多收）的单位；语义随账套，见 §5 |
| page | int | 必填 | 页码，从 1 开始 |
| pageSize | int | 必填 | 每页条数 |

### 4.2 `GET /admin/finance/statements/entries/page`（Query 参数）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ledgerType | string | **必填** | 账套，取值同 4.1；传 `STAFF` 报 596005 |
| refId | string | 必填 | 往来单位 ID（台账列表出参 `refId`） |
| direction | string | 可空 | 流水方向：`INCREASE` / `DECREASE` |
| sourceType | string | 可空 | 来源类型：`PAYMENT` / `PREPAY` |
| entryDateStart | string | 可空 | 流水日期起，格式 `yyyy-MM-dd` |
| entryDateEnd | string | 可空 | 流水日期止，格式 `yyyy-MM-dd` |
| teamNo | string | 可空 | 团号，精确过滤 |
| page | int | 必填 | 页码，从 1 开始 |
| pageSize | int | 必填 | 每页条数 |

## 5. 出参字段

### 5.1 statements/page 出参

统一分页包装 `PageResult`：`{ list/records: [...], total, page, pageSize }`（以前端现行解析字段为准，按现有页面使用的那个读）。

`records[]` 字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| ledgerType | string | 账套，可能值：`SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER`（新增后两个值） |
| refId | string | 往来单位 ID（Long 序列化为字符串，防精度丢失） |
| refName | string | 往来单位名称 |
| openingAmount | number | 期初净额，方向按账套（见下表） |
| increaseTotal | number | 本期增加合计（应收账套本期恒 0） |
| decreaseTotal | number | 本期减少合计（应收账套本期恒 0） |
| writeoffTotal | number | 核销合计 |
| adjustTotal | number | 财务调账合计 |
| netAmount | number | 当前净额，方向按账套（见下表） |

**金额符号语义对照表（前端展示必须按此区分）**：

| 账套 | openingAmount 期初净额 | netAmount 正数含义 | netAmount 负数含义 | 前端提示文案建议 |
|------|------------------------|---------------------|---------------------|------------------|
| `SUPPLIER` 供应商应付 | 期初应付 − 期初应收 | 我欠他（该付未付） | 多付他 | 应付 / 多付 |
| `SUPPLIER_RECV` 供应商应收 | 期初应收 − 期初应付 | 他欠我（该收未收） | 多收他 | 应收 / 多收 |
| `CUSTOMER` 客户应收 | 期初应收 − 期初应付 | 他欠我（该收未收） | 多收他 | 应收 / 多收 |

- **负值一律标红**（多付 / 多收属异常资金状态，需财务关注）。
- 同一列在不同账套 tab 下正负含义**相反**，不能直接复用「正=欠」的单一判断。

### 5.2 entries/page 出参

`records[]` 字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 明细 ID |
| ledgerType | string | 账套，可能值同 5.1 |
| refId | string | 往来单位 ID |
| refName | string | 往来单位名称 |
| entryDate | string | 流水日期 |
| sourceType | string | 来源类型：`PAYMENT` / `PREPAY` |
| sourceId | string | 来源单据 ID |
| sourceNo | string | 来源单号 |
| direction | string | `INCREASE` / `DECREASE` |
| amount | number | 金额（正数，方向由 direction 表达） |
| teamNo | string | 团号，无挂团时为空 |
| summary | string | 摘要 |

## 6. 枚举 / 数据字典

### ledgerType（账套类型）

| 值 | 含义 | 本期状态 |
|----|------|----------|
| `SUPPLIER` | 供应商应付 | 原有，不变 |
| `SUPPLIER_RECV` | 供应商应收 | **本期新增开放** |
| `CUSTOMER` | 客户应收 | **本期新增开放** |
| `STAFF` | 员工往来 | **未开放**，传了报 596005 |

### direction（流水方向）

| 值 | 含义 |
|----|------|
| `INCREASE` | 增加 |
| `DECREASE` | 减少 |

### sourceType（来源类型）

| 值 | 含义 |
|----|------|
| `PAYMENT` | 付款/收款 |
| `PREPAY` | 预付 |

## 7. 错误码

| 错误码 | 含义 | 触发场景 |
|--------|------|----------|
| 596005 | 账套非法或未开放 | `ledgerType` 传了 `STAFF` 或其他未开放/不存在的值 |

## 8. 示例

### 8.1 典型：查供应商应收台账（新开放账套）

请求：

```
GET /admin/finance/statements/page?ledgerType=SUPPLIER_RECV&page=1&pageSize=20
```

响应 200：

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "ledgerType": "SUPPLIER_RECV",
        "refId": "1927081523456789012",
        "refName": "草原牧歌车队有限公司",
        "openingAmount": 5000.00,
        "increaseTotal": 0,
        "decreaseTotal": 0,
        "writeoffTotal": 0,
        "adjustTotal": 0,
        "netAmount": 5000.00
      }
    ],
    "total": 1
  }
}
```

读法：该供应商应收 5000，即「他欠我 5000 该收未收」（正 = 他欠我）。

### 8.2 边界：应收账套明细返回空页（正常）+ 负净额

查客户应收明细（本期无业务流水）：

```
GET /admin/finance/statements/entries/page?ledgerType=CUSTOMER&refId=1927081523456789999&page=1&pageSize=20
```

响应 200（**空页属正常**，应收账套本期只有期初无流水）：

```json
{
  "code": 0,
  "data": {
    "list": [],
    "total": 0
  }
}
```

多收客户场景（负净额，前端标红）：

```json
{
  "ledgerType": "CUSTOMER",
  "refId": "1927081523456789999",
  "refName": "王某某",
  "openingAmount": -800.00,
  "increaseTotal": 0,
  "decreaseTotal": 0,
  "writeoffTotal": 0,
  "adjustTotal": 0,
  "netAmount": -800.00
}
```

读法：CUSTOMER 账套净额 -800 = 多收该客户 800，前端标红。

### 8.3 业务失败：传未开放账套 STAFF

请求：

```
GET /admin/finance/statements/page?ledgerType=STAFF&page=1&pageSize=20
```

响应：

```json
{
  "code": 596005,
  "message": "账套非法或未开放"
}
```

## 9. 业务边界

**适用**：
- 管理后台财务查看供应商应付 / 供应商应收 / 客户应收三个账套的期初挂账与（应付侧）流水。
- 应收侧（SUPPLIER_RECV / CUSTOMER）本期用于查看应收初始化录入的期初余额。

**不适用**：
- 员工往来（STAFF）查询——未开放，传了报 596005。
- 应收账套查业务流水——本期应收侧尚无业务流水入账，明细空页属正常，不要当 bug 报。

**特殊边界**：
- 应收账套 `increaseTotal` / `decreaseTotal` / `writeoffTotal` / `adjustTotal` 本期恒 0，`netAmount` 就等于 `openingAmount`（方向见 §5 对照表）。
- `refId` / `sourceId` 等 ID 字段为 Long 序列化的字符串，前端按字符串处理，不要转 number（防精度丢失）。

## 10. 修改前后对比

### 字段级对比

| 项 | 原来 | 现在 |
|----|------|------|
| 入参 `ledgerType` 取值域 | 仅 `SUPPLIER` 合法，其余报 596005 | `SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER` 合法；`STAFF` 仍报 596005 |
| 出参 `ledgerType` 实际出现值 | 只会是 `SUPPLIER` | 可能出现 `SUPPLIER_RECV` / `CUSTOMER` |
| 出参 `netAmount` 语义 | 只有应付口径：正 = 我欠他 / 负 = 多付他 | 按账套分化：应付口径不变；应收口径正 = 他欠我 / 负 = 多收他 |
| 出参 `openingAmount` 语义 | 期初应付 − 期初应收（单一口径） | 应付账 = 期初应付 − 期初应收；应收账 = 期初应收 − 期初应付（方向反过来） |

### 行为级对比

| 行为 | 原来 | 现在 |
|------|------|------|
| 传 `ledgerType=CUSTOMER` | 报 596005 | 正常返回客户应收台账 |
| 传 `ledgerType=SUPPLIER_RECV` | 报 596005 | 正常返回供应商应收台账 |
| 应收期初可见性 | 期初挂账在台账页完全看不到 | 切到应收账套即可看到期初净额 |
| SUPPLIER 账套行为 | —— | **完全不变**，老页面无感知 |

## 11. 影响评估 / 回滚

- **破坏兼容**：无。存量 `SUPPLIER` 账套的入参 / 出参 / 符号语义零变化，老前端不改也能跑。
- **前端同步上线**：非强制。但若要展示应收侧数据，前端需：
  1. 台账页按账套 tab 切换：供应商应付（SUPPLIER）/ 供应商应收（SUPPLIER_RECV）/ 客户应收（CUSTOMER）；
  2. 正负含义按 §5 对照表分账套判断，负值标红；
  3. 应收 tab 下明细为空是预期，建议展示「暂无流水」空态而非报错。
- **回滚方案**：后端回滚 = 恢复原取值域校验（SUPPLIER_RECV/CUSTOMER 重新报 596005）；无 DDL、无数据迁移，回滚无副作用。前端若已上 tab，回滚后应收 tab 会收到 596005，需前端同步下掉应收 tab。

## 12. 注意事项

1. **符号判断别偷懒**：`netAmount > 0` 在不同账套含义相反，前端任何「欠款/多付」文案、标红逻辑都必须先按 `ledgerType` 分支，不要写全局统一判断。
2. **应收空明细是正常**：SUPPLIER_RECV / CUSTOMER 本期无业务流水，entries 返回空页、`increaseTotal`/`decreaseTotal` 恒 0，不要当缺陷上报。
3. **STAFF 别放出入口**：员工往来账套未开放，前端不要给 STAFF 的 tab/选项；传了会吃 596005。
4. **ID 按字符串处理**：`refId` / `sourceId` 是 Long 序列化字符串，转 number 会精度丢失。
5. 页签展示名建议：SUPPLIER=供应商应付 / SUPPLIER_RECV=供应商应收 / CUSTOMER=客户应收。

## 13. 关联 / 联系人

- Issue：https://git.1814.love/wx/HL/issues/8719
- PR：https://git.1814.love/wx/HL/pulls/8727
- Commit：https://git.1814.love/wx/HL/commit/029000ef1f
- 后端负责人：@yst