# 考勤方案接口文档

本文档覆盖 HRO 管理后台考勤方案本体相关接口，对应页面：

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

## 基本信息

本地服务地址：

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

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

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

默认 fixture 模式下考勤方案数据为内存数据，服务重启后恢复默认值；开启 JDBC 持久化后，`atd_scheme`
通过 `project_id` 按当前管理员项目隔离。`projectId` 非空的项目管理员只能读写本项目方案，新建方案写入当前
`projectId`；平台全局态（`projectId=null`）不加项目过滤。历史 `project_id IS NULL` 方案不会自动对项目管理员可见。

## 通用响应

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` | 获取组织树 |
| `POST /dhr/user/selectPerson/getPersons` | 获取组织下人员 |

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

---

## 考勤方案 scheme

### 初始化（字典）

```http
POST /dhr/admin/atd/scheme/index
```

返回创建/编辑方案抽屉需要的所有下拉选项：

> 项目隔离说明：`checkTemplateGroups` 和 `overtimeTemplates` 已按当前 `projectId` 过滤。其它下拉对应的
> 周期、日历、请假/公出/补卡/每日汇总/班次模板表尚未全部项目化，仍随对应模块后续切片继续收口。

```json
{
  "code": 0,
  "data": {
    "prefix": "AG",
    "modelTypes": [
      {"id": "noCheck", "value": "noCheck", "display": "不打卡考勤"},
      {"id": "check", "value": "check", "display": "打卡考勤"},
      {"id": "stop", "value": "stop", "display": "暂停考勤"}
    ],
    "atdTypes": [
      {"id": "schedule", "value": "schedule", "display": "排班制"},
      {"id": "fixed", "value": "fixed", "display": "固定班制"}
    ],
    "calendars": [
      {"id": "default_calendar", "value": "default_calendar", "display": "默认日历"}
    ],
    "cycleTemplates": [
      {"id": "default_cycle", "value": "default_cycle", "display": "默认考勤周期"},
      {"id": "monthly_cycle", "value": "monthly_cycle", "display": "月度考勤"}
    ],
    "checkTemplateGroups": [
      {"id": "4614657879024617305", "value": "4614657879024617305", "display": "打卡"}
    ],
    "overtimeTemplates": [
      {"id": "6165602779003438728", "value": "6165602779003438728", "display": "默认加班规则"}
    ],
    "leaveTemplates": [
      {"id": "8637448601634856607", "value": "8637448601634856607", "display": "默认请假规则"}
    ],
    "officialTemplates": [
      {"id": "4711730941682665776", "value": "4711730941682665776", "display": "默认公出规则"}
    ],
    "cardTemplates": [
      {"id": "5012565295972865718", "value": "5012565295972865718", "display": "默认补卡规则"}
    ],
    "dataDayTemplates": [
      {"id": "7327471073147902139", "value": "7327471073147902139", "display": "默认每日汇总规则"}
    ],
    "classTemplates": [
      {"id": "6450849472663604448", "value": "6450849472663604448", "display": "多排班"},
      {"id": "7249540276522997896", "value": "7249540276522997896", "display": "生产班组排班"}
    ],
    "classCycleTemplates": [
      {"id": "default_cycle", "value": "default_cycle", "display": "默认考勤周期"}
    ]
  }
}
```

### 列表

```http
POST /dhr/admin/atd/scheme/list
```

请求体（标准分页）：

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

默认 fixture 数据（1 条预置考勤方案，`projectId=null`；项目态不可见，平台全局态可见）：

| 字段 | 值 |
|------|-----|
| `id` | `8750476355835819851` |
| `eId` | `8750476355835819851` |
| `prefix` | `AG` |
| `code` | `6595867831315664733` |
| `name` | `护士考勤方案` |
| `description` | `护士考勤方案` |
| `state` | `0`（启用） |
| `mgrOrgId` | `9017397430310779032` |
| `mgrOrgName` | `新乐市中医医院` |
| `mgrOrgType` | `company` |
| `modelType` | `check` |
| `modelTypeName` | `打卡考勤` |
| `type` | `schedule` |
| `managers` | `8004703653100268953` |
| `sourceType` | `预置` |
| `sourceTypeName` | `预置` |
| `rightType` | `0` |

关联规则组件：`calendarId=default_calendar`，`checkTemplateGroupId=4614657879024617305`，`cycleTemplateId=default_cycle`，`overtimeTemplateGroupId=6165602779003438728`，`leaveTemplateGroupId=8637448601634856607`，`officialTemplateGroupId=4711730941682665776`，`cardTemplateId=5012565295972865718`，`dataDayTemplateId=7327471073147902139`，`classTemplateId=6450849472663604448`。

列表行字段：`id`, `eId`, `prefix`, `code`, `name`, `description`, `state`, `mgrOrgId`, `mgrOrgName`, `mgrOrgType`, `calendarId`, `checkTemplateGroupId`, `cycleTemplateId`, `overtimeTemplateGroupId`, `leaveTemplateGroupId`, `officialTemplateGroupId`, `cardTemplateId`, `dataDayTemplateId`, `classTemplateId`, `type`, `modelType`, `managers`, `modelTypeName`, `calendarName`, `checkTemplateGroupName`, `cycleTemplateName`, `overtimeTemplateGroupName`, `leaveTemplateGroupName`, `officialTemplateGroupName`, `cardTemplateName`, `dataDayTemplateName`, `classTemplateName`, `rangesObj`, `rightsObj`, `rightsExcludeObj`, `rightType`, `sourceType`, `sourceTypeName`。

### 详情

```http
GET /dhr/admin/atd/scheme/detail?id=8750476355835819851
```

返回单条方案完整字段，行结构与列表行一致。

### 新增

```http
POST /dhr/admin/atd/scheme/save
```

请求体（直传 body，无嵌套）：

```json
{
  "code": "",
  "prefix": "AG",
  "name": "新考勤方案",
  "description": "备注",
  "state": 0,
  "modelType": "check",
  "type": "schedule",
  "mgrOrg": [
    {
      "id": "9017397430310779030",
      "name": "瑞鹤医疗测试",
      "typeFlag": "company"
    }
  ],
  "mgrOrgId": "9017397430310779030",
  "mgrOrgName": "瑞鹤医疗测试",
  "mgrOrgType": "company",
  "managers": "8004703653100268953",
  "calendarId": "default_calendar",
  "calendarName": "默认日历",
  "cycleTemplateId": "default_cycle",
  "cycleTemplateName": "默认考勤周期",
  "checkTemplateGroupId": "4614657879024617305",
  "checkTemplateGroupName": "打卡",
  "leaveTemplateGroupId": "8637448601634856607",
  "leaveTemplateGroupName": "默认请假规则",
  "officialTemplateGroupId": "4711730941682665776",
  "officialTemplateGroupName": "默认公出规则",
  "cardTemplateId": "5012565295972865718",
  "cardTemplateName": "默认补卡规则",
  "dataDayTemplateId": "7327471073147902139",
  "dataDayTemplateName": "默认每日汇总规则",
  "overtimeTemplateGroupId": "6165602779003438728",
  "overtimeTemplateGroupName": "默认加班规则",
  "classTemplateId": "",
  "classTemplateName": "",
  "rangesObj": [],
  "rightsObj": [],
  "rightsExcludeObj": [],
  "rightType": 0
}
```

默认值：`prefix=AG`，`modelType=check`，`type=schedule`。新建记录 `sourceType=custom`，`sourceTypeName=自定义`。
平台全局态未传 `overtimeTemplateGroupId` 时沿用历史默认加班规则组；项目态未传时不再隐式写入历史全局加班规则组。
若显式传入 `overtimeTemplateGroupId`，该加班规则组必须在当前 `projectId` 下可见，否则返回
「加班规则组不存在或已删除」。
`rangesObj`、`rightsObj`、`rightsExcludeObj` 保留原始 JSON 数组/对象形态。

### 更新

```http
POST /dhr/admin/atd/scheme/update
```

按 `id` 覆盖记录。项目管理员只能更新同项目方案；跨项目或已删除方案按「考勤方案不存在或已删除」处理。
保留已有 `code` 除非显式传入。未传的字段保留原值。

### 删除

```http
POST /dhr/admin/atd/scheme/delete
```

请求体：

```json
{
  "ids": ["8750476355835819851"],
  "eids": ["8750476355835819851"]
}
```

按 `ids` 和 `eids` 删除匹配行。项目管理员只能删除同项目方案；跨项目 id 不会被删除。响应 `data: true`。

> **简化说明**：本地 fixture 不做被引用保护检查。生产环境删除考勤方案时会校验是否被考勤档案引用。

---

## 管理员查询

### 查询可维护管理员

```http
POST /dhr/admin/atd/common/findManagers
```

响应：

```json
{
  "code": 0,
  "data": {
    "managers": [
      {
        "id": "8004703653100268953",
        "value": "8004703653100268953",
        "display": "李璨"
      }
    ]
  }
}
```

### 批量更新方案管理员

```http
POST /dhr/admin/atd/scheme/updateManagers
```

请求体：

```json
{
  "ids": ["8750476355835819851"],
  "eids": [],
  "managers": "8004703653100268953,2000000000000000001",
  "updateType": "override"
}
```

- `updateType`（或 `mode`）：`"override"`（覆盖，默认）/ `"append"`（追加）
- 追加模式会去重合并现有管理员

响应：

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