README.md

---
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 报表
- 接入对象存储以保存用户原图或长期归档文件