mirror of
https://github.com/Cccc-owo/CheckInApp.git
synced 2026-06-17 14:06:28 +00:00
docs: update
This commit is contained in:
@@ -1,792 +1,81 @@
|
|||||||
# 接龙自动打卡系统 V2
|
# CheckIn App V2
|
||||||
|
|
||||||
[](https://fastapi.tiangolo.com/)
|
[](https://fastapi.tiangolo.com/)
|
||||||
[](https://vuejs.org/)
|
[](https://vuejs.org/)
|
||||||
[](https://www.python.org/)
|
[](https://www.python.org/)
|
||||||
[](LICENSE)
|
|
||||||
|
|
||||||
一个全自动的接龙打卡系统,支持 QQ 扫码登录、定时自动打卡、Token 过期提醒等功能。采用前后端分离架构,提供完善的 Web 管理界面和 RESTful API。
|
接龙自动打卡系统，通过 QQ 登录实现每日自动考勤提交。
|
||||||
|
|
||||||
## ⚡ V2 重大更新
|
## 特性
|
||||||
|
|
||||||
🎉 **用户-任务分离架构** - 一个用户可以管理多个打卡任务
|
- QQ 扫码登录
|
||||||
🎉 **全局 Token 刷新** - 扫码一次更新所有任务
|
- 用户任务分离（一人多任务）
|
||||||
🎉 **任务级别控制** - 每个任务独立配置邮箱和启用状态
|
- 任务模板系统
|
||||||
🎉 **29 个 API 端点** - 更完善的功能覆盖
|
- 定时自动打卡
|
||||||
🎉 **任务所有权验证** - 更安全的权限控制
|
- 邮件通知
|
||||||
|
- 用户审批机制
|
||||||
|
- 管理后台
|
||||||
|
|
||||||
详见 [V2 架构文档](ARCHITECTURE_V2.md)
|
## 技术栈
|
||||||
|
|
||||||
## ✨ 主要特性
|
**后端**: FastAPI + SQLAlchemy + APScheduler + Selenium
|
||||||
|
**前端**: Vue 3 + Ant Design Vue + Pinia
|
||||||
|
**数据库**: SQLite
|
||||||
|
|
||||||
- 🔐 **QQ 扫码登录** - 支持通过 QQ 扫码快速登录认证
|
## 快速开始
|
||||||
- 👤 **多任务管理** - 一个用户管理多个打卡任务
|
|
||||||
- ⏰ **定时自动打卡** - 每天固定时间自动为启用的任务执行打卡
|
|
||||||
- 📧 **邮件通知** - Token 过期提醒、打卡结果通知
|
|
||||||
- 👥 **用户管理** - 完善的用户 CRUD 和权限管理
|
|
||||||
- 📋 **任务管理** - 创建、编辑、删除打卡任务
|
|
||||||
- 📊 **管理后台** - 可视化的数据统计和日志查看
|
|
||||||
- 🚀 **RESTful API** - 29 个标准化 API 端点,自动生成文档
|
|
||||||
- 🎯 **角色权限** - 普通用户和管理员角色分离
|
|
||||||
- 📱 **响应式界面** - 基于 Element Plus 的现代化 UI
|
|
||||||
|
|
||||||
## 🏗️ 技术架构
|
### 环境要求
|
||||||
|
|
||||||
### 后端
|
|
||||||
- **Web 框架**: FastAPI 0.109+
|
|
||||||
- **服务器**: Uvicorn (ASGI)
|
|
||||||
- **ORM**: SQLAlchemy 2.0+
|
|
||||||
- **数据库**: SQLite (可迁移到 PostgreSQL)
|
|
||||||
- **任务调度**: APScheduler 3.10+
|
|
||||||
- **自动化**: Selenium 4.16+
|
|
||||||
- **认证**: JWT (python-jose)
|
|
||||||
|
|
||||||
### 前端
|
|
||||||
- **框架**: Vue 3.5+
|
|
||||||
- **构建工具**: Vite 7+
|
|
||||||
- **UI 组件**: Element Plus 2.13+
|
|
||||||
- **状态管理**: Pinia 3.0+
|
|
||||||
- **路由**: Vue Router 4.6+
|
|
||||||
- **HTTP 客户端**: Axios 1.13+
|
|
||||||
|
|
||||||
## 📦 快速开始
|
|
||||||
|
|
||||||
### 前置要求
|
|
||||||
|
|
||||||
- Python 3.9+
|
- Python 3.9+
|
||||||
- Node.js 16+ (仅前端需要)
|
- Node.js 16+
|
||||||
- Chrome 浏览器
|
- Chrome 浏览器
|
||||||
- ChromeDriver
|
|
||||||
|
|
||||||
### 一键启动（推荐）
|
### 安装运行
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```cmd
|
|
||||||
# 启动所有服务（后端 + 前端）
|
|
||||||
manage.bat start-all
|
|
||||||
```
|
|
||||||
|
|
||||||
**Linux/Mac:**
|
|
||||||
```bash
|
```bash
|
||||||
# 给脚本执行权限
|
# 后端
|
||||||
chmod +x manage.sh
|
|
||||||
|
|
||||||
# 启动所有服务
|
|
||||||
./manage.sh start-all
|
|
||||||
```
|
|
||||||
|
|
||||||
### 手动启动
|
|
||||||
|
|
||||||
#### 1. 克隆项目
|
|
||||||
```bash
|
|
||||||
git clone <repository-url>
|
|
||||||
cd CheckInApp
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 后端设置
|
|
||||||
```bash
|
|
||||||
# 创建虚拟环境
|
|
||||||
python -m venv venv
|
python -m venv venv
|
||||||
|
venv\Scripts\activate # Windows
|
||||||
# 激活虚拟环境
|
source venv/bin/activate # Linux/Mac
|
||||||
# Windows:
|
|
||||||
venv\Scripts\activate
|
|
||||||
# Linux/Mac:
|
|
||||||
source venv/bin/activate
|
|
||||||
|
|
||||||
# 安装依赖
|
|
||||||
pip install -r backend/requirements.txt
|
pip install -r backend/requirements.txt
|
||||||
|
python3 run.py
|
||||||
|
|
||||||
# 配置环境变量（可选）
|
# 前端
|
||||||
cp .env.example .env
|
|
||||||
# 编辑 .env 文件设置 SECRET_KEY 等
|
|
||||||
|
|
||||||
# 启动后端
|
|
||||||
python run.py
|
|
||||||
```
|
|
||||||
|
|
||||||
后端服务将在 http://localhost:8000 启动
|
|
||||||
|
|
||||||
#### 3. 前端设置（可选）
|
|
||||||
```bash
|
|
||||||
# 进入前端目录
|
|
||||||
cd frontend
|
cd frontend
|
||||||
|
|
||||||
# 安装依赖
|
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
# 启动开发服务器
|
|
||||||
npm run dev
|
npm run dev
|
||||||
```
|
|
||||||
|
|
||||||
前端应用将在 http://localhost:3000 启动
|
# 创建管理员
|
||||||
|
|
||||||
### 4. 创建管理员账户
|
|
||||||
|
|
||||||
首次使用需要创建管理员账户:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Windows
|
|
||||||
venv\Scripts\python backend\scripts\create_admin.py
|
|
||||||
|
|
||||||
# Linux/Mac
|
|
||||||
python backend/scripts/create_admin.py
|
python backend/scripts/create_admin.py
|
||||||
```
|
```
|
||||||
|
|
||||||
按提示输入 alias(用户名) 并通过 QQ 扫码完成管理员创建。
|
|
||||||
|
|
||||||
## 📖 使用指南
|
|
||||||
|
|
||||||
### 访问地址
|
### 访问地址
|
||||||
|
|
||||||
- **前端应用**: http://localhost:3000
|
- 前端: <http://localhost:3000>
|
||||||
- **API 文档**: http://localhost:8000/docs
|
- API 文档: <http://localhost:8000/docs>
|
||||||
- **健康检查**: http://localhost:8000/health
|
|
||||||
|
|
||||||
### 登录流程
|
## 进程管理
|
||||||
|
|
||||||
1. 打开前端应用
|
|
||||||
2. 输入您的 alias(用户别名)
|
|
||||||
3. 点击"QQ 扫码登录"
|
|
||||||
4. 使用手机 QQ 扫描弹出的二维码
|
|
||||||
5. 扫码成功后自动登录系统
|
|
||||||
|
|
||||||
### 用户功能
|
|
||||||
|
|
||||||
- 查看 Token 状态和过期时间
|
|
||||||
- 查看和管理自己的打卡任务
|
|
||||||
- 创建新的打卡任务
|
|
||||||
- 手动触发单个任务打卡
|
|
||||||
- 启用/禁用任务
|
|
||||||
- 查看任务的打卡记录
|
|
||||||
- 查看个人信息
|
|
||||||
|
|
||||||
### 管理员功能
|
|
||||||
|
|
||||||
- 用户管理（创建、编辑、删除）
|
|
||||||
- 查看所有用户的任务
|
|
||||||
- 批量启用/禁用任务
|
|
||||||
- 批量触发打卡
|
|
||||||
- 查看所有打卡记录
|
|
||||||
- 查看系统日志
|
|
||||||
- 系统统计信息（用户数、任务数、打卡统计）
|
|
||||||
|
|
||||||
## ⚙️ 配置说明
|
|
||||||
|
|
||||||
### 环境变量 (`.env`)
|
|
||||||
|
|
||||||
```env
|
|
||||||
# JWT 密钥（生产环境必须修改）
|
|
||||||
SECRET_KEY=your-secret-key-change-in-production
|
|
||||||
|
|
||||||
# 管理员默认别名
|
|
||||||
ADMIN_ALIAS=admin
|
|
||||||
|
|
||||||
# 数据库 URL（可选）
|
|
||||||
DATABASE_URL=sqlite:///./data/checkin.db
|
|
||||||
|
|
||||||
# CORS 允许的域名
|
|
||||||
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
|
|
||||||
|
|
||||||
# Token 过期检查间隔（分钟）
|
|
||||||
TOKEN_CHECK_INTERVAL_MINUTES=30
|
|
||||||
|
|
||||||
# 会话文件清理间隔（小时）
|
|
||||||
SESSION_CLEANUP_INTERVAL_HOURS=24
|
|
||||||
|
|
||||||
# 注意：每个任务的打卡时间由任务的 cron_expression 字段控制
|
|
||||||
```
|
|
||||||
|
|
||||||
### 邮件配置 (`config.ini`)
|
|
||||||
|
|
||||||
```ini
|
|
||||||
[Email]
|
|
||||||
smtpserver = smtp.example.com
|
|
||||||
smtpport = 465
|
|
||||||
senderemail = your-email@example.com
|
|
||||||
senderpassword = your-password
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📂 项目结构
|
|
||||||
|
|
||||||
```
|
|
||||||
CheckInApp/
|
|
||||||
├── backend/ # FastAPI 后端
|
|
||||||
│ ├── main.py # 应用入口
|
|
||||||
│ ├── config.py # 配置管理
|
|
||||||
│ ├── dependencies.py # 认证中间件
|
|
||||||
│ ├── models/ # 数据库模型
|
|
||||||
│ │ ├── user.py # User 模型
|
|
||||||
│ │ ├── check_in_task.py # CheckInTask 模型 (V2 新增)
|
|
||||||
│ │ └── check_in_record.py # CheckInRecord 模型
|
|
||||||
│ ├── schemas/ # Pydantic Schema
|
|
||||||
│ │ ├── user.py
|
|
||||||
│ │ ├── task.py # (V2 新增)
|
|
||||||
│ │ ├── auth.py
|
|
||||||
│ │ └── check_in.py
|
|
||||||
│ ├── api/ # API 路由
|
|
||||||
│ │ ├── auth.py
|
|
||||||
│ │ ├── users.py
|
|
||||||
│ │ ├── tasks.py # (V2 新增)
|
|
||||||
│ │ ├── check_in.py
|
|
||||||
│ │ └── admin.py
|
|
||||||
│ ├── services/ # 业务逻辑
|
|
||||||
│ │ ├── auth_service.py
|
|
||||||
│ │ ├── user_service.py
|
|
||||||
│ │ ├── task_service.py # (V2 新增)
|
|
||||||
│ │ ├── check_in_service.py
|
|
||||||
│ │ └── scheduler_service.py
|
|
||||||
│ ├── workers/ # Selenium 工作模块
|
|
||||||
│ │ ├── token_refresher.py
|
|
||||||
│ │ ├── check_in_worker.py
|
|
||||||
│ │ └── email_notifier.py
|
|
||||||
│ └── scripts/ # 工具脚本
|
|
||||||
│ └── create_admin.py
|
|
||||||
├── frontend/ # Vue 3 前端
|
|
||||||
│ ├── src/
|
|
||||||
│ │ ├── api/ # API 调用
|
|
||||||
│ │ ├── components/ # 组件
|
|
||||||
│ │ ├── views/ # 页面
|
|
||||||
│ │ ├── stores/ # Pinia 状态
|
|
||||||
│ │ └── router/ # 路由配置
|
|
||||||
│ └── package.json
|
|
||||||
├── data/ # 数据库文件
|
|
||||||
├── logs/ # 日志文件
|
|
||||||
│ └── backend.log # 后端日志 (V2 更名)
|
|
||||||
├── sessions/ # 会话临时文件
|
|
||||||
├── venv/ # Python 虚拟环境
|
|
||||||
├── run.py # 后端启动脚本
|
|
||||||
├── manage.bat/sh # 进程管理脚本 (V2 增强)
|
|
||||||
├── ARCHITECTURE_V2.md # V2 架构文档 (新增)
|
|
||||||
└── config.ini # 邮件配置
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📊 API 端点
|
|
||||||
|
|
||||||
系统提供 **29 个 RESTful API 端点**:
|
|
||||||
|
|
||||||
### 认证 (`/api/auth`)
|
|
||||||
- `POST /api/auth/request_qrcode` - 请求 QQ 扫码
|
|
||||||
- `GET /api/auth/qrcode_status/{session_id}` - 查询扫码状态
|
|
||||||
- `POST /api/auth/verify_token` - 验证 Token
|
|
||||||
|
|
||||||
### 用户 (`/api/users`)
|
|
||||||
- `POST /api/users` - 创建用户（管理员）
|
|
||||||
- `GET /api/users/me` - 获取当前用户
|
|
||||||
- `GET /api/users/me/token_status` - Token 状态
|
|
||||||
- `GET /api/users/me/tasks` - 获取当前用户任务列表 **(V2 新增)**
|
|
||||||
- `GET /api/users` - 用户列表（管理员）
|
|
||||||
- `GET /api/users/{user_id}` - 获取指定用户
|
|
||||||
- `PUT /api/users/{user_id}` - 更新用户
|
|
||||||
- `DELETE /api/users/{user_id}` - 删除用户（管理员）
|
|
||||||
|
|
||||||
### 任务 (`/api/tasks`) **(V2 新增模块)**
|
|
||||||
- `POST /api/tasks` - 创建任务
|
|
||||||
- `GET /api/tasks` - 获取当前用户任务
|
|
||||||
- `GET /api/tasks/{task_id}` - 获取任务详情
|
|
||||||
- `PUT /api/tasks/{task_id}` - 更新任务
|
|
||||||
- `DELETE /api/tasks/{task_id}` - 删除任务
|
|
||||||
- `POST /api/tasks/{task_id}/toggle` - 切换任务状态
|
|
||||||
|
|
||||||
### 打卡 (`/api/check_in`)
|
|
||||||
- `POST /api/check_in/manual/{task_id}` - 手动触发任务打卡
|
|
||||||
- `GET /api/check_in/task/{task_id}/records` - 获取任务打卡记录
|
|
||||||
- `GET /api/check_in/records` - 所有记录（管理员）
|
|
||||||
- `GET /api/check_in/records/count` - 记录统计（管理员）
|
|
||||||
|
|
||||||
### 管理员 (`/api/admin`)
|
|
||||||
- `POST /api/admin/batch_toggle_tasks` - 批量启用/禁用任务
|
|
||||||
- `POST /api/admin/batch_check_in` - 批量打卡
|
|
||||||
- `GET /api/admin/logs` - 系统日志
|
|
||||||
- `GET /api/admin/stats` - 系统统计
|
|
||||||
|
|
||||||
详细 API 文档请访问: http://localhost:8000/docs
|
|
||||||
|
|
||||||
## ⏰ 自动化任务
|
|
||||||
|
|
||||||
系统自动执行以下定时任务:
|
|
||||||
|
|
||||||
1. **定时打卡**: 每天 20:00 为所有启用的任务执行打卡
|
|
||||||
2. **Token 检查**: 每 30 分钟检查一次,即将过期时发送邮件到任务的邮箱
|
|
||||||
3. **会话清理**: 每 24 小时清理过期的会话文件
|
|
||||||
|
|
||||||
## 🔧 进程管理
|
|
||||||
|
|
||||||
使用内置的进程管理脚本可以方便地管理服务:
|
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```cmd
|
|
||||||
manage.bat start-backend # 启动后端服务
|
|
||||||
manage.bat start-frontend # 启动前端服务
|
|
||||||
manage.bat start-all # 启动所有服务
|
|
||||||
manage.bat stop-backend # 停止后端
|
|
||||||
manage.bat stop-frontend # 停止前端
|
|
||||||
manage.bat stop-all # 停止所有服务
|
|
||||||
manage.bat status # 查看状态
|
|
||||||
manage.bat logs-backend # 查看后端日志
|
|
||||||
manage.bat logs-frontend # 查看前端日志
|
|
||||||
```
|
|
||||||
|
|
||||||
**Linux/Mac:**
|
|
||||||
```bash
|
|
||||||
./manage.sh start-backend
|
|
||||||
./manage.sh start-frontend
|
|
||||||
./manage.sh start-all
|
|
||||||
./manage.sh stop-backend
|
|
||||||
./manage.sh stop-frontend
|
|
||||||
./manage.sh stop-all
|
|
||||||
./manage.sh status
|
|
||||||
./manage.sh logs-backend
|
|
||||||
./manage.sh logs-frontend
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🐛 故障排查
|
|
||||||
|
|
||||||
### 端口被占用
|
|
||||||
```bash
|
|
||||||
# Windows
|
|
||||||
netstat -ano | findstr :8000
|
|
||||||
|
|
||||||
# Linux/Mac
|
|
||||||
lsof -i :8000
|
|
||||||
```
|
|
||||||
|
|
||||||
### 查看日志
|
|
||||||
```bash
|
|
||||||
# 后端日志
|
|
||||||
cat logs/backend.log
|
|
||||||
|
|
||||||
# 使用管理脚本查看
|
|
||||||
manage.bat logs-backend # Windows
|
|
||||||
./manage.sh logs-backend # Linux/Mac
|
|
||||||
```
|
|
||||||
|
|
||||||
### Selenium 问题
|
|
||||||
|
|
||||||
确保 Chrome 和 ChromeDriver 已正确配置。相关路径在 `backend/workers/` 中定义。
|
|
||||||
|
|
||||||
## 📚 文档
|
|
||||||
|
|
||||||
- [快速入门指南](QUICKSTART.md)
|
|
||||||
- [V2 架构文档](ARCHITECTURE_V2.md) **(推荐阅读)**
|
|
||||||
- [后端详细文档](backend/README.md)
|
|
||||||
- [后端开发总结](BACKEND_SUMMARY.md)
|
|
||||||
- [V1 旧版文档](v1/README.md)
|
|
||||||
|
|
||||||
## 🔒 安全建议
|
|
||||||
|
|
||||||
1. **生产环境务必修改 SECRET_KEY**
|
|
||||||
2. 不要将 `.env` 文件提交到版本控制
|
|
||||||
3. 定期更新依赖包
|
|
||||||
4. 使用 HTTPS 部署生产环境
|
|
||||||
5. 限制管理员账户数量
|
|
||||||
6. 定期备份数据库
|
|
||||||
|
|
||||||
## 🚀 部署
|
|
||||||
|
|
||||||
### Docker 部署（推荐）
|
|
||||||
```bash
|
|
||||||
# 构建镜像
|
|
||||||
docker-compose build
|
|
||||||
|
|
||||||
# 启动服务
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
### 传统部署
|
|
||||||
1. 使用 Gunicorn 运行后端
|
|
||||||
2. 构建前端并使用 Nginx 托管
|
|
||||||
3. 配置反向代理
|
|
||||||
|
|
||||||
详见部署文档。
|
|
||||||
|
|
||||||
## 📝 V2 更新日志
|
|
||||||
|
|
||||||
### 架构改进
|
|
||||||
- ✅ 实现用户-任务分离架构
|
|
||||||
- ✅ 新增 CheckInTask 数据模型
|
|
||||||
- ✅ 引入三层身份体系 (jwt_sub + alias + signature)
|
|
||||||
- ✅ 全局 Token 刷新机制
|
|
||||||
|
|
||||||
### 新增功能
|
|
||||||
- ✅ 任务管理 API (6个端点)
|
|
||||||
- ✅ 任务所有权验证
|
|
||||||
- ✅ 用户任务列表查询
|
|
||||||
- ✅ 任务级别的邮箱配置
|
|
||||||
- ✅ 任务级别的启用/禁用
|
|
||||||
|
|
||||||
### 功能优化
|
|
||||||
- ✅ API 端点从 18 个增加到 29 个
|
|
||||||
- ✅ 改进的权限控制系统
|
|
||||||
- ✅ 更清晰的代码结构
|
|
||||||
- ✅ UTF-8 编码全面支持
|
|
||||||
- ✅ 增强的日志系统
|
|
||||||
- ✅ 改进的进程管理脚本
|
|
||||||
|
|
||||||
## 🤝 贡献
|
|
||||||
|
|
||||||
欢迎提交 Issue 和 Pull Request!
|
|
||||||
|
|
||||||
## 📄 许可证
|
|
||||||
|
|
||||||
[MIT License](LICENSE)
|
|
||||||
|
|
||||||
## 🙏 致谢
|
|
||||||
|
|
||||||
感谢所有开源项目的贡献者!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**版本**: V2.0.0
|
|
||||||
**状态**: ✅ 生产就绪
|
|
||||||
**最后更新**: 2025-12-31
|
|
||||||
|
|
||||||
## 🏗️ 技术架构
|
|
||||||
|
|
||||||
### 后端
|
|
||||||
- **Web 框架**: FastAPI 0.109+
|
|
||||||
- **服务器**: Uvicorn (ASGI)
|
|
||||||
- **ORM**: SQLAlchemy 2.0+
|
|
||||||
- **数据库**: SQLite (可迁移到 PostgreSQL)
|
|
||||||
- **任务调度**: APScheduler 3.10+
|
|
||||||
- **自动化**: Selenium 4.16+
|
|
||||||
- **认证**: JWT (python-jose)
|
|
||||||
|
|
||||||
### 前端
|
|
||||||
- **框架**: Vue 3.5+
|
|
||||||
- **构建工具**: Vite 7+
|
|
||||||
- **UI 组件**: Element Plus 2.13+
|
|
||||||
- **状态管理**: Pinia 3.0+
|
|
||||||
- **路由**: Vue Router 4.6+
|
|
||||||
- **HTTP 客户端**: Axios 1.13+
|
|
||||||
|
|
||||||
## 📦 快速开始
|
|
||||||
|
|
||||||
### 前置要求
|
|
||||||
|
|
||||||
- Python 3.9+
|
|
||||||
- Node.js 16+ (仅前端需要)
|
|
||||||
- Chrome 浏览器
|
|
||||||
- ChromeDriver
|
|
||||||
|
|
||||||
### 一键启动（推荐）
|
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```cmd
|
|
||||||
# 启动所有服务（后端 + 前端）
|
|
||||||
start_all.bat
|
|
||||||
```
|
|
||||||
|
|
||||||
**Linux/Mac:**
|
|
||||||
```bash
|
|
||||||
# 给脚本执行权限
|
|
||||||
chmod +x start_all.sh
|
|
||||||
|
|
||||||
# 启动所有服务
|
|
||||||
./start_all.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### 手动启动
|
|
||||||
|
|
||||||
#### 1. 克隆项目
|
|
||||||
```bash
|
|
||||||
git clone <repository-url>
|
|
||||||
cd CheckInApp
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 后端设置
|
|
||||||
```bash
|
|
||||||
# 创建虚拟环境
|
|
||||||
python -m venv venv
|
|
||||||
|
|
||||||
# 激活虚拟环境
|
|
||||||
# Windows:
|
|
||||||
venv\Scripts\activate
|
|
||||||
# Linux/Mac:
|
|
||||||
source venv/bin/activate
|
|
||||||
|
|
||||||
# 安装依赖
|
|
||||||
pip install -r backend/requirements.txt
|
|
||||||
|
|
||||||
# 配置环境变量（可选）
|
|
||||||
cp .env.example .env
|
|
||||||
# 编辑 .env 文件设置 SECRET_KEY 等
|
|
||||||
|
|
||||||
# 启动后端
|
|
||||||
python run.py
|
|
||||||
```
|
|
||||||
|
|
||||||
后端服务将在 http://localhost:8000 启动
|
|
||||||
|
|
||||||
#### 3. 前端设置（可选）
|
|
||||||
```bash
|
|
||||||
# 进入前端目录
|
|
||||||
cd frontend
|
|
||||||
|
|
||||||
# 安装依赖
|
|
||||||
npm install
|
|
||||||
|
|
||||||
# 启动开发服务器
|
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
前端应用将在 http://localhost:3000 启动
|
|
||||||
|
|
||||||
### 4. 创建管理员账户
|
|
||||||
|
|
||||||
首次使用需要创建管理员账户：
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Windows
|
# Windows
|
||||||
venv\Scripts\python backend\scripts\create_admin.py
|
manage.bat start [all/backend/fronted]
|
||||||
|
manage.bat stop [all/backend/fronted]
|
||||||
|
manage.bat status
|
||||||
|
|
||||||
# Linux/Mac
|
# Linux/Mac
|
||||||
python backend/scripts/create_admin.py
|
./manage.sh start [all/backend/fronted]
|
||||||
```
|
./manage.sh stop [all/backend/fronted]
|
||||||
|
|
||||||
按提示输入 Signature 并通过 QQ 扫码完成管理员创建。
|
|
||||||
|
|
||||||
## 📖 使用指南
|
|
||||||
|
|
||||||
### 访问地址
|
|
||||||
|
|
||||||
- **前端应用**: http://localhost:3000
|
|
||||||
- **API 文档**: http://localhost:8000/docs
|
|
||||||
- **健康检查**: http://localhost:8000/health
|
|
||||||
|
|
||||||
### 登录流程
|
|
||||||
|
|
||||||
1. 打开前端应用
|
|
||||||
2. 输入您的 Signature（唯一标识）
|
|
||||||
3. 点击"QQ 扫码登录"
|
|
||||||
4. 使用手机 QQ 扫描弹出的二维码
|
|
||||||
5. 扫码成功后自动登录系统
|
|
||||||
|
|
||||||
### 用户功能
|
|
||||||
|
|
||||||
- 查看 Token 状态和过期时间
|
|
||||||
- 手动触发打卡
|
|
||||||
- 查看自己的打卡记录
|
|
||||||
- 查看个人信息
|
|
||||||
|
|
||||||
### 管理员功能
|
|
||||||
|
|
||||||
- 用户管理（创建、编辑、删除）
|
|
||||||
- 批量启用/禁用用户
|
|
||||||
- 批量触发打卡
|
|
||||||
- 查看所有打卡记录
|
|
||||||
- 查看系统日志
|
|
||||||
- 系统统计信息
|
|
||||||
|
|
||||||
## ⚙️ 配置说明
|
|
||||||
|
|
||||||
### 环境变量 (`.env`)
|
|
||||||
|
|
||||||
```env
|
|
||||||
# JWT 密钥（生产环境必须修改）
|
|
||||||
SECRET_KEY=your-secret-key-change-in-production
|
|
||||||
|
|
||||||
# 管理员默认标识
|
|
||||||
ADMIN_SIGNATURE=admin
|
|
||||||
|
|
||||||
# 数据库 URL（可选）
|
|
||||||
DATABASE_URL=sqlite:///./data/checkin.db
|
|
||||||
|
|
||||||
# CORS 允许的域名
|
|
||||||
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
|
|
||||||
|
|
||||||
# Token 过期检查间隔（分钟）
|
|
||||||
TOKEN_CHECK_INTERVAL_MINUTES=30
|
|
||||||
|
|
||||||
# 会话文件清理间隔（小时）
|
|
||||||
SESSION_CLEANUP_INTERVAL_HOURS=24
|
|
||||||
|
|
||||||
# 注意：每个任务的打卡时间由任务的 cron_expression 字段控制
|
|
||||||
```
|
|
||||||
|
|
||||||
### 邮件配置 (`config.ini`)
|
|
||||||
|
|
||||||
```ini
|
|
||||||
[Email]
|
|
||||||
smtpserver = smtp.example.com
|
|
||||||
smtpport = 465
|
|
||||||
senderemail = your-email@example.com
|
|
||||||
senderpassword = your-password
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📂 项目结构
|
|
||||||
|
|
||||||
```
|
|
||||||
CheckInApp/
|
|
||||||
├── backend/ # FastAPI 后端
|
|
||||||
│ ├── main.py # 应用入口
|
|
||||||
│ ├── config.py # 配置管理
|
|
||||||
│ ├── dependencies.py # 认证中间件
|
|
||||||
│ ├── models/ # 数据库模型
|
|
||||||
│ ├── schemas/ # Pydantic Schema
|
|
||||||
│ ├── api/ # API 路由
|
|
||||||
│ ├── services/ # 业务逻辑
|
|
||||||
│ ├── workers/ # Selenium 工作模块
|
|
||||||
│ └── scripts/ # 工具脚本
|
|
||||||
├── frontend/ # Vue 3 前端
|
|
||||||
│ ├── src/
|
|
||||||
│ │ ├── api/ # API 调用
|
|
||||||
│ │ ├── components/ # 组件
|
|
||||||
│ │ ├── views/ # 页面
|
|
||||||
│ │ ├── stores/ # Pinia 状态
|
|
||||||
│ │ └── router/ # 路由配置
|
|
||||||
│ └── package.json
|
|
||||||
├── data/ # 数据库文件
|
|
||||||
├── logs/ # 日志文件
|
|
||||||
├── sessions/ # 会话临时文件
|
|
||||||
├── venv/ # Python 虚拟环境
|
|
||||||
├── run.py # 后端启动脚本
|
|
||||||
├── manage.bat/sh # 进程管理脚本
|
|
||||||
├── start_all.bat/sh # 一键启动脚本
|
|
||||||
└── config.ini # 邮件配置
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📊 API 端点
|
|
||||||
|
|
||||||
系统提供 18 个 RESTful API 端点：
|
|
||||||
|
|
||||||
### 认证 (`/api/auth`)
|
|
||||||
- `POST /api/auth/request_qrcode` - 请求 QQ 扫码
|
|
||||||
- `GET /api/auth/qrcode_status/{session_id}` - 查询扫码状态
|
|
||||||
- `POST /api/auth/verify_token` - 验证 Token
|
|
||||||
|
|
||||||
### 用户 (`/api/users`)
|
|
||||||
- `POST /api/users` - 创建用户
|
|
||||||
- `GET /api/users/me` - 获取当前用户
|
|
||||||
- `GET /api/users/me/token_status` - Token 状态
|
|
||||||
- `GET /api/users` - 用户列表
|
|
||||||
- `PUT /api/users/{user_id}` - 更新用户
|
|
||||||
- `DELETE /api/users/{user_id}` - 删除用户
|
|
||||||
|
|
||||||
### 打卡 (`/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/admin`)
|
|
||||||
|
|
||||||
- `POST /api/admin/batch_check_in` - 批量打卡
|
|
||||||
- `GET /api/admin/logs` - 系统日志
|
|
||||||
- `GET /api/admin/stats` - 系统统计
|
|
||||||
|
|
||||||
详细 API 文档请访问: http://localhost:8000/docs
|
|
||||||
|
|
||||||
## ⏰ 自动化任务
|
|
||||||
|
|
||||||
系统自动执行以下定时任务：
|
|
||||||
|
|
||||||
1. **定时打卡**: 每天 20:00 为所有启用的用户执行打卡
|
|
||||||
2. **Token 检查**: 每 30 分钟检查一次，即将过期时发送邮件
|
|
||||||
3. **会话清理**: 每 24 小时清理过期的会话文件
|
|
||||||
|
|
||||||
## 🔧 进程管理
|
|
||||||
|
|
||||||
使用内置的进程管理脚本可以方便地管理后端服务：
|
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```cmd
|
|
||||||
manage.bat start # 启动服务（后台运行）
|
|
||||||
manage.bat stop # 停止服务
|
|
||||||
manage.bat restart # 重启服务
|
|
||||||
manage.bat status # 查看状态
|
|
||||||
```
|
|
||||||
|
|
||||||
**Linux/Mac:**
|
|
||||||
```bash
|
|
||||||
./manage.sh start
|
|
||||||
./manage.sh stop
|
|
||||||
./manage.sh restart
|
|
||||||
./manage.sh status
|
./manage.sh status
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🐛 故障排查
|
## 配置
|
||||||
|
|
||||||
### 端口被占用
|
复制 `.env.example` 到 `.env`
|
||||||
```bash
|
|
||||||
# Windows
|
|
||||||
netstat -ano | findstr :8000
|
|
||||||
|
|
||||||
# Linux/Mac
|
nginx 与 systemd 的配置文件参考已给出，见 `.example`
|
||||||
lsof -i :8000
|
|
||||||
```
|
|
||||||
|
|
||||||
### 查看日志
|
## 文档
|
||||||
```bash
|
|
||||||
# 后端日志
|
|
||||||
cat logs/CheckIn.log
|
|
||||||
|
|
||||||
# 使用管理脚本查看
|
- [架构设计](docs/architecture.md)
|
||||||
./manage.sh status
|
- [部署指南](docs/deployment.md)
|
||||||
```
|
- [开发指南](docs/development.md)
|
||||||
|
|
||||||
### Selenium 问题
|
|
||||||
|
|
||||||
确保 Chrome 和 ChromeDriver 已正确配置。相关路径在 `backend/workers/` 中定义。
|
|
||||||
|
|
||||||
## 📚 文档
|
|
||||||
|
|
||||||
- [快速入门指南](QUICKSTART.md)
|
|
||||||
- [后端详细文档](backend/README.md)
|
|
||||||
- [后端开发总结](BACKEND_SUMMARY.md)
|
|
||||||
- [V1 旧版文档](v1/README.md)
|
|
||||||
|
|
||||||
## 🔒 安全建议
|
|
||||||
|
|
||||||
1. **生产环境务必修改 SECRET_KEY**
|
|
||||||
2. 不要将 `.env` 文件提交到版本控制
|
|
||||||
3. 定期更新依赖包
|
|
||||||
4. 使用 HTTPS 部署生产环境
|
|
||||||
5. 限制管理员账户数量
|
|
||||||
|
|
||||||
## 🚀 部署
|
|
||||||
|
|
||||||
### Docker 部署（推荐）
|
|
||||||
```bash
|
|
||||||
# 构建镜像
|
|
||||||
docker-compose build
|
|
||||||
|
|
||||||
# 启动服务
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
### 传统部署
|
|
||||||
1. 使用 Gunicorn 运行后端
|
|
||||||
2. 构建前端并使用 Nginx 托管
|
|
||||||
3. 配置反向代理
|
|
||||||
|
|
||||||
详见部署文档。
|
|
||||||
|
|
||||||
## 📝 开发计划
|
|
||||||
|
|
||||||
- [x] 后端 API 开发
|
|
||||||
- [x] 前端基础框架
|
|
||||||
- [x] 用户认证系统
|
|
||||||
- [x] 管理员功能
|
|
||||||
- [ ] 批量导入用户
|
|
||||||
- [ ] 数据导出功能
|
|
||||||
- [ ] Docker 镜像优化
|
|
||||||
- [ ] 单元测试覆盖
|
|
||||||
|
|
||||||
## 🤝 贡献
|
|
||||||
|
|
||||||
欢迎提交 Issue 和 Pull Request！
|
|
||||||
|
|
||||||
## 📄 许可证
|
|
||||||
|
|
||||||
[MIT License](LICENSE)
|
|
||||||
|
|
||||||
## 🙏 致谢
|
|
||||||
|
|
||||||
感谢所有开源项目的贡献者！
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**版本**: V2.0.0
|
|
||||||
**状态**: ✅ 生产就绪
|
|
||||||
**最后更新**: 2025-12-31
|
|
||||||
|
|||||||
@@ -0,0 +1,181 @@
|
|||||||
|
# 架构设计
|
||||||
|
|
||||||
|
## 系统概述
|
||||||
|
|
||||||
|
CheckIn App V2 采用用户-任务分离架构，一个用户可管理多个打卡任务，全局 Token 刷新，任务级别独立控制。
|
||||||
|
|
||||||
|
## 核心架构
|
||||||
|
|
||||||
|
### V2 关键改进
|
||||||
|
|
||||||
|
- **用户-任务分离**: User 和 CheckInTask 独立管理
|
||||||
|
- **全局 Token**: 用户级别的 authorization token，一次扫码更新所有任务
|
||||||
|
- **任务级控制**: 每个任务独立的启用状态和邮箱配置
|
||||||
|
- **任务模板**: TaskTemplate 系统，快速创建标准化任务
|
||||||
|
|
||||||
|
### 数据模型
|
||||||
|
|
||||||
|
#### User（用户）
|
||||||
|
|
||||||
|
```python
|
||||||
|
- id: 主键
|
||||||
|
- jwt_sub: QQ ID（唯一）
|
||||||
|
- alias: 用户名
|
||||||
|
- email: 邮箱
|
||||||
|
- password_hash: 密码（可选）
|
||||||
|
- authorization: QQ Token（全局）
|
||||||
|
- jwt_exp: Token 过期时间
|
||||||
|
- role: admin/user
|
||||||
|
- is_approved: 审批状态
|
||||||
|
```
|
||||||
|
|
||||||
|
#### CheckInTask（任务）
|
||||||
|
|
||||||
|
```python
|
||||||
|
- id: 主键
|
||||||
|
- user_id: 所属用户
|
||||||
|
- name: 任务名称
|
||||||
|
- payload_config: JSON 配置（包含打卡字段）
|
||||||
|
- cron_expression: 定时表达式（如 "0 20 * * *"）
|
||||||
|
- is_active: 是否启用
|
||||||
|
```
|
||||||
|
|
||||||
|
#### CheckInRecord（记录）
|
||||||
|
|
||||||
|
```python
|
||||||
|
- id: 主键
|
||||||
|
- task_id: 所属任务
|
||||||
|
- status: success/failed/already_submitted
|
||||||
|
- response_text: API 响应
|
||||||
|
- trigger_type: scheduled/manual/admin
|
||||||
|
- check_in_time: 打卡时间
|
||||||
|
```
|
||||||
|
|
||||||
|
#### TaskTemplate（模板）
|
||||||
|
|
||||||
|
```python
|
||||||
|
- id: 主键
|
||||||
|
- name: 模板名称
|
||||||
|
- field_config: JSON 字段配置
|
||||||
|
- parent_id: 父模板（可选）
|
||||||
|
- is_active: 是否启用
|
||||||
|
```
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
### 后端
|
||||||
|
|
||||||
|
- **FastAPI**: Web 框架，自动生成 API 文档
|
||||||
|
- **SQLAlchemy**: ORM，支持多数据库
|
||||||
|
- **APScheduler**: 任务调度，动态加载 cron 任务
|
||||||
|
- **Selenium**: 浏览器自动化，获取 QQ Token 和打卡 payload
|
||||||
|
- **JWT**: 身份认证
|
||||||
|
- **SMTP**: 邮件通知
|
||||||
|
|
||||||
|
### 前端
|
||||||
|
|
||||||
|
- **Vue 3**: Composition API
|
||||||
|
- **Ant Design Vue**: UI 组件库
|
||||||
|
- **Pinia**: 状态管理
|
||||||
|
- **Axios**: HTTP 客户端，拦截器处理 Token
|
||||||
|
|
||||||
|
## 认证流程
|
||||||
|
|
||||||
|
### QQ 扫码登录
|
||||||
|
|
||||||
|
1. 用户输入 alias
|
||||||
|
2. 后端检查 alias 可用性和频率限制
|
||||||
|
3. Selenium 启动 headless Chrome，打开接龙登录页
|
||||||
|
4. 生成 QR code，返回给前端
|
||||||
|
5. 用户手机 QQ 扫码
|
||||||
|
6. Selenium 检测登录成功，提取 authorization token 和 jwt
|
||||||
|
7. 存储用户信息（待审批状态）
|
||||||
|
8. 管理员审批后用户可登录
|
||||||
|
|
||||||
|
### 密码登录
|
||||||
|
|
||||||
|
1. 用户设置密码后可使用 alias + password 登录
|
||||||
|
2. 后端验证密码，返回 JWT token
|
||||||
|
|
||||||
|
## 打卡流程
|
||||||
|
|
||||||
|
### 手动打卡
|
||||||
|
|
||||||
|
1. 用户点击任务的"立即打卡"按钮
|
||||||
|
2. 后端异步执行打卡任务
|
||||||
|
3. Selenium 获取最新 x-api-request-payload
|
||||||
|
4. 使用用户的 authorization token 调用接龙 API
|
||||||
|
5. 解析响应，存储记录
|
||||||
|
6. 返回结果
|
||||||
|
|
||||||
|
### 定时打卡
|
||||||
|
|
||||||
|
1. 系统启动时加载所有启用的任务
|
||||||
|
2. APScheduler 根据 cron_expression 调度
|
||||||
|
3. 到达时间后自动执行打卡流程
|
||||||
|
4. 发送邮件通知到任务配置的邮箱
|
||||||
|
|
||||||
|
## 调度任务
|
||||||
|
|
||||||
|
### Token 监控
|
||||||
|
|
||||||
|
- 间隔: 30 分钟（可配置）
|
||||||
|
- 功能: 检查 Token 过期时间
|
||||||
|
- 30 分钟内过期: 发送预警邮件
|
||||||
|
- 已过期 30 分钟内: 发送过期通知
|
||||||
|
|
||||||
|
### 会话清理
|
||||||
|
|
||||||
|
- 间隔: 24 小时
|
||||||
|
- 功能: 删除旧的 Selenium 会话文件
|
||||||
|
|
||||||
|
### 用户清理
|
||||||
|
|
||||||
|
- 间隔: 1 小时
|
||||||
|
- 功能: 删除 24 小时未审批的用户
|
||||||
|
|
||||||
|
## 权限控制
|
||||||
|
|
||||||
|
### 角色
|
||||||
|
|
||||||
|
- **admin**: 所有权限
|
||||||
|
- **user**: 仅操作自己的数据
|
||||||
|
|
||||||
|
### 验证机制
|
||||||
|
|
||||||
|
- 任务所有权验证: 确保用户只能操作自己的任务
|
||||||
|
- JWT 认证: 所有 API 需要有效 token
|
||||||
|
- 审批机制: 新用户需管理员审批
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
### 后端分层
|
||||||
|
|
||||||
|
```
|
||||||
|
backend/
|
||||||
|
├── api/ # 路由层（29 个端点）
|
||||||
|
├── services/ # 业务逻辑层
|
||||||
|
├── models/ # 数据模型层
|
||||||
|
├── schemas/ # 请求响应模型
|
||||||
|
├── workers/ # Selenium 工作模块
|
||||||
|
└── scripts/ # 工具脚本
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端分层
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/src/
|
||||||
|
├── api/ # API 调用封装
|
||||||
|
├── views/ # 页面组件
|
||||||
|
├── components/ # 可复用组件
|
||||||
|
├── stores/ # Pinia 状态
|
||||||
|
├── router/ # 路由配置
|
||||||
|
└── composables/ # 组合式函数
|
||||||
|
```
|
||||||
|
|
||||||
|
## 扩展性
|
||||||
|
|
||||||
|
- 数据库可切换到 PostgreSQL/MySQL
|
||||||
|
- 调度任务可扩展到 Celery
|
||||||
|
- 前端可独立部署到 CDN
|
||||||
|
- 支持 Docker 容器化部署
|
||||||
@@ -0,0 +1,220 @@
|
|||||||
|
# 部署指南
|
||||||
|
|
||||||
|
## 环境准备
|
||||||
|
|
||||||
|
### 系统要求
|
||||||
|
|
||||||
|
- Ubuntu 20.04+ / CentOS 7+ / Windows Server
|
||||||
|
- Python 3.9+
|
||||||
|
- Node.js 16+
|
||||||
|
- Chrome / Chromium
|
||||||
|
- 2GB+ RAM
|
||||||
|
|
||||||
|
### 依赖安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ubuntu
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install -y python3 nodejs npm chromium-browser
|
||||||
|
|
||||||
|
# CentOS
|
||||||
|
sudo yum install -y python3 nodejs npm chromium
|
||||||
|
```
|
||||||
|
|
||||||
|
## 生产部署
|
||||||
|
|
||||||
|
### 方式一：传统部署
|
||||||
|
|
||||||
|
#### 1. 后端部署
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆项目
|
||||||
|
git clone <repository>
|
||||||
|
cd CheckInApp
|
||||||
|
|
||||||
|
# 创建虚拟环境
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
pip install -r backend/requirements.txt
|
||||||
|
|
||||||
|
# 生产环境额外依赖
|
||||||
|
pip install gunicorn
|
||||||
|
|
||||||
|
# 配置环境变量
|
||||||
|
cp .env.example .env
|
||||||
|
vim .env # 修改环境变量
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 前端部署
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# 构建生产版本
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# 输出在 dist/ 目录
|
||||||
|
```
|
||||||
|
|
||||||
|
**使用 Nginx 托管**:
|
||||||
|
|
||||||
|
[示例文件](../nginx.conf.example)
|
||||||
|
|
||||||
|
#### 3. 使用 Systemd 管理
|
||||||
|
|
||||||
|
[示例文件](../checkin-app.service.example)
|
||||||
|
|
||||||
|
### 方式二：Docker 部署（推荐）
|
||||||
|
|
||||||
|
TODO(Maybe never)
|
||||||
|
|
||||||
|
## 配置优化
|
||||||
|
|
||||||
|
### 生产环境变量
|
||||||
|
|
||||||
|
[示例文件](../.env.example)
|
||||||
|
|
||||||
|
### 数据库迁移到 PostgreSQL
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装 PostgreSQL
|
||||||
|
sudo apt install postgresql postgresql-contrib
|
||||||
|
|
||||||
|
# 创建数据库
|
||||||
|
sudo -u postgres createdb checkin
|
||||||
|
sudo -u postgres createuser checkin_user
|
||||||
|
sudo -u postgres psql -c "ALTER USER checkin_user WITH PASSWORD 'password';"
|
||||||
|
|
||||||
|
# 修改 .env
|
||||||
|
DATABASE_URL=postgresql://checkin_user:password@localhost/checkin
|
||||||
|
```
|
||||||
|
|
||||||
|
## 安全加固
|
||||||
|
|
||||||
|
### 1. 防火墙配置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo ufw allow 22/tcp # SSH
|
||||||
|
sudo ufw allow 80/tcp # HTTP
|
||||||
|
sudo ufw allow 443/tcp # HTTPS
|
||||||
|
sudo ufw enable
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. SSL 证书（Let's Encrypt）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo apt install certbot python3-certbot-nginx
|
||||||
|
|
||||||
|
sudo certbot --nginx -d your-domain.com
|
||||||
|
|
||||||
|
# 自动续期
|
||||||
|
sudo systemctl enable certbot.timer
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 限制访问
|
||||||
|
|
||||||
|
- 修改 `.env` 中的 `CORS_ORIGINS` 为实际域名
|
||||||
|
- 在 Nginx 中配置 rate limiting
|
||||||
|
- 使用 fail2ban 防止暴力破解
|
||||||
|
|
||||||
|
## 监控维护
|
||||||
|
|
||||||
|
### 日志管理
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看后端日志
|
||||||
|
tail -f logs/backend.log
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数据库备份
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# SQLite 备份
|
||||||
|
cp data/checkin.db data/checkin.db.backup
|
||||||
|
|
||||||
|
# PostgreSQL 备份
|
||||||
|
pg_dump checkin > backup.sql
|
||||||
|
|
||||||
|
# 定时备份（crontab）
|
||||||
|
0 2 * * * /path/to/backup.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 性能监控
|
||||||
|
|
||||||
|
使用工具：
|
||||||
|
|
||||||
|
- Prometheus + Grafana
|
||||||
|
- New Relic
|
||||||
|
- Sentry（错误追踪）
|
||||||
|
|
||||||
|
## 扩展部署
|
||||||
|
|
||||||
|
### 负载均衡
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
upstream backend {
|
||||||
|
server 127.0.0.1:8000;
|
||||||
|
server 127.0.0.1:8001;
|
||||||
|
server 127.0.0.1:8002;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
location /api {
|
||||||
|
proxy_pass http://backend;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Redis 缓存
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 安装 redis
|
||||||
|
pip install redis
|
||||||
|
|
||||||
|
# 配置会话存储
|
||||||
|
REDIS_URL=redis://localhost:6379/0
|
||||||
|
```
|
||||||
|
|
||||||
|
## 故障排查
|
||||||
|
|
||||||
|
### 端口占用
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo lsof -i :8000
|
||||||
|
sudo kill -9 <PID>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Selenium 问题
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 检查 Chrome 版本
|
||||||
|
chromium --version
|
||||||
|
chromedriver --version
|
||||||
|
|
||||||
|
# 确保版本匹配
|
||||||
|
```
|
||||||
|
|
||||||
|
### 权限问题
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 确保目录权限正确
|
||||||
|
sudo chown -R www-data:www-data /path/to/CheckInApp
|
||||||
|
sudo chmod -R 755 /path/to/CheckInApp
|
||||||
|
```
|
||||||
|
|
||||||
|
## 回滚策略
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 保存当前版本
|
||||||
|
git tag -a v2.0.0 -m "Production release"
|
||||||
|
|
||||||
|
# 回滚到上一版本
|
||||||
|
git checkout v1.9.0
|
||||||
|
docker-compose down
|
||||||
|
docker-compose up -d --build
|
||||||
|
```
|
||||||
@@ -0,0 +1,398 @@
|
|||||||
|
# 开发指南
|
||||||
|
|
||||||
|
## 开发环境设置
|
||||||
|
|
||||||
|
### 后端开发
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆项目
|
||||||
|
git clone <repository>
|
||||||
|
cd CheckInApp
|
||||||
|
|
||||||
|
# 创建虚拟环境
|
||||||
|
python -m venv venv
|
||||||
|
source venv/bin/activate # Linux/Mac
|
||||||
|
venv\Scripts\activate # Windows
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
pip install -r backend/requirements.txt
|
||||||
|
|
||||||
|
# 安装开发依赖
|
||||||
|
pip install pytest pytest-asyncio black flake8
|
||||||
|
|
||||||
|
python3 run.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端开发
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# 启动开发服务器
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# 代码格式化
|
||||||
|
npm run lint
|
||||||
|
npm run format
|
||||||
|
```
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
### 后端目录说明
|
||||||
|
|
||||||
|
```
|
||||||
|
backend/
|
||||||
|
├── main.py # FastAPI 应用入口，CORS、路由注册
|
||||||
|
├── config.py # Pydantic Settings 配置
|
||||||
|
├── dependencies.py # 依赖注入（认证、权限）
|
||||||
|
├── exceptions.py # 自定义异常类
|
||||||
|
│
|
||||||
|
├── models/ # SQLAlchemy 数据模型
|
||||||
|
│ ├── database.py # 数据库连接、Session
|
||||||
|
│ ├── user.py
|
||||||
|
│ ├── check_in_task.py
|
||||||
|
│ ├── check_in_record.py
|
||||||
|
│ └── task_template.py
|
||||||
|
│
|
||||||
|
├── schemas/ # Pydantic 请求响应模型
|
||||||
|
│ ├── user.py
|
||||||
|
│ ├── task.py
|
||||||
|
│ ├── auth.py
|
||||||
|
│ └── response.py # 标准化响应
|
||||||
|
│
|
||||||
|
├── api/ # API 路由（按模块划分）
|
||||||
|
│ ├── auth.py # 认证相关
|
||||||
|
│ ├── users.py # 用户管理
|
||||||
|
│ ├── tasks.py # 任务管理
|
||||||
|
│ ├── check_in.py # 打卡功能
|
||||||
|
│ ├── admin.py # 管理员功能
|
||||||
|
│ └── templates.py # 模板管理
|
||||||
|
│
|
||||||
|
├── services/ # 业务逻辑层
|
||||||
|
│ ├── auth_service.py
|
||||||
|
│ ├── user_service.py
|
||||||
|
│ ├── task_service.py
|
||||||
|
│ ├── check_in_service.py
|
||||||
|
│ ├── scheduler_service.py
|
||||||
|
│ ├── template_service.py
|
||||||
|
│ └── registration_manager.py
|
||||||
|
│
|
||||||
|
└── workers/ # Selenium 自动化
|
||||||
|
├── token_refresher.py # QQ 登录
|
||||||
|
├── check_in_worker.py # 打卡执行
|
||||||
|
└── email_notifier.py # 邮件发送
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端目录说明
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/src/
|
||||||
|
├── main.js # Vue 应用入口
|
||||||
|
├── App.vue # 根组件
|
||||||
|
│
|
||||||
|
├── api/ # API 封装
|
||||||
|
│ ├── client.js # Axios 实例、拦截器
|
||||||
|
│ └── index.js # API 模块（auth, user, task 等）
|
||||||
|
│
|
||||||
|
├── views/ # 页面组件
|
||||||
|
│ ├── LoginView.vue
|
||||||
|
│ ├── DashboardView.vue
|
||||||
|
│ ├── TasksView.vue
|
||||||
|
│ ├── RecordsView.vue
|
||||||
|
│ └── admin/ # 管理员页面
|
||||||
|
│
|
||||||
|
├── components/ # 可复用组件
|
||||||
|
│ ├── TaskCard.vue
|
||||||
|
│ ├── RecordTable.vue
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── stores/ # Pinia 状态管理
|
||||||
|
│ ├── auth.js # 认证状态
|
||||||
|
│ ├── user.js # 用户信息
|
||||||
|
│ └── task.js # 任务列表
|
||||||
|
│
|
||||||
|
├── router/ # Vue Router
|
||||||
|
│ └── index.js # 路由配置、导航守卫
|
||||||
|
│
|
||||||
|
└── composables/ # 组合式函数
|
||||||
|
├── useAuth.js
|
||||||
|
└── useTask.js
|
||||||
|
```
|
||||||
|
|
||||||
|
## 开发流程
|
||||||
|
|
||||||
|
### 添加新功能
|
||||||
|
|
||||||
|
#### 1. 后端 API 开发
|
||||||
|
|
||||||
|
**步骤**:
|
||||||
|
|
||||||
|
1. 在 `models/` 定义数据模型
|
||||||
|
2. 在 `schemas/` 定义请求响应模型
|
||||||
|
3. 在 `services/` 实现业务逻辑
|
||||||
|
4. 在 `api/` 创建路由端点
|
||||||
|
5. 在 `main.py` 注册路由
|
||||||
|
|
||||||
|
**示例**: 添加一个新的"任务标签"功能
|
||||||
|
|
||||||
|
```python
|
||||||
|
# models/task_tag.py
|
||||||
|
class TaskTag(Base):
|
||||||
|
__tablename__ = "task_tags"
|
||||||
|
id = Column(Integer, primary_key=True)
|
||||||
|
task_id = Column(Integer, ForeignKey("check_in_tasks.id"))
|
||||||
|
tag_name = Column(String(50))
|
||||||
|
|
||||||
|
# schemas/tag.py
|
||||||
|
class TaskTagCreate(BaseModel):
|
||||||
|
tag_name: str
|
||||||
|
|
||||||
|
# services/tag_service.py
|
||||||
|
def create_tag(db: Session, task_id: int, tag_data: TaskTagCreate):
|
||||||
|
tag = TaskTag(task_id=task_id, tag_name=tag_data.tag_name)
|
||||||
|
db.add(tag)
|
||||||
|
db.commit()
|
||||||
|
return tag
|
||||||
|
|
||||||
|
# api/tags.py
|
||||||
|
@router.post("/tasks/{task_id}/tags")
|
||||||
|
def add_tag(task_id: int, tag: TaskTagCreate, db: Session = Depends(get_db)):
|
||||||
|
return tag_service.create_tag(db, task_id, tag)
|
||||||
|
|
||||||
|
# main.py
|
||||||
|
from api import tags
|
||||||
|
app.include_router(tags.router, prefix="/api")
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 前端开发
|
||||||
|
|
||||||
|
**步骤**:
|
||||||
|
|
||||||
|
1. 在 `api/index.js` 添加 API 调用
|
||||||
|
2. 在 `stores/` 创建或更新状态
|
||||||
|
3. 创建或更新 Vue 组件
|
||||||
|
4. 配置路由（如需要）
|
||||||
|
|
||||||
|
**示例**: 添加标签管理页面
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// api/index.js
|
||||||
|
export const tagApi = {
|
||||||
|
addTag: (taskId, data) => client.post(`/tasks/${taskId}/tags`, data),
|
||||||
|
getTags: (taskId) => client.get(`/tasks/${taskId}/tags`)
|
||||||
|
}
|
||||||
|
|
||||||
|
// stores/tag.js
|
||||||
|
export const useTagStore = defineStore('tag', {
|
||||||
|
state: () => ({
|
||||||
|
tags: []
|
||||||
|
}),
|
||||||
|
actions: {
|
||||||
|
async fetchTags(taskId) {
|
||||||
|
const { data } = await tagApi.getTags(taskId)
|
||||||
|
this.tags = data
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
// components/TagManager.vue
|
||||||
|
<template>
|
||||||
|
<div>
|
||||||
|
<a-tag v-for="tag in tags" :key="tag.id">{{ tag.tag_name }}</a-tag>
|
||||||
|
<a-button @click="addTag">添加标签</a-button>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数据库迁移
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 修改模型后生成迁移脚本
|
||||||
|
# 手动创建脚本在 backend/scripts/migrate_*.py
|
||||||
|
|
||||||
|
# 执行迁移
|
||||||
|
python backend/scripts/migrate_xxx.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### 测试
|
||||||
|
|
||||||
|
#### 后端测试
|
||||||
|
|
||||||
|
```python
|
||||||
|
# tests/test_task_service.py
|
||||||
|
import pytest
|
||||||
|
from backend.services import task_service
|
||||||
|
|
||||||
|
def test_create_task():
|
||||||
|
task = task_service.create_task(db, user_id=1, task_data)
|
||||||
|
assert task.name == "Test Task"
|
||||||
|
assert task.is_active == True
|
||||||
|
|
||||||
|
# 运行测试
|
||||||
|
pytest backend/tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 前端测试
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// tests/TaskCard.spec.js
|
||||||
|
import { mount } from '@vue/test-utils'
|
||||||
|
import TaskCard from '@/components/TaskCard.vue'
|
||||||
|
|
||||||
|
test('displays task name', () => {
|
||||||
|
const wrapper = mount(TaskCard, {
|
||||||
|
props: { task: { name: 'Test Task' } }
|
||||||
|
})
|
||||||
|
expect(wrapper.text()).toContain('Test Task')
|
||||||
|
})
|
||||||
|
|
||||||
|
// 运行测试
|
||||||
|
npm run test
|
||||||
|
```
|
||||||
|
|
||||||
|
## 代码规范
|
||||||
|
|
||||||
|
### 后端规范
|
||||||
|
|
||||||
|
- 使用 Black 格式化: `black backend/`
|
||||||
|
- 遵循 PEP 8
|
||||||
|
- 函数添加类型注解
|
||||||
|
- API 路由使用 Pydantic 模型验证
|
||||||
|
- 使用 dependency injection
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 好的示例
|
||||||
|
async def create_task(
|
||||||
|
task_data: TaskCreate,
|
||||||
|
db: Session = Depends(get_db),
|
||||||
|
current_user: User = Depends(get_current_user)
|
||||||
|
) -> TaskResponse:
|
||||||
|
"""创建新任务"""
|
||||||
|
return task_service.create_task(db, current_user.id, task_data)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端规范
|
||||||
|
|
||||||
|
- 使用 ESLint + Prettier
|
||||||
|
- 组件使用 Composition API
|
||||||
|
- 使用 `<script setup>` 语法
|
||||||
|
- Props 添加类型验证
|
||||||
|
- 统一使用 Ant Design Vue 组件
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<!-- 好的示例 -->
|
||||||
|
<script setup>
|
||||||
|
import { ref, computed } from 'vue'
|
||||||
|
|
||||||
|
const props = defineProps({
|
||||||
|
task: {
|
||||||
|
type: Object,
|
||||||
|
required: true
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
const isActive = computed(() => props.task.is_active)
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 调试技巧
|
||||||
|
|
||||||
|
### 后端调试
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 使用 logging
|
||||||
|
import logging
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
logger.info(f"Creating task for user {user_id}")
|
||||||
|
|
||||||
|
# 使用 pdb
|
||||||
|
import pdb; pdb.set_trace()
|
||||||
|
|
||||||
|
# 查看 SQL 查询
|
||||||
|
import logging
|
||||||
|
logging.basicConfig()
|
||||||
|
logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端调试
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 使用 Vue Devtools
|
||||||
|
// Chrome 扩展安装
|
||||||
|
|
||||||
|
// console 输出
|
||||||
|
console.log('Task data:', task.value)
|
||||||
|
|
||||||
|
// 调试 API 请求
|
||||||
|
axios.interceptors.request.use(request => {
|
||||||
|
console.log('Request:', request)
|
||||||
|
return request
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
### CORS 错误
|
||||||
|
|
||||||
|
在 `.env` 添加前端地址:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CORS_ORIGINS=http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数据库锁定
|
||||||
|
|
||||||
|
使用 connection pool:
|
||||||
|
|
||||||
|
```python
|
||||||
|
engine = create_engine(
|
||||||
|
DATABASE_URL,
|
||||||
|
pool_pre_ping=True,
|
||||||
|
pool_size=10
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Selenium 超时
|
||||||
|
|
||||||
|
增加等待时间:
|
||||||
|
|
||||||
|
```python
|
||||||
|
WebDriverWait(driver, 30).until(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Git 工作流
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 创建功能分支
|
||||||
|
git checkout -b feature/task-tags
|
||||||
|
|
||||||
|
# 提交代码
|
||||||
|
git add .
|
||||||
|
git commit -m "feat: add task tag functionality"
|
||||||
|
|
||||||
|
# 合并到主分支
|
||||||
|
git checkout main
|
||||||
|
git merge feature/task-tags
|
||||||
|
|
||||||
|
# 推送
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
## 性能优化
|
||||||
|
|
||||||
|
### 后端优化
|
||||||
|
|
||||||
|
- 使用 SQLAlchemy 的 `joinedload` 避免 N+1 查询
|
||||||
|
- 添加数据库索引
|
||||||
|
- 使用异步任务处理耗时操作
|
||||||
|
- 启用 gzip 压缩
|
||||||
|
|
||||||
|
### 前端优化
|
||||||
|
|
||||||
|
- 使用虚拟滚动处理大列表
|
||||||
|
- 路由懒加载
|
||||||
|
- 图片懒加载
|
||||||
|
- 使用 `keep-alive` 缓存组件
|
||||||
Reference in New Issue
Block a user