houqin-java/docs/02-功能清单-物业公司/05-考勤打卡.md

考勤打卡

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

功能概览

项目	说明
菜单名称	考勤打卡
子菜单	打卡点管理、打卡规则、考勤记录、异常审核、数据补录
功能编号	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	—

交互流程要求

1. 页面加载流程：进入页面 → 请求打卡点列表API → 渲染表格数据 → 默认无选中状态
2. 查询/筛选交互流程：填写筛选条件（打卡点名称/所属班组/状态）→ 点击"查询" → 调用列表API并刷新表格 → 点击"重置"清空条件并重新加载
3. 表单填写与提交流程：点击"新增打卡点" → 弹出新增弹窗 → 填写表单字段 → 点击确定 → 前端校验通过 → 调用新增API → 成功后关闭弹窗并刷新列表
4. 弹窗/抽屉交互流程：新增/编辑弹窗居中展示，宽度480px；点击遮罩层或右上角关闭按钮可关闭；未保存变更时提示确认
5. 行内操作流程：点击"编辑" → 弹出编辑弹窗（预填数据）→ 修改后提交 → 刷新当前行；点击"删除" → 弹出二次确认弹窗"确定删除该打卡点？" → 确认后调用删除API → 刷新列表
6. 异常与错误处理：API请求失败显示ElMessage.error提示；删除有关联人员的打卡点时提示"该打卡点下存在关联人员，无法删除"
7. 联动/级联交互：选择所属班组后，蓝牙Beacon下拉选项可按班组过滤；Beacon状态根据设备管理模块实时数据展示在线/离线
8. 权限控制交互表现：无attendance:point:create权限时隐藏"新增打卡点"按钮；无attendance:point:update权限时隐藏行内"编辑"按钮；无attendance:point:delete权限时隐藏行内"删除"按钮
9. H1 防重复请求(强制)："查询""新增打卡点"按钮点击后立即disabled并显示loading态；行内"编辑""删除"操作时整行添加半透明遮罩禁用重复点击；翻页/切换筛选条件时自动abort前一个未完成请求再发新请求；列表查询与下拉选项加载等并行请求互不阻塞
10. H2 超时配置(强制)：列表查询GET请求设置15s超时，新增/编辑POST请求设置30s超时；任何请求耗时>3s时在页面顶部展示全局ElLoading("数据加载中...")直到响应返回
11. H3 操作确认(强制)："删除打卡点"操作弹出ElMessageBox.confirm二次确认，type="error"，提示文案"确定删除该打卡点？删除后将不可恢复"
12. H6 批量限制(建议)：当前页面暂无批量操作；若后续扩展批量删除功能，单次批量删除上限50条记录，超出时提示"单次最多选择50条记录进行操作"
13. H8 反馈规范(建议)：新增/编辑成功后ElMessage.success显示2秒后自动消失，同时silent方式刷新列表（不显示loading遮罩）；失败提示ElMessage.error需用户手动关闭；网络异常时显示"网络连接异常，请检查网络后重试"并提供重试按钮

组件规范

元素	组件	配置参数
打卡点名称输入框	ElInput	maxlength=30, showWordLimit=true, placeholder="请输入打卡点名称"
所属班组下拉	ElSelect	filterable=true, clearable=true, placeholder="请选择所属班组"
位置描述输入框	ElInput	maxlength=100, showWordLimit=true, type="textarea", :rows=2
蓝牙Beacon下拉	ElSelect	filterable=true, clearable=true, placeholder="请选择蓝牙Beacon"
适用角色多选	ElSelect	multiple=true, collapseTags=true, placeholder="请选择适用角色"
状态下拉	ElSelect	clearable=true, :options=[{label:"在线",value:"online"},{label:"离线",value:"offline"}]
查询按钮	ElButton	type="primary", icon="Search"
重置按钮	ElButton	icon="Refresh"
新增打卡点按钮	ElButton	type="primary", icon="Plus"
列表表格	ElTable	stripe=true, border=true, :data=tableData
分页	ElPagination	layout="total, sizes, prev, pager, next", :page-sizes=[10,20,50]
新增/编辑弹窗	ElDialog	width="480px", :close-on-click-modal=false, :destroy-on-close=true
删除确认弹窗	ElMessageBox	type="warning", confirmButtonText="确定", cancelButtonText="取消"

校验规则

字段	规则	错误提示
打卡点名称	required, maxLength=30	请输入打卡点名称；打卡点名称不能超过30个字符
所属班组	required	请选择所属班组
位置描述	required, maxLength=100	请输入位置描述；位置描述不能超过100个字符
蓝牙Beacon	required	请选择蓝牙Beacon设备
适用角色	required	请选择适用角色

响应式布局

断点	布局调整
≥1280px（桌面端）	查询条件区水平排列，表格完整展示所有列，弹窗宽度480px
1024-1279px（Pad横屏）	查询条件区换行排列（名称独占一行，班组+状态一行），表格隐藏位置描述列，弹窗宽度420px
768-1023px（Pad竖屏）	查询条件区垂直堆叠，表格仅显示打卡点名称、所属班组、操作列，弹窗宽度90vw

---

页面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	—

交互流程要求

1. 页面加载流程：进入页面 → 请求规则列表API（按班组分组）→ 渲染规则卡片列表 → 默认展示全部班组卡片
2. 查询/筛选交互流程：本页无独立筛选条件，数据按班组以卡片形式展示，所有班组规则一次加载
3. 表单填写与提交流程：点击卡片"编辑"按钮 → 弹出编辑弹窗（预填当前规则数据）→ 修改时间与阈值 → 点击确定 → 前端校验通过 → 调用保存API → 成功后关闭弹窗并刷新对应卡片数据
4. 弹窗/抽屉交互流程：编辑弹窗居中展示，宽度520px；弹窗内时间选择器联动显示打卡窗口；点击遮罩层或关闭按钮可退出，未保存时提示确认
5. 行内操作流程：无行内操作，仅在卡片上提供"编辑"按钮
6. 异常与错误处理：严重迟到阈值≤迟到阈值时提示"严重迟到阈值必须大于迟到阈值"；严重早退阈值≤早退阈值时提示"严重早退阈值必须大于早退阈值"；打卡窗口起止时间逻辑冲突时提示错误
7. 联动/级联交互：修改上班时间时自动调整上班打卡窗口默认值（上班前30分~上班后30分）；修改下班时间同理自动调整下班打卡窗口
8. 权限控制交互表现：无attendance:rule:update权限时隐藏卡片"编辑"按钮，卡片仅展示只读信息
9. H1 防重复请求(强制)：卡片"编辑"按钮点击后立即disabled并显示loading态；编辑弹窗提交按钮点击后disabled防重复提交
10. H2 超时配置(强制)：规则查询GET请求设置15s超时，保存POST请求设置30s超时；请求耗时>3s时展示全局ElLoading
11. H4 脏数据检测(强制)：打开编辑弹窗时对当前规则数据进行deepClone快照；弹窗内监听表单变更计算isDirty状态；点击弹窗关闭按钮或遮罩层且isDirty为true时，弹出ElMessageBox.confirm提示"修改尚未保存，确定要关闭吗？"；路由离开前通过beforeRouteLeave守卫拦截未保存的变更
12. H8 反馈规范(建议)：保存成功后ElMessage.success("规则保存成功")显示2秒后自动消失并silent刷新对应卡片数据；失败提示需手动关闭；网络异常提供重试

组件规范

元素	组件	配置参数
上班时间选择	ElTimePicker	format="HH:mm", placeholder="请选择上班时间"
上班打卡窗口(起)	ElTimePicker	format="HH:mm", placeholder="上班打卡开始时间"
上班打卡窗口(止)	ElTimePicker	format="HH:mm", placeholder="上班打卡结束时间"
下班时间选择	ElTimePicker	format="HH:mm", placeholder="请选择下班时间"
下班打卡窗口(起)	ElTimePicker	format="HH:mm", placeholder="下班打卡开始时间"
下班打卡窗口(止)	ElTimePicker	format="HH:mm", placeholder="下班打卡结束时间"
迟到阈值	ElInputNumber	:min=0, :max=180, :step=5, controls-position="right"
严重迟到阈值	ElInputNumber	:min=1, :max=180, :step=5, controls-position="right"
早退阈值	ElInputNumber	:min=0, :max=180, :step=5, controls-position="right"
严重早退阈值	ElInputNumber	:min=1, :max=180, :step=5, controls-position="right"
规则卡片	ElCard	shadow="hover", :body-style="{ padding: '20px' }"
编辑按钮	ElButton	type="primary", link=true, icon="Edit"
编辑弹窗	ElDialog	width="520px", :close-on-click-modal=false, :destroy-on-close=true

校验规则

字段	规则	错误提示
上班时间	required	请选择上班时间
上班打卡窗口(起)	required, 必须早于上班时间	请选择上班打卡开始时间；上班打卡开始时间必须早于上班时间
上班打卡窗口(止)	required, 必须晚于上班时间	请选择上班打卡结束时间；上班打卡结束时间必须晚于上班时间
下班时间	required	请选择下班时间
下班打卡窗口(起)	required, 必须早于下班时间	请选择下班打卡开始时间；下班打卡开始时间必须早于下班时间
下班打卡窗口(止)	required, 必须晚于下班时间	请选择下班打卡结束时间；下班打卡结束时间必须晚于下班时间
迟到阈值(分钟)	required, ≥0	请输入迟到阈值；迟到阈值不能为负数
严重迟到阈值(分钟)	required, >迟到阈值	请输入严重迟到阈值；严重迟到阈值必须大于迟到阈值
早退阈值(分钟)	required, ≥0	请输入早退阈值；早退阈值不能为负数
严重早退阈值(分钟)	required, >早退阈值	请输入严重早退阈值；严重早退阈值必须大于早退阈值

响应式布局

断点	布局调整
≥1280px（桌面端）	规则卡片双列排列，卡片内信息水平展示，弹窗宽度520px
1024-1279px（Pad横屏）	规则卡片单列排列，卡片内信息水平展示，弹窗宽度480px
768-1023px（Pad竖屏）	规则卡片单列排列，卡片内信息垂直堆叠（标签与值分行显示），弹窗宽度90vw

---

页面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	分页查询

交互流程要求

1. 页面加载流程：进入页面 → 默认日期为今天 → 请求考勤记录API → 渲染表格数据
2. 查询/筛选交互流程：选择日期/班组/人员/打卡状态 → 点击"查询" → 调用API刷新表格 → 点击"重置"恢复默认条件（今天/全部/全部/全部）并重新加载
3. 表单填写与提交流程：本页无表单提交操作
4. 弹窗/抽屉交互流程：点击"查看详情" → 弹出详情弹窗展示完整打卡信息（打卡时间、方式、状态、打卡点、蓝牙设备信息等），宽度500px
5. 行内操作流程：点击"查看详情" → 调用详情API → 弹窗展示完整考勤记录详情
6. 异常与错误处理：API请求失败显示ElMessage.error提示；列表数据为空时展示ElEmpty空状态；补录标记列显示ElTag标签"补录"
7. 联动/级联交互：选择班组后人员筛选可按班组过滤；上班/下班状态字段根据状态值显示不同颜色Tag（正常-绿/迟到-橙/严重迟到-红/早退-橙/严重早退-红）
8. 权限控制交互表现：无attendance:record:view权限时隐藏"查看详情"按钮；主管仅看到本班组数据，员工仅看本人数据（后端数据权限控制）
9. H1 防重复请求(强制-轻量)："查询"按钮点击后disabled+loading态；行内"查看详情"按钮点击后整行半透明遮罩防重复；分页切换时abort前一次未完成请求；本页以查看为主，采用轻量级防重复策略
10. H2 超时配置(强制)：记录查询GET请求设置15s超时；请求耗时>3s时在表格区域展示ElLoading局部加载动画
11. H8 反馈规范(建议)：详情弹窗加载完成后正常展示，无需额外成功反馈；API请求失败时ElMessage.error提示需手动关闭；网络异常时显示重试按钮

组件规范

元素	组件	配置参数
日期选择	ElDatePicker	type="date", value-format="YYYY-MM-DD", placeholder="选择日期"
班组下拉	ElSelect	filterable=true, clearable=true, placeholder="请选择班组"
人员输入框	ElInput	placeholder="请输入人员姓名", clearable=true
打卡状态下拉	ElSelect	clearable=true, :options=[正常,迟到,早退,缺卡,补录]
查询按钮	ElButton	type="primary", icon="Search"
重置按钮	ElButton	icon="Refresh"
列表表格	ElTable	stripe=true, border=true, :data=tableData, :default-sort={prop:"上班打卡时间",order:"ascending"}
上班状态列	ElTag	:type=状态映射(正常→success/迟到→warning/严重迟到→danger)
下班状态列	ElTag	:type=状态映射(正常→success/早退→warning/严重早退→danger)
补录标记列	ElTag	type="info", v-if="is_supplement"
分页	ElPagination	layout="total, sizes, prev, pager, next", :page-sizes=[10,20,50]
详情弹窗	ElDialog	width="500px", :close-on-click-modal=true, :destroy-on-close=true

校验规则

字段	规则	错误提示
日期	非必填，格式校验	日期格式不正确
人员	最大20字	人员姓名不能超过20个字符
打卡状态	枚举值校验	请选择有效的打卡状态

响应式布局

断点	布局调整
≥1280px（桌面端）	查询条件区水平排列，表格完整展示所有10列，分页右对齐
1024-1279px（Pad横屏）	查询条件区换行排列，表格隐藏上班打卡方式、下班打卡方式列，保留8列
768-1023px（Pad竖屏）	查询条件区垂直堆叠，表格仅显示姓名、班组、上班状态、下班状态、操作列，分页居中

---

页面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	通过后自动补录打卡

交互流程要求

1. 页面加载流程：进入页面 → 调用申诉列表API GET /api/v1/attendance-appeals → 渲染异常审核表格，默认按申诉日期倒序排列，每页20条；同时加载审核状态下拉选项
2. 查询/筛选交互流程：选择审核状态/输入申诉人/选择日期范围 → 点击[查询] → 携带筛选参数重新请求第1页 → 点击[重置]清空条件并重新加载
3. 表单填写与提交流程：本页无新增表单，申诉数据由小程序端提交
4. 弹窗/抽屉交互流程：点击[审核]（审核状态=待审核时显示）→ 弹出审核弹窗，选择"通过"或"驳回"，驳回时必填驳回原因 → 确认后调用审核API → 审核通过后系统自动补录打卡记录 → 成功后关闭弹窗并刷新列表
5. 行内操作流程：点击[审核] → 弹窗选择通过/驳回 → 提交 → 刷新该行审核状态；点击[查看]（如有）→ 弹窗展示申诉详情
6. 异常与错误处理：审核已审核过的记录提示"该申诉已审核"；审核通过后自动补录打卡失败时提示"自动补录失败，请手动处理"；API请求失败显示ElMessage.error；列表无数据时显示ElEmpty
7. 联动/级联交互：审核状态筛选影响列表展示；蓝牙双模式下，策略=REQUIRED时异常申诉必须审核，策略=OPTIONAL时无需申诉（手动打卡）
8. 权限控制交互表现：无 attendance:appeal:approve 权限时[审核]按钮隐藏；主管仅审核本班组人员的申诉
9. H1 防重复请求(强制)："查询"按钮点击后disabled+loading态；行内[审核]按钮点击后整行禁用+半透明遮罩；分页切换时abort前一次未完成请求
10. H2 超时配置(强制)：申诉列表GET请求设置15s超时，审核POST请求设置30s超时；请求耗时>3s时展示全局ElLoading
11. H3 操作确认(强制)：审核操作（通过/驳回）为不可逆操作，提交前弹出ElMessageBox.confirm二次确认，通过操作type="info"提示"确定通过该申诉？通过后将自动补录打卡记录"，驳回操作type="warning"提示"确定驳回该申诉？"
12. H6 批量限制(建议)：当前页面暂无批量操作；若后续扩展批量审核功能，单次批量审核上限100条记录，超出时提示"单次最多选择100条进行批量审核"
13. H8 反馈规范(建议)：审核成功后ElMessage.success显示2秒后自动消失，silent刷新列表状态；失败提示需手动关闭；网络异常提供重试按钮

组件规范

元素	组件	配置参数
审核状态筛选	el-select	clearable, placeholder="全部状态"
申诉人输入	el-input	clearable, maxlength=20, placeholder="请输入申诉人"
日期范围	el-date-picker	type="daterange", value-format="YYYY-MM-DD", range-separator="至"
列表	el-table	stripe, border, :data="tableData"
分页	el-pagination	layout="total, sizes, prev, pager, next", :page-sizes="[10,20,50]"
审核状态标签	el-tag	待审核=warning / 已通过=success / 已驳回=danger
异常类型标签	el-tag	type="info", size="small"
审核按钮	el-button	type="primary", link, v-if="row.auditStatus==='pending'"
审核弹窗	el-dialog	title="审核异常申诉", width="500px", :close-on-click-modal="false"
审核结果	el-radio-group	v-model="auditForm.result"
驳回原因	el-input	type="textarea", :rows="3", maxlength=200, show-word-limit, v-if="auditForm.result==='reject'"
蓝牙双模式差异展示	el-descriptions	:column="2", border, title="蓝牙策略差异"

校验规则

字段	规则	错误提示
审核结果	必选	"请选择审核结果"
驳回原因	驳回时必填，maxlength=200	"请填写驳回原因"
日期范围	结束日期≥开始日期	"结束日期不能早于开始日期"

响应式布局

断点	布局调整
≥1280px（桌面端）	查询条件区水平排列，表格完整展示全部7列，弹窗宽度500px
1024-1279px（Pad横屏）	查询条件区换行排列，表格隐藏"申诉说明"列，弹窗宽度460px
768-1023px（Pad竖屏）	查询条件区垂直堆叠，表格仅显示申诉人、异常类型、审核状态、操作列，弹窗宽度90vw

---

页面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	—

交互流程要求

1. 页面加载流程：进入页面 → 调用补录列表API GET /api/v1/attendance-records/supplements → 渲染补录数据表格，默认按补录时间倒序排列，每页20条
2. 查询/筛选交互流程：选择审核状态/输入补录人/选择日期范围 → 点击[查询] → 重新加载数据 → 点击[重置]清空条件
3. 表单填写与提交流程：本页无新增表单，补录数据来源：①小程序端蓝牙失败后手动补录 ②异常申诉审核通过后系统自动补录
4. 弹窗/抽屉交互流程：点击[审核]（审核状态=待审核时显示）→ 弹出审核弹窗，选择"通过"或"驳回"，驳回时必填驳回原因 → 确认后调用审核API → 成功后关闭弹窗并刷新列表
5. 行内操作流程：点击[审核] → 弹窗选择通过/驳回 → 提交 → 刷新该行审核状态；自动补录的记录（异常申诉审核通过）标记为"自动补录"，无需二次审核
6. 异常与错误处理：审核已审核过的记录提示"该记录已审核"；API请求失败显示ElMessage.error；列表无数据时显示ElEmpty
7. 联动/级联交互：审核状态筛选影响列表展示；补录原因枚举来源于系统配置；自动补录记录与手动补录记录通过标签区分
8. 权限控制交互表现：无 attendance:supplement:approve 权限时[审核]按钮隐藏
9. H1 防重复请求(强制)："查询"按钮点击后disabled+loading态；行内[审核]按钮点击后整行禁用+半透明遮罩；分页切换时abort前一次未完成请求
10. H2 超时配置(强制)：补录列表GET请求设置15s超时，审核POST请求设置30s超时；请求耗时>3s时展示全局ElLoading
11. H3 操作确认(强制)：审核操作（通过/驳回）为不可逆操作，提交前弹出ElMessageBox.confirm二次确认，通过type="info"提示"确定通过该补录记录？"，驳回type="warning"提示"确定驳回该补录记录？"
12. H6 批量限制(建议)：当前页面暂无批量操作；若后续扩展批量审核功能，单次批量审核上限100条记录
13. H8 反馈规范(建议)：审核成功ElMessage.success 2秒自动消失+silent刷新列表；失败手动关闭；网络异常提供重试

组件规范

元素	组件	配置参数
审核状态筛选	el-select	clearable, placeholder="全部状态"
补录人输入	el-input	clearable, maxlength=20, placeholder="请输入补录人"
日期范围	el-date-picker	type="daterange", value-format="YYYY-MM-DD", range-separator="至"
列表	el-table	stripe, border, :data="tableData"
分页	el-pagination	layout="total, sizes, prev, pager, next", :page-sizes="[10,20,50]"
审核状态标签	el-tag	待审核=warning / 已通过=success / 已驳回=danger
补录类型标签	el-tag	自动补录=primary / 手动补录=warning, size="small"
审核按钮	el-button	type="primary", link, v-if="row.auditStatus==='pending'"
审核弹窗	el-dialog	title="审核补录", width="500px", :close-on-click-modal="false"
审核结果	el-radio-group	v-model="auditForm.result"
驳回原因	el-input	type="textarea", :rows="3", maxlength=200, show-word-limit, v-if="auditForm.result==='reject'"

校验规则

字段	规则	错误提示
审核结果	必选	"请选择审核结果"
驳回原因	驳回时必填，maxlength=200	"请填写驳回原因"
日期范围	结束日期≥开始日期	"结束日期不能早于开始日期"

响应式布局

断点	布局调整
≥1280px（桌面端）	查询条件区水平排列，表格完整展示全部列，弹窗宽度500px
1024-1279px（Pad横屏）	查询条件区换行排列，表格隐藏次要列，弹窗宽度460px
768-1023px（Pad竖屏）	查询条件区垂直堆叠，表格仅显示关键列，弹窗宽度90vw

---

需求追溯

功能点编号	功能名称	文档来源	后续服务	关联功能
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）