hl-api-changelog/changelogs-v2/2026-09/06_7164_期初建账-新增接口-管理后台.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	7164	往来期初建账（客户应收 / 供应商应付 / 员工往来 三本账）	admin	yst	新增接口	deployed	verified	verified	mmg	60ca7002		2026-09-10	verified 2026-09-10 mmg: 推翻 fin-init 预埋替换为真实契约三端点。opening.js 重写(getOpeningBalancePage/createOpeningBalance/adjustOpeningBalance)+纯函数;fin-init/index.vue 整页重写 segment 三账套页签(切签注入必填 ledgerType),INIT 新建(refId 字符串透传/应收应付至少填一项/FileUpload 佐证必填),ADJUST 调整仅 INIT 行触发存全量值非差额(evidenceUrl+reason 必填);移除现金银行预埋。opening-balance.spec 锁端点/至少填一项/调整全量。checkpoint 全绿含 Vitest 全量+生产构建。	2026-09-06	dev-v3

往来期初建账

1. 接口背景

财务域「期初建账」：系统启用财务模块时，对客户应收、供应商应付、员工往来三本账做期初余额的一次性录入与后续调整。期初金额必须附佐证材料（影像 URL），期初基准日由后端取当前未封账账期的起始日，前端无需传。

• 路径前缀：/admin/finance/opening-balances（3 个新端点）
• 服务：hl-finance（财务服务）

2. 变更清单

类型	接口	说明
新增	GET /admin/finance/opening-balances/page	往来期初分页（按账套过滤，支持类别/往来对象名筛选）
新增	POST /admin/finance/opening-balances	往来期初一次录入（同往来对象仅可录入一次初始期初）
新增	POST /admin/finance/opening-balances/adjust	往来期初调整单（须已录入初始期初；存调整全量值非差额）

3. 接口详情

3.1 期初分页 GET /page

• 使用场景：管理后台「期初建账」三个页签（客户应收 / 供应商应付 / 员工往来）的列表查询，页签切换 = 换 ledgerType。
• 认证：管理后台管理员 Token（Authorization: Bearer <admin-token>），未登录返 401。
• 幂等性：查询接口，天然幂等。
• 限流：网关默认限流，无特殊配置。

3.2 期初一次录入 POST /

• 使用场景：首次为某往来对象建立期初余额（INIT 行）。同一 (ledgerType, refId) 仅允许一条 INIT，重复录入报 598401。
• 认证：同上。幂等性：非幂等（重复提交报 598401 不会产生重复 INIT 行，前端提交后应禁用按钮）。
• 限流：网关默认。

3.3 期初调整单 POST /adjust

• 使用场景：已录入 INIT 后修正期初金额。存的是调整后全量值（非差额），每次调整落一行 kind=ADJUST，当前净额 = INIT + ΣADJUST 由后端现算。
• 认证：同上。幂等性：非幂等（每次提交落一行调整记录）。
• 限流：网关默认。

4. 接口入参

4.1 分页 Query（OpeningBalancePageReqVO）

字段	类型	必填	约束	说明
ledgerType	String	是	CUSTOMER/SUPPLIER/STAFF	账套：CUSTOMER 客户应收 / SUPPLIER 供应商应付 / STAFF 员工往来
kind	String	否	INIT/ADJUST	类别：INIT 初始 / ADJUST 期初调整；空=全部
refName	String	否	模糊匹配	往来对象名筛选；空=不限
page	Number	否	≥1，默认 1	页码
pageSize	Number	否	默认 20	每页条数

4.2 一次录入 Body（OpeningBalanceCreateReqVO）

字段	类型	必填	约束	说明
ledgerType	String	是	同上枚举	账套
refId	Number	是	—	往来对象 ID（客户/供应商/员工主键，按账套对应）
refName	String	是	≤128 字	往来对象名称（冗余快照，落库后不随主数据改名）
openingPayable	Number	条件	>0	期初应付（我欠他）；与 openingReceivable 至少填一项
openingReceivable	Number	条件	>0	期初应收（他欠我们）；与 openingPayable 至少填一项
evidenceUrl	String	是	—	佐证材料影像 URL（必传，缺失抛 598402）
remark	String	否	≤200 字	备注

4.3 调整单 Body（OpeningBalanceAdjustReqVO）

字段	类型	必填	约束	说明
ledgerType	String	是	同上枚举	账套
refId	Number	是	—	往来对象 ID（须已存在 INIT 行，否则 598404）
openingPayable	Number	否	>0	调整后全量期初应付（不调整传 null）
openingReceivable	Number	否	>0	调整后全量期初应收（不调整传 null）
evidenceUrl	String	是	—	佐证材料影像 URL（必传，缺失抛 598402）
reason	String	是	≤200 字	调整原因（必填留痕）

5. 出参字段

5.1 分页行（OpeningBalanceRowRespVO）

字段	类型	说明
id	String	期初行 ID（雪花 ID，Long 序列化为字符串防 JS 精度丢失）
ledgerType	String	账套码（CUSTOMER/SUPPLIER/STAFF）
refId	String	往来对象 ID（雪花字符串）
refName	String	往来对象名称快照
openingDate	String	期初基准日（yyyy-MM-dd，= 当前未封账账期起始日，后端带入）
kind	String	类别：INIT 初始 / ADJUST 期初调整
openingPayable	Number	期初应付（无 = null）
openingReceivable	Number	期初应收（无 = null）
evidenceUrl	String	佐证材料影像 URL
recordedByName	String	录入人姓名快照
createTime	String	创建时间（yyyy-MM-dd HH:mm:ss）

分页包裹：data.records[] / data.total / data.page / data.pageSize。

5.2 录入 / 调整响应（OpeningBalanceIdRespVO）

字段	类型	说明
id	String	新落库期初行 ID（雪花字符串）

6. 枚举 / 数据字典

ledgerType（账套，代码枚举）

值	中文	说明
CUSTOMER	客户应收	客户欠我们的期初
SUPPLIER	供应商应付	我们欠供应商的期初
STAFF	员工往来	员工借款/备用金期初

kind（期初行类别，代码枚举）

值	中文	说明
INIT	初始期初	首次录入，同往来对象唯一
ADJUST	期初调整	调整单，存调整后全量值，可多条

7. 错误码（段位 598400-598499）

错误码	含义	触发场景
598401	该往来对象期初已录入	同 (ledgerType, refId) 重复 POST 录入 INIT
598402	佐证材料必传	evidenceUrl 为空
598403	账期已封账，不允许录入或调整期初	当前账期已封账 / 无未封账账期（视同未开账）
598404	该往来对象尚未录入初始期初，不可调整	POST /adjust 时无 INIT 行
598405	期初应付/应收须至少填一项	两项均空或均 ≤0
598406	账套类型非法，须为 SUPPLIER、CUSTOMER 或 STAFF	ledgerType 传其他值

8. 示例

8.1 典型成功（供应商应付期初录入）

POST /admin/finance/opening-balances
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "ledgerType": "SUPPLIER",
  "refId": 2094123456789012345,
  "refName": "云山景区管理有限公司",
  "openingPayable": 50000.00,
  "openingReceivable": null,
  "evidenceUrl": "https://oss.example.com/evidence/abc.jpg",
  "remark": "2026 年 8 月对账单确认"
}

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

分页查询：

GET /admin/finance/opening-balances/page?ledgerType=SUPPLIER&page=1&pageSize=20

{"code":200,"success":true,"data":{"records":[{"id":"2094300011122233445","ledgerType":"SUPPLIER","refId":"2094123456789012345","refName":"云山景区管理有限公司","openingDate":"2026-09-01","kind":"INIT","openingPayable":50000.00,"openingReceivable":null,"evidenceUrl":"https://oss.example.com/evidence/abc.jpg","recordedByName":"腰苏图","createTime":"2026-09-06 10:00:00"}],"total":1,"page":1,"pageSize":20}}

8.2 边界情况（期初调整为零 / 双项同调）

调整单传全量值，可把某项调成新值、另一项保持 null 不动：

{
  "ledgerType": "SUPPLIER",
  "refId": 2094123456789012345,
  "openingPayable": 48000.00,
  "openingReceivable": null,
  "evidenceUrl": "https://oss.example.com/evidence/def.jpg",
  "reason": "对方减免 2000 元尾款"
}

{"code":200,"success":true,"data":{"id":"2094300099988877766"}}

空分页：无数据时 records=[]、total=0，HTTP 200，前端正常渲染空列表。

8.3 业务失败（重复录入 / 未录初始就调整）

POST /admin/finance/opening-balances   # 同一 refId 再次录入

{"code":598401,"message":"该往来对象期初已录入","success":false,"data":null}

POST /admin/finance/opening-balances/adjust   # 该对象从未录入 INIT

{"code":598404,"message":"该往来对象尚未录入初始期初，不可调整","success":false,"data":null}

缺佐证材料：{"code":598402,"message":"佐证材料必传"}；两项金额均空：{"code":598405,"message":"期初应付/应收须至少填一项"}。

9. 业务边界

适用：

• 财务模块上线初始化时，批量为三本账建立期初基准。
• 期初金额有误时，通过调整单修正（保留全部调整留痕）。

不适用 / 限制：

• 同往来对象只能录入一次 INIT，后续一律走调整单。
• 账期封账后禁止录入与调整（598403）；未开账（无未封账账期）同样拦截。
• 期初基准日不可指定，由后端取当前未封账账期的 start_date。
• 期初数据暂未回流勾稽到往来账（方案 A，留 TODO 接缝），本期仅作独立台账。

特殊边界：

• refName 是冗余快照，主数据改名不影响历史期初行显示。
• 调整单存全量值不是差额，前端表单应展示「调整后金额」而非「调增/调减」。

10. 注意事项

• 所有雪花 ID（id / refId）均已序列化为字符串，前端按 String 处理，勿转 Number。
• openingDate 由后端带入，入参里没有该字段。
• 前端三个页签（客户应收 / 供应商应付 / 员工往来）对应 ledgerType 三值，建议页签切换即重置筛选条件重新查询。
• 新表 fin_opening_balance（Flyway V20260906_101），部署时自动执行，无需前端动作。

11. 关联 / 联系人

• Issue：https://git.1814.love:8443/wx/HL/issues/7164
• PR：https://git.1814.love:8443/wx/HL/pulls/7166
• Commit：https://git.1814.love:8443/wx/HL/commit/d0f06fa2e8
• Epic：https://git.1814.love:8443/wx/HL/issues/7163
• 负责人：腰苏图（yst）