d1a07229e2
新增 wiki/ 知识库 (遵循 HMS wiki-methodology.md 5 节结构): - index.md (84 行) — 症状导航 13 条 + 模块索引 + 系统数据流 - architecture.md (120 行) — 基座剥离 7 耦合点 + Feature Flag + PIPL 合规 - handwriting-engine.md (124 行) — 双层 Canvas + O(1) 点缓冲 + 光栅化缓存 - data-layer.md (127 行) — Isar + SyncEngine 离线同步 + 踩坑记录 - frontend.md (118 行) — 16 模块地图 + BLoC 注入链 + 设计系统 - erp-diary.md (101 行) — 15 Entity / 10 Service / 8 Handler + API 端点 新增 docs/: - tech-debt-board.md (110 行) — 10 条技术债 + 偿还优先级排名 其他更新: - .gitignore: 添加 .understand-anything/ (待初始化) - CLAUDE.md §9: 添加 wiki 参考文档链接
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
---
|
||
title: Flutter 前端
|
||
updated: 2026-06-01
|
||
status: active
|
||
tags: [flutter, bloc, design-system, responsive]
|
||
---
|
||
|
||
# Flutter 前端
|
||
|
||
> 从 [[index]] 导航。关联: [[handwriting-engine]] [[data-layer]]
|
||
|
||
## 1. 设计决策
|
||
|
||
### Q: 为什么 BLoC 不是 Provider/Riverpod？
|
||
|
||
编辑器（strokes + elements + undo/redo + autoSave）、同步引擎（pending queue + network status）、日历（date range + mood filter）等复杂交互需要 Event/State 显式建模。BLoC 的单向数据流比 Provider 的 notifyListeners() 更可控。
|
||
|
||
### Q: 为什么 go_router？
|
||
|
||
声明式路由 + 深链接支持 + 路由守卫（auth guard 重定向未登录用户）。比 Navigator 2.0 更简洁。
|
||
|
||
### Q: 设计系统 7 色双模主题？
|
||
|
||
暖记定位"温暖治愈"，浅色模式奶油白(#FFF8F0) + 珊瑚色(#E07A5F) + 鼠尾草绿(#81B29A)；深色模式自动映射为暖色调暗色。面向小学生，所有颜色避免冷硬感。
|
||
|
||
### Q: 为什么手写模型不用 freezed？
|
||
|
||
Stroke/StrokePoint 是热路径高频创建对象，freezed 生成的代码有额外开销。手写实现 copyWith + toJson/fromJson 更轻量。
|
||
|
||
## 2. 关键文件 + 数据流
|
||
|
||
### 16 个功能模块
|
||
|
||
| 模块 | BLoC | 职责 |
|
||
|------|------|------|
|
||
| editor | EditorBloc | 手写 + 元素 + 撤销重做 + 自动保存 |
|
||
| auth | AuthBloc | 登录/注册/角色选择/班级码加入 |
|
||
| home | HomeBloc | 首页日记列表 + 搜索 |
|
||
| calendar | CalendarBloc | 日历视图 + 日期过滤 |
|
||
| mood | MoodBloc | 心情统计 + 趋势图 |
|
||
| class_ | ClassBloc | 班级管理 + 成员列表 |
|
||
| achievement | AchievementBloc | 成就徽章系统 |
|
||
| stickers | StickerBloc | 贴纸库浏览 + 选择 |
|
||
| templates | TemplateBloc | 模板画廊 |
|
||
| profile | SettingsBloc | 主题切换 + 个人设置 |
|
||
| search | — | 日记搜索 (Isar FTS 待实现) |
|
||
| teacher | — | 老师主题发布 + 批改 |
|
||
| parent | — | 家长监护 + 数据管理 |
|
||
| settings | — | 设置页面 UI |
|
||
|
||
### 注入链 (app.dart)
|
||
|
||
```
|
||
MultiRepositoryProvider
|
||
├─ ApiClient
|
||
├─ AuthRepository
|
||
├─ JournalRepository (= IsarJournalRepository, 离线优先)
|
||
├─ RemoteJournalRepository (供 SyncEngine)
|
||
├─ SyncEngine
|
||
├─ ClassRepository
|
||
└─ SettingsBloc (ChangeNotifier)
|
||
└─ BlocProvider<AuthBloc>
|
||
└─ MaterialApp.router (ListenableBuilder 监听主题)
|
||
```
|
||
|
||
### 路由表
|
||
|
||
`app_router.dart` (269 行) 定义完整路由：
|
||
- `/` → 首页（auth guard 重定向）
|
||
- `/login`, `/role-selection`, `/class-code-join`
|
||
- `/editor/:id?` → 编辑器
|
||
- `/calendar`, `/mood`, `/class`, `/achievements`
|
||
- `/stickers`, `/templates`, `/search`
|
||
- `/teacher/*`, `/parent/*`
|
||
- `/settings`, `/profile`
|
||
|
||
## 3. 代码逻辑
|
||
|
||
### 不变量
|
||
|
||
⚡ **响应式断点** — 手机 <600px 底部 TabBar 单列 / 平板 600-1024px 侧边双栏 / 桌面 >1024px 三栏
|
||
|
||
⚡ **触摸目标 ≥ 44px** — 面向小学生，所有可交互元素不小于 44px
|
||
|
||
⚡ **设计 Token 统一管理** — `core/constants/design_tokens.dart` 定义间距/圆角/阴影
|
||
|
||
⚡ **SettingsBloc 用 ChangeNotifier** — 不用 BLoC 因为设置是全局状态，ChangeNotifier + ListenableBuilder 更轻量
|
||
|
||
### 主题系统
|
||
|
||
```
|
||
AppTheme.light() / AppTheme.dark()
|
||
├─ 7 色 × 2 模式 (bg/accent/secondary/tertiary/fg/surface/rose)
|
||
├─ 3 套字体 (Noto Sans SC / Caveat / JetBrains Mono)
|
||
├─ 4 级圆角 (10/16/22/28/pill)
|
||
└─ 动画曲线 cubic-bezier(0.34, 1.56, 0.64, 1) — 弹性过冲
|
||
```
|
||
|
||
## 4. 活跃问题 + 陷阱
|
||
|
||
| 问题 | 级别 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| 编辑器不加载已有数据 | HIGH | 待做 | journalId 非空时需从 Isar 读取 |
|
||
| 搜索功能空壳 | MEDIUM | 待做 | Isar FTS 未实现 |
|
||
| 深色模式细节 | LOW | 持续 | 部分组件深色适配需检查 |
|
||
|
||
### 历史教训
|
||
|
||
- F11 深色模式修复需要 bloat bloc 测试套件同步更新 (05317d5)
|
||
- NuanjiApp 是 StatelessWidget，build() 可被调用多次 → 全局依赖应在 build() 中创建单例
|
||
|
||
## 5. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|------|------|
|
||
| 2026-06-01 | IsarJournalRepository 注入为主 JournalRepository (2481c8f) |
|
||
| 2026-06-01 | 设置页 UI + Mood/成就/贴纸 BLoC (8331db6) |
|
||
| 2026-06-01 | 初始创建 — 16 模块地图、注入链、设计系统 |
|