AI人脸识别考勤系统 - 技术架构文档1. 架构设计graph TBsubgraph 前端层Web[React管理界面br人员管理/考勤记录/设置]Client[React考勤客户端br摄像头扫描/实时识别]endsubgraph 后端层API[Express API服务器brRESTful API]FR[Python人脸识别服务brInsightFace/ArcFace]endsubgraph 数据层DB[SQLite数据库br员工信息/考勤记录]FS[文件存储br人脸照片/特征向量]endWeb -- APIClient -- APIClient --|视频帧上传| FRAPI --|特征提取/比对请求| FRAPI -- DBAPI -- FSFR -- FS架构说明前端React TypeScript Tailwind CSSVite构建后端APIExpress TypeScript处理业务逻辑和数据库操作人脸识别服务Python FastAPI使用InsightFace进行人脸检测、特征提取和1:N比对数据库SQLite轻量级无需额外安装支持离线运行通信前端与Express通过RESTful API通信Express与Python服务通过HTTP通信2. 技术说明前端React18 TypeScript Tailwind CSS3 Vite初始化工具vite-init (react-express-ts模板)后端APIExpress4 TypeScript (ESM)人脸识别服务Python 3.10 / FastAPI / InsightFace (insightface onnxruntime)数据库SQLite (better-sqlite3)状态管理Zustand路由react-router-dom图标lucide-react文件上传multerExcel导出exceljs3. 路由定义路由用途/仪表盘 - 今日考勤概览/employees人员管理 - 员工列表/employees/new人员录入 - 新增员工/employees/:id/edit人员编辑 - 修改员工信息/attendance考勤记录 - 打卡流水查询/settings考勤设置 - 规则与参数配置/scanner考勤客户端 - 摄像头扫描打卡界面4. API定义4.1 员工管理// 获取员工列表 GET /api/employees?page1pageSize20departmentkeyword Response: { data: Employee[], total: number, page: number } // 获取单个员工 GET /api/employees/:id Response: Employee // 创建员工multipart/form-data含照片 POST /api/employees Body: { emp_id: string, name: string, department: string, position: string, photo: File } Response: Employee // 更新员工 PUT /api/employees/:id Body: { name?: string, department?: string, position?: string, status?: active|disabled, photo?: File } Response: Employee // 删除员工 DELETE /api/employees/:id Response: { success: boolean } // 批量导入 POST /api/employees/batch Body: FormData { file: File (zip包含照片Excel) } Response: { success: number, failed: number, errors: string[] }4.2 考勤记录// 获取考勤记录 GET /api/attendance?date2026-06-07departmentemp_idpage1pageSize20 Response: { data: AttendanceRecord[], total: number } // 创建打卡记录由识别服务调用 POST /api/attendance Body: { emp_id: string, face_score: number, device_id: string } Response: AttendanceRecord // 导出考勤记录 GET /api/attendance/export?dateFrom2026-06-01dateTo2026-06-07department Response: Blob (Excel文件) // 获取今日统计 GET /api/attendance/today-stats Response: { total: number, present: number, late: number, absent: number, recentRecords: AttendanceRecord[] }4.3 考勤设置// 获取设置 GET /api/settings Response: AttendanceSettings // 更新设置 PUT /api/settings Body: AttendanceSettings Response: AttendanceSettings4.4 人脸识别服务APIPython FastAPI// 人脸特征提取从上传图片 POST /fr/extract Body: FormData { image: File } Response: { success: boolean, feature: number[], bbox: [number,number,number,number], quality: number } // 人脸比对1:N搜索 POST /fr/search Body: { feature: number[], threshold: number } Response: { matched: boolean, emp_id: string | null, score: number } // 从视频帧检测人脸并比对 POST /fr/detect-and-search Body: FormData { image: File, threshold: number } Response: { detected: boolean, faces: Array{ bbox: number[], emp_id: string | null, score: number } } // 健康检查 GET /fr/health Response: { status: ok, model_loaded: boolean }4.5 数据类型定义interface Employee { id: number; emp_id: string; // 工号 name: string; // 姓名 department: string; // 部门 position: string; // 职位 photo_path: string; // 照片路径 feature_path: string; // 特征向量文件路径 status: active | disabled; created_at: string; updated_at: string; } interface AttendanceRecord { id: number; emp_id: string; employee_name: string; capture_time: string; // 打卡时间 device_id: string; // 设备标识 type: check_in | check_out; // 上班/下班 face_score: number; // 人脸比对分数 status: normal | late | early | absent; created_at: string; } interface AttendanceSettings { check_in_time: string; // 上班时间 09:00 check_out_time: string; // 下班时间 18:00 check_in_start: string; // 上班打卡开始时间 06:00 check_in_end: string; // 上班打卡截止时间 10:00 check_out_start: string; // 下班打卡开始时间 17:00 check_out_end: string; // 下班打卡截止时间 23:59 late_threshold_min: number; // 迟到判定分钟数 cooldown_min: number; // 重复打卡冷却时间分钟 face_threshold: number; // 人脸比对阈值 0-1 device_id: string; // 本设备标识 }5. 服务器架构图graph LR Controller[Controllerbr路由与参数校验] -- Service[Servicebr业务逻辑] Service -- Repository[Repositorybr数据访问] Repository -- Database[SQLitebr数据存储] Service -- FRClient[FRClientbr人脸识别HTTP客户端] FRClient -- FRService[Python FastAPIbr人脸识别服务] FRService -- InsightFace[InsightFacebr人脸检测与特征提取] FRService -- FeatureStore[特征文件存储br本地.npy文件]6. 数据模型6.1 数据模型定义erDiagram employee { int id PK string emp_id UK 工号 string name 姓名 string department 部门 string position 职位 string photo_path 照片路径 string feature_path 特征向量路径 string status 状态: active/disabled datetime created_at 创建时间 datetime updated_at 更新时间 } attendance_record { int id PK string emp_id FK 工号 datetime capture_time 打卡时间 string device_id 设备标识 string type 类型: check_in/check_out float face_score 比对分数 string status 状态: normal/late/early/absent datetime created_at 创建时间 } settings { int id PK string key UK 设置键 string value 设置值(JSON) datetime updated_at 更新时间 } sync_log { int id PK string device_id 设备标识 string action 同步动作 string status 状态 datetime synced_at 同步时间 } employee ||--o{ attendance_record : emp_id6.2 数据定义语言-- 员工信息表 CREATE TABLE IF NOT EXISTS employee ( id INTEGER PRIMARY KEY AUTOINCREMENT, emp_id TEXT NOT NULL UNIQUE, name TEXT NOT NULL, department TEXT NOT NULL DEFAULT , position TEXT NOT NULL DEFAULT , photo_path TEXT NOT NULL DEFAULT , feature_path TEXT NOT NULL DEFAULT , status TEXT NOT NULL DEFAULT active CHECK(status IN (active, disabled)), created_at TEXT NOT NULL DEFAULT (datetime(now, localtime)), updated_at TEXT NOT NULL DEFAULT (datetime(now, localtime)) ); -- 打卡记录表 CREATE TABLE IF NOT EXISTS attendance_record ( id INTEGER PRIMARY KEY AUTOINCREMENT, emp_id TEXT NOT NULL, capture_time TEXT NOT NULL, device_id TEXT NOT NULL DEFAULT default, type TEXT NOT NULL DEFAULT check_in CHECK(type IN (check_in, check_out)), face_score REAL NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT normal CHECK(status IN (normal, late, early, absent)), created_at TEXT NOT NULL DEFAULT (datetime(now, localtime)), FOREIGN KEY (emp_id) REFERENCES employee(emp_id) ); -- 索引 CREATE INDEX IF NOT EXISTS idx_attendance_emp_id ON attendance_record(emp_id); CREATE INDEX IF NOT EXISTS idx_attendance_capture_time ON attendance_record(capture_time); CREATE INDEX IF NOT EXISTS idx_attendance_date ON attendance_record(date(capture_time)); CREATE INDEX IF NOT EXISTS idx_employee_department ON employee(department); CREATE INDEX IF NOT EXISTS idx_employee_status ON employee(status); -- 系统设置表 CREATE TABLE IF NOT EXISTS settings ( id INTEGER PRIMARY KEY AUTOINCREMENT, key TEXT NOT NULL UNIQUE, value TEXT NOT NULL DEFAULT {}, updated_at TEXT NOT NULL DEFAULT (datetime(now, localtime)) ); -- 同步日志表 CREATE TABLE IF NOT EXISTS sync_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, device_id TEXT NOT NULL, action TEXT NOT NULL, status TEXT NOT NULL DEFAULT pending, synced_at TEXT NOT NULL DEFAULT (datetime(now, localtime)) ); -- 默认设置 INSERT OR IGNORE INTO settings (key, value) VALUES (attendance_rules, {check_in_time:09:00,check_out_time:18:00,check_in_start:06:00,check_in_end:10:00,check_out_start:17:00,check_out_end:23:59,late_threshold_min:0,cooldown_min:5}), (face_recognition, {threshold:0.6,device_id:default});7. Python人脸识别服务设计7.1 技术栈框架FastAPI uvicorn人脸检测与识别InsightFace (buffalo_l模型) onnxruntime依赖insightface, onnxruntime, opencv-python, numpy, pillow7.2 服务端口Express API服务器3001Python人脸识别服务3002Vite开发服务器51737.3 特征库管理每个员工的人脸特征向量保存为.npy文件存储在data/features/目录服务启动时加载所有特征到内存构建特征矩阵新增/删除员工时通过API通知特征库更新1:N比对使用余弦相似度阈值默认0.67.4 启动方式# 安装Python依赖 pip install fastapi uvicorn insightface onnxruntime opencv-python numpy pillow # 启动人脸识别服务 cd face_recognition_service python main.py8. 项目目录结构AI考勤/ ├── src/ # React前端代码 │ ├── components/ # 通用组件 │ ├── pages/ # 页面组件 │ │ ├── Dashboard.tsx # 仪表盘 │ │ ├── Employees.tsx # 人员管理 │ │ ├── Attendance.tsx # 考勤记录 │ │ ├── Settings.tsx # 考勤设置 │ │ └── Scanner.tsx # 考勤客户端 │ ├── hooks/ # 自定义Hooks │ ├── utils/ # 工具函数 │ ├── App.tsx # 应用入口 │ └── main.tsx # 渲染入口 ├── api/ # Express后端代码 │ ├── routes/ # API路由 │ ├── services/ # 业务逻辑 │ ├── repositories/ # 数据访问 │ ├── middleware/ # 中间件 │ ├── database.ts # 数据库初始化 │ └── index.ts # 服务器入口 ├── face_recognition_service/ # Python人脸识别服务 │ ├── main.py # FastAPI入口 │ ├── face_engine.py # 人脸识别引擎封装 │ ├── feature_store.py # 特征库管理 │ └── requirements.txt # Python依赖 ├── data/ # 数据目录 │ ├── database.sqlite # SQLite数据库 │ ├── photos/ # 员工照片 │ └── features/ # 特征向量文件 ├── migrations/ # 数据库迁移SQL ├── shared/ # 前后端共享类型 ├── package.json ├── tsconfig.json ├── vite.config.ts └── tailwind.config.js