葫芦数学 Hulumath
面向全年龄数学兴趣用户的“数学人生宇宙”。当前仓库包含可运行的 Django 模块化单体、响应式 Web 客户端、运营后台、内容种子、实时比赛基础设施和生产部署配置。
当前发布版本：v1.2.1。变更与迁移说明见 v1.2.1 Release Notes。
参与贡献
提交代码、内容或文档前，请先完整阅读 代码贡献指南。
所有改动必须通过 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 或更高版本。
make install
make migrate
make seed
make run
访问 http://127.0.0.1:8000/。本地种子邀请码为 HULU2026，仅用于开发体验。
管理后台位于 http://127.0.0.1:8000/admin/。创建管理员：
make local-admin
默认本地测试账号为 local_admin / LocalAdmin2026!。该命令仅允许在
DJANGO_DEBUG=true 时运行，不会接触或修改生产管理员。需要自定义时：
cd backend
../.venv/bin/python manage.py init_local_admin \
--username jacky_local \
--password '仅用于本机的测试密码' \
--reset-password
测试
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
本地验证生产拓扑：
docker compose up --build
迁移由独立 migrate 服务执行，Web 进程只在迁移成功、MySQL 和 Redis 健康后启动。
Gitea 会在 PR 合并到 main 后自动测试和部署：
目录
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/ 契约可作为后续两端共用后端。