编年史 · 第三篇 · 2026-07-03 ~ 2026-07-17（AI生成）
项目性质
从 Django 网页端到 Flutter 离线优先跨平台 App 的重构。学生端 + 教师端两个独立 Flutter 应用，共享 Django API 后端。
关键数字
| 指标 | 数值 |
|---|---|
| 时间段 | 7/3 ~ 7/17（15 天） |
| Git commits | 893（单人） |
| 源码库 | D:\Hermes\zhangyuzhixue_app_v2\（6.2 GB，含构建产物） |
| 源文件 | Dart 276 / Python 137 / HTML 76 / Markdown 43 / CSS 7 / JS 10 |
| 测试文件 | 86 Flutter（student）+ 1（teacher）+ 15 Django |
| Hermes 会话 | ~318 会话 / ~85K 消息 / ~59M input tokens |
| 总费用 | ¥554.80（含 v1，但 v2 占 ~70%+） |
时间轴
07/03 07/09 07/10 07/12 07/14 07/17
├── 设计期 ─┤├─ 编码冲刺 ─────────────────────────────┤├─ 收尾 ─┤
原型/架构 Phase 0-5 走查工具 修复密集期 发布准备
第一阶段：设计期（7/3 ~ 7/9）
7 天，~200 commits，全 Hermes 驱动
设计期的模式是：你描述需求 → Hermes 生成 HTML 原型 / 设计文档 → 你审查 → 迭代。没有写一行 Flutter/Django 代码。
| 日期 | 工作内容 | 关键产出 |
|---|---|---|
| 7/3 | 项目创建 + 设计总览 | Flutter 脚手架，加载设计规范文档 |
| 7/4 | UI 原型设计（28 页） | HTML 原型：底栏导航（作业/推荐/组卷/我的） |
| 7/4 | 积分/等级/成就系统设计 | 三种积分 + 等级 + 流水 + 成就初版 |
| 7/4 | 组卷/偏好/统计功能设计 | 智能组卷 + 自主选题 + 筛选面板 |
| 7/6 | 关于页/同步队列/个人信息编辑 | 系统栏入口 + 检查更新弹窗 |
| 7/7 | Repository 层规范 + 解题模式设计 | 13 个 Repository 文件 + 解法切换 |
| 7/8 | 讲义 + 解题页 + 本地数据库 | Drift schema + 存档机制 + 冷却机制 |
| 7/9 | PDF + 同步引擎 + 架构定稿 | 3 次 PDF 方案迭代，同步队列设计，7 层架构图 |
设计期要事
PDF 方案三次迭代（7/9）：
- Flutter 客户端渲染（
_ExamPdfService）— 被否 - 服务端 HTML → 浏览器打印 — 定稿
- 客户端只留入口 + 引导弹窗 — 最终形态
教师端决策（7/10）： 在"纯 Web"和"Flutter 独立 App"之间选择了混合方案：
- 教师使用 Flutter 学生端 App 的部分功能 + 轻量 Web 仪表盘
- 这个决策后来导致了大量代码复用问题（催生 shared 包）
数据架构定稿：
- 三库分离：
app.db（用户数据）/lectures.db（讲义）/assets.db（配图） - 同步引擎：登录全量拉取 + 增量 sync_queue 异步推送
- 方案 B：讲义客户端镜像存储 raw markdown，渲染时解析分隔符
第二阶段：编码高峰（7/10 ~ 7/11）
2 天，从 0 到可用 App，Hermes 峰值活跃期
7/10 — Phase 0 + Phase 1（服务端全量）
Hermes 会话：20 会话，7,911 消息，4.3M input tokens
| 子阶段 | 内容 | 说明 |
|---|---|---|
| Phase 0.1 | Django 脚手架 | 5 Apps + settings + urls + flake8 zero |
| Phase 0.2 | Flutter 脚手架 | flutter_app/ + Riverpod + analyze/test zero |
| Phase 0.3 | 着陆页 | privacy/terms + 微信二维码 |
| Phase 0.4 | CI | GitHub Actions（放弃 Gitee Go） |
| Phase 1.1 | 5 App models + admin | accounts / courses / interactions / qbank / system |
| Phase 1.2 | 题库数据迁移 | 6 步迁移 + 数据清洗 + 试卷排序 ID |
| Phase 1.3 | JWT 认证 API | 注册/登录/刷新 + pytest 测试 |
| Phase 1.4 | 同步 API | VersionCheck + SyncPush |
| Phase 1.5 | 用户 API + 讲义 API | getUserInfo / courses / chapters / content |
| Phase 1.6 | 构建脚本 | assets.db / lectures.db 构建工具（26 测试场景） |
| Phase 1.7 | PDF 视图 | 签名 Token + 试卷 HTML 渲染 |
| Phase 1.8 | Admin 系统工具 | 构建 / 邀请码 / 批量导入 |
7/11 — Phase 2 + Phase 3 + Phase T（全量编码）
🔥 峰值日： 60 会话，16,027 消息，9.5M input tokens
| 时间段 | 内容 |
|---|---|
| 凌晨~上午 | Phase 2 数据层（DAO/Repository/同步引擎/更新机制 + 88+57 测试） |
| 上午~下午 | Phase 3 Flutter UI（MainShell/登录/首页/解题/讲义/作业/组卷/推荐/统计/个人中心） |
| 下午~晚间 | Phase T 教师端 + 审计修复启动 |
| 晚间 | 第一轮审计修复（5 轮 Type A~E 并行审计） |
审计体系在这一天成雏形：
7/11 09:19 Type A — 服务端审计-1
7/11 09:27 Type C — Flutter UI 审计-1
7/11 09:47 Type B — Flutter 数据层审计-1
7/11 09:49 Type D — 教师端审计-1
7/11 09:49 Type E — 部署审计-1
7/11 09:52 新审计发现问题修复-A组（893 条消息 — 最长会话之一）
7/11 10:19 Type A — 服务端审计-2 ...
7/11 12:43 Type A/E — 审计-3 ...
7/11 13:58 真实问题修复-第一轮（835 条消息）
这个模式后来提炼为 fix-batch-workflow：审计→发现问题→分类→批量修复→验证→下一轮。
第三阶段：工具构建 + 走查（7/12 ~ 7/13）
7/12 — winnav + Visual E2E Audit 工具
这一天的核心主题是构建自动化走查工具。Hermes 花了大量会话调试 Windows 桌面自动化：
| 事件 | 说明 |
|---|---|
| winnav 工具封装 | 将 pyautogui + mss 截图封装为 OCR 定位+点击工具 |
| 视觉审计调试 | 测试 winnav 是否能定位 Flutter App 的 tab 栏、按钮等元素 |
| 走查流程设计 | 设计 visual-e2e-audit skill 的走查路径 |
| 首次走查模块 2 | 637 条消息，实际驱动 App 走查 |
共 25+ 次 winnav 测试会话，从简单的"找到 tab 栏"到完整的走查流程。
7/13 — UAT 走查密集期
三次走查（模块 2/3/5）+ skill 体系完善 + 首次完整用户测试：
| 事件 | 会话大小 | 说明 |
|---|---|---|
| 走查 skill 修订 | 601 条消息 | 完善 visual-e2e-audit skill |
| 三次走查模块 3 | 457 条消息 | 解题页面逐页走查 |
| 自动走查 | 490 条消息 | 半自动化走查尝试 |
| 手动 UAT | 901 条消息 | 最长会话之一，完整模拟学生使用 |
| competitive-audit | 387 条消息 | 竞品心态审计"我的"页面 |
第四阶段：修复密集期（7/14 ~ 7/15）
11 个横切探查 + 批量修复，覆盖全系统。
| 探查主题 | 会话大小 | 修复内容 |
|---|---|---|
| 首页问题 | 811 条 | 同步行/角标/队列错误 |
| 偏好问题 | 583 条 | 编辑链路断裂/全选覆盖/标签丢失 |
| 学习统计 | 632 条 | 热力图/统计卡片/图表数据 |
| 解题页面 | 587 条 | 选择题/填空题/解答题三题型全面排查 |
| 积分流水 | 608 条 | 同步问题/流水显示 |
| 选填解题 | 586 条 | 冷却/提交/结果显示 |
| 解题地图 | 391 条 | 存档切换/欢迎视图 |
| 大题解题 | 401 条 | 子题展开/步骤展示 |
| 同步系统 | 445 条 | 队列/版本检查/数据一致性 |
| 筛选项 | 611 条 | 空语义/全选/排序/折叠 |
| 推荐页面 | 518 条 | 双模式/推荐算法/卡片渲染 |
这些探查的模式是跨切探查（cross-cut investigation）：在一个主题上横切 UI 层 → 数据流 → 数据层 → 服务端 API → 边界情况，一次性发现全部问题。
7/15 — 性能优化 + 共享包 + 教师端 App
| 工作 | 说明 |
|---|---|
| 14 项性能优化 | SQL 聚合替代全表扫描 / N+1 批量查询 / executemany |
| 6 项第二轮性能 | 服务端 N+1 / 统计页并行 / profile 优化 |
| 4 项教师端性能 | 全表扫描 / 重复查询 / 幽灵方法 |
| N+1 修复 | preview_page 批量 getQuestionDetailsBatch（7N→4 次查询） |
| 共享包抽取 | 消除两端 17 对重复组件，1 个 commit（82495d2） |
| 教师端 App 排查 | 809 条消息，全面排查崩溃/白屏/数据加载问题 |
| UI 对齐修复 | 6 轮 UI 割裂修复（统一 Card/EdgeInsets/颜色常量） |
| app 身份信息 | 版本号/包名/图标/窗口标题 四平台统一 |
第五阶段：发布准备（7/16 ~ 7/17）
| 工作 | 说明 |
|---|---|
| 错误提示友好化 | 26 页面的 _error = e.toString() → 中文提示 |
| OperationLog | 运行日志 + 导出按钮 + API 拦截器 + 导航日志 |
| CI 修复 | Flutter analyze + Django flake8/pytest 全绿 |
| 代码同步 | 教师端和学生端 shared 包同步 |
| 版本号 | v1.0.0-alpha.2+1 |
| Android 发布 | 权限修复 / 包名修正 / 版本号对齐 |
| iOS 发布 | 内测 TestFlight 准备 |
| 着陆页 | 下载链接 / 网盘备用 / 响应式修复 |
| 安装包 | Windows .iss Inno Setup 构建配置 |
7/16 冲刺细节
从 session 标题可以看到当日工作流：
07:13 教师端和学生端代码同步 422 msgs
07:23 flutter analyze 检查 32 msgs ← 快速检查
07:44 版本号更新问题 140 msgs
08:08 错误提示不完善修复 563 msgs
08:29 android 联网问题修复 299 msgs
08:55 项目了解 + 发布检查 71 msgs
08:58 返回弹窗禁止返回问题 232 msgs
09:11 android 同步失败问题 317 msgs
09:14 偏好编辑覆盖问题 408 msgs
09:19 重新作答修复 122 msgs
09:36 组卷页面退出问题 59 msgs
09:38 日志格式问题 377 msgs
09:52 个人数据同步问题修复 192 msgs
10:24 填空题竞态条件修复 61 msgs
15 个独立会话，几乎不间断，当天共 10,371 条消息。
Phase 对照总览
| Phase | 名称 | 日期 | Commits | 说明 |
|---|---|---|---|---|
| — | 设计期 | 7/3~7/9 | ~200 | 原型 + 文档，无代码 |
| 0.1~0.4 | 脚手架 | 7/10 | ~30 | Django + Flutter + 着陆页 + CI |
| 1.1~1.8 | 服务端 | 7/10 | ~60 | 6 App 全量 API |
| 2.1~2.5 | 数据层 | 7/10~7/11 | ~100 | DAO → Repository → 同步引擎 |
| 3a~3h | Flutter UI | 7/11 | ~150 | 8 个子步骤，全量 UI |
| T.1~T.6 | 教师端 | 7/11 | ~30 | Web 框架 + 登录 + 功能页 |
| 4.1~4.5 | 辅助系统 | 7/11~7/14 | ~100 | 积分/成就/弹窗/同步队列/引导 |
| 5 | 集成测试 | 7/13~7/15 | 穿插 | 走查工具 + E2E |
| 6 | 上线准备 | 7/16~7/17 | ~200 | 发布/修复/性能/审计 |
关键设计文档
v2 的设计文档体系分 8 大类，位于 docs/：
| 编号 | 分类 | 内容 |
|---|---|---|
| 00 | 整体情况 | 落地计划、验收清单、变更记录 |
| 01 | 架构 | 7 层架构图、技术规范 |
| 02 | 数据 | 数据库结构、数据流 |
| 03 | 服务端 | API 设计、PDF 方案、构建脚本 |
| 04 | UI | 76 页 HTML 原型 + solve-pages |
| 05 | Flutter | 组件规范、Repository 层、同步引擎 |
| 06 | 教师端 | Web 原型、功能边界 |
| 07 | 工作流 | 着陆页、工作流原则 |
| 08 | 监控 | Sentry、OperationLog |
当前状态（7/17）
- 学生端： v1.0.0-alpha.2+1，Android / iOS / Windows / macOS 全平台
- 教师端： v1.0.0-alpha.2+1，Windows 优先
- 服务端： 已部署至 ECS（zhangyuzhixue.top），Cloudflare Tunnel
- 着陆页： 已上线，含下载链接
- CI： GitHub Actions 全绿
- 已知问题： 若干未修复 bug（标记在 session 中，待 fix-batch-workflow）
遗留的工作
- 教师端 Android/iOS 打包
- App Store 上架
- 用户数据迁移（v1→v2）
- Sentry 全量观测
- 更多 E2E 自动化测试
- 部分设计文档待落地