# 葫芦数学 Hulumath

面向全年龄数学兴趣用户的“数学人生宇宙”。当前仓库包含可运行的 Django 模块化单体、响应式 Web 客户端、运营后台、内容种子、实时比赛基础设施和生产部署配置。

## 参与贡献

提交代码、内容或文档前，请先完整阅读 [代码贡献指南](CONTRIBUTING.md)。

所有改动必须通过 PR 提交，并由仓库负责人 Jacky 审查批准后才能合并。贡献指南同时包含供 AI 编程助手快速建立上下文的架构、约束、测试和部署说明。

## 已实现

- 邀请码注册、登录、个人资料、会话记录和管理员审计模型
- 12 题 MathBTI、16 种数学人格、人物卡与数学精灵初始化
- 统一版本化剧情引擎、85 节点信仰者主线、2 个人物 Skill 样板
- 剧情服务端存档、嵌套资源效果、结局与幂等选择
- 入门、标准、进阶三赛道的实时 1v1、今日挑战、单人闯关、24 点和数独
- 题目版本、服务端计时判分、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
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/` 契约可作为后续两端共用后端。