|
|
# 考勤打卡
|
|
|
|
|
|
> 模块编码：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）
|