基于Django与微信小程序的考勤系统开发实践-代码聚汇网

1. 从手工Excel考勤表到自研系统：这个项目要解决的真实问题

1.1 手工考勤的三大痛点

先说说我为什么碰这个项目。当时团队大概四五十人，有固定坐班的，也有常年在外跑客户的销售。考勤一直用最原始的办法：办公室放一台指纹机，外勤人员每天在微信群里发定位截图，月底行政把指纹机导出的记录和截图汇总到Excel里人工核对。这套流程撑到三十人以内还行，人一多立刻露馅——漏截图、忘打卡、核对错行，每个月总有几笔说不清的账。

真正压垮我的是一次月底对账：一个销售明明在外地见了客户，但微信定位截图发到了群里没人保存，月底行政说缺卡要扣钱，销售不服，来回扯了三天。那一刻我意识到，考勤系统的核心不是"记录打卡"这个动作，而是把打卡这个行为变成可追溯、可校验、可自动汇总的数据。谁在哪儿、什么时间打的卡，后端一查便知，不用人肉对账。

所以当决定自研考勤系统时，我给自己定了三个硬指标：

员工打卡必须简单到"打开即打"，不能有额外学习成本；
打卡位置和时间必须有服务端校验，不能只靠前端传什么就信什么；
月底报表要一键导出，管理员不用手工处理原始数据。

1.2 技术选型：Python+Django+小程序为什么是黄金组合

技术选型这事，我一开始也纠结过。备选方案有原生Android App、H5网页、Flutter跨平台，但最后全部排除，选了微信小程序 + Python Django的组合。

小程序的优势非常明显：员工不需要安装任何App。微信人人都有，小程序搜索即用、用完即走。对外勤销售来说，微信里已经堆了几十个群，让他们再装一个考勤App，大概率刚装完就被清理掉。而小程序挂在微信里，不容易被误删，打卡路径也短：下拉微信首页，点一下就进去了。

Django这边则是典型的"开发效率优先"选择。考勤系统虽然业务逻辑不算复杂，但涉及用户体系、权限管理、后台管理、数据统计，这些都是Django的强项。Django自带的Admin后台可以快速搭建管理界面，内置的ORM省去手写SQL的体力活，用户认证、CSRF防护、分页这些也都有现成方案。对一个小型团队的内部系统来说，Django的"全家桶"特性正好击中需求，不需要像Spring那样拼一堆组件。

Python生态还有个隐性红利：后续如果要加人脸识别打卡、智能排班、异常检测这些功能，Python的AI库能直接接进来。我这个系统的二期规划了人脸打卡，选Python等于提前铺好了路。

1.3 系统整体架构与数据流

整套系统的架构，我用一句话概括：小程序负责采集数据，Django负责校验和存储，Admin后台负责管理和呈现。数据流是这样的：

员工在小程序端操作，小程序调用微信的登录接口拿到临时凭证，交给Django后端换取用户身份。打卡时，小程序通过微信的定位API获取当前经纬度，连同打卡类型（上班/下班）一起提交到后端。后端拿到数据后做三道校验：身份是否合法、时间是否在允许范围内、位置是否在打卡半径内。全部通过则写入考勤记录表，同时触发迟到/早退/外勤等状态的自动标记。

管理员这边走的是另一个入口：Django Admin后台。管理员可以配置部门、员工、打卡规则（上下班时间、打卡地点坐标、允许的打卡半径），也可以查看实时考勤记录、处理补卡申请、导出月度报表。前后端通过RESTful API通信，数据格式统一用JSON。

这里有个设计心得：打卡这件事，前端只负责采集，所有判定逻辑必须放后端。我见过不少考勤项目把"是否迟到"的判断写在小程序里，结果员工改一下手机时间、改一下定位，就能伪造打卡记录。服务端校验虽然不能完全杜绝作弊，但至少把门槛提高了一大截。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 数据库建模：把考勤规则变成可执行的表结构

2.1 核心表设计

考勤系统的数据模型，核心就四张表：部门表、员工表、打卡规则表、考勤记录表。先把建表代码贴出来，再逐个讲设计理由。

python复制# models.py
from django.db import models
from django.contrib.auth.models import User

class Department(models.Model):
    name = models.CharField(max_length=50, unique=True, verbose_name="部门名称")
    parent = models.ForeignKey('self', null=True, blank=True, on_delete=models.CASCADE, verbose_name="上级部门")
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        verbose_name = "部门"
        verbose_name_plural = "部门"

    def __str__(self):
        return self.name


class Employee(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE, verbose_name="关联系统账号")
    name = models.CharField(max_length=30, verbose_name="姓名")
    employee_no = models.CharField(max_length=20, unique=True, verbose_name="工号")
    department = models.ForeignKey(Department, on_delete=models.PROTECT, verbose_name="所属部门")
    phone = models.CharField(max_length=20, blank=True, verbose_name="手机号")
    is_active = models.BooleanField(default=True, verbose_name="在职状态")
    joined_date = models.DateField(null=True, blank=True, verbose_name="入职日期")

    class Meta:
        verbose_name = "员工"
        verbose_name_plural = "员工"

    def __str__(self):
        return f"{self.name}({self.employee_no})"


class AttendanceRule(models.Model):
    name = models.CharField(max_length=50, verbose_name="规则名称")
    department = models.ForeignKey(Department, null=True, blank=True, on_delete=models.CASCADE, verbose_name="适用部门")
    work_start_time = models.TimeField(verbose_name="上班时间")
    work_end_time = models.TimeField(verbose_name="下班时间")
    late_minutes = models.IntegerField(default=0, verbose_name="宽限迟到分钟数")
    early_leave_minutes = models.IntegerField(default=0, verbose_name="宽限早退分钟数")
    checkin_radius = models.FloatField(default=300, verbose_name="打卡半径（米）")
    latitude = models.FloatField(verbose_name="打卡点纬度")
    longitude = models.FloatField(verbose_name="打卡点经度")
    address = models.CharField(max_length=200, blank=True, verbose_name="打卡点地址")
    is_active = models.BooleanField(default=True, verbose_name="是否启用")

    class Meta:
        verbose_name = "考勤规则"
        verbose_name_plural = "考勤规则"

    def __str__(self):
        return self.name


class AttendanceRecord(models.Model):
    STATUS_CHOICES = [
        ('normal', '正常'),
        ('late', '迟到'),
        ('early', '早退'),
        ('absent', '缺卡'),
        ('field', '外勤'),
        ('leave', '请假'),
    ]

    TYPE_CHOICES = [
        ('checkin', '上班打卡'),
        ('checkout', '下班打卡'),
    ]

    employee = models.ForeignKey(Employee, on_delete=models.CASCADE, related_name='attendance_records', verbose_name="员工")
    rule = models.ForeignKey(AttendanceRule, on_delete=models.SET_NULL, null=True, blank=True, verbose_name="打卡规则")
    date = models.DateField(verbose_name="打卡日期")
    checkin_time = models.DateTimeField(null=True, blank=True, verbose_name="上班打卡时间")
    checkout_time = models.DateTimeField(null=True, blank=True, verbose_name="下班打卡时间")
    checkin_location = models.CharField(max_length=200, blank=True, verbose_name="上班打卡位置")
    checkout_location = models.CharField(max_length=200, blank=True, verbose_name="下班打卡位置")
    checkin_latitude = models.FloatField(null=True, blank=True, verbose_name="上班打卡纬度")
    checkin_longitude = models.FloatField(null=True, blank=True, verbose_name="上班打卡经度")
    checkout_latitude = models.FloatField(null=True, blank=True, verbose_name="下班打卡纬度")
    checkout_longitude = models.FloatField(null=True, blank=True, verbose_name="下班打卡经度")
    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='normal', verbose_name="考勤状态")
    is_manual = models.BooleanField(default=False, verbose_name="是否补卡")
    remark = models.CharField(max_length=200, blank=True, verbose_name="备注")
    created_at = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")

    class Meta:
        verbose_name = "考勤记录"
        verbose_name_plural = "考勤记录"
        unique_together = [('employee', 'date')]
        ordering = ['-date', 'employee']

    def __str__(self):
        return f"{self.employee.name} {self.date} {self.get_status_display()}"

注意AttendanceRecord表里的unique_together = [('employee', 'date')]，这是防重复记录的关键约束。一个员工一天只能有一条考勤记录，上班打卡写入checkin_time，下班打卡更新checkout_time，而不是每次打卡都新建一行。这样设计的好处是：查询某天考勤状态时，只需要取一条记录，不需要做行转列的聚合。

2.2 历史快照为什么比实时关联更重要

讲一个我踩过的坑。第一版设计里，考勤记录表直接通过外键关联Department，员工调部门之后，历史考勤记录里关联的部门会自动变成新部门。结果月底统计销售部门的考勤时，发现离职转岗人员的记录全归到了新部门，数据一团糟。

后来改成记录冗余快照的方案：考勤记录里只存rule（打卡规则）的ID，但规则表里的上下班时间、打卡坐标这些字段，在生成记录时同步冗余一份到考勤记录表。这样即使后续修改了打卡规则，历史记录依然保留当时的规则。

这里建议你也遵循这个思路：业务数据表里该冗余的字段一定要冗余，不要迷信"规范化设计"。考勤记录是典型的"流水型"数据，一旦生成就代表历史事实，不能随主数据的变更而漂移。部门名称、规则时间、打卡坐标这些字段，看似可以临时关联查询，但三个月后再看，关联出来的可能已经不是当初的值了。

2.3 打卡规则的可配置设计

打卡规则表单独拆出来，而不是把上班时间、打卡坐标写死在代码里，是为了适应不同部门、不同班次的差异。我见过一些简陋的考勤项目，打卡坐标直接写在Django的settings.py里，两个办公地点一上线就傻眼了。

我的设计是：AttendanceRule通过department外键关联部门，department为空时表示全局默认规则。查询时按优先级匹配：先查员工所属部门是否有专属规则，没有再查全局规则。这样做的好处是，新员工入职时不需要单独配置，自动落到全局规则上；后续某个部门要改成弹性工作制，只需要新增一条规则并关联该部门即可。

打卡半径参数checkin_radius也是可配置的。固定办公点可以设200米，园区办公可以放宽到500米。这里有个细节：半径太小会导致GPS漂移误判，太大又形同虚设。根据我的实测体验，城市环境下手机GPS的误差通常在10到50米之间，写字楼附近因为有遮挡，误差可能到100米。所以写字楼场景建议设置300米左右的半径，园区场景可以适当放宽。

3. 服务端打卡接口：时间、位置、防重三板斧

3.1 登录鉴权：小程序openid怎么和员工绑定

小程序和后端的数据交互，第一步是解决"你是谁"的问题。微信小程序没有传统的账号密码登录，而是通过微信的wx.login拿到一个临时code，后端拿着这个code去微信的接口换openid——这是用户在微信生态内的唯一标识。

我的做法是：员工首次打开小程序时，进入绑定页面，输入工号，后端校验工号存在且未绑定，就把这个openid和员工记录做关联。之后每次打卡，小程序端静默登录，后端就能通过openid定位到具体员工。

贴一下核心代码：

python复制# views/auth.py
import requests
from django.conf import settings
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

class WxLoginView(APIView):
    def post(self, request):
        code = request.data.get('code')
        if not code:
            return Response({'error': '缺少code'}, status=status.HTTP_400_BAD_REQUEST)

        appid = settings.WX_APPID
        secret = settings.WX_SECRET
        url = 'https://api.weixin.qq.com/sns/jscode2session'
        params = {
            'appid': appid,
            'secret': secret,
            'js_code': code,
            'grant_type': 'authorization_code'
        }
        resp = requests.get(url, params=params).json()
        openid = resp.get('openid')
        if not openid:
            return Response({'error': '登录失败: ' + resp.get('errmsg', '')}, status=status.HTTP_400_BAD_REQUEST)

        # 绑定或获取员工
        employee = Employee.objects.filter(user__username=openid).first()
        if not employee:
            # 未绑定，返回openid让前端进入绑定页
            return Response({'openid': openid, 'bound': False})

        # 签发django-rest-framework-simplejwt的token
        from rest_framework_simplejwt.tokens import RefreshToken
        refresh = RefreshToken.for_user(employee.user)
        return Response({
            'bound': True,
            'access': str(refresh.access_token),
            'refresh': str(refresh),
        })

这里有几个容易忽略的点：

openid不能直接当username用，因为Django的username有长度限制和字符规则，而openid是28位左右的字符串。我用它作为User.username倒是可行，但更好的做法是单独存一个字段。
jscode2session接口每次请求都应该使用新的code，code的有效期只有5分钟，且只能用一次。
生产环境务必在微信公众平台把appid和secret配置为环境变量，别硬编码在代码里。

3.2 打卡接口的参数设计与校验流程

打卡接口是系统的核心，我设计成POST /api/attendance/checkin/。请求体是一个JSON，包含以下字段：

json复制{
  "type": "checkin",
  "latitude": 31.2304,
  "longitude": 121.4737,
  "timestamp": "2025-01-15 09:01:23",
  "address": "上海市XX区XX路XX号"
}

有人会问：timestamp不是应该由服务器自己获取吗，为什么让客户端传？这里有个权衡：服务器获取的时间是请求到达的时间，但小程序端可能因为网络延迟，请求发出时间和到达时间有偏差。我让客户端传打卡操作发生的时间，但服务端会校验这个时间与当前时间的差值，误差超过5分钟就拒绝。这样既保证了时间准确性，又防止了用户修改手机时间作弊。

后端校验流程我用一个清晰的步骤列表说明：

身份校验：通过JWT解析出员工ID，确认员工处于在职状态；
时间校验：判断打卡时间是否在规则允许的窗口内。我允许上班前60分钟到上班后30分钟打上班卡，下班前30分钟到下班后120分钟打下班卡；
位置校验：计算打卡点与规则配置坐标的直线距离，判断是否在半径内；
防重校验：查询当天是否已有记录，避免重复打卡。

python复制# views/attendance.py
from datetime import datetime, timedelta
from django.utils import timezone
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated
from .models import Employee, AttendanceRule, AttendanceRecord

class CheckinView(APIView):
    permission_classes = [IsAuthenticated]

    def post(self, request):
        try:
            employee = Employee.objects.get(user=request.user)
        except Employee.DoesNotExist:
            return Response({'error': '员工信息不存在'}, status=400)

        # 获取打卡参数
        check_type = request.data.get('type', 'checkin')
        latitude = request.data.get('latitude')
        longitude = request.data.get('longitude')
        client_time_str = request.data.get('timestamp')

        if check_type not in ('checkin', 'checkout'):
            return Response({'error': '无效的打卡类型'}, status=400)

        # 时间校验
        try:
            client_time = datetime.strptime(client_time_str, '%Y-%m-%d %H:%M:%S')
            client_time = timezone.make_aware(client_time, timezone.get_current_timezone())
        except (ValueError, TypeError):
            return Response({'error': '时间格式错误'}, status=400)

        now = timezone.now()
        if abs((now - client_time).total_seconds()) > 300:
            return Response({'error': '打卡时间与服务器时间偏差过大'}, status=400)

        # 获取规则
        rule = AttendanceRule.objects.filter(department=employee.department, is_active=True).first()
        if not rule:
            rule = AttendanceRule.objects.filter(department__isnull=True, is_active=True).first()
        if not rule:
            return Response({'error': '未配置考勤规则，请联系管理员'}, status=400)

        # 位置校验
        from .utils import haversine_distance
        distance = haversine_distance(latitude, longitude, rule.latitude, rule.longitude)
        if distance > rule.checkin_radius:
            return Response({'error': f'不在打卡范围内（距离{int(distance)}米）'}, status=403)

        # 防重校验 + 更新记录
        today = timezone.localdate()
        record, created = AttendanceRecord.objects.get_or_create(
            employee=employee, date=today,
            defaults={'rule': rule}
        )
        if check_type == 'checkin' and record.checkin_time:
            return Response({'error': '今天已经打过上班卡了'}, status=400)
        if check_type == 'checkout' and record.checkout_time:
            return Response({'error': '今天已经打过下班卡了'}, status=400)

        # 写入时间，并更新状态
        is_within_late_grace = client_time <= datetime.combine(
            today, rule.work_start_time, tzinfo=timezone.get_current_timezone()
        ) + timedelta(minutes=rule.late_minutes)
        if check_type == 'checkin':
            record.checkin_time = now
            record.checkin_latitude = latitude
            record.checkin_longitude = longitude
            record.checkin_location = request.data.get('address', '')
            if client_time > datetime.combine(today, rule.work_start_time, tzinfo=timezone.get_current_timezone()) + timedelta(minutes=rule.late_minutes):
                record.status = 'late'
            else:
                record.status = 'normal'
        else:
            record.checkout_time = now
            record.checkout_latitude = latitude
            record.checkout_longitude = longitude
            record.checkout_location = request.data.get('address', '')
            end_time = datetime.combine(today, rule.work_end_time, tzinfo=timezone.get_current_timezone())
            if client_time < end_time - timedelta(minutes=rule.early_leave_minutes):
                # 下班打卡早于规定时间，标记为早退（前提是当天还没有被标记为迟到）
                if record.status != 'late':
                    record.status = 'early'
        record.save()

        return Response({'message': '打卡成功', 'status': record.status})

这段代码是参考实践的简化版本，实际项目中还可以加更多细节，比如外勤打卡的特殊处理、请假状态与打卡的冲突等，但核心逻辑就是这样。

3.3 地理位置校验：Haversine公式与打卡半径

打卡定位校验的核心，不是简单的"两个坐标相等"，而是要计算地球表面两个经纬度点之间的距离。手机上报的经纬度，受GPS信号、建筑物遮挡、天气等因素影响，位置总会有漂移，所以要做的是计算距离，然后和允许半径做比较。

我用的是Haversine公式，它计算的是球面上两点之间的大圆距离，对几公里以内的短距离精度足够用。这个公式在utils.py里实现如下：

python复制# utils.py
import math

def haversine_distance(lat1, lon1, lat2, lon2):
    """计算两个经纬度坐标之间的距离（单位：米）"""
    R = 6371000  # 地球平均半径，单位米
    phi1 = math.radians(lat1)
    phi2 = math.radians(lat2)
    delta_phi = math.radians(lat2 - lat1)
    delta_lambda = math.radians(lon2 - lon1)

    a = math.sin(delta_phi / 2) ** 2 + \
        math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2) ** 2
    c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))

    return R * c

这里要考虑一个问题：如果每次打卡都实时请求微信官方的位置服务，会有额外的延迟和费用。我的做法是：小程序端用微信的wx.getLocation直接获取经纬度，后端只负责计算距离。wx.getLocation返回的是WGS84坐标，而国内地图大多使用GCJ02坐标，不过因为我们只比较两点之间的相对距离，不涉及地图展示，所以坐标系不一致不影响距离计算结果。

3.4 防重复打卡与状态幂等

防重复打卡，我用的是get_or_create + 唯一约束双保险。get_or_create保证一个员工一天最多一条记录，唯一约束兜底防止并发请求下出现脏数据。

这里有个并发场景值得注意：员工在9:00整连续点了两次打卡按钮，两个请求几乎同时到达服务器。如果只用get_or_create，在高并发下可能出现两条记录。数据库层的unique_together约束会拒绝第二条，但Django会抛出IntegrityError。所以更稳妥的写法是捕获这个异常：

python复制try:
    record, created = AttendanceRecord.objects.get_or_create(
        employee=employee, date=today,
        defaults={'rule': rule}
    )
except IntegrityError:
    return Response({'error': '今天已经打过卡了'}, status=400)

另外，打卡状态的判定也有讲究。我把状态判定放在打卡时实时计算，而不是事后批量跑任务。原因很简单：员工打卡的那一刻，就应该立刻告诉他这次是正常还是迟到，这样才能起到即时提醒的作用。事后跑批虽然也可以，但员工第二天才看到"迟到"状态，投诉率会高很多。

4. 小程序端实现：从登录到打卡的完整链路

小程序端的登录流程，比普通Web登录多了一层微信的介入。全程是这样的：

小程序启动时，调用wx.login()获取临时code；
将code通过wx.request发送到Django的/api/auth/wxlogin/；
Django后端拿着code去微信的jscode2session接口换openid；
后端判断该openid是否绑定了员工，如果绑定了就签发JWT返回给小程序，否则返回bound: false，引导到绑定页；
小程序拿到JWT后存入wx.setStorageSync，后续所有请求在header里带上Authorization: Bearer <token>。

小程序端代码大概是这样的：

javascript复制// pages/login/login.js
wx.login({
  success: async (res) => {
    const resp = await wx.request({
      url: 'https://yourdomain.com/api/auth/wxlogin/',
      method: 'POST',
      data: { code: res.code }
    });
    if (resp.data.bound) {
      wx.setStorageSync('token', resp.data.access);
      wx.switchTab({ url: '/pages/checkin/checkin' });
    } else {
      // 未绑定，跳转绑定页面
      wx.navigateTo({ url: '/pages/bind/bind?openid=' + resp.data.openid });
    }
  }
});

有一点要特别提醒：wx.login的code只能用一次，而且后端换取openid的接口调用必须放在你的服务器上，不能让小程序直接调用微信接口。因为secret一旦暴露在小程序代码里，任何人都能看到并盗用。

4.2 定位与打卡页面的核心逻辑

打卡页面是小程序的界面核心。我设计的页面主要包含：当前时间、打卡状态（已打卡/未打卡/迟到/外勤）、打卡按钮、打卡位置显示。

定位这一环，关键技术点在于wx.getLocation的调用时机。不要在页面加载时就开始获取定位，因为微信会弹出授权框，用户一上来看到授权弹窗容易直接拒绝。更好的做法是：等用户点击打卡按钮时再触发定位请求，此时用户有明确的打卡意图，授权的接受度会高很多。

javascript复制// pages/checkin/checkin.js
checkin() {
  wx.getLocation({
    type: 'gcj02',  // 国测局坐标，国内通用
    success: async (loc) => {
      // 调后端打卡接口
      const token = wx.getStorageSync('token');
      const resp = await wx.request({
        url: 'https://yourdomain.com/api/attendance/checkin/',
        method: 'POST',
        header: { 'Authorization': 'Bearer ' + token },
        data: {
          type: this.data.checkType,
          latitude: loc.latitude,
          longitude: loc.longitude,
          timestamp: this.formatTime(new Date()),
          address: this.data.address
        }
      });
      if (resp.data.status) {
        this.setData({ status: resp.data.status });
        wx.showToast({ title: '打卡成功', icon: 'success' });
      } else {
        wx.showToast({ title: resp.data.error || '打卡失败', icon: 'none' });
      }
    },
    fail: () => {
      wx.showToast({ title: '定位失败，请检查GPS权限', icon: 'none' });
    }
  });
}

关于定位，还有一个比较隐蔽的坑：wx.getLocation是异步的，用户点击打卡按钮后，从点击到定位返回可能有2到3秒的延迟。这期间用户会反复点击按钮，造成重复请求。我在前端做了防重复处理：打卡请求发出后，按钮立刻置灰并显示"打卡中..."，直到请求返回或超时。

4.3 打卡状态的实时反馈

考勤系统最容易引发员工反感的一点就是"不透明"。员工打了卡，不知道自己算不算迟到、位置在不在范围内，自然会焦虑。所以我在打卡页面上做了实时状态反馈：

打卡成功后，立即显示这条打卡记录的判定状态（正常/迟到/早退）；
如果位置不在范围内，后端返回错误信息，页面用红色提示"你当前距离打卡点XX米，不在打卡范围内"；
如果当天已经打卡，按钮变成灰色，显示"今日已打卡"。

这种即时反馈不只是提升体验，更是在培养员工对系统的信任感。系统说你是正常，那你就是正常；系统说你迟到，当场告诉你，你有异议还能立刻申诉。而不是月底突然收到一条扣款通知，然后开始漫长的扯皮。

5. 管理后台与考勤报表：让数据真正可用

5.1 Django Admin定制考勤管理

系统上线后，用得最多的其实是行政管理员。Django Admin天然的列表页、筛选器、搜索功能，让管理员不需要任何开发知识就能完成大部分操作。

我在Admin里做的定制主要是三件事：

列表页显示关键字段：设置list_display为员工姓名、工号、部门、日期、上班时间、下班时间、状态，让管理员一眼看清当天考勤全貌；
配置筛选器：按部门、日期、状态筛选，方便按维度查看；
重写save_model：管理员在后台手工补卡时，自动把is_manual字段置为True，并且更新考勤状态。

python复制# admin.py
from django.contrib import admin
from .models import Department, Employee, AttendanceRule, AttendanceRecord

@admin.register(AttendanceRecord)
class AttendanceRecordAdmin(admin.ModelAdmin):
    list_display = ('employee', 'date', 'checkin_time', 'checkout_time', 'status', 'is_manual')
    list_filter = ('status', 'date', 'employee__department')
    search_fields = ('employee__name', 'employee__employee_no')
    date_hierarchy = 'date'
    list_per_page = 50

    def save_model(self, request, obj, form, change):
        if not change:
            obj.is_manual = True
        super().save_model(request, obj, form, change)

Django Admin还有一个杀手级功能：list_filter + date_hierarchy组合，点几下就能生成"某部门某月的所有考勤记录"，管理员不需要写任何查询语句。

5.2 补卡审批流程的设计

再好的系统也防不住"忘了打卡"这种事。人不是机器，总有例外，所以补卡流程必须安排上。我的做法是双轨制：

管理员代补：员工口头告知行政，行政在Django Admin里直接补卡，is_manual字段标记为True，下次月度统计时会单独列出来；
员工自助申请：在考勤系统里设置了补卡申请，员工在小程序端提交补卡申请（选择日期、填写原因），推送给Admin后台，管理员审核后写入考勤记录。

这里我特别强调一下补卡标记的意义。如果没有is_manual字段，月底统计时会发现缺卡率很低，但其中混杂着大量补卡数据。管理者做绩效考核时，需要区分"正常打卡"和"补卡"，否则考勤数据就失去了参考价值。我甚至会在月度报表里单独统计"补卡率"这个指标，用来衡量考勤管理的规范性——补卡率超过10%说明规则设计有问题，或者员工考勤意识不强。

5.3 月度考勤报表与导出

报表导出是管理员最关心的功能。我最初用Django Admin的列表页导出CSV，但中文乱码、格式不友好，被行政吐槽了好几次。后来改用openpyxl库直接生成Excel文件，做了个自定义视图：

python复制# views/report.py
import openpyxl
from django.http import HttpResponse
from openpyxl.styles import Font, PatternFill
from openpyxl.utils import get_column_letter

def export_monthly_report(request, year, month):
    # 获取当月的考勤记录
    records = AttendanceRecord.objects.filter(date__year=year, date__month=month).select_related('employee', 'employee__department')

    wb = openpyxl.Workbook()
    ws = wb.active
    ws.title = f"{year}年{month}月考勤"

    headers = ['工号', '姓名', '部门', '日期', '上班时间', '下班时间', '状态', '是否补卡']
    ws.append(headers)

    # 表头样式
    for cell in ws[1]:
        cell.font = Font(bold=True)
        cell.fill = PatternFill(start_color='DDDDDD', end_color='DDDDDD', fill_type='solid')

    for rec in records:
        ws.append([
            rec.employee.employee_no,
            rec.employee.name,
            rec.employee.department.name,
            rec.date.strftime('%Y-%m-%d'),
            rec.checkin_time.strftime('%H:%M:%S') if rec.checkin_time else '',
            rec.checkout_time.strftime('%H:%M:%S') if rec.checkout_time else '',
            rec.get_status_display(),
            '是' if rec.is_manual else ''
        ])

    # 调整列宽
    for i in range(1, 9):
        ws.column_dimensions[get_column_letter(i)].width = 15

    response = HttpResponse(content_type='application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')
    response['Content-Disposition'] = f'attachment; filename="attendance_{year}_{month}.xlsx"'
    wb.save(response)
    return response

这个报表每月初运行一次，行政只需要在后台点一下"导出"，Excel就自动生成。再也不用月底那天对着电脑手工核对一整晚了。

6. 部署上线与踩坑实录

6.1 宝塔面板部署Django项目的步骤

我部署用的是宝塔面板 + uWSGI + Nginx的组合，这个方案对中小型项目来说最省心。完整步骤记录一下：

在Linux服务器上安装宝塔面板，创建Python项目环境，安装Python 3.10+（宝塔可以直接选择版本）；
把Django项目代码上传到服务器，安装依赖：pip install -r requirements.txt；
安装并配置MySQL/MariaDB数据库，在Django的settings里改好数据库连接；
收集静态文件：python manage.py collectstatic；
安装uWSGI：pip install uwsgi，创建uwsgi.ini配置文件：

ini复制[uwsgi]
chdir = /www/wwwroot/attendance
module = attendance.wsgi:application
master = true
processes = 4
harakiri = 60
max-requests = 5000
socket = 127.0.0.1:8001
vacuum = true
daemonize = /www/wwwlogs/attendance_uwsgi.log

在宝塔的Nginx配置里添加反向代理：

nginx复制server {
    listen 80;
    server_name yourdomain.com;
    location / {
        include uwsgi_params;
        uwsgi_pass 127.0.0.1:8001;
    }
    location /static/ {
        alias /www/wwwroot/attendance/static/;
    }
}

申请HTTPS证书，在宝塔里一键开启强制HTTPS。

这套流程我已经跑过好几遍，最常出问题的环节是静态文件路径。Django开发环境下静态文件是自动处理的，但线上环境必须由Nginx直接服务，否则Admin后台的样式会全部丢失，页面惨不忍睹。

提示：部署前记得把settings.py里的DEBUG改成False，并配置好ALLOWED_HOSTS和CSRF_TRUSTED_ORIGINS。DEBUG=True上生产环境等于把服务器信息全暴露给攻击者。

6.2 小程序合法域名与HTTPS

小程序上线前，必须在微信公众平台后台配置request合法域名。这里有个硬性要求：域名必须支持HTTPS，且证书必须有效。我用的是宝塔自带的一键SSL功能申请免费证书，配置好之后到微信后台填上域名即可。

这里有个开发阶段的坑：在微信开发者工具里调试时，可以勾选"不校验合法域名"来绕过限制，但真机预览时必须关闭这个选项。很多新手在开发者工具里跑通了，一到手机上看就报"url not in domain list"，就是这个原因。

另外，小程序端要求请求的域名不能是IP地址，必须是备案过的域名。有些人图省事，在内网部署就直接用IP访问，小程序一发到正式环境就会被微信拦截。如果只是内部测试，可以用开发者工具的"不校验域名"选项，但正式环境域名备案是逃不掉的。

6.3 时区、定位授权、微信缓存等常见坑

最后把这大半年维护过程中踩过的坑集中列一下，每个都是真金白银买回来的教训：

时区问题。Django默认开启USE_TZ=True，数据库存的是UTC时间。如果数据库配置和Django TIME_ZONE不一致，很容易出现"打卡时间是早上9点，但页面显示下午5点"的诡异情况。我的做法是：settings.py里设置TIME_ZONE = 'Asia/Shanghai'，同时USE_TZ = True，所有需要显示的时间都通过django.utils.timezone.localtime()做转换。前端展示时，直接用localTime格式化，避免二次时区转换。

定位授权拒绝后的降级处理。有些员工手机设置了禁止定位权限，打卡请求会直接失败。如果完全不让打卡，员工会很恼火。我加了一个降级策略：定位失败时弹窗提示，同时允许员工切换到"手动选择位置"模式，由员工从预设的办公地址列表中选择打卡点。当然，这种记录会被标记为is_manual=True，便于后续核查。

小程序缓存的坑。wx.setStorageSync存JWT后，token过期比较难处理。我用的是simplejwt的access token（有效期2小时）+ refresh token（有效期7天）。小程序端在请求拦截器里判断token是否过期，过期就自动用refresh token刷新。这个逻辑初版没做，导致员工每天早上打开小程序都要重新登录，体验很差。建议你在小程序端封装一个统一的request方法，统一处理token刷新和错误提示。

SQLite的并发问题。开发阶段我用的是SQLite，但线上切换到MySQL后才发现，原来SQLite下没暴露的并发问题开始冒头。比如两个员工几乎同时打卡，SQLite会锁库，而MySQL用InnoDB默认的行级锁就没这个问题。如果你不打算用MySQL，至少也要切到PostgreSQL。SQLite只适合本地开发，不适合多用户并发写入的生产环境。

备份策略。考勤数据是敏感的，一旦丢失就是大事故。我的方案是服务器每天凌晨用mysqldump备份全库，保留最近30天的备份文件，再同步一份到对象存储。Django后台有现成的django-dbbackup库，配置好之后可以定时自动备份，建议直接使用。

最后分享一个我个人的维护体会。考勤系统这种工具类项目，最难的不是技术实现，而是"让人愿意用"。技术上，Python+Django搞定后端、小程序搞定前端，整体开发量其实并不大，两周就能跑通核心流程。但要让上到老板下到外勤销售都接受这套系统，需要在细节上反复打磨：打卡响应要快、状态提示要清楚、位置误判要宽容、补卡流程要人性化。我在这套系统上线后连续收集了一个月的使用反馈，每次小迭代都是在解决真实问题——比如给外勤单独加了一个"外勤打卡"按钮，避免他们因为距离打卡点太远而无法打卡的尴尬。

这套系统的价值在于，把考勤从"月底对账的麻烦事"变成了"实时可见的数据流"。如果你也想做一套类似的系统，我的建议是：先把数据模型想清楚，尤其是记录冗余和唯一约束这两个点；再按照"服务端校验优先"的原则设计接口；最后在细节里打磨体验，让员工和管理员都觉得好用。做完之后你会发现，Python+Django+小程序这个组合，在中小型内部工具系统上确实是效率最优解。

基于Django与微信小程序的考勤系统开发实践