README.md

metadata

title: Spring Check-In Activity Manager
emoji: 🌿
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
fullWidth: true
header: default
short_description: 春日打卡行动管理系统，支持用户与多管理员后台、活动任务、线索发布与图片审核。

Spring Check-In Activity Manager

这是一个可直接部署到 Hugging Face Docker Space 的春日打卡行动系统，包含：

• 用户端 /login：学号 + 密码登录
• 管理员端 /admin：多管理员后台，支持超级管理员
• 用户管理：手动录入用户，按小组分配成员
• 小组管理：卡片式展示每个小组与人数上限
• 活动发布：一个活动包含多个打卡任务，可配置开始/截止时间
• 图片上传：用户提交图片会自动压缩到 2MB 以下并暂存到本地
• 图片审核：管理员统一审核通过/驳回，并支持勾选批量下载
• 线索发布：管理员为任务上传线索图，按固定时间间隔自动发布
• 排行榜：按完成打卡点数量优先、总耗时次优进行小组排序，可控制是否对用户可见

目录结构

app/
  main.py
  config.py
  database.py
  models.py
  routes/
  services/
  static/
  templates/
ca.pem
Dockerfile
requirements.txt
README.md

必填 Hugging Face Secrets

在 Hugging Face Space 的 Settings -> Variables and secrets 中至少配置以下运行时 Secrets：

• ADMIN：超级管理员账号
• PASSWORD：超级管理员密码
• SQL_PASSWORD：Aiven MySQL 的密码
• SESSION_SECRET：用于 Session 签名的随机长字符串

可选 Variables

如果你想覆盖默认连接配置，可以额外设置这些 Variables：

• SQL_USER，默认 avnadmin
• SQL_HOST，默认 mysql-2bace9cd-cacode.i.aivencloud.com
• SQL_PORT，默认 21260
• SQL_DATABASE，默认 CAM
• MYSQL_CA_FILE，默认 ca.pem
• APP_TIMEZONE，默认 Asia/Shanghai
• UPLOAD_ROOT，默认 data/submissions
• DATABASE_URL，如设置则优先使用完整数据库连接串

数据存储说明

• 任务主图和线索图存入 MySQL，并在入库前自动压缩到 200KB 以下。
• 用户打卡图不会写入 MySQL，而是保存在应用本地临时目录中，默认是 data/submissions/。
• 本地文件用于管理员审核、预览和批量下载。
• Docker Space 容器重启后，本地临时文件可能丢失，因此本项目按“临时文件”设计；若后续需要长期保存，可以再接入对象存储。

本地运行

先准备环境变量：

cp .env.example .env

Windows PowerShell 示例：

$env:ADMIN="superadmin"
$env:PASSWORD="change-me-now"
$env:SQL_PASSWORD="your_mysql_password"
$env:SESSION_SECRET="replace-with-a-long-random-secret"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload

部署到 Hugging Face Space

1. 在 Hugging Face 上创建一个新的 Space，并选择 Docker 作为 SDK。
2. 将当前仓库文件上传到 Space 仓库根目录。
3. 确认 README.md 顶部保留了 sdk: docker 和 app_port: 7860 的 YAML 元数据。
4. 在 Space 设置中填入 ADMIN、PASSWORD、SQL_PASSWORD、SESSION_SECRET。
5. 确保 ca.pem 一并上传到仓库根目录。
6. 等待 Space 自动构建完成。

关键行为说明

• 超级管理员账号由环境变量 ADMIN / PASSWORD 初始化，并在启动时自动同步到数据库。
• 任务线索图如果存在，会根据 线索发布时间间隔 和任务顺序计算发布时间；用户端会轮询并在移动端触发震动提醒。
• 排行榜按小组聚合，排序规则是：
  1. 已审核通过的打卡点数量降序
  2. 总耗时升序

后续可选增强

• 给管理员增加活动编辑与任务删除功能
• 给用户增加二次提交历史记录
• 增加导出 Excel 报表
• 接入对象存储以保存用户原图或长期归档文件