AttendanceGenerator 是一款面向保安服务公司的智能考勤管理系统,用于解决多岗位、多员工月度考勤表的生成与调整问题。系统支持自然语言对话式考勤调整,能够自动计算出勤天数、缺勤天数、加班时长,并一键生成符合企业格式的 Excel 考勤表。
项目采用双版本并行维护策略:
- **FastAPI 版本**:H5 响应式页面 + 本地 JSON 文件存储,适合局域网或服务器部署。
- **CloudBase 版本**:微信小程序 + Python 云函数 + CloudBase 文档型数据库/云存储,适合移动端随时随地使用。
### 1.2 核心功能模块
| 模块 | 功能说明 |
|------|----------|
| **员工配置管理** | 按岗位组织员工,维护姓名、入职日期、工资标准、各类补贴、备注等信息,支持增删改查。 |
| **考勤调整** | 支持自然语言输入(如"丁志中1-20号加班0.5"),AI 自动解析为结构化考勤数据;支持请假、全班加班、半天加班三种状态。 |
| **Excel 自动生成** | 基于 openpyxl 操作 Excel 模板,自动填充"明细表"(正常班 + 加班表)和"汇总表"(出勤/缺勤/补贴/工资标准),保留原有格式与合并单元格。 |
| **历史记录管理** | 每月考勤调整自动保存,支持查看历史月份、快速加载、删除旧记录。 |
| **AI 对话助手** | 集成 OpenAI 兼容接口,通过对话状态机引导用户完成考勤调整。 |
### 1.3 考勤状态规则
系统内置三种考勤标记,对应 Excel 中的显示规则:
| 用户表述 | 系统标记 | 明细表显示 | 汇总表影响 |
|----------|----------|------------|------------|
| 请假 / 停班 | `停` | 正常班显示"停" | 计入缺勤天数、休息天数 |
| 加班 / 全班 | `班` | 加班表显示红字"班" | 不计入缺勤 |
| 半天 / 4小时 | `0.5` | 加班表显示红字"0.5" | 不计入缺勤 |
### 2.1 技术栈
| 层次 | FastAPI 版本 | CloudBase 版本 |
|------|-------------|---------------|
| **前端** | Vue 3(CDN)+ 原生 JS,单页面 H5 | 微信小程序(WXML / WXSS / JS) |
| **后端框架** | FastAPI + Uvicorn | Python 3.9 云函数 |
| **数据存储** | JSON 文件(`config/`、`config/attendance/`) | CloudBase 文档型数据库(NoSQL) |
| **文件存储** | 本地文件系统(`output/`、`templates/`) | CloudBase 云存储 |
| **Excel 处理** | openpyxl | openpyxl |
| **AI 能力** | OpenAI 兼容 API(支持 GPT、DeepSeek 等) | OpenAI 兼容 API |
| **数据校验** | Pydantic v1 | Pydantic v1 |
### 2.2 项目结构
```
attendance_generator/
├── src/ # FastAPI 版本后端
│ ├── main.py # FastAPI 入口,API 路由
│ ├── models.py # Pydantic 数据模型
│ ├── config_manager.py # JSON 配置文件读写
│ ├── ai_service.py # LLM 对话服务
│ ├── excel_generator.py # Excel 生成器
│ └── test/ # 单元测试
├── static/ # H5 前端
│ ├── index.html # Vue 3 单页面
│ └── app.js # 前端逻辑
├── cloudfunctions/attendance/ # CloudBase 云函数
│ ├── index.py # 云函数入口,context 认证提取
│ ├── src/main_handler.py # 请求路由(兼容 HTTP/云调用)
│ ├── src/config_manager.py # 数据库版配置管理
│