编年史 · 第一篇 · 速览仪表板（AI生成）
关键数字#
| 指标 |
数值 |
备注 |
| 总耗时 |
28 天 |
2026-06-19 ~ 2026-07-17 |
| 产品版本迭代 |
2 代 |
v1 网页端 → v2 Flutter 跨平台 |
| Git commits |
1,023 |
v1: 130 + v2: 893 |
| 平台覆盖 |
4 端 |
Android / iOS / Windows / macOS |
| 客户端数量 |
2 个 |
学生端 Flutter App + 教师端 Flutter App |
| 共享代码 |
1 个 |
packages/shared 消除 17 对重复组件 |
| 服务端 Django App |
6 个 |
accounts / courses / interactions / qbank / system / math_platform |
Hermes Agent 使用量#
| 指标 |
口径：state.db（增量） |
口径：DeepSeek 后台（累积计费） |
| 会话数 |
600 |
— |
| 消息数 |
~115,000 |
— |
| 总 Tokens |
~104M |
14,081,786,297（14.08B） |
| 其中 Input |
~76M |
— |
| 其中 Output |
~27.5M |
— |
| Reasoning |
~5.9M |
— |
| API 请求数 |
50,845 |
80,968 |
| Tool Calls |
62,338 |
— |
| 总费用 |
— |
¥554.80 |
| 使用模型 |
deepseek-v4-flash（599/600 会话） |
— |
为何两个口径差 136 倍？
state.db 只记每次 API 响应的新增 tokens；DeepSeek 按每次请求的完整上下文窗口计费（含之前所有轮次累积的历史）。14.08B / 80,968 ≈ 174K tokens/请求，即平均每次都携带了约 174K 的上下文。
产品架构#
┌────────────────────────────────────────┐
│ 学生端 Flutter App │
│ (Android / iOS / Windows / macOS) │
│ SQLite (Drift) · Riverpod · GoRouter │
└──────────────┬─────────────────────────┘
│ HTTP API (JSON)
▼
┌────────────────────────────────────────┐
│ 教师端 Flutter App │
│ (Android / iOS / Windows / macOS) │
│ 复用 student 数据层 + 共享包 │
└──────────────┬─────────────────────────┘
│ HTTP API (JSON)
▼
┌────────────────────────────────────────┐
│ Django API 服务端 │
│ 6 Apps · JWT Auth · SQLite · Sentry │
│ nginx + gunicorn · Cloudflare Tunnel │
└──────────────┬─────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ 着陆页 / 教师 Web 端 │
│ 纯静态 HTML+CSS+JS │
└────────────────────────────────────────┘
数据流#
登录 → 全量拉取 user.db.gz（gzip 压缩 SQLite）
运行 → 本地 SQLite（优先）→ 写入 sync_queue → 异步推送
更新 → 版本号检查 → .db 整库替换（讲义/题库/assets 分别管理）
v1 vs v2 对比#
| 维度 |
v1 — math_platform |
v2 — zhangyuzhixue_app_v2 |
| 时间段 |
6/19 ~ 7/2（14天） |
7/3 ~ 7/17（15天） |
| 客户端 |
Django 模板网页 |
Flutter 原生 App × 2 |
| 技术栈 |
Django + REST + HTML/JS |
Flutter + Drift + Riverpod + Django API |
| 数据架构 |
服务端渲染，在线依赖 |
离线优先（SQLite + 同步引擎） |
| Git 提交 |
130 |
893 |
| 源文件 |
~137 .py + ~76 .html |
276 .dart + 137 .py + 76 .html |
| 测试 |
少量 pytest |
86 Flutter + 15 Django 测试文件 |
| 质量保障 |
无系统化审计 |
5 维度审计 + fix-batch-workflow |
| AI 会话 |
~30K 消息 / 17M tokens |
~85K 消息 / 59M tokens |
| 版本号 |
— |
v1.0.0-alpha.2+1 |
时间轴#
v1 设计/开发期 过渡 v2 设计期 v2 编码冲刺
├───────────────────────┤├─────┤├──────────┤├────────────────────────┤
06/19 07/02 07/03 07/09 07/10 07/17
↑ ↑ ↑
Flutter 可行性论证 设计定稿 Phase 0 开始编码
| 区间 |
核心事件 |
| 6/19 ~ 6/27 |
v1 题库建设、PDF 生成、解题逻辑修复、内容校对 |
| 6/28 ~ 7/1 |
v1 收尾 · Flutter 可行性论证 · v2 设计启动 |
| 7/2 |
初始项目骨架创建 · 设计文档全面编写 |
| 7/3 ~ 7/9 |
v2 设计阶段：HTML 原型 / 架构/API/数据库设计（~200 commits） |
| 7/10 |
Phase 0-1：脚手架 + CI + 服务端全量 API |
| 7/11 |
🔥 峰值日：Phase 2-3（数据层+UI全量）+ Phase T（教师端）· 60 会话 |
| 7/12 |
走查工具构建（winnav）+ 首轮 Visual E2E Audit |
| 7/13 |
走查密集期 + Audit 系统完善 + 首次完整 UAT |
| 7/14 |
修复密集期：积分/同步/筛选/推荐/解题/等级/成就 |
| 7/15 |
冲刺修复 + 教师端 App + 性能优化 + 共享包抽取 |
| 7/16 |
发布准备：版本号/图标/着陆页/CI/Android/iOS 打包 |
| 7/17 |
收尾：最后批次修复 |
产物清单#
| 类型 |
数量 |
路径 |
| 设计文档 |
43 .md |
docs/（8 大分类 + _archive） |
| HTML 原型 |
76 页 |
docs/04-UI/html/ |
| Hermes Skill |
30+ |
项目专属 3 + 通用 30+ |
| 着陆页 |
1 套 |
landing/ |
| 安装包签名 |
1 套 |
.iss（Inno Setup） |
| 构建脚本 |
6 个 |
scripts/（版本号/图标/数据库构建） |
| 数据库备份 |
多份 |
docs/_archive/db_backup_* |
| 字体 |
14 字重 |
Noto Serif CJK SC + Noto Serif SC |
关键决策回顾#
| 决策 |
路径 A（被否） |
路径 B（执行） |
代价 |
| PDF 方案 |
Flutter 端渲染 |
服务端 HTML → 浏览器打印 |
3 次迭代，数天开销 |
| 教师端架构 |
纯 Web 端 |
Flutter 独立 App + Web 辅助 |
从复制改到共享包，多次重构 |
| 代码复用 |
复制后改 |
抽取 shared 包 |
7/15 单次 commit 消除 17 对重复 |
| 数据同步 |
每次实时拉取 |
登录全量拉取 + 增量 sync queue |
— |
| 测试策略 |
集中在逻辑层 |
分层测试（算法→DAO→Repository→Widget→E2E） |
— |
相关链接#
- v1 源码库：
D:\Hermes\math_platform\
- v1 脚本工坊：
D:\Hermes\platform_script\
- v2 源码库：
D:\Hermes\zhangyuzhixue_app_v2\
- 备份：
D:\Hermes\backups\
- 字体：
D:\Hermes\字体\
- 在线访问： zhangyuzhixue.top