# 假期余额档案接口文档

本文档覆盖劳动力管理 / 考勤档案 / 假期余额档案页面，对应线上路由：

```text
/dhr/attendancePro/admin/pc/home.html#/leaveBalanceRecord
```

本地前端联调路由：

```text
/workforce/archive/leave-balance
```

## 当前阶段

- 本模块当前为内存 fixture，用于支撑前端联调。
- 服务重启后恢复默认余额、明细和调休结算数据。
- 已实现接口形状、动态表头、筛选配置、分页、基础组织/日期/条件过滤，以及批量编辑、删除、调休转加班费、取消结算的内存更新。
- 真实假期发放、请假扣减顺序、删除后重排、调休转加班费对月度汇总的影响，仍属于后续计算引擎范围。

## 通用响应

```json
{
  "code": 0,
  "costTimes": 0,
  "data": {},
  "message": "请求成功"
}
```

## 假期余额

| 接口 | 说明 |
| --- | --- |
| `POST /dhr/admin/atd/leaveBalance/index` | 初始化余额列表，返回 `columns`、`tableHeadDataUrl`、`personStates`、`leaveTemplates`、`options`、`searchConfig` |
| `POST /dhr/admin/atd/leaveBalance/list` | 查询余额列表，支持 `deptId`、`startDate/endDate`、`queryParam`、`conditions`、`pageNo/pageIndex` |
| `POST /dhr/admin/atd/leaveBalance/export` | 导出当前筛选，fixture 返回大任务 |
| `POST /dhr/admin/atd/leaveBalance/log/index` | 初始化员工余额变更记录页 |
| `POST /dhr/admin/atd/leaveBalance/log/list` | 查询员工余额变更记录 |

`columns` 中余额字段使用 `otherProp.canDetail=true` 标识可穿透明细。

## 假期明细

| 接口 | 说明 |
| --- | --- |
| `POST /dhr/admin/atd/leaveBalanceDetail/index` | 初始化非调休假明细，返回假期类型、发放方式、状态、筛选配置 |
| `POST /dhr/admin/atd/leaveBalanceDetail/list` | 查询非调休假明细 |
| `POST /dhr/admin/atd/leaveBalanceDetail/reCalc` | 重新计算假期总量，fixture 返回大任务 |
| `POST /dhr/admin/atd/leaveBalanceDetail/batchEdit` | 批量编辑明细，按 `ids` + `dataList[0]` 做内存 patch |
| `POST /dhr/admin/atd/leaveBalanceDetail/delete` | 删除明细，兼容 `idList` 和 `ids` |
| `POST /dhr/admin/atd/leaveBalanceDetail/import` | 导入明细，fixture 返回大任务 |
| `POST /dhr/admin/atd/leaveBalanceDetail/export` | 导出明细，fixture 返回大任务 |

## 调休假明细

| 接口 | 说明 |
| --- | --- |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/index` | 初始化调休假明细，返回日期类型、调休单位、筛选配置 |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/list` | 查询调休记录 |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/list4JBF` | 查询调休结算加班费记录 |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/batchEdit` | 批量编辑调休记录 |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/delayToJBF` | 调休转加班费，fixture 生成结算记录并扣减当前调休余额 |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/cancelToJBF` | 取消结算，fixture 删除对应结算记录 |
| `POST /dhr/admin/atd/leaveBalanceDetail/tx/export` | 导出调休明细，fixture 返回大任务 |

导入和删除复用：

- `POST /dhr/admin/atd/leaveBalanceDetail/import`
- `POST /dhr/admin/atd/leaveBalanceDetail/delete`

## 默认数据

- 员工：李璨、赵异常。
- 假期类型：年假、病假、调休假。
- 余额列：年假余额、病假余额、调休假余额。
- 非调休明细：年假、病假各一条。
- 调休明细：工作日、休息日各一条。

## 阶段边界

fixture 不执行以下真实规则：

- 根据请假规则自动发放余额。
- 请假生效后的实时扣减和余额回滚。
- 调休假按开始日期、结转状态、周期结束日期的真实扣减顺序。
- 删除调休明细后的排班重排和新增总量置零。
- 调休转加班费对月度汇总字段的真实影响。