BeetleRunBackEnd

项目简介

本项目为 BeetleRun 打卡后端服务，基于 FastAPI + SQLModel 实现，支持用户打卡、数据统计、排行榜、数据备份等功能。

目录结构（重构后）

beetleRunBk/
├── main.py                # FastAPI 启动入口，仅负责启动和路由注册
├── app/
│   ├── routers/           # 路由层，所有API路由集中于 api_router.py
│   ├── services/          # 业务逻辑层，建议继续细分
│   ├── models/            # 数据模型与数据库连接
│   └── ...
├── static/                # 静态资源
├── templates/             # Jinja2 模板
├── backups/               # 数据库备份
├── start.sh               # 启动脚本
└── beetleRunBk.service    # systemd 服务文件

快速启动

pip install fastapi sqlmodel jinja2 uvicorn
./start.sh

systemd 注册

sudo ln -s $(pwd)/beetleRunBk.service /etc/systemd/system/beetleRunBk.service
sudo systemctl daemon-reload
sudo systemctl enable beetleRunBk
sudo systemctl start beetleRunBk
sudo systemctl status beetleRunBk

blockly 插件

可将 blokyly_plugin_bk.txt 加载到 koishi-plugin-blockly-null。

API 参考

路径	方法	说明	参数/Body	返回/渲染页面
/	GET	数据筛选主页	-	web.html
/web	POST	数据筛选API	user_id, name, min_distance, max_distance	JSON数据
/stat	GET/POST	用户统计	user_id	user_stat.html/JSON
/bind	POST	用户绑定	user_id, name	bind_success.html / bind_fail.html
/checkin	POST	打卡	user_id, distance, ...	多种打卡成功/失败页面
/list	GET/POST	打卡记录分页	user_id, page, size	list.html
/rank	GET/POST	排行榜	mode（可选）	rank.html
/delete	POST	删除打卡记录	user_id	delete_checkin_success.html / checkin_fail.html
/erase	POST	删除单条打卡记录	id	JSON
/backup	POST	数据备份	backup_name（可选）	backup_success.html
/archive	POST	归档并清空打卡	backup_name（可选）	backup_success.html

---

如需二次开发，建议在 app/services/ 继续细分业务逻辑，保持代码整洁易维护。