wx/hl-api-changelog

派生 0

文件

T

yaosutu 315e9dbb2e

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

详情

财务初始化三tab对齐原型：纠偏前端4tab为3tab（应收初始化/应付初始化/现金银行初始化），删员工往来tab（#8507 #8511）

2026-09-30 10:32:47 +08:00

14 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	8507	财务初始化页面 tab 结构纠偏：应为 3 tab（应收初始化/应付初始化/现金银行初始化），删「员工往来」tab，应收初始化内按往来对象选 CUSTOMER/SUPPLIER_RECV（#8507 #8511）	admin	yst(GIT)	修改接口	deployed	not_required	pending				2026-09-30	财务初始化（菜单：参数设置/财务初始化）前端页面 tab 结构与原型不符的纠偏单。原型只有 3 个 tab（应收初始化/应付初始化/现金银行初始化），按「初始化场景」划分，初始化里没有「员工往来」期初（员工借款/备用金属付款管理业务流程，不在初始化）。当前前端做成了 4 个 tab（客户应收/供应商应付/供应商应收/员工往来），按「往来对象类型」划分，需重构。后端接口零改动、已全部部署测试服并验证通过：应收/应付走 /admin/finance/opening-balances（按 ledgerType 区分 CUSTOMER/SUPPLIER_RECV/SUPPLIER），现金银行走 /admin/finance/fund-accounts（账户期初结存），两套接口互相独立。本文自包含全部入参/出参/枚举/错误码/示例。	2026-09-30	dev-v3

finance：财务初始化三 tab 对齐原型（管理后台）

性质：前端实现纠偏。后端接口无新增/无变更，已在测试服就绪。本文告诉前端「正确的 tab 结构 + 每个 tab 怎么调既有接口」。

1. 接口背景

财务初始化是账套启用前录入期初数据的入口（菜单：参数设置 / 财务初始化）。

原型 finance-prototype.html（页面 id cfg-fininit）规定财务初始化只有 3 个 tab，按「初始化场景」划分：

财务初始化
├─ 应收初始化      启用前欠我们的款（客户欠款 + 供应商杂项应收）
├─ 应付初始化      启用前我们欠供应商的款
└─ 现金银行初始化  各资金账户启用前已有结存

当前前端实现错误：做成了 4 个 tab（客户应收 / 供应商应付 / 供应商应收 / 员工往来），按「往来对象类型」划分。两处偏差：

tab 划分维度错了——应按「初始化场景」（应收/应付/现金银行），不是按「往来对象类型」（客户/供应商/员工）。
多出了「员工往来」tab——原型财务初始化没有员工往来期初。员工借款/备用金是「付款管理 / 员工借款」的业务单据流（页面 loan-stf / payex-stfloan），不属于财务初始化。

「供应商应收」不是独立 tab：它是「应收初始化」tab 内部、往来对象选「供应商」时的一种（供应商欠我们的杂项应收：押金退还/赔偿款/口车费/其他应收）。

2. 变更清单（前端 tab 结构改动）

#	改动	说明
1	删除「员工往来」tab	初始化无此场景
2	tab 改 3 个并改名	`应收初始化` / `应付初始化` / `现金银行初始化`
3	「客户应收」+「供应商应收」合并进「应收初始化」一个 tab	tab 内用「往来对象」下拉（客户/供应商）切换 ledgerType
4	「供应商应付」改名「应付初始化」	固定 ledgerType=SUPPLIER，去掉对象细分字段
5	新增「现金银行初始化」tab	接 `/admin/finance/fund-accounts` 系列接口（账户期初结存）

3. tab ↔ 接口 / 账套映射（核心）

前端 tab	tab 内「往来对象」	调接口	传 `ledgerType`
应收初始化	客户	`POST /admin/finance/opening-balances` 等	`CUSTOMER`
应收初始化	供应商	同上	`SUPPLIER_RECV`
应付初始化	（固定供应商，无此下拉）	同上	`SUPPLIER`
现金银行初始化	—	`/admin/finance/fund-accounts` 系列	—（无 ledgerType 概念）

应收初始化一个 tab 对应两个 ledgerType，按用户选的「往来对象」决定传哪个；金额字段填 openingReceivable。应付初始化固定 SUPPLIER，金额填 openingPayable。

4. 应收初始化 tab（ledgerType = CUSTOMER / SUPPLIER_RECV）

4.1 列表（分页）

GET /admin/finance/opening-balances/page

入参（query）：

字段	类型	必填	说明
pageNo	int	是	页码
pageSize	int	是	每页
ledgerType	string	是	`CUSTOMER` 或 `SUPPLIER_RECV`
kind	string	否	`INIT` 初始 / `ADJUST` 期初调整；空=全部
refName	string	否	往来对象名模糊搜索

应收初始化 tab 顶部建议加「往来对象」筛选（全部/客户/供应商）：客户→CUSTOMER、供应商→SUPPLIER_RECV、全部→两个 ledgerType 各查一次合并。

出参（data.records[]）：

字段	类型	说明
id	string	期初行 ID
ledgerType	string	账套回显
refId	string	往来对象 ID
refName	string	往来对象名称
customerCategory	string	对象细分编码（CUSTOMER=客户分类 / SUPPLIER_RECV=应收性质；SUPPLIER 为 null）
customerCategoryName	string	对象细分中文名（列表直接显示这个；字典不可用为 null）
companyId	string	所属公司主体 ID
companyName	string	所属公司主体名
openingDate	string	期初基准日（=当前未封账账期起始日），只读
kind	string	`INIT` / `ADJUST`
openingPayable	number	期初应付（应收 tab 恒 null，忽略）
openingReceivable	number	期初应收（本 tab 显示这个金额）
evidenceUrl	string	佐证材料影像 URL（可空）
recordedByName	string	录入人姓名
createTime	string	创建时间

4.2 新建期初

POST /admin/finance/opening-balances

表单（按原型应收表单三段递进）：

往来对象（下拉必填）：客户 / 供应商
对象细分（下拉必填，标签随往来对象变）：
- 客户 → 标签「客户分类」，选项 = 字典 fin_customer_category
- 供应商 → 标签「应收性质」，选项 = 字典 fin_recv_nature
往来对象名称（下拉必填）：
- 供应商 → GET /admin/supplier/items/list?status=ACTIVE（取 supplierId + shortName/fullName）
- 客户 → 客户列表（按所选客户分类过滤）
应收欠款（数字必填，>0）
所属公司（下拉单选必填）：GET /v3/admin/travel-agency/enabled（取 agencyId+agencyName）
记账日期（只读）：前端不传，后端落 openingDate=当前账期起始日
备注（文本域选填，≤200 字）

请求体：

字段	类型	必填	说明
ledgerType	string	是	`CUSTOMER`（选了客户）/ `SUPPLIER_RECV`（选了供应商）
refId	Long	是	往来对象 ID
refName	string	是	往来对象名称（≤128）
customerCategory	string	条件必填	对象细分编码：CUSTOMER→fin_customer_category 编码；SUPPLIER_RECV→fin_recv_nature 编码。两账套均必填
companyId	Long	是	所属公司主体 ID
openingReceivable	number	是	期初应收金额，>0
openingPayable	—	否	应收 tab 不传（传了后端也忽略不落库）
evidenceUrl	string	否	佐证材料影像 URL
remark	string	否	备注（≤200）

响应：data.id = 新建期初行 ID。

请求示例（供应商应收）：

{
  "ledgerType": "SUPPLIER_RECV",
  "refId": 2104918057506041857,
  "refName": "柴河星悦酒店",
  "customerCategory": "DEPOSIT_REFUND",
  "companyId": 2051922156798779394,
  "openingReceivable": 1.01,
  "remark": "押金退还期初"
}

响应示例：

{ "code": 200, "message": "成功", "data": { "id": "2105077077235662849" }, "success": true }

4.3 期初调整

POST /admin/finance/opening-balances/adjust

字段	类型	必填	说明
ledgerType	string	是	同新建
refId	Long	是	往来对象 ID（须已有 INIT 行，否则 598404）
openingReceivable	number	条件	调整后期初应收（全量值非差额）；CUSTOMER/SUPPLIER_RECV 落库
openingPayable	number	条件	调整后期初应付；仅 SUPPLIER 落库
evidenceUrl	string	否	佐证影像
reason	string	是	调整原因（≤200）

分类/性质/公司沿用 INIT 行快照，调整单不开放改。

5. 应付初始化 tab（ledgerType = SUPPLIER）

接口同应收（/admin/finance/opening-balances 一套），差异：

项	应付初始化
ledgerType	固定 `SUPPLIER`
往来对象	固定「供应商」，无客户/供应商下拉；直接供应商列表 `GET /admin/supplier/items/list?status=ACTIVE`
customerCategory	不传（SUPPLIER 忽略，供应商类别随供应商档案带出不手选）
金额字段	传 `openingPayable`（期初应付，>0），不传 `openingReceivable`

列表看 openingPayable（openingReceivable 恒 null）。

6. 现金银行初始化 tab（走资金账户接口，独立）

此 tab 是资金账户的期初结存，与应收/应付的 opening-balances 完全独立，接 /admin/finance/fund-accounts：

操作	接口	说明
列表	`GET /admin/finance/fund-accounts/page`	本 tab 列表（列：账户名称/类型/期初结存/操作）
新建账户（录期初结存）	`POST /admin/finance/fund-accounts`	建户时录账户信息+期初结存
期初调整	`POST /admin/finance/fund-accounts/{id}/opening-adjust`	唯一改期初途径，落 OPENING 留痕流水
建户表单三组下拉	`GET /admin/finance/fund-accounts/options`	accountType/nature/channel（字典 fin_fund_account_*）

⚠️ opening-adjust 差额为 0 时返 595105（不落流水），非 200 幂等——前端需区分「200 调整成功」vs「595105 无需调整」，不要把 595105 当失败弹错。

7. 枚举 / 数据字典

7.1 ledgerType（账套，OpeningLedgerTypeEnum）

所属字段：ledgerType | 类型：String | 必填：✅

值	中文	金额字段	用于 tab
`SUPPLIER`	供应商应付（我欠他）	openingPayable	应付初始化
`CUSTOMER`	客户应收（他欠我们）	openingReceivable	应收初始化（往来对象=客户）
`SUPPLIER_RECV`	供应商应收（他欠我们：押金退还/赔偿款/口车费/其他应收）	openingReceivable	应收初始化（往来对象=供应商）

7.2 kind（类别）

所属字段：kind | 类型：String | 必填：❌（查询过滤用）

值	中文	说明
`INIT`	初始	首次录入（同对象仅一次）
`ADJUST`	期初调整	对已有 INIT 的调整留痕

7.3 应收性质（字典 fin_recv_nature，SUPPLIER_RECV 的 customerCategory）

值	中文
`DEPOSIT_REFUND`	押金退还
`COMPENSATION`	赔偿款
`CAR_FEE`	口车费
`OTHER`	其他应收

7.4 客户分类（字典 fin_customer_category，CUSTOMER 的 customerCategory）

经 GET /admin/dict/all 或字典接口取 fin_customer_category 当前生效值。

8. 下拉数据源汇总

下拉	接口 / 字典
供应商列表	`GET /admin/supplier/items/list?status=ACTIVE`
公司主体	`GET /v3/admin/travel-agency/enabled`
客户分类（应收-客户）	字典 `fin_customer_category`
应收性质（应收-供应商）	字典 `fin_recv_nature`（押金退还/赔偿款/口车费/其他应收）
资金账户类型/性质/渠道	`GET /admin/finance/fund-accounts/options`

9. 错误码

code	含义	触发场景
598401	同往来对象 INIT 已录过	重复新建初始期初
598403	账期已封账	封账后新建/调整
598404	须先录初始期初	调整时无 INIT 行
598405	期初金额须大于0	金额 ≤0
598407	公司主体非法	companyId 无效
598408	客户分类必填	CUSTOMER 缺 customerCategory
598409	供应商应收性质必填	SUPPLIER_RECV 缺 customerCategory
598410	对象细分取值非法	customerCategory 不在字典内
595105	期初调整差额为 0	现金银行 opening-adjust 无需调整（非错误）

10. 修改前后对比

项	改前（当前前端错误）	改后（对齐原型）
tab 数	4 个	3 个
tab 名	客户应收/供应商应付/供应商应收/员工往来	应收初始化/应付初始化/现金银行初始化
划分维度	往来对象类型	初始化场景
员工往来 tab	有（多出）	删除
供应商应收	独立 tab	并入应收初始化（往来对象=供应商，ledgerType=SUPPLIER_RECV）
现金银行初始化	缺	新增（接 fund-accounts 期初）

11. 影响评估 / 回滚

后端接口变更：无（零改动，已 deployed）
是否破坏向后兼容：前端页面重构，接口契约不变
前端是否必须同步上线：是（当前 4 tab 结构与后端账套语义不符，「员工往来」tab 调任何接口都会失败——后端无员工往来账套）

12. 注意事项

金额字段二选一：应收 tab 填 openingReceivable、应付 tab 填 openingPayable，不要同传两个（后端按 ledgerType 只落对应方向，另一方向忽略）。
记账日期只读、前端不传，后端落当前账期起始日。
同一往来对象 INIT 仅可录一次；要改走「期初调整」。
「现金银行初始化」与「应收/应付初始化」是两套独立接口（fund-accounts vs opening-balances），不要混用。

14 KiB

原始文件 Blame 文件历史

finance：财务初始化三 tab 对齐原型（管理后台）

1. 接口背景

2. 变更清单（前端 tab 结构改动）

3. tab ↔ 接口 / 账套映射（核心）

4. 应收初始化 tab（ledgerType = CUSTOMER / SUPPLIER_RECV）

4.1 列表（分页）

4.2 新建期初

4.3 期初调整

5. 应付初始化 tab（ledgerType = SUPPLIER）

6. 现金银行初始化 tab（走资金账户接口，独立）

7. 枚举 / 数据字典

7.1 ledgerType（账套，OpeningLedgerTypeEnum）

7.2 kind（类别）

7.3 应收性质（字典 fin_recv_nature，SUPPLIER_RECV 的 customerCategory）

7.4 客户分类（字典 fin_customer_category，CUSTOMER 的 customerCategory）

8. 下拉数据源汇总

9. 错误码

10. 修改前后对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

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

finance：财务初始化三 tab 对齐原型（管理后台）

1. 接口背景

2. 变更清单（前端 tab 结构改动）

3. tab ↔ 接口 / 账套映射（核心）

4. 应收初始化 tab（ledgerType = CUSTOMER / SUPPLIER_RECV）

4.1 列表（分页）

4.2 新建期初

4.3 期初调整

5. 应付初始化 tab（ledgerType = SUPPLIER）

6. 现金银行初始化 tab（走资金账户接口，独立）

7. 枚举 / 数据字典

7.1 ledgerType（账套，OpeningLedgerTypeEnum）

7.2 kind（类别）

7.3 应收性质（字典 fin_recv_nature，SUPPLIER_RECV 的 customerCategory）

7.4 客户分类（字典 fin_customer_category，CUSTOMER 的 customerCategory）

8. 下拉数据源汇总

9. 错误码

10. 修改前后对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

14 KiB

原始文件 Blame 文件历史