wx/hl-api-changelog

派生 0

文件

T

Mimingguang 8b683169ea

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): #8751 回写前端 implemented(mmg,ref 7ed2db889)

2026-10-04 14:58:10 +08:00

21 KiB

原始文件 Blame 文件历史

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	8751	往来台账升级为按往来对象净额视图——入参 ledgerType 改名 partyType（反转 #8719）	admin	yst	修改接口	deployed	not_required	implemented	mmg	7ed2db889cc4a7b7bdb33bf6d6ed56300ed9a899	v2.1	2026-10-04	反转 #8719 单账套契约：#8719 的 ledgerType 三账套入参（SUPPLIER/SUPPLIER_RECV/CUSTOMER）作废，前端 mmg 已按 #8719 交付的三账套页签需返工，改按本契约 partyType 两对象净额视图重对接。核心：供应商应收+应付是同一本供应商往来的两个方向，合并轧差算净额（应付−应收，正=我欠他/负=他欠我）；入参 ledgerType→partyType 破坏性改名；明细新增期初构成行（sourceType=OPENING），纯期初供应商点详情不再空白。前端已交付(2026-10-04)：statement.js 契约层重写 PARTY_TYPE 两值字典+净额 meta 对象两分支(负值一律标红)+sourceType 加 OPENING;新建 _shared/StatementLedger.vue 共享页体,supplier 页重写为薄壳(三账套页签下掉固定 SUPPLIER,storage-key 留旧键,行内核销保留),新建 customer 薄壳页(菜单本期新增);writeoff/opening 的 ledgerType 是各自 API 自身契约零适配,提交 7ed2db889。	2026-10-04	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（测试服真实数据）：

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

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

响应：

{
  "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. 注意事项

符号判断按 partyType 两分支：供应商正=我欠他（该付未付）/ 负=他欠我；客户正=他欠我（该收未收）/ 负=我多收。负值一律标红。不要残留 #8719 的三账套判断逻辑。
供应商应收页签下掉：SUPPLIER_RECV 不再是合法查询值，页面上供应商应收入口必须删（传了吃 596005）。供应商的应收金额已通过轧差体现在 SUPPLIER 净额里。
明细兼容 OPENING 行：期初构成行 teamNo=null、sourceNo=opening_id、direction 恒 INCREASE，渲染时按 sourceType 字典显示「期初」徽标即可；筛团号/筛 DECREASE 时不出期初行属预期。
纯期初对象明细有数据了：不要再对「明细空」做空态兜底以外的特殊处理——空明细只出现在该对象真的既无流水又无期初时（正常不会进列表）。
司导往来别调本接口：司导走 /admin/finance/guide-ledger/* 独立接口（另有契约），本台账 partyType 没有也不接受 STAFF。
ID 按字符串处理：refId/id/sourceId 是 Long 序列化字符串，转 number 会精度丢失。
页签展示名建议：SUPPLIER=供应商往来 / CUSTOMER=客户往来。

13. 关联 / 联系人

Issue：wx/HL#8751
PR：wx/HL#8772
Commit：https://git.1814.love/wx/HL/commit/67cf0ee7be
被反转契约：#8719（changelogs-v2/2026-10/02_8719_应收侧往来台账放开-修改接口-管理后台.md，frontend_status 已标 superseded）
后端负责人：@yst

21 KiB 原始文件 Blame 文件历史 Unescape Escape