hl-api-changelog/changelogs-v2/2026-09/09_6951_财务账期设置-新增接口-管理后台.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	6951	财务账期设置（列表 + 开新账期 + 封账）	admin	yst	新增接口	deployed	verified	verified	mmg	21540997		2026-09-09	后端已合 dev-v3（param 参数设置域）并部署测试服。首期起始日任选；非首期须紧接上期；同时最多一个开账期。	2026-09-09	dev-v3

财务账期设置

1. 接口背景

财务域「账期」：财务核算的会计期间。同一时间最多一个开账期，封账后进入下一期。属财务域 param 参数设置域。

2. 变更清单

类型	接口	说明
新增	GET /admin/finance/account-periods/page	账期分页列表
新增	POST /admin/finance/account-periods	开新账期
新增	POST /admin/finance/account-periods/{id}/close	封账

3. 接口详情

3.1 分页列表 GET /page

入参（Query + 分页）：isClosed（0 开着 / 1 已封账，空=全部）/ pageNo / pageSize。

出参行（AccountPeriodRowRespVO，Long ID 序列化为 String）：

字段	类型	说明
id	String	账期ID
periodName	String	账期名称
startDate	String	起始日（yyyy-MM-dd）
endDate	String	截止日（yyyy-MM-dd，开账中为 null）
isClosed	Integer	0 开着 / 1 已封账
closedByName	String	封账操作人姓名
closedTime	String	封账时间（yyyy-MM-dd HH:mm:ss）

3.2 开新账期 POST /

入参（AccountPeriodCreateReqVO）：

字段	必填	说明
periodName	是	账期名称（≤50 字）
startDate	是	起始日（yyyy-MM-dd；须为上期截止日的次日，首期任选）

出参：{id}（新账期ID，String）。

3.3 封账 POST /{id}/close

入参（AccountPeriodCloseReqVO，可空 body）：endDate（可选，缺省=该账期起始日所在月的月末）。

4. 枚举 / 数据字典

• isClosed：0 开着 / 1 已封账

5. 错误码（段位 598100-598199）

码	含义
598101	账期不存在
598102	账期已封账
598103	存在未封账的旧账期，请先封账
598104	账期起始日与现有账期重叠或更早
598105	账期起始日须为上期截止日的次日
598106	账期截止日不能早于起始日

6. 示例

开新账期（紧接上期）

POST /admin/finance/account-periods  {"periodName":"2026-09期","startDate":"2026-09-01"}
→ 200 {"id":"2097..."}

封账（缺省月末）

POST /admin/finance/account-periods/{id}/close  {}
→ 200

起始日不紧接上期（异常）

POST /admin/finance/account-periods  {"periodName":"X","startDate":"2026-09-05"}
→ 598105 账期起始日须为上期截止日的次日

7. 注意事项

• 首期账期起始日任选；之后每期必须紧接上期截止日次日。
• 同时最多一个开账期；封账后才能开下一期。
• 长整型 ID 序列化为字符串。

8. 关联 / 联系人

• Issue：https://git.1814.love:8443/wx/HL/issues/6951
• Commit：https://git.1814.love:8443/wx/HL/commit/fc87029a68
• 负责人：腰苏图（yst）