hl-api-changelog/changelogs-v2/2026-10/02_8719_应收侧往来台账放开-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8719	应收侧往来台账放开——ledgerType 取值域扩为 SUPPLIER/SUPPLIER_RECV/CUSTOMER（#8719）	admin	yst	修改接口	deployed	not_required	implemented	mmg	b7bca8502a898be1e8f3d95ae0817bcdd2006cc0		2026-10-02	⚠️【本契约将被 #8751 反转，前端需返工】前端 mmg 已按本文档交付（2026-10-02），但 #8751 用户拍板方案 A：台账入参由 ledgerType 单账套三值改为 partyType 往来对象净额视图（SUPPLIER=供应商应付+应收轧差/CUSTOMER=客户应收），ledgerType 入参作废，前端台账页需按 #8751 最新 changelog 重对接。原记录：应收初始化录入的应收期初（客户应收/供应商应收）原在往来台账看不到，本期放开应收侧台账：/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 随行账套上送。	2026-10-02	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：

{
  "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（空页属正常，应收账套本期只有期初无流水）：

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

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

{
  "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

响应：

{
  "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：wx/HL#8719
• PR：wx/HL#8727
• Commit：https://git.1814.love/wx/HL/commit/029000ef1f
• 后端负责人：@yst