# 考勤相关功能

> 模块编码：attendance
> 端侧：微信小程序
> 关联文档：01-模块划分.md（v4.0）、02-功能清单-小程序端.md（§5）、03-业务流转逻辑-小程序端.md（§5）、05-接口规范.md（§9）、06-项目技术要求.md

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 考勤打卡 |
| 子菜单 | 上班打卡 / 下班打卡 / 打卡记录 / 异常申诉 / 考勤日历 / 考勤审核 |
| 功能编号 | MP-AT-01 ~ MP-AT-06 |
| 权限编码 | attendance:record:*、attendance:appeal:*、attendance:supplement:* |

## 页面清单

### 页面1：上班打卡

- **页面路径**：`/pages/attendance/clock-in`
- **适用角色**：全部
- **页面元素**：
  - 当前时间显示（大字时钟）
  - 打卡状态指示（未打卡/已打卡）
  - 蓝牙扫描状态指示器
  - 当前打卡点名称
  - 蓝牙信号强度显示
  - 打卡按钮
  - 补录/申诉入口
- **查询条件**：无
- **列表字段**：无
- **界面布局**：
  - 顶部：当前时间大字显示
  - 中部：打卡点信息 + 蓝牙状态
  - 底部：打卡按钮（圆形大按钮）
- **操作按钮**：
  - 「上班打卡」→ 记录上班打卡（权限：attendance:record:create）
  - 「异常申诉」→ 跳转异常申诉页（蓝牙未检测到时显示）

**蓝牙策略判断逻辑**：
- 调用 `GET /system/bluetooth-policy → attendance_check`
- 策略=REQUIRED：必须连接指定打卡点蓝牙Beacon后才可打卡
  - 验证Beacon属于本人班组打卡点
  - 打卡成功记录 `check_method=BLUETOOTH`
- 策略=OPTIONAL：可选蓝牙打卡或手动打卡
  - 手动打卡：`check_method=MANUAL`

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-AT-01 | 上班打卡 | 02-小程序端 §5 | 记录操作日志 | 考勤记录、打卡点管理 |

---

### 页面2：下班打卡

- **页面路径**：`/pages/attendance/clock-out`
- **适用角色**：全部
- **页面元素**：
  - 当前时间显示（大字时钟）
  - 打卡状态指示（未打卡/已打卡）
  - 上班打卡时间显示
  - 蓝牙扫描状态指示器
  - 当前打卡点名称
  - 打卡按钮
  - 补录/申诉入口
- **查询条件**：无
- **列表字段**：无
- **界面布局**：
  - 顶部：当前时间 + 上班打卡时间
  - 中部：打卡点信息 + 蓝牙状态
  - 底部：打卡按钮（圆形大按钮）
- **操作按钮**：
  - 「下班打卡」→ 记录下班打卡（权限：attendance:record:create）
  - 「异常申诉」→ 跳转异常申诉页

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-AT-02 | 下班打卡 | 02-小程序端 §5 | 记录操作日志 | 考勤记录 |

---

### 页面3：打卡记录

- **页面路径**：`/pages/attendance/records`
- **适用角色**：全部
- **页面元素**：
  - 月份选择器
  - 统计信息卡片（出勤天数/迟到/早退/缺卡）
  - 打卡记录列表
  - 记录详情弹窗
- **查询条件**：
  - 月份筛选
  - 状态筛选（全部/正常/迟到/早退/缺卡/补录）
- **列表字段**：

| 字段 | 类型 | 说明 |
|------|------|------|
| 日期 | 日期 | 打卡日期 |
| 上班时间 | 时间 | 上班打卡时间 |
| 下班时间 | 时间 | 下班打卡时间 |
| 打卡方式 | 标签 | 蓝牙/手动/补录 |
| 状态 | 标签 | 正常/迟到/早退/缺卡 |

- **界面布局**：
  - 顶部：月份选择器 + 统计数字横向排列
  - 中部：按日期分组的打卡记录列表
  - 底部：无操作栏
- **操作按钮**：
  - 「查看详情」→ 查看打卡详情（含打卡点、蓝牙信息等）
  - 「异常申诉」→ 对异常记录发起申诉

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-AT-03 | 打卡记录 | 02-小程序端 §5 | 无 | 考勤日历 |

---

### 页面4：异常申诉

- **页面路径**：`/pages/attendance/appeal`
- **适用角色**：全部（蓝牙失灵/系统宕机时）
- **页面元素**：
  - 异常日期选择
  - 异常类型选择（上班/下班/全天）
  - 异常原因选择（蓝牙故障/手机异常/系统异常/忘记打卡/其他）
  - 补充说明输入框（多行文本）
  - 照片上传区（补充证据，≤9张）
  - 提交按钮
- **查询条件**：无
- **列表字段**：无
- **界面布局**：
  - 顶部：申诉模式提示
  - 中部：原因选择 + 说明填写 + 照片上传
  - 底部：提交按钮
- **操作按钮**：
  - 「提交申诉」→ 提交打卡异常申诉（权限：attendance:appeal:create）
  - 申诉提交后等待主管审核（Web/小程序均可审核）

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-AT-04 | 异常申诉 | 02-小程序端 §5 | 主管审核 | 考勤审核 |

---

### 页面5：考勤日历

- **页面路径**：`/pages/attendance/calendar`
- **适用角色**：全部
- **页面元素**：
  - 月历视图（日历格子）
  - 每日状态标记（颜色点）
  - 点击日期显示详情弹窗
  - 图例说明
- **查询条件**：
  - 月份切换（左右滑动）
- **列表字段**：无（日历模式）
- **界面布局**：
  - 顶部：月份切换 + 统计信息
  - 中部：月历网格，每日格子中用颜色点标记状态
    - 绿色：正常
    - 黄色：迟到/早退
    - 红色：缺卡
    - 蓝色：补录
    - 灰色：休息日
  - 底部：图例说明
- **操作按钮**：
  - 「点击日期」→ 显示当日打卡详情弹窗

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-AT-05 | 考勤日历 | 02-小程序端 §5 | 无 | 打卡记录 |

---

### 页面6：考勤审核

- **页面路径**：`/pages/attendance/review`
- **适用角色**：主管
- **页面元素**：
  - 待审核申诉列表
  - 申诉详情查看
  - 审核操作区（通过/驳回）
  - 驳回原因输入框
- **查询条件**：
  - 状态筛选（待审核/已通过/已驳回）
  - 日期筛选
  - 人员筛选
- **列表字段**：

| 字段 | 类型 | 说明 |
|------|------|------|
| 申诉人 | 文本 | 员工姓名 |
| 申诉日期 | 日期 | 异常打卡日期 |
| 异常类型 | 标签 | 上班/下班/全天 |
| 申诉原因 | 文本 | 原因摘要 |
| 提交时间 | 时间 | 申诉提交时间 |
| 审核状态 | 标签 | 待审核/已通过/已驳回 |

- **界面布局**：
  - 顶部：筛选条件
  - 中部：申诉卡片列表
  - 底部：审核操作按钮（通过/驳回）
- **操作按钮**：
  - 「通过」→ 系统自动补录打卡记录，标注"补录"（权限：attendance:appeal:approve）
  - 「驳回」→ 填写驳回原因，通知员工

**审核流程**：
```
员工提交异常申诉（小程序端）
      │
  主管审核（Web+小程序均可）
      │
  ┌─审核通过─┐  ┌─审核驳回─┐
  系统自动补录      通知员工
  打卡记录          申诉未通过
  标注"补录"        记录审核日志
  记录审核日志
```

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-AT-06 | 考勤审核 | 02-小程序端 §5 | 补录打卡记录 | 操作日志、考勤管理（Web端） |

---

## 业务规则

1. **蓝牙策略**：考勤打卡受蓝牙策略控制（`GET /system/bluetooth-policy → attendance_check`）
2. **蓝牙强制打卡**：策略=REQUIRED时，必须在指定打卡点连接蓝牙Beacon后才可打卡
   - 验证Beacon属于本人班组打卡点
   - 打卡成功记录 `check_method=BLUETOOTH` + Beacon标识
3. **非强制蓝牙**：策略=OPTIONAL时，可选蓝牙打卡或手动打卡（`check_method=MANUAL`）
4. **打卡点验证**：蓝牙打卡时验证Beacon属于本人班组绑定的打卡点
5. **打卡时间**：自动记录精确到秒
6. **异常申诉审核**：主管在Web端或小程序端均可审核
7. **补录标记**：审核通过后系统自动补录打卡记录，标记 `is_supplement=true`
8. **操作日志**：所有打卡操作记录审计日志
9. **双端审批**：打卡异常申诉支持Web+小程序双端审核

## 状态流转

### 打卡状态

```
未打卡 → 已打卡（正常/迟到/早退）
    ↓
  缺卡 → 异常申诉 → 审核通过 → 补录打卡（标记补录）
                  → 审核驳回 → 保持缺卡
```

### 申诉审核状态

```
待审核 → 审核通过 → 系统补录打卡记录
      → 审核驳回 → 通知员工
```