docs(changelog): 8751 往来台账净额视图破坏性契约 partyType（反转 #8719）

2026-10-04 09:48:42 +08:00
@@ -0,0 +1,391 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8751"
+title: "往来台账升级为按往来对象净额视图——入参 ledgerType 改名 partyType（反转 #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: ""
+status_note: "反转 #8719 单账套契约：#8719 的 ledgerType 三账套入参（SUPPLIER/SUPPLIER_RECV/CUSTOMER）作废，前端 mmg 已按 #8719 交付的三账套页签需返工，改按本契约 partyType 两对象净额视图重对接。核心：供应商应收+应付是同一本供应商往来的两个方向，合并轧差算净额（应付−应收，正=我欠他/负=他欠我）；入参 ledgerType→partyType 破坏性改名；明细新增期初构成行（sourceType=OPENING），纯期初供应商点详情不再空白。"
+updated_at: "2026-10-04"
+base: "dev-v3"
+---
+
+# finance：往来台账净额视图——ledgerType 改名 partyType（管理后台）
+
+> ⚠️ **修改接口（破坏性，反转 #8719）**：两个接口入参 `ledgerType` **改名** `partyType`，取值域从三账套（SUPPLIER/SUPPLIER_RECV/CUSTOMER）收敛为**往来对象两值**（SUPPLIER/CUSTOMER）；供应商应付+应收两账套按 refId 轧差合并为一个供应商净额。按 #8719 交付的三账套页签**必须返工**。
+
+## 1. 接口背景
+
+#8719 把往来台账从单账套 SUPPLIER 扩为 SUPPLIER/SUPPLIER_RECV/CUSTOMER 三账套分别查询。上线后发现业务口径不对：**供应商的应收和应付是同一本供应商往来的两个方向**，分开看两本账无法回答「我到底欠不欠这个供应商钱」。
+
+#8751 用户拍板方案 A：台账从「按账套单查」升级为「**按往来对象轧差算净额**」——供应商往来 = 应付账套（SUPPLIER）+ 应收账套（SUPPLIER_RECV）按同一供应商 refId 轧差，**应付 − 应收 = 净额**。客户往来保持应收口径不变。
+
+同时解决 #8719 遗留问题：纯期初（只有期初挂账、无业务流水）的往来对象点详情明细是空白——本期明细接口把**期初构成行**（期初录入 / 期初调整）也 UNION 进来，期初怎么来的看得见。
+
+## 2. 变更清单
+
+| # | 接口 | 变更点 | 类型 |
+|---|------|--------|------|
+| 1 | `GET /admin/finance/statements/page` | 入参 `ledgerType` **改名** `partyType`，取值域三账套 → 两对象 | ⚠️ 破坏性改名 |
+| 2 | `GET /admin/finance/statements/entries/page` | 入参 `ledgerType` **改名** `partyType`，同上 | ⚠️ 破坏性改名 |
+| 3 | 两接口 | 出参字段 `ledgerType` → `partyType`，值只会是 `SUPPLIER` / `CUSTOMER` | ⚠️ 字段改名 |
+| 4 | statements/page | 供应商行金额 = 应付 + 应收两账套按 refId **轧差合并**（应付−应收） | 🔧 口径变化 |
+| 5 | entries/page | 出参新增**期初构成行**：`sourceType=OPENING`、`direction=INCREASE`、`summary=期初录入/期初调整` | ✨ 新增行类型 |
+| 6 | entries/page | 入参 `sourceType` 筛选新增合法值 `OPENING` | ✨ 枚举扩域 |
+| 7 | 两接口 | `SUPPLIER_RECV` 不再作为独立查询值，传了报 596005 | ⚠️ 取值收敛 |
+| 8 | 菜单 | /finance/current-account 下新增「司导往来 /guide」「客户往来 /customer」菜单 | ✨ 菜单新增 |
+
+## 3. 接口详情
+
+| 项 | statements/page | entries/page |
+|---|---|---|
+| 方法 + 路径 | `GET /admin/finance/statements/page` | `GET /admin/finance/statements/entries/page` |
+| 接口名 | 往来账账页分页（按往来对象净额视图） | 往来流水明细分页（业务流水+期初构成 UNION） |
+| 使用场景 | 管理后台 → 财务 → 往来账 → 供应商往来 / 客户往来列表页 | 台账页点某往来对象后的明细流水（含期初构成） |
+| 认证 | 管理后台登录态（JWT） | 同左 |
+| 幂等性 | 只读查询，天然幂等 | 只读查询，天然幂等 |
+| 限流 | 无特殊限流 | 无特殊限流 |
+
+## 4. 接口入参
+
+### 4.1 `GET /admin/finance/statements/page`（Query 参数）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| partyType | string | **必填** | 往来对象类型：`SUPPLIER` 供应商往来（应付−应收轧差净额）/ `CUSTOMER` 客户往来（应收）；传 `STAFF` / `SUPPLIER_RECV` / 其他非法值报 596005 |
+| refName | string | 可空 | 往来对象名，模糊匹配；空=不限 |
+| negativeOnly | boolean | 可空 | true=只返回净额为负的行（供应商 负=他欠我 / 客户 负=我多收，前端标红场景） |
+| page | int | 必填 | 页码，从 1 开始 |
+| pageSize | int | 必填 | 每页条数 |
+
+### 4.2 `GET /admin/finance/statements/entries/page`（Query 参数）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| partyType | string | **必填** | 往来对象类型，取值同 4.1；`STAFF`/`SUPPLIER_RECV`/非法值报 596005 |
+| refId | string | 可空 | 往来对象 ID（供应商/客户主键，Long 字符串）；空=不限 |
+| direction | string | 可空 | 增减方向：`INCREASE` 净额增 / `DECREASE` 净额减；空=不限（非法值不报错，查不出行返回空页） |
+| sourceType | string | 可空 | 来源类型：`PAYMENT` 应付款 / `PREPAY` 预付款 / `OPENING` 期初构成行（**本期新增**）；空=不限 |
+| entryDateStart | string | 可空 | 入账日期起，格式 `yyyy-MM-dd`；晚于 entryDateEnd 报 596009 |
+| entryDateEnd | string | 可空 | 入账日期止，格式 `yyyy-MM-dd` |
+| teamNo | string | 可空 | 团号，精确过滤（**期初构成行无团号**，填团号后结果不含期初行） |
+| page | int | 必填 | 页码，从 1 开始 |
+| pageSize | int | 必填 | 每页条数 |
+
+## 5. 出参字段
+
+统一分页包装 `PageResult`（`list/records` + `total` 等，以前端现行解析字段为准）。
+
+### 5.1 statements/page 出参 records[]
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| partyType | string | 往来对象类型，只会是 `SUPPLIER` / `CUSTOMER` |
+| refId | string | 往来对象 ID（Long 序列化字符串，防精度丢失） |
+| refName | string | 往来对象名（流水名优先，改名取新） |
+| openingAmount | number | 期初净额（供应商=应付期初−应收期初；客户=应收期初−应付期初） |
+| increaseTotal | number | 本期净额增合计（供应商=应付增+应收减；客户=应收增） |
+| decreaseTotal | number | 本期净额减合计（供应商=应付减+应收增；客户=应收减） |
+| writeoffTotal | number | 本期核销合计（**本期恒 0**，核销开放后有值） |
+| adjustTotal | number | 本期调账合计（**本期恒 0**，调账二期开放后有值） |
+| netAmount | number | 净往来余额 = openingAmount + increaseTotal − decreaseTotal − writeoffTotal + adjustTotal |
+
+**金额符号语义对照表（方向做反 = 金额全错，前端必须按此实现）**：
+
+| partyType | netAmount 正数含义 | netAmount 负数含义 | 前端展示 |
+|-----------|---------------------|---------------------|----------|
+| `SUPPLIER` 供应商往来 | **我欠他**（该付未付） | **他欠我**（多付/预付他） | 负值标红 |
+| `CUSTOMER` 客户往来 | **他欠我**（该收未收） | 我多收他 | 负值标红 |
+
+- 供应商口径与 #8719 的 SUPPLIER（应付）单账套一致：正=我欠他；区别在于本期净额已**扣掉应收侧**（预付款/多付款）。
+- 期初净额 openingAmount 同样按对象口径轧差：供应商 = 应付期初 − 应收期初。
+
+### 5.2 entries/page 出参 records[]
+
+明细 = 业务流水行 + 期初构成行 **UNION 合并**，按 `entryDate` 倒序。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | string | 明细行 ID（业务流水=entry_id，期初构成行=opening_id） |
+| partyType | string | 往来对象类型：`SUPPLIER` / `CUSTOMER` |
+| refId | string | 往来对象 ID |
+| refName | string | 往来对象名快照 |
+| entryDate | string | 入账日期（业务发生日；期初构成行=期初基准日） |
+| sourceType | string | `PAYMENT` 应付款 / `PREPAY` 预付款 / `OPENING` 期初构成行 |
+| sourceId | string | 来源单据 ID（期初构成行=opening_id） |
+| sourceNo | string | 来源单号（期初构成行无独立单号，回退 opening_id 字符串） |
+| direction | string | `INCREASE` 净额增 / `DECREASE` 净额减；**期初构成行恒 INCREASE**，前端映射「净额+」/「净额−」徽标 |
+| amount | number | 金额（恒正，方向由 direction 表达；期初构成行=该行账套方向金额：应付账行取应付金额/应收账行取应收金额） |
+| teamNo | string | 团号（可空；预付款与期初构成行无团号为 null） |
+| summary | string | 摘要（白话业务词，如「应付款付讫」；期初构成行=`期初录入`/`期初调整`） |
+
+**供应商净额视图下的明细构成**：`partyType=SUPPLIER` 时，SUPPLIER（应付）和 SUPPLIER_RECV（应收）**两账套的业务流水与期初行都会进明细**——应收侧行（如预付款收回、应收期初）以轧差方向并入，方向已折算成净额增减，前端按 direction 渲染即可，无需自己区分账套。
+
+**纯期初对象不再空白**：只有期初挂账、无业务流水的往来对象，明细页现在能看到 `OPENING` 行（期初录入/期初调整各一条），解决 #8719 期间「点详情一片空白」的问题。
+
+## 6. 枚举 / 数据字典
+
+### partyType（往来对象类型，入参 + 出参）
+
+| 值 | 含义 | 底层账套合并规则 |
+|----|------|------------------|
+| `SUPPLIER` | 供应商往来净额（正=我欠他 / 负=他欠我） | 应付 SUPPLIER（权重 +1）+ 应收 SUPPLIER_RECV（权重 −1）按 refId 轧差 |
+| `CUSTOMER` | 客户往来（应收，正=他欠我） | 应收 CUSTOMER 单账套 |
+
+**非法值（传了报 596005）**：`STAFF`（员工往来本期不开放，司导走独立 GuideLedger 接口 `/guide-ledger/*`）、`SUPPLIER_RECV`（已并入 SUPPLIER 净额，不再独立查询）、其他任意值。
+
+### sourceType（明细来源类型）
+
+| 值 | 含义 | 本期状态 |
+|----|------|----------|
+| `PAYMENT` | 应付款 | 原有 |
+| `PREPAY` | 预付款 | 原有 |
+| `OPENING` | 期初构成行（期初录入/期初调整） | **本期新增** |
+
+### direction（增减方向）
+
+| 值 | 含义 |
+|----|------|
+| `INCREASE` | 净额增（期初构成行恒为此值） |
+| `DECREASE` | 净额减 |
+
+## 7. 错误码
+
+| 错误码 | 文案 | 触发场景 |
+|--------|------|----------|
+| 596005 | 账套或往来对象类型非法/本期未开放 | `partyType` 传 `STAFF` / `SUPPLIER_RECV` / 空 / 其他非法值 |
+| 596009 | 入账日期区间倒置 | entries/page 的 `entryDateStart` 晚于 `entryDateEnd` |
+
+## 8. 示例
+
+### 8.1 典型：供应商往来净额列表
+
+请求：
+
+```
+GET /admin/finance/statements/page?partyType=SUPPLIER&page=1&pageSize=20
+```
+
+响应 200（测试服真实数据）：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "list": [
+      {
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928540674",
+        "refName": "天边草原勇士车穿越",
+        "openingAmount": 1322.00,
+        "increaseTotal": 0,
+        "decreaseTotal": 0,
+        "writeoffTotal": 0,
+        "adjustTotal": 0,
+        "netAmount": 1322.00
+      },
+      {
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928000001",
+        "refName": "寻龙诀航拍",
+        "openingAmount": 3333.00,
+        "increaseTotal": 0,
+        "decreaseTotal": 0,
+        "writeoffTotal": 0,
+        "adjustTotal": 0,
+        "netAmount": 3333.00
+      },
+      {
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928000002",
+        "refName": "天边草原下午茶",
+        "openingAmount": -10000.00,
+        "increaseTotal": 0,
+        "decreaseTotal": 0,
+        "writeoffTotal": 0,
+        "adjustTotal": 0,
+        "netAmount": -10000.00
+      }
+    ],
+    "total": 3
+  }
+}
+```
+
+读法：
+- 勇士车穿越 net=+1322：应付侧期初 2522 − 应收侧期初 1200 = **我欠他 1322**（该付未付）。
+- 寻龙诀航拍 net=+3333：纯期初供应商，欠他 3333。
+- 天边草原下午茶 net=**−10000**：**他欠我 10000**（多付/预付），前端标红。
+
+### 8.2 边界：纯期初供应商明细——期初构成行可见
+
+请求（勇士车穿越，refId=2105165036928540674）：
+
+```
+GET /admin/finance/statements/entries/page?partyType=SUPPLIER&refId=2105165036928540674&page=1&pageSize=20
+```
+
+响应 200（4 条 OPENING 期初构成行：应付侧期初录入 2222 + 期初调整 300；应收侧期初录入 1000 + 期初调整 200）：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "list": [
+      {
+        "id": "2105165037000000004",
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928540674",
+        "refName": "天边草原勇士车穿越",
+        "entryDate": "2026-09-01",
+        "sourceType": "OPENING",
+        "sourceId": "2105165037000000004",
+        "sourceNo": "2105165037000000004",
+        "direction": "INCREASE",
+        "amount": 300.00,
+        "teamNo": null,
+        "summary": "期初调整"
+      },
+      {
+        "id": "2105165037000000003",
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928540674",
+        "refName": "天边草原勇士车穿越",
+        "entryDate": "2026-09-01",
+        "sourceType": "OPENING",
+        "sourceId": "2105165037000000003",
+        "sourceNo": "2105165037000000003",
+        "direction": "INCREASE",
+        "amount": 2222.00,
+        "teamNo": null,
+        "summary": "期初录入"
+      },
+      {
+        "id": "2105165037000000002",
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928540674",
+        "refName": "天边草原勇士车穿越",
+        "entryDate": "2026-09-01",
+        "sourceType": "OPENING",
+        "sourceId": "2105165037000000002",
+        "sourceNo": "2105165037000000002",
+        "direction": "INCREASE",
+        "amount": 200.00,
+        "teamNo": null,
+        "summary": "期初调整"
+      },
+      {
+        "id": "2105165037000000001",
+        "partyType": "SUPPLIER",
+        "refId": "2105165036928540674",
+        "refName": "天边草原勇士车穿越",
+        "entryDate": "2026-09-01",
+        "sourceType": "OPENING",
+        "sourceId": "2105165037000000001",
+        "sourceNo": "2105165037000000001",
+        "direction": "INCREASE",
+        "amount": 1000.00,
+        "teamNo": null,
+        "summary": "期初录入"
+      }
+    ],
+    "total": 4
+  }
+}
+```
+
+读法：应付侧期初 = 2222（录入）+ 300（调整）= 2522；应收侧期初 = 1000 + 200 = 1200；轧差 2522 − 1200 = 1322，与列表页 netAmount 一致。期初行 `amount` 是**该行所属账套方向的金额**（应付账行取应付金额、应收账行取应收金额），direction 已折算成对净额的方向，前端直接按 direction 渲染「净额+」徽标即可，不用自己再轧一次。
+
+### 8.3 业务失败：传旧账套值 SUPPLIER_RECV / 未开放 STAFF
+
+请求：
+
+```
+GET /admin/finance/statements/page?partyType=SUPPLIER_RECV&page=1&pageSize=20
+```
+
+响应：
+
+```json
+{
+  "code": 596005,
+  "message": "账套或往来对象类型非法/本期未开放"
+}
+```
+
+`partyType=STAFF` 同样报 596005。旧入参名 `ledgerType` 已删，只传 `ledgerType=SUPPLIER` 不带 `partyType` 会因缺少必填参数报参数校验错误（partyType 不能为空）。
+
+## 9. 业务边界
+
+**适用**：
+- 管理后台财务查看供应商往来（应付+应收轧差净额）与客户往来（应收）的账页余额与明细流水。
+- 查看往来对象期初挂账的构成（期初录入/期初调整各多少）。
+
+**不适用**：
+- 员工/司导往来查询——`STAFF` 不开放（报 596005）；司导往来走**独立接口** `GET /admin/finance/guide-ledger/*`（本期新增菜单「司导往来」对应页面调它，**不是**本台账接口）。
+- 按账套（ledgerType 维度）拆账——本接口只提供对象净额视图，无账套级查询入口。
+
+**特殊边界**：
+- `writeoffTotal` / `adjustTotal` 本期恒 0（核销/调账能力后续开放），前端列照渲染 0 即可。
+- 明细 `direction`/`sourceType` 筛非法值**不报错**，返回空页（期初行恒 INCREASE/OPENING 且无团号：筛 `direction=DECREASE`、`sourceType≠OPENING` 或填 `teamNo` 时结果不含期初行）。
+- `refId` / `id` / `sourceId` 均为 Long 序列化字符串，前端按字符串处理，禁转 number（精度丢失）。
+- 期初构成行无独立单号，`sourceNo` 回退为 opening_id 字符串，不要用 sourceNo 跳期初单据详情。
+
+## 10. 修改前后对比
+
+### 字段级对比
+
+| 项 | 原来（#8719 契约） | 现在（#8751） |
+|----|---------------------|----------------|
+| 入参名 | `ledgerType` | **`partyType`**（ledgerType 作废，传了不生效） |
+| 入参取值域 | `SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER` 三账套 | `SUPPLIER` / `CUSTOMER` **两对象**；`SUPPLIER_RECV` 改为报 596005 |
+| 出参类型字段 | `ledgerType`（可能三值） | `partyType`（只会 SUPPLIER/CUSTOMER） |
+| 供应商行金额口径 | 应付、应收**分两本账**各查各的 | 应付 − 应收**轧差合并**为一个净额行 |
+| 明细行构成 | 仅业务流水（纯期初对象明细空白） | 业务流水 + 期初构成行（sourceType=OPENING）UNION |
+| sourceType 取值 | `PAYMENT` / `PREPAY` | 新增 `OPENING` |
+| 符号语义 | 按账套分化三套口径 | 按对象两套口径：供应商 正=我欠他；客户 正=他欠我 |
+
+### 行为级对比
+
+| 行为 | 原来 | 现在 |
+|------|------|------|
+| 传 `SUPPLIER_RECV` 查供应商应收 | 正常返回应收账套 | **报 596005**（已并入 SUPPLIER 净额） |
+| 查供应商「总欠多少」 | 前端拿应付、应收两行自己算差 | 后端直接返回轧差后净额一行 |
+| 纯期初供应商点详情 | 明细空白 | 看到 OPENING 期初录入/调整构成行 |
+| 传 `STAFF` | 报 596005 | 仍报 596005（不变） |
+| CUSTOMER 客户往来 | 正常返回（#8719 新增） | 行为不变，口径不变 |
+
+## 11. 影响评估 / 回滚
+
+- **破坏兼容**：**是**。入参改名 + 取值收敛，按 #8719 交付的前端代码不改必坏：
+  1. 入参 `ledgerType=xxx` → `partyType=xxx`；
+  2. 三账套页签（供应商应付/供应商应收/客户应收）→ **两对象页签**（供应商往来/客户往来），供应商应收页签下掉；
+  3. 正负含义判断从「按 ledgerType 三分支」改为「按 partyType 两分支」（供应商 正=我欠他 / 客户 正=他欠我，负值标红）；
+  4. 明细列表渲染逻辑需兼容 `sourceType=OPENING` 行（无团号、无业务单号，summary=期初录入/期初调整）。
+- **菜单配合**：/finance/current-account 下现有三个对象菜单——供应商往来 /finance/current-account/supplier（既有，页面改净额视图）、司导往来 /finance/current-account/guide（本期新增，调独立 guide-ledger 接口，不在本次契约内）、客户往来 /finance/current-account/customer（本期新增）。
+- **回滚方案**：后端回滚 = 恢复 #8719 的 ledgerType 三账套契约；无 DDL、无数据迁移（净额为查询时现算，不存列），回滚无副作用。前端若已上净额视图，回滚后需恢复三账套页签——**建议前后端同批上线/同批回滚，不要错开**。
+
+## 12. 注意事项
+
+1. **符号判断按 partyType 两分支**：供应商 正=我欠他（该付未付）/ 负=他欠我；客户 正=他欠我（该收未收）/ 负=我多收。负值一律标红。不要残留 #8719 的三账套判断逻辑。
+2. **供应商应收页签下掉**：`SUPPLIER_RECV` 不再是合法查询值，页面上供应商应收入口必须删（传了吃 596005）。供应商的应收金额已通过轧差体现在 SUPPLIER 净额里。
+3. **明细兼容 OPENING 行**：期初构成行 `teamNo=null`、`sourceNo`=opening_id、`direction` 恒 INCREASE，渲染时按 sourceType 字典显示「期初」徽标即可；筛团号/筛 DECREASE 时不出期初行属预期。
+4. **纯期初对象明细有数据了**：不要再对「明细空」做空态兜底以外的特殊处理——空明细只出现在该对象真的既无流水又无期初时（正常不会进列表）。
+5. **司导往来别调本接口**：司导走 `/admin/finance/guide-ledger/*` 独立接口（另有契约），本台账 partyType 没有也不接受 STAFF。
+6. **ID 按字符串处理**：`refId`/`id`/`sourceId` 是 Long 序列化字符串，转 number 会精度丢失。
+7. 页签展示名建议：SUPPLIER=供应商往来 / CUSTOMER=客户往来。
+
+## 13. 关联 / 联系人
+
+- Issue：https://git.1814.love/wx/HL/issues/8751
+- PR：https://git.1814.love/wx/HL/pulls/8772
+- Commit：https://git.1814.love/wx/HL/commit/67cf0ee7be
+- 被反转契约：#8719（`changelogs-v2/2026-10/02_8719_应收侧往来台账放开-修改接口-管理后台.md`，frontend_status 已标 superseded）
+- 后端负责人：@yst