如何开发人事及OA管理系统的考勤管理板块？（附架构图+流程图+代码参考）

swift
┌────────────┐
                 │ 门禁/打卡机 │
                 └─────┬──────┘
                       │打卡数据
 ┌──────────┐     ┌────▼────┐     ┌────────────┐
 │ 手机APP  │◀────│ API 网关│────▶│ 后端微服务 │
 │(Android/IOS)│   └────┬────┘     │ - 考勤服务 │
 └──────────┘          │          │ - 审批服务 │
                       │          └────┬───────┘
                 ┌─────▼────┐             │
                 │ 第三方集成│(企业微信/钉钉/门禁)│
                 └─────┬────┘             │
                       │ 消息/回调         │
                 ┌─────▼────┐         ┌───▼────┐
                 │ 消息队列  │         │ 数据库  │
                 │ (Kafka/RabbitMQ) │ │ (MySQL) │
                 └─────┬────┘         └────────┘
                       │
                 ┌─────▼────┐
                 │ 报表/BI  │(OLAP/Redis缓存)
                 └─────────┘

css
[员工打卡] -> [API网关] -> [消息队列] -> [打卡解析服务] -> [raw_attendance] -> [规则引擎] -> [attendance_record]

sql
-- 员工表
CREATE TABLE employee (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  emp_no VARCHAR(50) UNIQUE,
  name VARCHAR(100),
  dept_id BIGINT,
  job_title VARCHAR(100),
  work_status ENUM('active','left','on_leave'),
  created_at DATETIME,
  updated_at DATETIME
);
-- 原始打卡记录（raw）
CREATE TABLE raw_attendance (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  emp_id BIGINT NOT NULL,
  device_id VARCHAR(100),
  clock_time DATETIME NOT NULL,
  latitude DECIMAL(10,7),
  longitude DECIMAL(10,7),
  photo_url VARCHAR(255),
  source ENUM('device','mobile','third_party'),
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- 处理后的考勤记录
CREATE TABLE attendance_record (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  emp_id BIGINT NOT NULL,
  date DATE NOT NULL,
  shift_id BIGINT, -- 排班
  clock_in DATETIME,
  clock_out DATETIME,
  total_work_minutes INT,
  status JSON, -- { "am":"normal","pm":"late", ... }
  is_locked BOOLEAN DEFAULT FALSE,
  updated_at DATETIME
);
-- 请假/加班/补卡申请表 (统一申请表)
CREATE TABLE attendance_request (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  emp_id BIGINT NOT NULL,
  req_type ENUM('leave','overtime','补卡','外勤','出差','调休'),
  start_time DATETIME,
  end_time DATETIME,
  hours DECIMAL(5,2), -- 申请时长
  reason TEXT,
  attachments JSON,
  status ENUM('pending','approved','rejected','cancelled'),
  applicant_id BIGINT,
  approver_chain JSON, -- 审批链与意见
  created_at DATETIME,
  updated_at DATETIME
);

ts
// src/controllers/clockController.ts
import { Request, Response } from 'express';
import db from '../db';
import { publishToQueue } from '../mq';
export async function receiveClock(req: Request, res: Response) {
  const { empId, deviceId, clockTime, lat, lng, photo } = req.body;
  if (!empId || !clockTime) return res.status(400).send({ error: '缺少参数' });
  // 保存 raw
  const [result] = await db.execute(
    'INSERT INTO raw_attendance (emp_id, device_id, clock_time, latitude, longitude, photo_url) VALUES (?, ?, ?, ?, ?, ?)',
    [empId, deviceId, clockTime, lat || null, lng || null, photo || null]
  );
  // 异步发送到消息队列，由 worker 处理规则
  await publishToQueue('attendance_raw', { id: result.insertId });
  return res.json({ ok: true, rawId: result.insertId });
}

ts
// src/workers/processRaw.ts
import db from '../db';
export async function processRawRecord(rawId: number) {
  const [rows] = await db.execute('SELECT * FROM raw_attendance WHERE id=?', [rawId]);
  if (!rows.length) return;
  const raw = rows[0];
  const empId = raw.emp_id;
  const date = raw.clock_time.toISOString().slice(0,10);
  // 简化逻辑：如果已有上班时间则把此作为下班
  const [existing] = await db.execute('SELECT * FROM attendance_record WHERE emp_id=? AND date=?', [empId, date]);
  if (!existing.length) {
    await db.execute(
      'INSERT INTO attendance_record (emp_id, date, clock_in, updated_at) VALUES (?, ?, ?, NOW())',
      [empId, date, raw.clock_time]
    );
  } else {
    const rec = existing[0];
    // 更新下班时间为latest time
    let clockOut = rec.clock_out ? (new Date(rec.clock_out) < new Date(raw.clock_time) ? raw.clock_time : rec.clock_out) : raw.clock_time;
    // 计算工作分钟数（简化）
    const inTime = new Date(rec.clock_in);
    const outTime = new Date(clockOut);
    const minutes = Math.max(0, Math.round((outTime.getTime()-inTime.getTime())/60000));
    await db.execute('UPDATE attendance_record SET clock_out=?, total_work_minutes=?, updated_at=NOW() WHERE id=?', [clockOut, minutes, rec.id]);
  }
}

ts
// src/controllers/requestController.ts
export async function createRequest(req: Request, res: Response) {
  const { empId, reqType, startTime, endTime, hours, reason, attachments } = req.body;
  // 校验
  // 插入
  const [result] = await db.execute(
    'INSERT INTO attendance_request (emp_id, req_type, start_time, end_time, hours, reason, attachments, status, applicant_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, "pending", ?, NOW())',
    [empId, reqType, startTime, endTime, hours, reason, JSON.stringify(attachments || []), empId]
  );
  // 发起审批流（示例：简单串行的审批）
  // sendNotificationToApprover(...)
  res.json({ ok: true, requestId: result.insertId });
}

jsx
// ClockButton.jsx
import React from 'react';
import axios from 'axios';
export default function ClockButton({ empId }) {
  async function handleClock(type='in') {
    // 获取位置
    navigator.geolocation.getCurrentPosition(async pos => {
      const payload = {
        empId,
        deviceId: 'mobile-'+navigator.userAgent,
        clockTime: new Date().toISOString(),
        lat: pos.coords.latitude,
        lng: pos.coords.longitude,
      };
      // 上传拍照可以通过 input file 或相机API
      const res = await axios.post('/api/clock', payload);
      if (res.data.ok) alert('打卡成功');
      else alert('打卡失败');
    }, err => {
      alert('获取位置失败: '+err.message);
    }, { enableHighAccuracy: true, timeout: 10000 });
  }
  return <button onClick={()=>handleClock()}>立即打卡</button>;
}

sql
SELECT e.emp_no, e.name, a.date,
  a.clock_in, a.clock_out, a.total_work_minutes,
  JSON_EXTRACT(a.status, '$.am') AS morning_status,
  JSON_EXTRACT(a.status, '$.pm') AS afternoon_status
FROM attendance_record a
JOIN employee e ON e.id = a.emp_id
WHERE a.date BETWEEN '2025-07-01' AND '2025-07-31'
AND e.dept_id = 10
ORDER BY e.emp_no, a.date;