🎯 考勤打卡系统重写需求文档

项目概述

开发一个现代化的考勤打卡系统，专门针对外派工程项目的灵活考勤管理需求。系统支持多工程并行、一天多次打卡、智能地理位置验证等功能。

技术栈架构调整

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│React Native App │    │   Vue3/React    │    │   Bun Backend   │
│ (Android端全功能)│◄──►│   Web管理端     │◄──►│  (API + WS)     │
│ 普通用户+管理员  │    │   (SPA应用)     │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   MySQL 5.7     │
                    └─────────────────┘

核心技术选型

后端: Bun + Elysia.js + Drizzle ORM + JWT + WebSocket
Web管理端: Vue3 + TypeScript + Vite + Element Plus + 高德地图JS API
或者: React + TypeScript + Vite + Ant Design + 高德地图JS API
移动端: React Native + Expo + TypeScript + 高德地图SDK + AsyncStorage离线缓存
数据库: MySQL 5.7 本地连接：localhost:3306 用户名密码都是root
地图服务: 高德地图API (主) + 百度地图API (备用)

架构调整说明

管理后台改为SPA: 避免Next.js的SSR复杂性，更好兼容高德地图API
React Native双模式: 支持普通用户和管理员登录，管理员可在移动端完成所有管理功能
Web端可选: Web管理端作为补充，主要用于大屏幕操作和数据展示

业务场景与核心需求

1. 外派工程管理

多工程并行: 支持同时管理多个外派工程项目
动态人员分配: 员工可以分配到不同工程，支持跨工程调配
灵活考勤规则: 每个工程可以有独立的考勤地点和时间规则
一天多次打卡: 支持上班下班多次打卡（适应外派工作特点）

2. 智能地理位置验证

混合定位: GPS + Wi-Fi + 蓝牙信标
地理围栏: 圆形和多边形电子围栏
WiFi辅助: 指定WiFi SSID作为打卡验证
离线打卡: 网络断开时本地缓存，恢复后自动同步

3. 实时同步与监控

WebSocket实时通信: 打卡状态实时推送
设备指纹防伪: 防止位置伪造和设备替换
异常检测: 自动识别异常打卡行为

数据库设计要求

核心表结构

-- 用户表
users (id, username, password_hash, real_name, phone, email, department, role, device_hash, active)

-- 工程项目表  
projects (id, name, description, client_name, project_manager, start_date, end_date, status, budget, location_id)

-- 工程人员分配表
project_assignments (id, project_id, user_id, role, start_date, end_date, hourly_rate, is_active)

-- 打卡地点表
locations (id, name, address, latitude, longitude, radius, geofence, wifi_ssids, work_time_start, work_time_end, project_id, is_main_location, active)

-- 打卡记录表
check_records (id, user_id, location_id, project_id, check_type, latitude, longitude, accuracy, address, distance, wifi_ssid, device_info, photo_url, is_offline_sync)

-- 考勤统计表
attendance_summary (id, user_id, project_id, date, check_in_count, check_out_count, first_check_in, last_check_out, total_work_minutes, is_abnormal)

功能模块详细需求

📱 React Native + Expo移动端 (双模式设计)

通用功能模块

登录认证
JWT token认证
设备指纹绑定
角色识别 (employee/manager/admin)
自动登录保持
用户界面切换
根据用户角色显示不同界面
普通用户: 简洁的打卡界面
管理员: 完整的管理功能界面

普通用户模式功能

打卡功能
实时定位获取
地理围栏验证
WiFi SSID检测
拍照上传（可选）
离线打卡缓存
工程切换
显示用户分配的工程列表
自动识别当前位置对应的工程
手动切换工程打卡
历史记录
个人打卡历史
按工程筛选
离线数据同步状态

管理员模式功能

工程管理
工程列表查看和搜索
创建、编辑、删除工程项目
工程状态管理
工程详情查看
团队管理
人员分配到工程
角色和权限设置
工时和薪资配置
人员调配管理
地点管理
高德地图集成选点
地理围栏设置
WiFi配置管理
工作时间设置
考勤监控
实时打卡状态查看
考勤统计和报表
异常记录分析
数据导出功能
用户管理
员工档案管理
权限分配
设备绑定管理

🖥️ Vue3/React Web管理端 (可选补充)

技术选型建议

方案A: Vue3技术栈

Vue3 + TypeScript + Vite + Pinia + Element Plus + 高德地图JS API

方案B: React技术栈

React + TypeScript + Vite + Zustand + Ant Design + 高德地图JS API

核心功能模块

地图管理中心
高德地图大屏展示
批量地点管理
可视化围栏编辑
地点导入导出
数据分析中心
考勤数据可视化
多维度统计图表
趋势分析报告
异常数据挖掘
系统配置中心
全局参数设置
权限模板管理
系统日志查看
备份恢复功能

⚡ Bun后端API

1. 认证模块

POST /auth/login     // 用户登录 (支持角色识别)
POST /auth/logout    // 用户登出  
GET  /auth/profile   // 获取用户信息
POST /auth/refresh   // 刷新token

2. 工程管理模块

GET    /projects              // 获取工程列表
POST   /projects              // 创建工程
GET    /projects/:id          // 获取工程详情
PUT    /projects/:id          // 更新工程
DELETE /projects/:id          // 删除工程
GET    /projects/:id/assignments    // 获取工程人员分配
POST   /projects/:id/assignments    // 添加人员到工程
PUT    /projects/:id/assignments/:assignmentId  // 更新人员分配
DELETE /projects/:id/assignments/:assignmentId  // 移除人员

3. 地点管理模块

GET    /locations/all         // 获取所有地点（管理员）
GET    /locations             // 获取用户可用地点
POST   /locations             // 创建地点
PUT    /locations/:id         // 更新地点
DELETE /locations/:id         // 删除地点
POST   /locations/assign      // 分配地点给用户
GET    /locations/nearby      // 获取附近地点

4. 打卡模块

POST   /checkin               // 提交打卡
GET    /checkin/records       // 获取打卡记录
GET    /checkin/today         // 获取今日打卡状态
POST   /checkin/sync          // 离线数据同步
GET    /checkin/status        // 获取实时打卡状态

5. 报表模块

GET    /reports/attendance    // 考勤统计报表
GET    /reports/detailed      // 详细考勤分析
GET    /reports/summary       // 考勤汇总
POST   /reports/export        // 导出报表
GET    /reports/realtime      // 实时统计数据

6. 用户管理模块

GET    /users                 // 获取用户列表
POST   /users                 // 创建用户
PUT    /users/:id             // 更新用户
DELETE /users/:id             // 删除用户
POST   /users/:id/reset-password  // 重置密码
GET    /users/:id/assignments     // 获取用户工程分配

7. WebSocket实时通信

ws://localhost:8080/ws
- 实时打卡状态推送
- 地点更新通知
- 异常告警推送
- 系统消息广播

关键技术实现要求

1. Flutter双模式UI设计

// 根据用户角色显示不同界面
class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final user = Provider.of<UserProvider>(context).user;

    switch (user.role) {
      case 'admin':
      case 'manager':
        return AdminDashboard();
      case 'employee':
      default:
        return EmployeeDashboard();
    }
  }
}

2. 智能打卡逻辑

// 打卡验证流程
1. 获取用户当前活跃的工程分配
2. 获取工程关联的所有打卡地点
3. 计算用户位置与各地点的距离
4. 验证地理围栏 + WiFi SSID
5. 自动关联到最近的有效工程
6. 记录打卡并推送实时状态

3. 离线同步机制

// React Native端离线缓存
- AsyncStorage本地存储打卡记录
- 网络恢复时自动批量同步
- 冲突检测和数据合并
- 同步状态实时反馈

4. 地图集成方案

// 高德地图JS API (Web端)
- 地点选择和坐标获取
- 地理围栏绘制
- 逆地理编码获取地址
- 批量地点管理

// 高德地图React Native SDK (移动端)
- 实时定位和地图显示
- 地理围栏检测
- Expo Location位置服务

高德地图api 相关key: 管理后台 Web端(JS API) Key:ce5fad118b8766d89a6602b6f1afe914 安全密钥:7142ad20f8f925bc9cb4fa0844f75c31
后端 Web服务 Key:a7b6e9d8d7144fe33f448eb79f808da5 安全密钥:无

开发优先级

第一阶段 (核心功能)

数据库设计和初始化
后端API基础架构
用户认证和权限系统
React Native基础打卡功能
React Native双模式界面设计

第二阶段 (管理功能)

React Native管理员界面开发
工程项目管理功能
团队人员分配功能
地点管理和地图集成
基础考勤报表

第三阶段 (高级功能)

离线同步机制
WebSocket实时通信
高级报表和分析
Web管理端开发（可选）

第四阶段 (优化完善)

性能优化
异常处理完善
用户体验优化
部署和运维工具

部署与运维要求

环境配置

开发环境: Windows + Android Studio Giraffe 2022.3.1
生产环境: 腾讯云服务器 (2核4G推荐)
数据库: MySQL 5.7
反向代理: Nginx
SSL证书: Let's Encrypt

性能要求

API响应时间: < 200ms
打卡处理: < 500ms
WebSocket延迟: < 100ms
离线同步: 支持1000+条记录批量同步
并发用户: 支持100+用户同时在线

安全要求

JWT token认证
设备指纹防伪
API接口权限控制
敏感数据加密存储
防SQL注入和XSS攻击

重点调整说明: 1. 管理后台改为SPA: 使用Vue3或React，避免Next.js的地图集成问题 2. React Native双模式: 一个App支持普通用户和管理员，管理员可完成所有管理功能 3. Web端可选: Web管理端作为补充，主要用于大屏幕数据分析和批量操作 4. 地图集成优化: 在SPA环境下更好地集成高德地图API