CheckInApp/docs/architecture.md

架构设计

系统概述

CheckIn App V2 采用用户-任务分离架构，一个用户可管理多个打卡任务，全局 Token 刷新，任务级别独立控制。

核心架构

V2 关键改进

• 用户-任务分离: User 和 CheckInTask 独立管理
• 全局 Token: 用户级别的 authorization token，一次扫码更新所有任务
• 任务级控制: 每个任务独立的启用状态和邮箱配置
• 任务模板: TaskTemplate 系统，快速创建标准化任务

数据模型

User（用户）

- id: 主键
- jwt_sub: QQ ID（唯一）
- alias: 用户名
- email: 邮箱
- password_hash: 密码（可选）
- authorization: QQ Token（全局）
- jwt_exp: Token 过期时间
- role: admin/user
- is_approved: 审批状态

CheckInTask（任务）

- id: 主键
- user_id: 所属用户
- name: 任务名称
- payload_config: JSON 配置（包含打卡字段）
- cron_expression: 定时表达式（如 "0 20 * * *"）
- is_active: 是否启用

CheckInRecord（记录）

- id: 主键
- task_id: 所属任务
- status: success/failed/already_submitted
- response_text: API 响应
- trigger_type: scheduled/manual/admin
- check_in_time: 打卡时间

TaskTemplate（模板）

- 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 容器化部署