# 考勤补卡规则接口文档

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

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

## 基本信息

本地服务地址：

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

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

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

当前补卡规则数据为内存数据，服务重启后恢复默认值。

## 通用响应

EHR 旧接口响应：

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

## 公共接口（复用已有模块）

以下接口由登录鉴权、加班规则、请假规则模块提供，补卡规则页面可复用：

| 接口 | 说明 |
|------|------|
| `GET /n/oursContext?routerUrl=...` | 页面上下文 |
| `GET /home.do?method=getPortalColor` | 主题色 |
| `POST /dhr/admin/atd/common/generateCode` | 生成编码 |
| `GET /dhr/user/selectPerson/init` | 组织选择初始化 |
| `POST /dhr/user/selectPerson/getOrg` | 获取组织树 |

公共接口文档详见 [登录鉴权](../auth/api.md)、[加班规则](overtime-api.md)、[请假规则](leave-api.md)。

---

## 1. 补卡规则列表

```http
POST /dhr/admin/atd/cardTemplate/list
Content-Type: application/json
Authorization: Bearer <token>
```

### 请求体

```json
{
  "pageIndex": "1",
  "pageSize": "20",
  "queryParam": [
    {
      "expression": "like",
      "field": "name",
      "value": "补卡"
    }
  ],
  "sortFields": []
}
```

支持按 `name`、`state` 等字段筛选，expression 支持 `like` / `=`。

### 响应

```json
{
  "code": 0,
  "data": {
    "dataList": [
      {
        "id": "5012565295972865718",
        "code": "5012565295972865718",
        "prefix": "AH",
        "name": "默认补卡规则",
        "mgrOrgId": "9017397430310779032",
        "mgrOrgName": "新乐市中医医院",
        "mgrOrgType": "department",
        "sourceType": "预置",
        "state": 0,
        "description": "",
        "cardStateTypes": "noCheck",
        "cardTimeLimit": 3,
        "cardTimeLimitName": "3",
        "cardTimeLimitCycle": "naturalMonth",
        "cardTimeLimitEnable": 1,
        "cardTypeIds": "",
        "cardTypeIdsLimit": "",
        "lastDateLimit": -1,
        "lastDateLimitEnable": 0,
        "noStatisticsTypes": "start,end"
      }
    ],
    "needTotal": true,
    "pageIndex": 1,
    "pageSize": 20,
    "queryParam": [],
    "sortFields": [],
    "total": 1
  }
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 规则 ID |
| code | string | 编码 |
| prefix | string | 编码前缀，默认 `AH` |
| name | string | 规则名称 |
| mgrOrgId | string | 所属组织 ID |
| mgrOrgName | string | 所属组织名称 |
| mgrOrgType | string | 组织类型 |
| sourceType | string | 数据来源：`预置` / `自定义` |
| state | number | 状态：`0` 启用 |
| description | string | 备注 |
| cardStateTypes | string | 可补卡状态，逗号分隔：`noCheck` 缺卡 / `late` 迟到 |
| cardTimeLimit | number | 补卡次数限制值 |
| cardTimeLimitCycle | string | 补卡次数限制周期 |
| cardTimeLimitEnable | number | 是否限制补卡次数：`1` 开启 / `0` 关闭 |
| cardTypeIds | string | 关联补卡类型 ID |
| cardTypeIdsLimit | string | 补卡类型限制值 |
| lastDateLimit | number | 最晚补卡天数，`-1` 表示不限制 |
| lastDateLimitEnable | number | 是否限制最晚补卡天数：`1` 开启 / `0` 关闭 |
| noStatisticsTypes | string | 不计统计类型，逗号分隔 |

---

## 2. 新增补卡规则

```http
POST /dhr/admin/atd/cardTemplate/save
Content-Type: application/json
Authorization: Bearer <token>
```

### 请求体（直传 body）

```json
{
  "name": "自定义补卡规则",
  "prefix": "AH",
  "state": 0,
  "mgrOrgId": "9017397430310779030",
  "mgrOrgName": "瑞鹤医疗测试",
  "mgrOrgType": "company",
  "description": "测试规则",
  "cardStateTypes": "noCheck,late",
  "cardTimeLimit": 30,
  "cardTimeLimitCycle": "naturalMonth",
  "cardTimeLimitEnable": 1,
  "cardTypeIds": "",
  "cardTypeIdsLimit": "",
  "lastDateLimit": -1,
  "lastDateLimitEnable": 0,
  "noStatisticsTypes": "start,end"
}
```

### 响应

返回保存后的完整记录，`sourceType` 为 `自定义`。

---

## 3. 编辑补卡规则

```http
POST /dhr/admin/atd/cardTemplate/update
Content-Type: application/json
Authorization: Bearer <token>
```

### 请求体（直传 body，含 `id`）

```json
{
  "id": "5012565295972865718",
  "name": "默认补卡规则-已修改",
  "prefix": "AH",
  "state": 0,
  "mgrOrgId": "9017397430310779030",
  "mgrOrgName": "瑞鹤医疗测试",
  "mgrOrgType": "company",
  "description": "修改后的备注",
  "cardStateTypes": "noCheck",
  "cardTimeLimit": 5,
  "cardTimeLimitCycle": "naturalMonth",
  "cardTimeLimitEnable": 1,
  "cardTypeIds": "",
  "cardTypeIdsLimit": "",
  "lastDateLimit": -1,
  "lastDateLimitEnable": 0,
  "noStatisticsTypes": "start,end"
}
```

与 `save` 共用同一处理逻辑，带 `id` 时更新已有记录。

---

## 4. 删除补卡规则

```http
POST /dhr/admin/atd/cardTemplate/delete
Content-Type: application/json
Authorization: Bearer <token>
```

### 请求体

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

`eids` 字段会被忽略。

### 响应

```json
{
  "code": 0,
  "data": true
}
```

---

## 默认数据

服务启动时预置一条补卡规则：

| 字段 | 值 |
|------|----|
| code | 5012565295972865718 |
| prefix | AH |
| 业务编码 | AH5012565295972865718 |
| name | 默认补卡规则 |
| state | 0（启用） |
| sourceType | 预置 |
| mgrOrgName | 新乐市中医医院 |