mirror of
https://github.com/Cccc-owo/CheckInApp.git
synced 2026-06-17 14:06:28 +00:00
docs: remove some old docs
This commit is contained in:
@@ -1,258 +0,0 @@
|
||||
# 接龙自动打卡系统 - 后端 API
|
||||
|
||||
FastAPI 后端服务，提供用户管理、QQ 扫码登录、自动打卡等功能。
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 配置环境
|
||||
|
||||
创建 `.env` 文件（可选）：
|
||||
|
||||
```env
|
||||
# 邮件通知配置（可选）
|
||||
SMTP_SERVER=smtp.example.com
|
||||
SMTP_PORT=465
|
||||
SMTP_SENDER_EMAIL=your-email@example.com
|
||||
SMTP_SENDER_PASSWORD=your-password-here
|
||||
|
||||
# Chrome 浏览器配置（可选）
|
||||
CHROME_BINARY_PATH=
|
||||
CHROMEDRIVER_PATH=
|
||||
```
|
||||
|
||||
### 3. 初始化数据库
|
||||
|
||||
数据库会在首次启动时自动初始化。
|
||||
|
||||
### 4. 创建管理员用户
|
||||
|
||||
```bash
|
||||
python backend/scripts/create_admin.py
|
||||
```
|
||||
|
||||
按照提示输入管理员信息：
|
||||
- Signature: 管理员标识（唯一）
|
||||
- ThreadId: 接龙 ID
|
||||
- 邮箱: 接收通知的邮箱
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
```bash
|
||||
# 开发模式（支持热重载）
|
||||
cd backend
|
||||
python main.py
|
||||
|
||||
# 或者使用 uvicorn
|
||||
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
|
||||
|
||||
# 生产模式
|
||||
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4
|
||||
```
|
||||
|
||||
### 6. 访问 API 文档
|
||||
|
||||
启动后访问: http://localhost:8000/docs
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
backend/
|
||||
├── main.py # FastAPI 应用入口
|
||||
├── config.py # 配置管理
|
||||
├── dependencies.py # 认证中间件
|
||||
├── requirements.txt # Python 依赖
|
||||
├── models/ # 数据库模型
|
||||
│ ├── database.py # 数据库配置
|
||||
│ ├── user.py # User 模型
|
||||
│ └── check_in_record.py # CheckInRecord 模型
|
||||
├── schemas/ # Pydantic Schema
|
||||
│ ├── user.py # 用户相关 Schema
|
||||
│ ├── auth.py # 认证相关 Schema
|
||||
│ └── check_in.py # 打卡相关 Schema
|
||||
├── api/ # API 路由
|
||||
│ ├── auth.py # 认证 API
|
||||
│ ├── users.py # 用户管理 API
|
||||
│ ├── check_in.py # 打卡 API
|
||||
│ └── admin.py # 管理员 API
|
||||
├── services/ # 业务逻辑层
|
||||
│ ├── auth_service.py # 认证服务
|
||||
│ ├── user_service.py # 用户服务
|
||||
│ ├── check_in_service.py # 打卡服务
|
||||
│ └── scheduler_service.py # 调度服务
|
||||
├── workers/ # Selenium 工作模块
|
||||
│ ├── token_refresher.py # Token 刷新（QQ 扫码）
|
||||
│ ├── check_in_worker.py # 打卡执行
|
||||
│ └── email_notifier.py # 邮件通知
|
||||
└── scripts/ # 工具脚本
|
||||
└── create_admin.py # 创建管理员用户
|
||||
```
|
||||
|
||||
## 🔌 API 端点
|
||||
|
||||
### 认证 API (`/api/auth`)
|
||||
|
||||
- `POST /api/auth/request_qrcode` - 请求 QQ 扫码二维码
|
||||
- `GET /api/auth/qrcode_status/{session_id}` - 检查扫码状态
|
||||
- `POST /api/auth/verify_token` - 验证 Token 有效性
|
||||
|
||||
### 用户 API (`/api/users`)
|
||||
|
||||
- `POST /api/users` - 创建用户（管理员）
|
||||
- `GET /api/users/me` - 获取当前用户信息
|
||||
- `GET /api/users/me/token_status` - 获取 Token 状态
|
||||
- `GET /api/users` - 获取所有用户（管理员）
|
||||
- `GET /api/users/{user_id}` - 获取指定用户
|
||||
- `PUT /api/users/{user_id}` - 更新用户信息
|
||||
- `DELETE /api/users/{user_id}` - 删除用户（管理员）
|
||||
|
||||
### 打卡 API (`/api/check_in`)
|
||||
|
||||
- `POST /api/check_in/manual` - 手动触发打卡
|
||||
- `GET /api/check_in/my_records` - 查看自己的打卡记录
|
||||
- `GET /api/check_in/records` - 查看所有打卡记录（管理员）
|
||||
- `GET /api/check_in/records/count` - 获取打卡记录统计（管理员）
|
||||
|
||||
### 管理员 API (`/api/admin`)
|
||||
|
||||
- `POST /api/admin/batch_check_in` - 批量触发打卡
|
||||
- `GET /api/admin/logs` - 获取系统日志
|
||||
- `GET /api/admin/stats` - 获取系统统计
|
||||
|
||||
## ⚙️ 配置说明
|
||||
|
||||
### 邮件配置 (`config.ini`)
|
||||
|
||||
在项目根目录创建 `config.ini`：
|
||||
|
||||
```ini
|
||||
[Email]
|
||||
smtpserver = smtp.example.com
|
||||
smtpport = 465
|
||||
senderemail = your-email@example.com
|
||||
senderpassword = your-password
|
||||
```
|
||||
|
||||
### 定时任务配置
|
||||
|
||||
在 `.env` 文件中配置（或在 `backend/config.py` 中设置默认值）：
|
||||
|
||||
- `TOKEN_CHECK_INTERVAL_MINUTES`: Token 检查间隔（默认 30 分钟）
|
||||
- `SESSION_CLEANUP_INTERVAL_HOURS`: 会话清理间隔（默认 24 小时）
|
||||
|
||||
**注意**：每个任务的打卡时间由任务自身的 `cron_expression` 字段控制（支持标准 Crontab 表达式）。
|
||||
|
||||
## 🔐 认证流程
|
||||
|
||||
1. 用户输入 Signature 并请求二维码
|
||||
2. 后端启动 Selenium 获取 QQ 登录二维码
|
||||
3. 前端轮询检查扫码状态
|
||||
4. 用户使用手机 QQ 扫码
|
||||
5. 后端获取 Token 并解析 JWT
|
||||
6. 用户后续请求使用 `Authorization: Bearer <token>` header
|
||||
|
||||
## 📊 定时任务
|
||||
|
||||
系统会自动执行以下定时任务：
|
||||
|
||||
1. **定时打卡**: 每天 20:00 为所有启用的用户执行打卡
|
||||
2. **Token 过期检查**: 每 30 分钟检查一次，Token 在 30 分钟内过期时发送邮件提醒
|
||||
3. **会话文件清理**: 每 24 小时清理超过 24 小时的旧会话文件
|
||||
|
||||
## 🛠️ 开发说明
|
||||
|
||||
### 添加新的 API 端点
|
||||
|
||||
1. 在 `backend/schemas/` 中定义请求/响应 Schema
|
||||
2. 在 `backend/services/` 中实现业务逻辑
|
||||
3. 在 `backend/api/` 中创建 API 路由
|
||||
4. 在 `backend/main.py` 中注册路由
|
||||
|
||||
### 数据库迁移
|
||||
|
||||
如果修改了模型，删除 `data/checkin.db` 并重启服务即可重新创建数据库。
|
||||
|
||||
⚠️ 注意：生产环境建议使用 Alembic 进行数据库迁移。
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### 问题：无法启动 Selenium
|
||||
|
||||
确保已安装 Chrome 和 ChromeDriver：
|
||||
|
||||
```bash
|
||||
# 检查路径配置
|
||||
ls chrome-linux64/chrome
|
||||
ls chromedriver
|
||||
```
|
||||
|
||||
### 问题：Token 验证失败
|
||||
|
||||
检查数据库中用户的 `authorization` 字段是否有值。
|
||||
|
||||
### 问题：定时任务未执行
|
||||
|
||||
检查日志文件 `logs/CheckIn.log`，确认调度器是否成功启动。
|
||||
|
||||
### 问题：邮件发送失败
|
||||
|
||||
检查 `config.ini` 配置是否正确，SMTP 服务器是否可访问。
|
||||
|
||||
## 📝 环境变量
|
||||
|
||||
可选的环境变量：
|
||||
|
||||
- `DATABASE_URL`: 数据库 URL（默认使用 SQLite）
|
||||
- `CORS_ORIGINS`: 允许的前端域名（默认 localhost:5173 和 localhost:3000）
|
||||
- `SMTP_SERVER`: 邮件服务器地址（用于邮件通知，可选）
|
||||
- `SMTP_SENDER_EMAIL`: 发件人邮箱（用于邮件通知，可选）
|
||||
- `CHROME_BINARY_PATH`: Chrome 浏览器路径（可选，留空自动检测）
|
||||
- `CHROMEDRIVER_PATH`: ChromeDriver 路径（可选，留空自动下载）
|
||||
|
||||
## 🚀 部署建议
|
||||
|
||||
### 使用 Gunicorn
|
||||
|
||||
```bash
|
||||
pip install gunicorn
|
||||
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
|
||||
```
|
||||
|
||||
### 使用 Systemd
|
||||
|
||||
创建 `/etc/systemd/system/checkin-api.service`：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=CheckIn API Service
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=your-user
|
||||
WorkingDirectory=/path/to/CheckInApp
|
||||
Environment="PATH=/path/to/venv/bin"
|
||||
ExecStart=/path/to/venv/bin/gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
启动服务：
|
||||
|
||||
```bash
|
||||
sudo systemctl enable checkin-api
|
||||
sudo systemctl start checkin-api
|
||||
sudo systemctl status checkin-api
|
||||
```
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目仅供学习和研究使用。
|
||||
@@ -1,230 +0,0 @@
|
||||
# 接龙自动打卡系统 - 前端
|
||||
|
||||
基于 Vue 3 + Vite + Element Plus 的现代化前端应用。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **框架**: Vue 3 (Composition API)
|
||||
- **构建工具**: Vite
|
||||
- **UI 库**: Element Plus
|
||||
- **路由**: Vue Router 4
|
||||
- **状态管理**: Pinia
|
||||
- **HTTP 客户端**: Axios
|
||||
- **图标**: @element-plus/icons-vue
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── api/ # API 接口
|
||||
│ │ ├── client.js # Axios 客户端配置
|
||||
│ │ └── index.js # API 方法封装
|
||||
│ ├── assets/ # 静态资源
|
||||
│ ├── components/ # 公共组件
|
||||
│ │ ├── Layout.vue # 布局组件
|
||||
│ │ ├── Navbar.vue # 导航栏
|
||||
│ │ └── QRCodeModal.vue # QR 码扫码组件
|
||||
│ ├── router/ # 路由配置
|
||||
│ │ └── index.js
|
||||
│ ├── stores/ # Pinia 状态管理
|
||||
│ │ ├── auth.js # 认证状态
|
||||
│ │ ├── user.js # 用户状态
|
||||
│ │ ├── checkIn.js # 打卡状态
|
||||
│ │ └── admin.js # 管理员状态
|
||||
│ ├── utils/ # 工具函数
|
||||
│ │ └── helpers.js # 通用辅助函数
|
||||
│ ├── views/ # 页面组件
|
||||
│ │ ├── LoginView.vue # 登录页
|
||||
│ │ ├── DashboardView.vue # 用户仪表盘
|
||||
│ │ ├── RecordsView.vue # 打卡记录
|
||||
│ │ ├── NotFoundView.vue # 404 页面
|
||||
│ │ └── admin/ # 管理员页面
|
||||
│ │ ├── UsersView.vue # 用户管理
|
||||
│ │ ├── RecordsView.vue # 所有打卡记录
|
||||
│ │ ├── StatsView.vue # 统计信息
|
||||
│ │ └── LogsView.vue # 系统日志
|
||||
│ ├── App.vue # 根组件
|
||||
│ ├── main.js # 入口文件
|
||||
│ └── style.css # 全局样式
|
||||
├── .env # 环境变量
|
||||
├── .env.development # 开发环境变量
|
||||
├── .env.production # 生产环境变量
|
||||
├── vite.config.js # Vite 配置
|
||||
├── package.json # 依赖配置
|
||||
└── README.md # 本文件
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 开发模式
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
访问 http://localhost:3000
|
||||
|
||||
### 生产构建
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建产物在 `dist/` 目录。
|
||||
|
||||
### 预览生产构建
|
||||
|
||||
```bash
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 用户功能
|
||||
|
||||
- **QQ 扫码登录**: 支持 QQ 扫码认证
|
||||
- **个人仪表盘**: 查看 Token 状态、手动打卡
|
||||
- **打卡记录**: 查看个人打卡历史和统计
|
||||
- **Token 管理**: 实时监控 Token 过期状态
|
||||
|
||||
### 管理员功能
|
||||
|
||||
- **用户管理**: CRUD 操作、批量启用/禁用、批量打卡
|
||||
- **打卡记录**: 查看所有用户的打卡记录
|
||||
- **统计信息**: 系统整体运行数据统计
|
||||
- **系统日志**: 实时查看系统运行日志
|
||||
|
||||
## API 代理配置
|
||||
|
||||
开发环境下，Vite 会自动代理 `/api` 请求到后端服务器：
|
||||
|
||||
```javascript
|
||||
// vite.config.js
|
||||
server: {
|
||||
port: 3000,
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8000',
|
||||
changeOrigin: true,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
创建 `.env.local` 文件自定义配置：
|
||||
|
||||
```env
|
||||
VITE_API_BASE_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
## 路由结构
|
||||
|
||||
- `/login` - 登录页面
|
||||
- `/dashboard` - 用户仪表盘（需登录）
|
||||
- `/records` - 打卡记录（需登录）
|
||||
- `/admin/users` - 用户管理（需管理员权限）
|
||||
- `/admin/records` - 所有打卡记录（需管理员权限）
|
||||
- `/admin/stats` - 统计信息（需管理员权限）
|
||||
- `/admin/logs` - 系统日志（需管理员权限）
|
||||
|
||||
## 状态管理
|
||||
|
||||
使用 Pinia 进行全局状态管理：
|
||||
|
||||
- **authStore**: 认证状态（Token、用户信息）
|
||||
- **userStore**: 用户管理相关
|
||||
- **checkInStore**: 打卡记录相关
|
||||
- **adminStore**: 管理员功能相关
|
||||
|
||||
## 组件说明
|
||||
|
||||
### QRCodeModal
|
||||
|
||||
QQ 扫码登录组件，支持：
|
||||
- 自动获取二维码
|
||||
- 轮询扫码状态
|
||||
- 倒计时和进度显示
|
||||
- 二维码过期提示和刷新
|
||||
|
||||
### Navbar
|
||||
|
||||
导航栏组件，支持：
|
||||
- 基于角色的菜单显示
|
||||
- 当前路由高亮
|
||||
- 用户信息显示
|
||||
- 退出登录
|
||||
|
||||
### Layout
|
||||
|
||||
页面布局组件，包含：
|
||||
- 顶部导航栏
|
||||
- 主内容区域
|
||||
- 响应式布局
|
||||
|
||||
## 开发规范
|
||||
|
||||
1. **组件命名**: 使用 PascalCase
|
||||
2. **文件命名**: 组件文件使用 PascalCase，工具文件使用 camelCase
|
||||
3. **API 调用**: 统一通过 stores 调用，不直接在组件中调用
|
||||
4. **错误处理**: 使用 try-catch 并显示友好的错误提示
|
||||
5. **Loading 状态**: 异步操作需显示加载状态
|
||||
|
||||
## 浏览器支持
|
||||
|
||||
- Chrome >= 87
|
||||
- Firefox >= 78
|
||||
- Safari >= 14
|
||||
- Edge >= 88
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 启动时端口被占用
|
||||
|
||||
修改 `vite.config.js` 中的 `server.port` 配置。
|
||||
|
||||
### API 请求失败
|
||||
|
||||
检查后端服务是否启动，默认应在 http://localhost:8000 运行。
|
||||
|
||||
### 构建产物过大
|
||||
|
||||
Element Plus 已配置按需加载，如需进一步优化，可以：
|
||||
- 使用动态导入 (dynamic import)
|
||||
- 配置 CDN 引入
|
||||
- 启用 gzip 压缩
|
||||
|
||||
## 部署
|
||||
|
||||
### Nginx 配置示例
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com;
|
||||
root /var/www/checkin/frontend/dist;
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
|
||||
location /api {
|
||||
proxy_pass http://localhost:8000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user