feat(finance): 应收侧往来台账放开 ledgerType 扩域 changelog（#8719 / PR #8727）

statements/page 与 entries/page 入参 ledgerType 由仅 SUPPLIER 扩为 SUPPLIER / SUPPLIER_RECV / CUSTOMER（STAFF 未开放报 596005）； netAmount/openingAmount 符号方向按账套分化，应收账套本期无流水空页属正常。
2026-10-02 17:09:34 +08:00
@@ -0,0 +1,309 @@
+---
+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: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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 符号方向按账套不同，详见正文对照表。"
+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