# 考勤加班规则接口文档

本文档根据 `/Users/huangcongqiang/Desktop/ehr-recording-2026-06-11T02-48-39-687Z.md` 中的页面录制补齐，覆盖页面：

```text
/dhr/attendancePro/admin/pc/home.html#/workRuleDetail
/dhr/attendancePro/admin/pc/home.html#/workRuleCalc
/dhr/attendancePro/admin/pc/home.html#/workRuleCategory
```

## 基本信息

本地服务地址：

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

除 `/api/auth/login` 与健康检查外，接口需要携带 Bearer Token：

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

当前考勤数据为内存数据，用于前端联调和页面流程验证；服务重启后会恢复默认数据。

## 登录

### POST `/api/auth/login`

请求：

```json
{
  "account": "admin",
  "password": "Admin@123456"
}
```

响应：

```json
{
  "code": 0,
  "message": "请求成功",
  "data": {
    "token": "...",
    "tokenType": "Bearer",
    "expiresAt": "...",
    "user": {
      "id": "1000000000000000001",
      "account": "admin",
      "name": "HRO管理员",
      "orgId": "9017397430310779028",
      "orgName": "HRO 总部"
    }
  }
}
```

## 通用响应

EHR 旧接口响应：

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

门户 `.do` 接口响应：

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

## 页面初始化接口

### GET `/n/oursContext`

Query：

```text
routerUrl=/dhr/attendancePro/admin/pc/home.html#/workRuleDetail
```

用途：返回当前组织、用户、模块开关和权限上下文。

### GET `/home.do?method=getPortalColor`

用途：返回门户主题色配置。

### POST `/home.do?method=index4PC`

用途：门户首页基础信息占位接口。

### POST `/home.do?method=findPortalLayout`

用途：门户布局占位接口。

### GET `/ehr/portalSection.do?method=toDayList`

用途：门户今日事项占位接口。

### GET `/workflow/workflowSection.do?method=myWorkflowList`

用途：门户流程列表占位接口。

### GET `/ehr/portalSection.do?method=personInfoByTimeScope`

用途：门户人员统计占位接口。

### GET `/ehr/portalSection.do?method=riskData`

用途：门户风险数据占位接口。

## 加班规则组

项目隔离：`atd_overtime_template_group` 已通过 V82 增加 `project_id`。项目管理员只读写当前
`projectId` 的加班规则组；新建规则组写入当前 `projectId`；平台全局态（`projectId=null`）不加项目过滤。
历史 `project_id IS NULL` 规则组不会自动对项目管理员可见。

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

用途：加班规则组列表，支持分页和简单过滤。

请求：

```json
{
  "pageIndex": "1",
  "pageSize": "20",
  "queryParam": [
    {
      "dataType": "ARRAYS_INTEGER",
      "display": "启用",
      "expression": "in",
      "field": "state",
      "type": 1,
      "value": "0"
    }
  ],
  "sortFields": []
}
```

响应核心字段：

```json
{
  "code": 0,
  "data": {
    "dataList": [
      {
        "id": "6165602779003438728",
        "code": "6165602779003438728",
        "prefix": "AW",
        "name": "默认加班规则",
        "mgrOrgId": "9017397430310779031",
        "mgrOrgName": "津冀大区-李璨",
        "mgrOrgType": "department",
        "sourceType": "预置",
        "state": 0,
        "projectId": null
      }
    ],
    "pageIndex": 1,
    "pageSize": 20,
    "total": 1
  },
  "message": "请求成功"
}
```

支持的过滤：

```text
field=state, expression=in
field=name, expression=like
```

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

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

响应包含：

```text
prefix
calcTemplates
convertTypes
dateTypes
officialTypes
overtimeTypes
overtimeUnitTypes
partTypes
tipTypes
```

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

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

响应：

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

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

用途：新增或编辑加班规则组。请求结构沿用录制文件中的旧系统结构。项目态编辑其它项目 id 时按
“加班规则组不存在或已删除”处理。

请求示例：

```json
{
  "overtimeTemplateGroup": {
    "code": "6105207492683486569",
    "convertType": "manual",
    "dateBelongSplitTime": "00:00",
    "dateBelongType": "workDate",
    "dayHour": 8,
    "delayJBFDateType": "overtimeDate",
    "markNoCountRest": 1,
    "maxHourCycle": 0,
    "maxHourCycleTipType": "forbid",
    "mgrOrgId": "9017397430310779030",
    "mgrOrgName": "瑞鹤医疗测试",
    "mgrOrgType": "company",
    "name": "哈哈",
    "overtimeLimitCycle": "naturalMonth",
    "prefix": "AW",
    "state": 0
  },
  "overtimeTemplateMap": {}
}
```

响应：

```json
{
  "code": 0,
  "data": {
    "id": "6105207492683487000",
    "code": "6105207492683486569",
    "prefix": "AW",
    "name": "哈哈",
    "mgrOrgName": "瑞鹤医疗测试",
    "sourceType": "自定义",
    "state": 0,
    "projectId": "当前管理员项目 id"
  },
  "message": "请求成功"
}
```

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

用途：删除加班规则组。

请求：

```json
{
  "eids": [null],
  "ids": ["6105207492683487000"]
}
```

响应：

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

## 计算规则

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

用途：计算规则页签初始化选项。

响应包含：

```text
prefix=AY
calcTypes: approve/按审批时长算加班, check/按打卡时长算加班,
  approveAndCheckIntersection/审批与打卡时间取交集,
  approveAndCheckUnion/审批与打卡时间取并集, custom/自定义计算
checkRangeTypes: all/全部打卡, firstLast/首末卡, classOutside/班次外打卡
convertTypes: manual/自定义, classHour/按当天班次时长折算
resultHandleTypes: rest/转调休, fee/转加班费, employeeChoose/员工加班单选转调休/加班费
timeHandleTypes: section/分段处理, total/合计处理
```

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

用途：计算规则列表，支持分页和简单过滤。

默认返回 1 条预置规则：

```json
{
  "id": "6165602779003438729",
  "eId": "6165602779003438729",
  "code": "6165602779003438729",
  "prefix": "AY",
  "name": "默认加班计算规则（审批与打卡取交集）",
  "calcType": "approveAndCheckIntersection",
  "calcTypeName": "审批与打卡时间取交集",
  "checkRangeType": "all",
  "checkRangeTypeName": "全部打卡",
  "convertType": "manual",
  "convertTypeName": "自定义",
  "dayHour": 8,
  "startHour": 0,
  "stepHour": 0.5,
  "resultHandleType": "rest",
  "resultHandleTypeName": "转调休",
  "timeHandleType": "section",
  "timeHandleTypeName": "分段处理",
  "sourceType": "预置",
  "state": 0
}
```

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

用途：新增或编辑计算规则。接受 flat body 或嵌套在 `overtimeCalcType`/`overtimeCalcRule` 下的请求体。

请求示例：

```json
{
  "name": "测试计算规则",
  "prefix": "AY",
  "calcType": "approve",
  "checkRangeType": "firstLast",
  "convertType": "classHour",
  "resultHandleType": "fee",
  "timeHandleType": "total",
  "dayHour": 8,
  "startHour": 0,
  "stepHour": 1.0,
  "state": 0,
  "description": "测试备注"
}
```

响应返回完整的计算规则行，含 `id/code/eId/calcTypeName` 等派生字段。
若 `id` 为空则自动生成，若 `code` 为空则自动生成编码。
新建行 `sourceType` 默认为 `自定义`。

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

用途：更新已有计算规则。行为与 `save` 相同，按 `id` 匹配已有行并更新字段。

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

用途：删除计算规则。按 `ids`（或 `eids`）删除自定义行，预置行（`sourceType=预置`）不会被删除。

请求：

```json
{
  "eids": [null],
  "ids": ["6105207492683487001"]
}
```

响应：

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

## 加班类别

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

用途：加班类别页签初始化选项。

响应包含：

```text
prefix=AU
dateTypes: workDay/工作日, restDay/休息日, holiday/节假日
```

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

用途：加班类别列表，支持分页和筛选。

默认返回三条预置类别：

```text
工作日加班 (workDay)
休息日加班 (restDay)
节假日加班 (holiday)
```

每行包含 `id/eId/code/prefix/name/display/value/dateType/dateTypeName/dateTypes/dateTypeNames/state/sourceType/description` 字段，
同时保留旧规则组下拉兼容的 `id/value/display/dateType` 字段。
其中 `dateTypes`、`dateTypeNames` 为数组，用于前端编辑回显；`dateType`、`dateTypeName` 保留单值兼容。

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

用途：新增或编辑加班类别。接受 flat body 或嵌套在 `overtimeType` 下的请求体。

请求示例：

```json
{
  "name": "测试加班类别",
  "prefix": "AU",
  "dateType": "restDay",
  "state": 0,
  "description": "测试备注"
}
```

响应返回完整的加班类别行，含 `id/code/eId/dateTypeName/dateTypes/dateTypeNames/display/value` 等派生字段。
`dateTypes`、`dateTypeNames` 以数组返回；同时返回首个日期类别的 `dateType`、`dateTypeName` 便于旧字段兼容。
若 `id` 为空则自动生成，若 `code` 为空则自动生成编码。
新建行 `sourceType` 默认为 `自定义`。

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

用途：更新已有加班类别。行为与 `save` 相同，按 `id` 匹配已有行并更新字段。

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

用途：删除加班类别。按 `ids`（或 `eids`）删除自定义行，预置行（`sourceType=预置`）不会被删除。

请求：

```json
{
  "eids": [null],
  "ids": ["6105207492683487002"]
}
```

响应：

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

## 组织选择

### GET `/dhr/user/selectPerson/init`

Query：

```text
roleType=attendanceProMgr
```

用途：打开所属组织选择弹窗时加载配置。

### POST `/dhr/user/selectPerson/getOrg`

请求：

```json
{
  "includeDisabledDepartment": false,
  "otherParam": "group",
  "roleType": "attendanceProMgr",
  "type": "group"
}
```

响应默认返回：

```text
河北瑞鹤医疗器械有限公司
瑞鹤医疗测试
```

## 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/overtimeTemplateGroup/list \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"pageIndex":"1","pageSize":"20","queryParam":[{"field":"state","expression":"in","value":"0"}],"sortFields":[]}'
```

## 当前限制

- 数据保存在内存中，重启后恢复默认值。
- 计算规则和加班类别已支持完整的 save/update/delete 操作；预置行（`sourceType=预置`）受删除保护。
- 列表排序字段已原样返回，但当前未执行排序逻辑。
- 默认本地 profile 不检查 Redis，`/actuator/health` 可用于基础服务健康检查；`prod` profile 默认开启 Redis 健康检查。