| --- |
| 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 以下并暂存到本地 |
| - 图片审核：管理员统一审核通过/驳回，并支持勾选批量下载 |
| - 线索发布：管理员为任务上传线索图，按固定时间间隔自动发布 |
| - 排行榜：按完成打卡点数量优先、总耗时次优进行小组排序，可控制是否对用户可见 |
|
|
| ## 目录结构 |
|
|
| ```text |
| 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 容器重启后，本地临时文件可能丢失，因此本项目按“临时文件”设计；若后续需要长期保存，可以再接入对象存储。 |
|
|
| ## 本地运行 |
|
|
| 先准备环境变量： |
|
|
| ```bash |
| cp .env.example .env |
| ``` |
|
|
| Windows PowerShell 示例： |
|
|
| ```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 报表 |
| - 接入对象存储以保存用户原图或长期归档文件
|
|
|
