# 考勤打卡

> 模块编码：attendance
> 端侧：Web + 小程序（双端）
> 关联文档：01-模块划分 §3.5 / 02-功能清单-物业公司 §5 / 03-业务流转逻辑-物业公司 §5 / 05-接口规范 §9.2 / 06-项目技术要求 §4.4

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 考勤打卡 |
| 子菜单 | 打卡点管理、打卡规则、考勤记录、异常审核、数据补录 |
| 功能编号 | PR-A-01 ~ PR-A-05 |
| 权限编码前缀 | attendance:point:* / attendance:rule:* / attendance:record:* / attendance:appeal:* / attendance:supplement:* |

---

## 页面1：打卡点管理页

**页面编号**：PR-A-01-P01
**端侧归属**：Web专属
**页面路径**：/attendance/points

### 界面布局

```
┌──────────────────────────────────────────────────────────────────┐
│ [面包屑] 考勤打卡 > 打卡点管理                                      │
├──────────────────────────────────────────────────────────────────┤
│ [查询条件区]                                                      │
│ 打卡点名称[____] 所属班组[▼] 状态[▼]                [查询] [重置]  │
├──────────────────────────────────────────────────────────────────┤
│ [操作栏]  [新增打卡点]                                            │
├──────────────────────────────────────────────────────────────────┤
│ [列表区]                                                          │
│ 序号| 打卡点名称 | 所属班组 | 蓝牙Beacon | Beacon状态 | 操作       │
│ 1  | 1号楼大厅   | 水电班   | B-001     | 在线       | 编辑 删除  │
│ 2  | 2号楼入口   | 巡检班   | B-002     | 离线       | 编辑 删除  │
├──────────────────────────────────────────────────────────────────┤
│ [分页]  共8条                                                     │
└──────────────────────────────────────────────────────────────────┘
```

### 表单字段（新增/编辑弹窗）

| 字段名 | 控件类型 | 必填 | 默认值 | 数据来源 | 校验规则 |
|--------|----------|------|--------|----------|----------|
| 打卡点名称 | 文本输入 | 是 | — | 自填 | 最大30字 |
| 所属班组 | 下拉单选 | 是 | — | 班组列表 | — |
| 位置描述 | 文本输入 | 是 | — | 自填 | 最大100字 |
| 蓝牙Beacon | 下拉单选 | 是 | — | 蓝牙设备管理 | — |
| 适用角色 | 下拉多选 | 是 | 全部 | 固定选项 | 全部/主管/员工 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 新增打卡点 | attendance:point:create | 操作栏 | 始终 | — |
| 编辑 | attendance:point:update | 行操作 | 始终 | — |
| 删除 | attendance:point:delete | 行操作 | 无人员关联 | 二次确认 |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 列表查询 | /api/v1/attendance-points | GET | — |
| 新增 | /api/v1/attendance-points | POST | — |
| 编辑 | /api/v1/attendance-points/{id} | PUT | — |

---

## 页面2：打卡规则页

**页面编号**：PR-A-02-P01
**端侧归属**：Web专属
**页面路径**：/attendance/rules

### 界面布局

```
┌──────────────────────────────────────────────────────────────────┐
│ [面包屑] 考勤打卡 > 打卡规则                                       │
├──────────────────────────────────────────────────────────────────┤
│ [按班组显示规则卡片]                                               │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 水电维修班                                                    │ │
│ │ 上班时间：08:00    上班打卡窗口：07:30~08:30                    │ │
│ │ 下班时间：17:00    下班打卡窗口：16:30~17:30                    │ │
│ │ 迟到规则：>08:00 迟到  >08:30 严重迟到                         │ │
│ │ 早退规则：<17:00 早退  <16:30 严重早退                         │ │
│ │                                              [编辑]           │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 巡检一班                                                      │ │
│ │ ...                                                [编辑]     │ │
│ └──────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```

### 表单字段（编辑弹窗）

| 字段名 | 控件类型 | 必填 | 默认值 | 数据来源 | 校验规则 |
|--------|----------|------|--------|----------|----------|
| 上班时间 | 时间选择 | 是 | 08:00 | 自填 | — |
| 上班打卡窗口(起) | 时间选择 | 是 | 上班前30分 | 自填 | — |
| 上班打卡窗口(止) | 时间选择 | 是 | 上班后30分 | 自填 | — |
| 下班时间 | 时间选择 | 是 | 17:00 | 自填 | — |
| 下班打卡窗口(起) | 时间选择 | 是 | 下班前30分 | 自填 | — |
| 下班打卡窗口(止) | 时间选择 | 是 | 下班后30分 | 自填 | — |
| 迟到阈值(分钟) | 数字输入 | 是 | 0 | 自填 | ≥0 |
| 严重迟到阈值(分钟) | 数字输入 | 是 | 30 | 自填 | >迟到阈值 |
| 早退阈值(分钟) | 数字输入 | 是 | 0 | 自填 | ≥0 |
| 严重早退阈值(分钟) | 数字输入 | 是 | 30 | 自填 | >早退阈值 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 编辑 | attendance:rule:update | 卡片操作 | 始终 | — |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 规则查询 | /api/v1/attendance-rules | GET | 按班组查询 |
| 保存 | /api/v1/attendance-rules | POST | — |

---

## 页面3：考勤记录页

**页面编号**：PR-A-03-P01
**端侧归属**：Web专属
**页面路径**：/attendance/records

### 查询条件

| 字段名 | 控件类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| 日期 | 日期选择 | 否 | 今天 | — |
| 班组 | 下拉单选 | 否 | 全部 | — |
| 人员 | 文本输入 | 否 | — | 模糊匹配 |
| 打卡状态 | 下拉单选 | 否 | 全部 | 正常/迟到/早退/缺卡/补录 |

### 列表字段

| 序号 | 字段名 | 列宽 | 支持排序 | 说明 |
|------|--------|------|----------|------|
| 1 | 姓名 | 80px | 否 | — |
| 2 | 班组 | 100px | 否 | — |
| 3 | 上班打卡时间 | 120px | 是 | — |
| 4 | 上班打卡方式 | 90px | 否 | 蓝牙/手动/补录 |
| 5 | 上班状态 | 80px | 否 | 正常/迟到/严重迟到 |
| 6 | 下班打卡时间 | 120px | 是 | — |
| 7 | 下班打卡方式 | 90px | 否 | — |
| 8 | 下班状态 | 80px | 否 | 正常/早退/严重早退 |
| 9 | 补录标记 | 70px | 否 | 补录显示"补录"标签 |
| 10 | 操作 | 80px | — | 查看详情 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 查看详情 | attendance:record:view | 行操作 | 始终 | — |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 记录查询 | /api/v1/attendance-records | GET | 分页查询 |

---

## 页面4：异常审核页

**页面编号**：PR-A-04-P01
**端侧归属**：Web专属
**页面路径**：/attendance/appeals

### 查询条件

| 字段名 | 控件类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| 审核状态 | 下拉单选 | 否 | 全部 | 待审核/已通过/已驳回 |
| 申诉人 | 文本输入 | 否 | — | 模糊匹配 |
| 日期范围 | 日期范围 | 否 | — | — |

### 列表字段

| 序号 | 字段名 | 列宽 | 支持排序 | 说明 |
|------|--------|------|----------|------|
| 1 | 申诉人 | 80px | 否 | — |
| 2 | 班组 | 100px | 否 | — |
| 3 | 申诉日期 | 100px | 是 | — |
| 4 | 异常类型 | 100px | 否 | 蓝牙故障/手机异常/系统异常/忘记打卡/其他 |
| 5 | 申诉说明 | 200px | 否 | — |
| 6 | 审核状态 | 90px | 是 | 待审核(黄)/已通过(绿)/已驳回(红) |
| 7 | 操作 | 100px | — | 审核/查看 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 审核 | attendance:appeal:approve | 行操作 | 审核状态=待审核 | 通过/驳回弹窗 |

### 通知触发

| 触发操作 | 通知对象 | 通知方式 | 消息模板 | 文档来源 |
|----------|----------|----------|----------|----------|
| 审核通过 | 申诉人 | 小程序推送 | 申诉通过，系统自动补录打卡 | 03-物业公司 §5 / 03-小程序端 §5.1 |
| 审核驳回 | 申诉人 | 小程序推送 | 申诉未通过 | 03-物业公司 §5 |

### 蓝牙双模式差异

| 元素 | 策略=REQUIRED | 策略=OPTIONAL |
|------|---------------|---------------|
| 打卡方式 | 仅蓝牙打卡 | 蓝牙/手动双按钮 |
| 蓝牙失败 | 提交异常申诉 | 可直接手动打卡(check_method=MANUAL) |
| 异常申诉 | 必须审核 | 无需申诉(手动打卡) |
| 打卡记录标记 | check_method=BLUETOOTH | check_method=MANUAL |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 申诉列表 | /api/v1/attendance-appeals | GET | — |
| 审核 | /api/v1/attendance-appeals/{id}/approve | POST | 通过后自动补录打卡 |

---

## 页面5：数据补录页

**页面编号**：PR-A-05-P01
**端侧归属**：Web专属
**页面路径**：/attendance/supplement

### 补录数据标记规范

| 标记项 | 说明 |
|--------|------|
| is_supplement | true |
| supplement_reason | 蓝牙故障/系统异常/其他 |
| supplement_audit_status | 待审核/通过/驳回 |
| 自动补录 | 异常申诉审核通过后系统自动补录打卡记录 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 审核 | attendance:supplement:approve | 行操作 | 审核状态=待审核 | — |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 补录列表 | /api/v1/attendance-records/supplements | GET | — |
| 审核 | /api/v1/attendance-records/supplements/{id}/approve | POST | — |

---

## 需求追溯

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| PR-A-01 | 打卡点管理 | 02-物业公司 §5 / 03-物业公司 §5 | 打卡点→蓝牙绑定→小程序打卡 | 组织架构(打卡点分配) / 系统配置(蓝牙设备) |
| PR-A-02 | 打卡规则 | 02-物业公司 §5 / 03-物业公司 §5 | 规则→迟到早退判定 | — |
| PR-A-03 | 考勤记录 | 02-物业公司 §5 | — | 统计报表→考勤统计 |
| PR-A-04 | 异常审核 | 02-物业公司 §5 / 03-物业公司 §5 | 审核→自动补录打卡 | 小程序端异常申诉(MP-AT-04) |
| PR-A-05 | 数据补录 | 02-物业公司 §5 | 补录→审核 | 操作日志→补录日志 |

## 业务规则

1. **蓝牙强制打卡**：策略=REQUIRED时必须在指定打卡点连接蓝牙后才可打卡（来源：01 §9 / 06 §4.4）
2. **蓝牙双模式**：策略=OPTIONAL时允许手动打卡(check_method=MANUAL)（来源：06 §4.4）
3. **异常申诉流程**：蓝牙失败→提交异常申诉→主管审核→通过后系统自动补录打卡记录（来源：03-物业公司 §5 / 03-小程序端 §5.1）
4. **打卡窗口**：上班/下班各设打卡时间窗口，窗口外打卡标记异常（来源：02-物业公司 PR-A-02）
5. **迟到/早退规则**：可自定义迟到、严重迟到、早退、严重早退的分钟阈值（来源：02-物业公司 PR-A-02）
6. **数据权限**：主管仅看本班组数据，员工仅看本人数据（来源：01 §1.3）
7. **打卡判定**：不判断距离，只要成功连接蓝牙设备即可打卡（来源：06 §5.4）