101 行
3.3 KiB
Markdown
101 行
3.3 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6951"
|
||
title: "财务账期设置（列表 + 开新账期 + 封账）"
|
||
consumer: "admin"
|
||
author: "yst"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "21540997"
|
||
target_release: ""
|
||
verified_at: "2026-09-09"
|
||
status_note: "后端已合 dev-v3（param 参数设置域）并部署测试服。首期起始日任选；非首期须紧接上期；同时最多一个开账期。"
|
||
updated_at: "2026-09-09"
|
||
base: "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）
|