mirror of
https://github.com/Cccc-owo/CheckInApp.git
synced 2026-06-17 05:56:29 +00:00
183 lines
4.3 KiB
Markdown
183 lines
4.3 KiB
Markdown
# 架构设计
|
||
|
||
## 系统概述
|
||
|
||
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 任务
|
||
- **Playwright**: 浏览器自动化，获取 QQ Token 和打卡 payload
|
||
- **JWT**: 身份认证
|
||
- **SMTP**: 邮件通知
|
||
|
||
### 前端
|
||
|
||
- **Vue 3**: Composition API
|
||
- **TypeScript**: 前端类型约束
|
||
- **shadcn-vue**: 共享 UI primitive
|
||
- **Tailwind CSS**: 设计令牌和布局表达
|
||
- **fetch + local API helpers**: 请求封装和 Token 处理
|
||
|
||
## 认证流程
|
||
|
||
### QQ 扫码登录
|
||
|
||
1. 用户输入 alias
|
||
2. 后端检查 alias 可用性和频率限制
|
||
3. Playwright 启动 headless Chromium，打开接龙登录页
|
||
4. 生成 QR code，返回给前端
|
||
5. 用户手机 QQ 扫码
|
||
6. Playwright 检测登录成功，提取 authorization token 和 jwt
|
||
7. 存储用户信息（待审批状态）
|
||
8. 管理员审批后用户可登录
|
||
|
||
### 密码登录
|
||
|
||
1. 用户设置密码后可使用 alias + password 登录
|
||
2. 后端验证密码，返回 JWT token
|
||
|
||
## 打卡流程
|
||
|
||
### 手动打卡
|
||
|
||
1. 用户点击任务的"立即打卡"按钮
|
||
2. 后端异步执行打卡任务
|
||
3. Playwright 获取最新 x-api-request-payload
|
||
4. 使用用户的 authorization token 调用接龙 API
|
||
5. 解析响应，存储记录
|
||
6. 返回结果
|
||
|
||
### 定时打卡
|
||
|
||
1. 系统启动时加载所有启用的任务
|
||
2. APScheduler 根据 cron_expression 调度
|
||
3. 到达时间后自动执行打卡流程
|
||
4. 发送邮件通知到任务配置的邮箱
|
||
|
||
## 调度任务
|
||
|
||
### Token 监控
|
||
|
||
- 间隔: 30 分钟（可配置）
|
||
- 功能: 检查 Token 过期时间
|
||
- 30 分钟内过期: 发送预警邮件
|
||
- 已过期 30 分钟内: 发送过期通知
|
||
|
||
### 会话清理
|
||
|
||
- 间隔: 24 小时
|
||
- 功能: 删除旧的 Playwright 会话文件
|
||
|
||
### 用户清理
|
||
|
||
- 间隔: 1 小时
|
||
- 功能: 删除 24 小时未审批的用户
|
||
|
||
## 权限控制
|
||
|
||
### 角色
|
||
|
||
- **admin**: 所有权限
|
||
- **user**: 仅操作自己的数据
|
||
|
||
### 验证机制
|
||
|
||
- 任务所有权验证: 确保用户只能操作自己的任务
|
||
- JWT 认证: 所有 API 需要有效 token
|
||
- 审批机制: 新用户需管理员审批
|
||
|
||
## 目录结构
|
||
|
||
### 后端分层
|
||
|
||
```
|
||
apps/backend/
|
||
├── api/ # 路由层（29 个端点）
|
||
├── services/ # 业务逻辑层
|
||
├── models/ # 数据模型层
|
||
├── schemas/ # 请求响应模型
|
||
├── workers/ # Playwright 工作模块
|
||
└── scripts/ # 工具脚本
|
||
```
|
||
|
||
### 前端分层
|
||
|
||
```
|
||
apps/frontend/src/
|
||
├── api/ # API 调用封装
|
||
├── app/ # 认证、路由、主题
|
||
├── views/ # 页面组件
|
||
├── components/ # 可复用组件和 shadcn primitives
|
||
├── utils/ # 格式化与显示 helper
|
||
└── style.css # 全局 token 和语义样式
|
||
```
|
||
|
||
## 扩展性
|
||
|
||
- 数据库可切换到 PostgreSQL/MySQL
|
||
- 调度任务可扩展到 Celery
|
||
- 前端可独立部署到 CDN
|
||
- 支持 Docker 容器化部署
|