# 考勤请假规则接口文档

本文档覆盖 HRO 管理后台请假规则相关接口，对应页面：

```text
/dhr/attendancePro/admin/pc/home.html#/leaveRuleDetail   (请假规则组)
/dhr/attendancePro/admin/pc/home.html#/leaveRuleCategory (普通假模板)
/dhr/attendancePro/admin/pc/home.html#/leaveRuleTX       (调休假)
/dhr/attendancePro/admin/pc/home.html#/leaveRuleParental (育儿假)
/dhr/attendancePro/admin/pc/home.html#/leaveRuleCity     (城市额度规则)
/dhr/attendancePro/admin/pc/home.html#/leaveRuleLactation(哺乳假)
```

## 基本信息

本地服务地址：

```text
http://127.0.0.1:8080
```

除 `/api/auth/login` 外，接口需要携带 Bearer Token：

```http
Authorization: Bearer <token>
```

当前请假规则数据为 **内存 Fixture 存储**，服务重启后恢复默认值。**不包含真实假期计算引擎**，仅支撑请求/响应形状兼容和前端联调。

## 通用响应

EHR 旧接口响应：

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

门户 `.do` 接口响应：

```json
{
  "async": false,
  "errcode": 0,
  "msg": {},
  "success": true,
  "waitSecond": 0
}
```

## 假期模板行字段

normal / tx / parental 三类假期模板列表行包含以下前端模型字段（除已有 `id/code/prefix/name/unit/unitName/dayHours` 外）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `eId` | string | 等同 id |
| `leaveType` | string | normal / tx / parental / lactation |
| `leaveTypeName` | string | 普通假 / 调休假 / 育儿假 / 哺乳假 |
| `leaveTemplateType` | string | normal / parental / lactation |
| `leaveTemplateTypeName` | string | 对应中文名 |
| `isPaid` | int | 1=带薪, 0=不带薪（事假为 0） |
| `description` | string | 描述 |
| `icon` | string | icon-default / icon-annual / icon-sick / icon-tx / icon-parental / icon-lactation |
| `balanceRule` | string | 不限制余额 / 加班时长转调休 / 按规则发放 |

### index 端点字典增强

各 `index` 端点除原有字段外，额外返回：

**leaveTemplate/index**：`leaveTypes`（含 normal/parental/tx/lactation 四种）、`icons`（6 种图标选项）、`unitClassOptions`（班次列表）、`dateTypes`、`roundingModes`。

**leaveTemplate/tx/index**：`deductTypes`（按发放时间/按日期类型/按日期类别）、`overdraftExpiryTypes`（考勤期间/本年度）、`icons`。

**leaveTemplate/parental/index**：`familyRelationOptions`（子女/养子女/继子女）、`icons`。

## 公共接口

### POST `/dhr/admin/atd/common/generateCode`

用途：新增规则时生成编码。

响应：

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

## 请假规则组

默认数据：1 条预设规则组（前缀 `AQ`，名称 "默认请假规则"）。

### POST `/dhr/admin/atd/leaveTemplateGroup/list`

列表查询，支持分页和简单过滤。

请求：

```json
{
  "pageIndex": "1",
  "pageSize": "20",
  "queryParam": [
    { "field": "state", "expression": "in", "value": "0" }
  ],
  "sortFields": []
}
```

响应核心字段：

```json
{
  "data": {
    "dataList": [
      {
        "id": "8637448601634856607",
        "code": "8637448601634856607",
        "prefix": "AQ",
        "name": "默认请假规则",
        "mgrOrgId": "9017397430310779031",
        "mgrOrgName": "津冀大区-李璨",
        "mgrOrgType": "department",
        "sourceType": "预置",
        "state": 0
      }
    ],
    "pageIndex": 1,
    "pageSize": 20,
    "total": 1
  }
}
```

### POST `/dhr/admin/atd/leaveTemplateGroup/index`

打开新增/编辑抽屉时加载下拉选项。

响应包含：`prefix`, `leaveTemplateTypes`, `leaveTemplates`, `unitTypes`, `calcTypes`, `dateTypes`, `roundingModes`。

`leaveTemplates` 目前包含 7 个普通假模板和调休假、育儿假、哺乳假 3 个特殊模板候选，供组合假配置回显。

### POST `/dhr/admin/atd/leaveTemplateGroup/save`

新增或编辑请假规则组。支持嵌套 `leaveTemplateGroup` 对象和扁平 `leaveTemplates` 列表；组合假配置 `comboLeaveInfo` 可放在顶层或 `leaveTemplateGroup` 内，保存后会在列表中原样回传。

请求示例：

```json
{
  "leaveTemplateGroup": {
    "code": "6105207492683487000",
    "name": "自定义请假规则",
    "prefix": "AQ",
    "mgrOrgId": "9017397430310779030",
    "mgrOrgName": "瑞鹤医疗测试",
    "state": 0,
    "description": "描述",
    "leaveGroupEnable": 1
  },
  "leaveTemplates": [
    {
      "leaveTemplateId": "9017397430310779028_nj",
      "name": "年假",
      "type": "normal",
      "visible": true,
      "balanceEnable": true,
      "leaveRuleMode": "independent",
      "allowOverdraft": false,
      "sort": 1
    }
  ],
  "comboLeaveInfo": {
    "enabled": true,
    "groups": [
      {
        "primaryLeaveId": "9017397430310779028_nj",
        "primaryLeaveName": "年假",
        "secondaryLeaveIds": ["9017397430310779028_sj"],
        "deductOrder": "leaveOrder"
      }
    ]
  }
}
```

### POST `/dhr/admin/atd/leaveTemplateGroup/update`

同 save，编辑已存在的规则组。

### POST `/dhr/admin/atd/leaveTemplateGroup/delete`

删除请假规则组。

请求：

```json
{ "ids": ["6105207492683487000"] }
```

## 普通假模板

默认数据：7 条预设模板（年假、事假、病假、婚假、产假、陪产假、丧假），前缀 `AP`，单位 `天`。

### POST `/dhr/admin/atd/leaveTemplate/list`

列表查询，支持分页和过滤。

### POST `/dhr/admin/atd/leaveTemplate/index`

加载下拉选项。

响应包含：`prefix`, `leaveTemplateTypes`, `leaveTemplateGroups`, `unitTypes`, `balanceSendRules`, `balanceSendWays`, `calcTypes`, `dateTypes`, `roundingModes`, `limitBalanceTypes`, `balanceOverviews`

### POST `/dhr/admin/atd/leaveTemplate/save`

新增普通假模板。

### POST `/dhr/admin/atd/leaveTemplate/update`

编辑普通假模板。

### POST `/dhr/admin/atd/leaveTemplate/delete`

删除普通假模板。

### GET `/dhr/admin/atd/leaveTemplate/balance/detail`

获取指定模板的额度配置详情。

Query: `id=9017397430310779028_nj`

兼容参数：`leaveTemplateId=9017397430310779028_nj`

响应核心字段：

```json
{
  "data": {
    "leaveTemplateId": "9017397430310779028_nj",
    "dayHours": "8",
    "unit": "day",
    "unitName": "天",
    "balanceSendRule": "immediately",
    "balanceSendWay": "full",
    "limitBalance": "0",
    "calcType": "natural",
    "convertType": "round",
    "roundingMode": "halfUp"
  }
}
```

### POST `/dhr/admin/atd/leaveTemplate/balance/update`

更新额度配置，返回大任务对象。支持透传扩展字段：`balanceRule`、`annualQuota`、`allowOverdraft`、`overdraftQuota`、`releaseType`、`cycleType`、`extendValidType`、`refreshBalance`、`scriptEnabled`。

请求：

```json
{
  "id": "9017397430310779028_nj",
  "dayHours": "8",
  "unit": "day",
  "balanceSendRule": "immediately",
  "balanceRule": "限制余额",
  "annualQuota": "5",
  "allowOverdraft": 1,
  "overdraftQuota": "3"
}
```

响应：

```json
{
  "data": {
    "id": "9000000000000000000",
    "name": "修改假期余额规则",
    "state": 1,
    "progress": 0,
    "message": "处理中"
  }
}
```

### GET `/dhr/admin/atd/leaveTemplate/rule/detail`

获取指定模板的规则配置详情。返回顶部兼容字段和嵌套 `leaveTemplate` 对象，包含 `unit`、`calcType`、`dateTypeIds`、`defaultClassId`、`convertType`、`scale`、`roundingMode`、`unitMinTime`、`unitMinTimeType`、`unitMaxTime`、`unitTime`、`dayHours`、`halfDayType`、`inGroup`、`leaveLimitType`、`leaveLimitRuleObj`、`limitBalance`、`limitCount`、`limitDay`、`overdraft`、`skipRestDay`、`skipHoliday`、`type`、`leaveTemplateType` 等字段。

Query: `id=9017397430310779028_nj`

兼容参数：`leaveTemplateId=9017397430310779028_nj`

### POST `/dhr/admin/atd/leaveTemplate/rule/update`

更新规则配置。支持透传 `unitMinTime`、`unitMinTimeType`、`unitMaxTime`、`unitTime`、`dayHours`、`halfDayType`、`overdraft`、`dateTypeIds`、`convertType`、`scale` 等字段，同时更新嵌套 `leaveTemplate` 对象。

## 调休假

默认数据：1 条预设（调休假），前缀 `AX`。

### POST `/dhr/admin/atd/leaveTemplate/tx/index`

加载调休假页签选项。

### POST `/dhr/admin/atd/leaveTemplate/tx/list`

调休假列表。

### POST `/dhr/admin/atd/leaveTemplate/tx/update`

更新调休假模板。

### GET `/dhr/admin/atd/leaveTemplate/tx/balance/detail`

获取调休假额度配置。

### POST `/dhr/admin/atd/leaveTemplate/tx/balance/update`

更新调休假额度，返回大任务。

### GET `/dhr/admin/atd/leaveTemplate/tx/leave/detail`

获取调休假规则配置。

### POST `/dhr/admin/atd/leaveTemplate/tx/leave/update`

更新调休假规则。

## 育儿假

默认数据：1 条预设（育儿假），前缀 `APA`。

### POST `/dhr/admin/atd/leaveTemplate/parental/list`

育儿假列表。

### POST `/dhr/admin/atd/leaveTemplate/parental/index`

加载育儿假页签选项。

### POST `/dhr/admin/atd/leaveTemplate/parental/update`

更新育儿假模板。

### GET `/dhr/admin/atd/leaveTemplate/parental/balance/detail`

获取育儿假额度配置。

### POST `/dhr/admin/atd/leaveTemplate/parental/balance/update`

更新育儿假额度，返回大任务。

### GET `/dhr/admin/atd/leaveTemplate/parental/rule/detail`

获取育儿假规则配置。

### POST `/dhr/admin/atd/leaveTemplate/parental/rule/update`

更新育儿假规则。

## 哺乳假

默认数据：1 条预设（哺乳假），前缀 `APL`，单位 `小时`。

### POST `/dhr/admin/atd/leaveTemplate/lactation/index`

加载哺乳假页签选项。

响应包含：`prefix=APL`、`leaveTypes`、`leaveTemplateTypes`、`unitTypes`（仅 hour）、`icons`、`familyRelationOptions`（子女/养子女/继子女）、`lactationRestPositions`（firstInAfter=第一次上班后 / lastOutBefore=最后一次下班前）、`childMonthStartDefault=0`、`childMonthEndDefault=12`。

### POST `/dhr/admin/atd/leaveTemplate/lactation/list`

哺乳假列表，默认返回 1 条。

### POST `/dhr/admin/atd/leaveTemplate/lactation/update`

更新哺乳假模板名称、图标、描述、启用状态等。

### GET `/dhr/admin/atd/leaveTemplate/lactation/balance/detail`

获取哺乳假额度配置。默认值：`unit=hour, unitName=小时, balanceRule=不限制余额, limitBalance=0`。

### POST `/dhr/admin/atd/leaveTemplate/lactation/balance/update`

更新哺乳假额度配置，返回大任务。

### GET `/dhr/admin/atd/leaveTemplate/lactation/rule/detail`

获取哺乳假规则配置。默认值：`childMonthStart=0, childMonthEnd=12, multipleChildren=false, restPositions=[firstInAfter, lastOutBefore]，restPositionHours: {firstInAfter: 0.5, lastOutBefore: 0.5}`。

### POST `/dhr/admin/atd/leaveTemplate/lactation/rule/update`

更新哺乳假规则（允许申请范围、多子女叠加、休假方式等）。

## 城市额度规则

初始为空列表，前缀 `APB`。

### POST `/dhr/admin/atd/leaveBalanceTemplate/index`

加载城市额度页签选项。

### POST `/dhr/admin/atd/leaveBalanceTemplate/list`

城市额度规则列表。

### POST `/dhr/admin/atd/leaveBalanceTemplate/checkCity`

检查城市是否可用。始终返回 `true`。

### POST `/dhr/admin/atd/leaveBalanceTemplate/save`

新增城市额度规则。

### GET `/dhr/admin/atd/leaveBalanceTemplate/detail`

获取单条城市额度规则详情。

Query: `id=...`

### POST `/dhr/admin/atd/leaveBalanceTemplate/update`

更新城市额度规则。

### POST `/dhr/admin/atd/leaveBalanceTemplate/delete`

删除城市额度规则。

## 大任务桩

用于额度更新的异步任务模拟。

### POST `/bigTask.do?method=myTaskList`

返回大任务列表。

### GET `/bigTask.do?method=getProgress`

查询任务进度。

Query: `taskId=9000000000000000000`

响应字段直接位于顶层，首次查询后任务状态变为完成 (state=5)。

## Curl 联调示例

```bash
TOKEN=$(curl -s -X POST http://127.0.0.1:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"account":"admin","password":"Admin@123456"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["token"])')

# 请假规则组列表
curl -s -X POST http://127.0.0.1:8080/dhr/admin/atd/leaveTemplateGroup/list \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"pageIndex":"1","pageSize":"20"}'

# 普通假模板列表
curl -s -X POST http://127.0.0.1:8080/dhr/admin/atd/leaveTemplate/list \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"pageIndex":"1","pageSize":"20"}'

# 获取额度详情
curl -s "http://127.0.0.1:8080/dhr/admin/atd/leaveTemplate/balance/detail?id=9017397430310779028_nj" \
  -H "Authorization: Bearer $TOKEN"

# 更新额度
curl -s -X POST http://127.0.0.1:8080/dhr/admin/atd/leaveTemplate/balance/update \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id":"9017397430310779028_nj","dayHours":"8"}'

# 大任务查询
TASK_ID=$(curl -s -X POST http://127.0.0.1:8080/dhr/admin/atd/leaveTemplate/balance/update \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id":"9017397430310779028_nj"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["id"])')

curl -s "http://127.0.0.1:8080/bigTask.do?method=getProgress&taskId=$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"
```

## 当前限制

- 数据保存在内存中，重启后恢复默认值（**Fixture 存储，无真实请假计算引擎**）。
- 城市额度默认无数据，需通过 save 接口新增。
- 大任务首次 `getProgress` 查询后即标记完成。
- 列表排序字段已原样返回但未执行排序逻辑。
- 余额规则更新不触发真实余额计算/重算。
- 哺乳假规则保存仅持久化字段，不驱动实际请假明细生成。
- 调休假扣减逻辑、组合假、跨档折算等高级计算为字段级桩，不执行真实核算。