94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# 葫芦数学 Hulumath
|
|
|
|
面向全年龄数学兴趣用户的“数学人生宇宙”。当前仓库包含可运行的 Django 模块化单体、响应式 Web 客户端、运营后台、内容种子、实时比赛基础设施和生产部署配置。
|
|
|
|
## 已实现
|
|
|
|
- 邀请码注册、登录、个人资料、会话记录和管理员审计模型
|
|
- 12 题 MathBTI、16 种数学人格、人物卡与数学精灵初始化
|
|
- 统一版本化剧情引擎、85 节点信仰者主线、2 个人物 Skill 样板
|
|
- 剧情服务端存档、嵌套资源效果、结局与幂等选择
|
|
- 入门、标准、进阶三赛道的实时 1v1、今日挑战和单人闯关
|
|
- 题目版本、服务端计时判分、Elo Rating、排行榜和基础反作弊
|
|
- Channels WebSocket 比赛进度通道，Redis Channel Layer
|
|
- LaTeX 文档与版本、六级零基础课程、练习判定
|
|
- 54 条旧版志愿者视频、五维能力地图、专业筛选与融合视频流
|
|
- 视频观看进度、幂等奖励、收藏、五维能力、数学精灵和人物卡册
|
|
- 多工具工具箱：口算入口、科学计算器、符号查询、函数绘图和 LaTeX Lab
|
|
- Django Admin、健康检查、请求 ID、限流与统一 API 错误结构
|
|
- MySQL 8.0/Redis Docker Compose、Gitea CI 和自动化测试
|
|
|
|
## 本地启动
|
|
|
|
要求 Python 3.9 或更高版本。
|
|
|
|
```bash
|
|
make install
|
|
make migrate
|
|
make seed
|
|
make run
|
|
```
|
|
|
|
访问 `http://127.0.0.1:8000/`。本地种子邀请码为 `HULU2026`，仅用于开发体验。
|
|
|
|
管理后台位于 `http://127.0.0.1:8000/admin/`。创建管理员：
|
|
|
|
```bash
|
|
cd backend
|
|
../.venv/bin/python manage.py createsuperuser
|
|
```
|
|
|
|
## 测试
|
|
|
|
```bash
|
|
make check
|
|
make test
|
|
```
|
|
|
|
测试覆盖邀请码消费、密码哈希、MathBTI 计分、剧情校验与幂等存档、Contest 判分与超时、实时匹配、Elo 结算、LaTeX 判定和成长初始化。
|
|
|
|
## 生产运行
|
|
|
|
复制 `.env.production.example` 为服务器上的 `.env.production`，并注入真实密钥。生产模式要求：
|
|
|
|
- `DJANGO_DEBUG=false`
|
|
- 强随机 `DJANGO_SECRET_KEY`
|
|
- MySQL 8.0 `DATABASE_URL`
|
|
- Redis `REDIS_URL`
|
|
- 正确的 `DJANGO_ALLOWED_HOSTS` 和 `CORS_ALLOWED_ORIGINS`
|
|
|
|
本地验证生产拓扑：
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
迁移由独立 `migrate` 服务执行，Web 进程只在迁移成功、MySQL 和 Redis 健康后启动。
|
|
|
|
Gitea 会在 PR 合并到 `main` 后自动测试和部署：
|
|
|
|
- [Ubuntu + 宝塔面板从零部署](docs/BAOTA_UBUNTU_FROM_ZERO.md)
|
|
- [自动发布机制与运维说明](docs/DEPLOYMENT.md)
|
|
- [MySQL 8 数据迁移说明](docs/MYSQL8_MIGRATION.md)
|
|
|
|
## 目录
|
|
|
|
```text
|
|
backend/
|
|
├── accounts/ # 用户、邀请码、会话、审计
|
|
├── math_life/ # MathBTI、统一剧情、人物 Skill
|
|
├── contest/ # 题库、比赛、匹配、Rating
|
|
├── latex_lab/ # 公式、课程、练习
|
|
├── progression/ # 五维能力、精灵、卡牌、奖励
|
|
├── content/ # 视频、知识卡片、人物内容
|
|
├── engagement/ # 签到与通知
|
|
├── common/ # 健康检查、错误、日志
|
|
└── config/ # Django/ASGI 配置
|
|
```
|
|
|
|
API 统一使用 `/api/v1/` 前缀，WebSocket 使用 `/ws/v1/` 前缀。
|
|
|
|
## 当前环境限制
|
|
|
|
Taro 小程序和 Next.js 独立客户端尚未生成。当前机器没有 Node.js，规定的小程序模板初始化工具无法运行；现有响应式 Web 客户端与 `/api/v1/` 契约可作为后续两端共用后端。
|