微信小程序-cloudebase云函数-考勤管理系统

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 # 数据库版配置管理
│