编年史 · 第二篇 · 2026-06-19 ~ 2026-07-02（AI生成）
项目性质
纯 Django 网页端应用：服务端渲染 HTML 模板，学生通过浏览器访问，管理员通过 Django Admin 管理后台操作。无原生客户端。
关键数字
| 指标 | 数值 |
|---|---|
| 时间段 | 6/19 ~ 7/2（14 天） |
| Git commits | 130（单人） |
| 源码库 | D:\Hermes\math_platform\（48.1 MB，含构建产物） |
| 实验工坊 | D:\Hermes\platform_script\（63.5 MB，无 Git） |
| Hermes 会话 | ~283 会话 / ~30K 消息 / ~17M input tokens |
| Django Apps | 6 个（accounts / courses / interactions / qbank / system / math_platform） |
| 服务端部署 | ECS（域名 zhangyuzhixue.top）· nginx + gunicorn · SQLite |
时间轴
06/19 06/24 06/28 07/02
├── 题库建设 ─────┤ ├── 工程期 ───────┤├── 收尾 ─┤├── 过渡 ─┤
题库校对/转码 PDF/解题/服务器 GitHub Actions CI v2 设计启动
第一阶段：题库建设（6/19 ~ 6/23）
核心工作：将北京高考数学试题（2020~2026）从原始格式转为结构化题库。
| 事件 | 描述 |
|---|---|
| 试题转码 | 高三模拟试题从 Word/PDF 转为结构化数据 |
| 全库结构扫描 | 检查 798 道题的完整性、字段一致性 |
| LaTeX 修复 | 修复题库中渲染错误的数学公式 |
| 题库校对 | 逐题核对答案、选项、解析 |
会话关键词： “全库结构完整性扫描”、“高中数学题库现状汇报”、“LaTeX 公式渲染排查”
第二阶段：工程期（6/24 ~ 6/27）
从内容建设转向功能开发。
| 事件 | 关键会话 | 产出 |
|---|---|---|
| PDF 生成 | “PDF生成现状报告”、“PDF测试方案实施” | HTML+KaTeX → PDF 服务端管线 |
| 解题模式 | “解题模式恢复与完成逻辑分析”、“假完成Bug原因追溯” | 选择题/填空题/解答题三题型交互 |
| 权限系统 | “教师改助教评估报告”、“权限系统等级方案评估” | 角色分级 + 管理员/教师/学生权限 |
| 性能优化 | “网站访问速度问题分析” | nginx 调优 + Cloudflare Tunnel |
| 服务器运维 | “服务器故障排查” | ECS 维护 + 数据库备份 |
| Flutter 论证 | “Flutter版本可行性计划” | 这是 v2 的种子 |
第三阶段：收尾与过渡（6/28 ~ 7/2）
v1 收尾工作 + v2 设计启动的分水岭。
| 日期 | 事件 |
|---|---|
| 6/28 | math_platform 最后一批 Git commit |
| 7/1 | “如果我想在同一个服务器上再搭建一个新项目…” — v2 可行性讨论 |
| 7/2 | “读取一下 D:\Hermes\docs\章鱼智学app设计规范.md” — v2 设计文档首次加载 |
7/2 是关键转折日： 当天创建了 v2 的项目骨架（flutter create），同时 v1 的最后一个 Git commit 完成。
技术架构
用户浏览器
│
▼
Cloudflare Tunnel（HTTPS 终结）
│
▼
nginx（反向代理 + 静态文件）
│
▼
gunicorn（Django WSGI）
│
├── accounts（用户/认证）
├── courses（讲义/课程）
├── interactions（答题/评分）
├── qbank（题库管理）
├── system（系统配置）
└── math_platform（项目配置/URL 分发）
关键特征：
- 纯服务端渲染： Django Template + HTML/CSS/JS，无 SPA
- 在线依赖： 每次操作都需要网络请求，无离线能力
- 单数据库： SQLite 单文件，所有数据集中存储
- Markdown + LaTeX： 问答区使用
marked.js+KaTeX前端渲染
教师端（v1）
v1 没有独立的教师端 App。教师通过 Django Admin 后台 + 自定义管理页面完成：
- 讲义上传与编辑
- 学生进度查看
- 班级管理
数据基础
题库
- 总量： ~798 道北京高考数学题
- 年份覆盖： 2020 ~ 2026
- 来源： 一模、二模、高考真题
- 内容格式： Markdown 题干 + LaTeX 数学公式（
$...$/$$...$$） - 配图： 几何题配图（WebP 格式，从 PDF 提取）
- 分步解析： 选择题/填空题的 AI 生成分步解答
字体
- Noto Serif CJK SC（7 字重）— PDF 中文排版
- Noto Serif SC（7 字重）— PDF 补充字体
- 总量：437 MB
实验工坊（platform_script/）
D:\Hermes\platform_script\ 是 v1 的"后厨"——无 Git 版本管理的脚本集合：
- 题库格式转换脚本（Word→Markdown→结构化数据）
- PDF 配图提取脚本
- LaTeX 渲染兼容性测试
- 题库校对与修复脚本
- Obsidian 笔记跳转测试
- 讲义笔记系统
v1 的主要问题（催生 v2 的原因）
| 问题 | 表现 | v2 的改进 |
|---|---|---|
| 移动端体验差 | 网页在手机上缩放/点击困难 | Flutter 原生跨平台 |
| 网络依赖 | 无网就不能用 | 离线优先（SQLite + 同步引擎） |
| 慢速渲染 | 题库页面加载大量 DOM | Flutter 原生渲染 |
| 单端 | 只有学生浏览器可用 | 学生端 + 教师端双 Flutter App |
| 无系统化测试 | 没有 CI，全靠手动 | GitHub Actions + 分层测试体系 |
| 无审计流程 | bug 改完就当修好了 | 5 维度审计 + fix-batch-workflow |
v1 的 GitHub Actions CI
v1 后期（6/24 左右）引入了 GitHub Actions CI，但只覆盖了 Django：
flake8Python 代码风格检查pytest单元测试（少量）
v2 的 CI 在此基础上扩展为并行 Flutter analyze + Django flake8/pytest。
关联的 Hermes 对话
以下是 v1 时期的关键会话（按时间排序）：
| 日期 | 会话主题 | 消息数 |
|---|---|---|
| 6/19 | 学习解构文件标注方式 | 588 |
| 6/19 | 并行运行两个进程 | 733 |
| 6/19 | 全库结构完整性扫描 | 653 |
| 6/20 | math_platform Project Review | 597 |
| 6/20 | 高中数学题库现状 | 276 |
| 6/23 | 自动化测试现状汇总 | 906 |
| 6/24 | 讲义功能修改评估 | 410 |
| 6/24 | PDF 生成现状报告 | 111 |
| 6/24 | 解题模式恢复与完成逻辑分析 | 526 |
| 6/24 | Django Admin 数据恢复 | 515 |
| 6/24 | 教师改助教评估报告 | 671 |
| 6/24 | 自主刷题问题汇报 | 414 |
| 6/24 | Flutter 版本可行性计划 | 347 ← v2 种子 |
| 6/24 | 个性化组卷功能实施方案 | 578 |
| 6/26 | Flutter 客户端状态汇总 | 723 |
| 6/26 | 全面对比 Flutter App 和网页端 | 212 |
| 6/28 | LaTeX 公式渲染全面排查 | 220 |
| 7/2 | 读取 v2 设计规范 | 464 |
到 v2 的演进路径
v1 math_platform v2 zhangyuzhixue_app_v2
─────────────── ───────────────────────
Django templates Flutter App × 2
└─ 移动端体验差 ─────────→ 原生跨平台
└─ 网络依赖 ─────────────→ 离线优先 + 同步引擎
└─ 教师=Admin 后台 ─────→ 独立教师端 Flutter App
Django REST API Django REST API（复用/增强）
└─ 认证 ─────────────────→ 增加 JWT token 刷新
└─ 同步 ─────────────────→ 新增版本检查 + sync push
└─ 讲义 ─────────────────→ 拆为独立 DB
题库数据（798题） 题库数据（保留 + 增强）
└─ SQLite 单文件 ────────→ 三库分离（app/lectures/assets）
HTML 原型（14页+） Flutter UI（120+页面/组件）
└─ 设计资产完全复用 ─────→ 原型先行，代码后跟
| 无系统化测试 GitHub Actions CI
· 86 Flutter 测试文件
· 15 Django 测试文件
· 5 维度审计体系
v1 的完整 Git 日志见 06-附录A-Git完整日志.md。