116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# 葫芦数学 Hulumath
|
|
|
|
面向全年龄数学兴趣用户的“数学人生宇宙”。当前仓库包含可运行的 Django 模块化单体、响应式 Web 客户端、运营后台、内容种子、实时比赛基础设施和生产部署配置。
|
|
|
|
当前发布版本：**v1.2.0**。变更与迁移说明见
|
|
[v1.2.0 Release Notes](docs/RELEASE_NOTES_V1.2.0.md)。
|
|
|
|
## 参与贡献
|
|
|
|
提交代码、内容或文档前，请先完整阅读 [代码贡献指南](CONTRIBUTING.md)。
|
|
|
|
所有改动必须通过 PR 提交，并由仓库负责人 Jacky 审查批准后才能合并。贡献指南同时包含供 AI 编程助手快速建立上下文的架构、约束、测试和部署说明。
|
|
|
|
## 已实现
|
|
|
|
- 邀请码注册、登录、个人资料、会话记录和管理员审计模型
|
|
- 12 题 MathBTI、16 种数学人格、人物卡与数学精灵初始化
|
|
- 统一版本化剧情引擎、85 节点信仰者主线、2 个人物 Skill 样板
|
|
- 剧情服务端存档、嵌套资源效果、结局与幂等选择
|
|
- 统一玩家池的口算、数独 Timerun、24 点实时 1v1，以及随机今日挑战和单人闯关
|
|
- 题目版本、服务端计时判分、Elo Rating、排行榜和基础反作弊
|
|
- Channels WebSocket 比赛进度通道，Redis Channel Layer
|
|
- LaTeX 文档与版本、六级零基础课程、练习判定
|
|
- 54 条旧版志愿者视频、五维能力地图、专业筛选与融合视频流
|
|
- 视频观看进度、幂等奖励、收藏、五维能力、数学精灵和人物卡册
|
|
- 多工具工具箱：强计算器、增强函数绘图、统一联机数学画板、符号查询和 LaTeX Lab
|
|
- 信仰者人生 20 印记、4 个组合彩蛋、4 个直博方向与独立全屏交互
|
|
- 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
|
|
make local-admin
|
|
```
|
|
|
|
默认本地测试账号为 `local_admin` / `LocalAdmin2026!`。该命令仅允许在
|
|
`DJANGO_DEBUG=true` 时运行，不会接触或修改生产管理员。需要自定义时：
|
|
|
|
```bash
|
|
cd backend
|
|
../.venv/bin/python manage.py init_local_admin \
|
|
--username jacky_local \
|
|
--password '仅用于本机的测试密码' \
|
|
--reset-password
|
|
```
|
|
|
|
## 测试
|
|
|
|
```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)
|
|
- [本地实时 1v1 与联机码约战测试](docs/LOCAL_REALTIME_TEST.md)
|
|
|
|
## 目录
|
|
|
|
```text
|
|
backend/
|
|
├── accounts/ # 用户、邀请码、会话、审计
|
|
├── math_life/ # MathBTI、统一剧情、人物 Skill
|
|
├── contest/ # 题库、比赛、匹配、Rating
|
|
├── latex_lab/ # 公式、课程、练习
|
|
├── progression/ # 五维能力、精灵、卡牌、奖励
|
|
├── content/ # 视频、知识卡片、人物内容
|
|
├── engagement/ # 签到与通知
|
|
├── toolbox/ # 受限数学计算内核与工具 API
|
|
├── common/ # 健康检查、错误、日志
|
|
└── config/ # Django/ASGI 配置
|
|
```
|
|
|
|
API 统一使用 `/api/v1/` 前缀，WebSocket 使用 `/ws/v1/` 前缀。
|
|
|
|
## 当前环境限制
|
|
|
|
Taro 小程序和 Next.js 独立客户端尚未生成。当前机器没有 Node.js，规定的小程序模板初始化工具无法运行；现有响应式 Web 客户端与 `/api/v1/` 契约可作为后续两端共用后端。
|