docs: 更新 Wiki 文档 — 数据层/前端/后端/健康/索引同步至最新

2026-06-07 10:44:26 +08:00
parent 41ef28f20b
commit ed8252d7c8
5 changed files with 87 additions and 36 deletions
--- a/wiki/data-layer.md
+++ b/wiki/data-layer.md
@@ -1,6 +1,6 @@
 ---
 title: 数据层
-updated: 2026-06-01
+updated: 2026-06-07
 status: active
 tags: [isar, offline-first, sync, repository-pattern]
 ---
@@ -112,7 +112,7 @@ syncEngine.restorePendingQueue();  // fire-and-forget 恢复队列
 | authorId 硬编码 'local' | HIGH | 待修 | EditorPage 未接入 AuthBloc 获取真实用户 |
 | SyncEngine 仅 WiFi | MEDIUM | Phase 2 | 蜂窝数据同步未实现 |
 | 版本冲突静默覆盖 | MEDIUM | Phase 2 | "本地优先"策略，需 UI 手动解决 |
-| 编辑器未加载已有数据 | MEDIUM | 待做 | journalId 非空时未从 Isar 读取 |
+| ~~编辑器未加载已有数据~~ | ~~MEDIUM~~ | ✅ 已修复 | _loadExistingJournal 读取日记 + 元素 + 笔画 |

 ### 历史教训

@@ -123,5 +123,6 @@ syncEngine.restorePendingQueue();  // fire-and-forget 恢复队列

 | 日期 | 变更 |
 |------|------|
+| 2026-06-07 | 编辑器加载已有数据已修复、打开已有日记默认查看模式 |
 | 2026-06-01 | Isar 集成完成：3 Collection + Repository + SyncEngine 持久化 (2481c8f) |
 | 2026-06-01 | 初始创建 — 数据层架构、Isar 踩坑记录 |
--- a/wiki/erp-diary.md
+++ b/wiki/erp-diary.md
@@ -1,6 +1,6 @@
 ---
 title: erp-diary 后端模块
-updated: 2026-06-01
+updated: 2026-06-07
 status: active
 tags: [rust, axum, seaorm, diary, api]
 ---
@@ -29,23 +29,23 @@ tags: [rust, axum, seaorm, diary, api]

 ```
 crates/erp-diary/src/
-├── lib.rs          (206 行) — DiaryModule 实现 + Feature Flag 注册
-├── dto.rs          (569 行) — 请求/响应 DTO + Validate 注解
+├── lib.rs          (280 行) — DiaryModule 实现 + Feature Flag 注册
+├── dto.rs          (640 行) — 请求/响应 DTO + Validate 注解
 ├── error.rs        (193 行) — DiaryError 15 种变体 → HTTP 状态码
 ├── event.rs        (61 行)  — 事件定义 (diary.created 等)
 ├── state.rs        (13 行)  — DiaryState (DiaryModule 专用状态)
 ├── entity/         (15 文件) — SeaORM Entity
-├── service/        (10 文件) — 业务逻辑
-└── handler/        (8 文件)  — HTTP Handler + utoipa 注解
+├── service/        (12 文件) — 业务逻辑
+└── handler/        (10 文件) — HTTP Handler + utoipa 注解
 ```

 ### Entity 清单 (15 个)

 achievement, class_member, comment, handwriting_stroke, journal_element, journal_entry, parent_child_binding, school_class, sticker, sticker_pack, teacher_profile, template, topic_assignment, user_achievement, user_settings

-### Service 清单 (10 个)
+### Service 清单 (12 个)

-journal, class, comment, content_safety, achievement, mood_stats, notification, sticker, sync, topic
+journal, class, comment, content_safety, achievement, mood_stats, notification, sticker, sync, topic, **parent**, **discover**

 ### API 端点

@@ -60,6 +60,8 @@ journal, class, comment, content_safety, achievement, mood_stats, notification,
 | `/api/v1/diary/stickers` | sticker_handler | 贴纸管理 |
 | `/api/v1/diary/stats` | stats_handler | 心情/写作统计 |
 | `/api/v1/diary/sync` | sync_handler | 增量同步 API |
+| `/api/v1/diary/discover` | discover_handler | 发现页聚合（每日推荐/热门话题/精选模板/达人日记） |
+| `/api/v1/diary/parent` | parent_handler | 家长绑定 + 数据管理 |

 ### 集成契约

@@ -95,6 +97,7 @@ journal, class, comment, content_safety, achievement, mood_stats, notification,
 | 文件上传未实现 | MEDIUM | 待做 | 照片/贴纸文件上传参考健康模块 |
 | 代码分布 | INFO | 参考 | service 层 51.7%、handler 20.1%、entity 15.6%、dto 11.1% |
 | 班级码硬编码 | LOW | 待修 | 前端 teacher 模块班级码 'a1b2c3' 未接入后端 |
+| 发现页硬编码 | — | ✅ 已修复 | DiscoverBloc + GET /diary/discover 全链路打通 |

 ### 代码量参考

@@ -111,5 +114,6 @@ journal, class, comment, content_safety, achievement, mood_stats, notification,

 | 日期 | 变更 |
 |------|------|
+| 2026-06-07 | 新增 discover_service + discover_handler (GET /diary/discover)、parent_handler 补充文档 |
 | 2026-06-01 | 补充代码量分布、班级码硬编码问题 |
 | 2026-06-01 | 初始创建 — Entity/Service/Handler 清单、API 端点、集成契约 |
--- a/wiki/frontend.md
+++ b/wiki/frontend.md
@@ -1,6 +1,6 @@
 ---
 title: Flutter 前端
-updated: 2026-06-01
+updated: 2026-06-07
 status: active
 tags: [flutter, bloc, design-system, responsive]
 ---
@@ -43,9 +43,10 @@ Stroke/StrokePoint 是热路径高频创建对象，freezed 生成的代码有
 | stickers | StickerBloc | 贴纸库浏览 + 选择 |
 | templates | TemplateBloc | 模板画廊 |
 | profile | SettingsBloc | 主题切换 + 个人设置 |
-| search | — | 日记搜索 (Isar FTS 待实现) |
+| search | SearchBloc | 日记搜索（按心情/标签/关键词） |
 | teacher | — | 老师主题发布 + 批改 |
-| parent | — | 家长监护 + 数据管理 |
+| parent | ParentBloc | 家长监护 + 数据管理 |
+| discover | DiscoverBloc | 发现页（每日推荐/热门话题/精选模板/达人日记） |
 | settings | — | 设置页面 UI |

 ### 注入链 (app.dart)
@@ -100,10 +101,12 @@ AppTheme.light() / AppTheme.dark()

 | 问题 | 级别 | 状态 | 说明 |
 |------|------|------|------|
-| 编辑器不加载已有数据 | HIGH | 待做 | journalId 非空时需从 Isar 读取 |
-| SSE 端口不一致 | HIGH | 待修 | SSE 用 8080，API 用 3000，推送必然失败 |
+| ~~编辑器不加载已有数据~~ | ~~HIGH~~ | ✅ 已修复 | _loadExistingJournal 从 Isar 读取日记 + 元素 + 笔画 |
+| ~~SSE 端口不一致~~ | ~~HIGH~~ | ✅ 已修复 | AppConfig 统一管理 apiBaseUrl/sseBaseUrl，均指向 3000 |
+| ~~编辑器打开即弹出画笔~~ | ~~HIGH~~ | ✅ 已修复 | 打开已有日记默认查看模式，点"编辑"才进入编辑模式 |
 | API base URL 硬编码 | HIGH | 待修 | localhost:3000 硬编码，生产环境需配置化 |
-| 前端测试为零 | HIGH | 待做 | 70 个 Dart 文件无任何测试覆盖 |
+| 多处硬编码数据未对接 API | HIGH | 部分修复 | 见下方「硬编码数据清单」 |
+| 前端测试覆盖不足 | MEDIUM | 持续 | 15 个测试文件 203 个用例，auth_bloc 有 1 个失败待修 |
 | 状态管理不统一 | MEDIUM | 待规划 | 5 模块用 BLoC，5 模块用 ChangeNotifier |
 | freezed 声明未使用 | MEDIUM | 待清理 | pubspec 声明了但全部手写不可变类 |
 | SyncEngine 缺少网络监听 | MEDIUM | 待做 | 只有 trySync() 方法，无自动触发 |
@@ -112,6 +115,44 @@ AppTheme.light() / AppTheme.dark()
 | core/utils/ 空目录 | LOW | 待填充 | 缺少日期格式化、颜色解析等通用工具 |
 | 深色模式细节 | LOW | 持续 | 部分组件深色适配需检查 |

+### 硬编码数据清单
+
+> 2026-06-07 全面排查结果。标记 ✅ 已修复 / ❌ 待修复。
+
+**HIGH — 已有 API，应直接替换：**
+
+| 页面 | 文件 | 硬编码内容 | 后端 API | 状态 |
+|------|------|-----------|----------|------|
+| 首页 | home_page.dart | 用户名 `'小暖'` | AuthBloc.user | ❌ |
+| 个人 | profile_page.dart | 头像 emoji `'😊'` | AuthBloc.user | ❌ |
+| 个人 | profile_page.dart | 6 个固定成就徽章 | AchievementBloc | ❌ |
+| 搜索 | search_page.dart | 4 个假模板名称 | TemplateBloc | ❌ |
+| 贴纸 | sticker_library_page.dart | 精选贴纸包"治愈小动物" | StickerBloc | ❌ |
+| 教师 | teacher_page.dart | 班级码 `'a1b2c3'` | ClassBloc | ❌ |
+| 班级 | class_page.dart | 头像首字固定 `'同'` | JournalEntry.authorId | ❌ |
+| 发现 | discover_page.dart | 全部 4 板块假数据 | GET /diary/discover | ✅ |
+
+**MEDIUM — 需要 API 或可延后：**
+
+| 页面 | 文件 | 硬编码内容 | 备注 |
+|------|------|-----------|------|
+| 搜索 | search_page.dart | 热门搜索 8 个关键词 | 需新增后端 API |
+| 编辑器 | sticker_picker_sheet.dart | 60 个内置 emoji 贴纸 | Phase 1 占位，贴纸包 API 已有 |
+| 编辑器 | tag_panel.dart | 10 个推荐标签 | 可从用户历史标签推导 |
+| 贴纸 | sticker_library_page.dart | 8 个固定分类名 | StickerBloc 已有分类数据 |
+| 模板 | template_gallery_page.dart | 每张卡片固定"学生专属"/"简约"标签 | 模板 API 已有 |
+| 个人 | profile_page.dart | 贴纸数 `'--'` | 需新增统计 API |
+
+**LOW — 可接受的 UI 设计常量：**
+
+| 页面 | 内容 | 说明 |
+|------|------|------|
+| 编辑器 | 画笔/文本颜色面板 | 设计工具调色板 |
+| 编辑器 | 字号选项 [小/中/大] | 编辑器选项 |
+| 首页/日历 | 心情/天气 emoji 映射 | enum → UI 展示映射 |
+| 引导页 | 3 步引导内容 | 静态引导文案 |
+| 班级 | 快捷评语模板 7 条 | 内置教学工具 |
+
 ### 历史教训

 - F11 深色模式修复需要 bloat bloc 测试套件同步更新 (05317d5)
@@ -123,6 +164,10 @@ AppTheme.light() / AppTheme.dark()

 | 日期 | 变更 |
 |------|------|
+| 2026-06-07 | 发现页全链路打通：DiscoverBloc + GET /diary/discover，替换全部硬编码 |
+| 2026-06-07 | 全面排查硬编码数据，新增「硬编码数据清单」章节 |
+| 2026-06-07 | 编辑器新增查看模式（打开已有日记默认只读）、元素图层调整（置顶/置底）|
+| 2026-06-07 | 日历页面修复：初始加载自动填充 selectedDayJournals |
 | 2026-06-01 | 补充状态管理不统一、SSE 端口问题、测试缺失等新发现 |
 | 2026-06-01 | IsarJournalRepository 注入为主 JournalRepository (2481c8f) |
 | 2026-06-01 | 设置页 UI + Mood/成就/贴纸 BLoC (8331db6) |
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -1,6 +1,6 @@
 ---
 title: 暖记知识库首页
-updated: 2026-06-02
+updated: 2026-06-07
 status: active
 ---

@@ -10,21 +10,21 @@ status: active

 ## 关键数字

-> 最后更新: 2026-06-02 | 基线: main (8111471)
+> 最后更新: 2026-06-07 | 基线: main (4cb91f3)

 | 指标 | 值 |
 |------|-----|
 | Rust crate | 8 个（6 基座 + 1 入口 + erp-diary） |
-| Rust 总代码 | ~51,500 行 |
-| erp-diary 新增 | 5,108 行（41 个文件） |
-| Dart 文件 | 74 个（~19,500 行） |
+| Rust 总代码 | ~52,000 行 |
+| erp-diary 新增 | ~5,600 行（45 个文件） |
+| Dart 文件 | 112 个（~27,000 行） |
 | 管理端前端 (React) | ~317 个 TypeScript 文件 |
 | SeaORM Entity | 15 个（erp-diary） + 50+（基座） |
 | 数据库迁移 | 58 个（42 基座 + 15 diary + 1 role seed） |
-| 后端测试 | 77 个通过 ✅ |
-| 前端 BLoC 测试 | 84 个通过 ✅ |
+| 后端测试 | 88 个通过 ✅ |
+| 前端测试 | 15 个文件、203 个用例通过 ✅（1 个失败待修） |
 | flutter analyze | 0 error ✅ |
-| Git 提交 | 22 次 |
+| Git 提交 | 107 次 |

 ## 三端架构

--- a/wiki/project-health.md
+++ b/wiki/project-health.md
@@ -1,13 +1,13 @@
 ---
 title: 项目健康度评估
-updated: 2026-06-01
+updated: 2026-06-07
 status: active
 tags: [health, tech-debt, risk, improvement]
 ---

 # 项目健康度评估

-> 从 [[index]] 导航。本文档基于 2026-06-01 全量代码分析生成。
+> 从 [[index]] 导航。本文档基于 2026-06-01 全量代码分析生成，2026-06-07 更新。

 ## 总体评分

@@ -15,7 +15,7 @@ tags: [health, tech-debt, risk, improvement]
 |------|------|------|
 | 架构设计 | ⭐⭐⭐⭐⭐ | 模块化 ErpModule trait、分层清晰、基座复用 |
 | 代码质量 | ⭐⭐⭐⭐ | Rust 错误处理规范、Flutter 注释质量高、分层一致 |
-| 测试覆盖 | ⭐⭐ | 后端 ~50 测试尚可、前端 **0 测试** 是最大短板 |
+| 测试覆盖 | ⭐⭐⭐ | 后端 ~77 测试通过、前端 15 个测试文件 203 个用例（仍有 1 个失败待修）|
 | 安全合规 | ⭐⭐⭐⭐⭐ | PIPL 合规框架完整、PII 加密、RLS 多租户隔离 |
 | 文档维护 | ⭐⭐⭐⭐⭐ | wiki 6 页 + 技术债看板 + CLAUDE.md，同步度高 |
 | DevOps | ⭐⭐ | Docker 配置完善但未验证、CI/CD 缺失、无自动化 |
@@ -30,7 +30,7 @@ tags: [health, tech-debt, risk, improvement]
 | TD-1 | authorId 硬编码 'local' | P0 | 0.5 天 |
 | TD-3 | Docker 部署未验证 | P0 | 0.5 天 |
 | TD-7 | Settings 持久化未实现 | P1 | 0.5 天 |
-| TD-8 | 编辑器不加载已有日记 | P1 | 1 天 |
+| ~~TD-8~~ | ~~编辑器不加载已有日记~~ | ~~P1~~ ✅ | ~~1 天~~ |
 | TD-4 | toImage() 同步阻塞主线程 | P1 | 1 天 |
 | TD-2 | CI/CD 未建立 | P2 | 1 天 |
 | TD-5 | 前端测试为零 | P2 | 3 天 |
@@ -42,8 +42,8 @@ tags: [health, tech-debt, risk, improvement]

 | 编号 | 债务 | 优先级 | 预估 | 位置 |
 |------|------|--------|------|------|
-| NEW-1 | 前端测试缺失（TD-5 补充：0 回归保护） | **Critical** | 3 天 | `app/test/` |
-| NEW-2 | SSE 端口不一致 (8080 vs 3000) | **Critical** | 0.5 天 | `sse_notification_service.dart:42` |
+| ~~NEW-1~~ | ~~前端测试缺失（0 回归保护）~~ | ~~Critical~~ ✅ | ~~3 天~~ | 15 个测试文件 203 用例，auth_bloc 1 个失败待修 |
+| ~~NEW-2~~ | ~~SSE 端口不一致 (8080 vs 3000)~~ | ~~Critical~~ ✅ | ~~0.5 天~~ | AppConfig 统一管理，均指向 3000 |
 | NEW-3 | Dockerfile 不存在（生产部署引用） | **High** | 1 天 | `docker-compose.production.yml` |
 | NEW-4 | API base URL 硬编码 localhost | **High** | 0.5 天 | `api_client.dart:29` |
 | NEW-5 | 班级码后端验证未实现 | **High** | 1 天 | `auth_bloc.dart:141` TODO |
@@ -57,12 +57,12 @@ tags: [health, tech-debt, risk, improvement]
 | 模块 | 完成度 | 关键缺失 |
 |------|--------|---------|
 | 手写引擎 | **95%** | toImage 异步化 |
-| 编辑器 | **95%** | 文字输入/图片上传为占位 |
+| 编辑器 | **98%** | 查看模式 + 图层调整已实现，文字输入/图片上传为占位 |
 | 认证 | **85%** | 班级码后端验证 TODO |
 | 首页 | **90%** | — |
 | 设计系统 | **90%** | `core/utils/` 空目录 |
 | 设置 | **85%** | 持久化未实现 |
-| 日历 | **85%** | 周视图/时间线未实现 |
+| 日历 | **90%** | 初始加载已修复，周视图/时间线未实现 |
 | 数据层 | **85%** | SyncEngine 缺少网络监听 |
 | 班级 | **80%** | — |
 | 心情统计 | **80%** | — |
@@ -91,10 +91,10 @@ erp-core ← erp-auth ← erp-server

 | 风险 | 概率 | 影响 | 缓解 |
 |------|------|------|------|
-| 前端无测试导致回归 | 高 | 高 | TD-5: 建立核心 BLoC/Repository 单元测试 |
+| 前端测试覆盖不足 | 中 | 中 | 15 个测试文件已建立，auth_bloc 1 个失败待修 |
 | Feature Flag 未实现限制扩展 | 中 | 中 | NEW-8: 补充 Cargo features 配置 |
 | Docker 生产部署无法构建 | 高 | 高 | NEW-3: 创建 Dockerfile + 验证 |
-| SSE 端口不匹配致推送失败 | 确定 | 中 | NEW-2: 统一为 3000 端口 |
+| ~~SSE 端口不匹配致推送失败~~ | ~~确定~~ ✅ | ~~中~~ | AppConfig 已统一为 3000 |
 | 手写 toImage 卡 UI | 中 | 中 | TD-4: compute() isolate 异步光栅化 |
 | 大文件超 800 行限制 | 中 | 低 | erp-plugin manifest.rs(1809) + data_service.rs(1907) 需拆分 |

@@ -102,7 +102,7 @@ erp-core ← erp-auth ← erp-server

 ### 第一阶段（1-2 天）— 紧急修复

-1. **NEW-2**: SSE 端口统一为 3000
+1. ~~**NEW-2**: SSE 端口统一为 3000~~ ✅
 2. **TD-1**: authorId 接入 AuthBloc
 3. **NEW-4**: API base URL 环境配置化

@@ -110,17 +110,18 @@ erp-core ← erp-auth ← erp-server

 4. **TD-2**: CI/CD 基础流水线
 5. **TD-3 + NEW-3**: Docker 部署验证 + Dockerfile 创建
-6. **TD-5**: 核心模块单元测试（AuthBloc, EditorBloc, JournalRepository）
+6. ~~**TD-5**: 核心模块单元测试~~ ✅ 已有 15 个测试文件，持续补充

 ### 第三阶段（持续）— 质量提升

 7. **NEW-7**: 通用 catch(e) → 类型化异常处理
 8. **NEW-8**: Feature Flag 配置落地
 9. **TD-4**: toImage() 异步光栅化
-10. **TD-8**: 编辑器加载已有日记
+10. ~~**TD-8**: 编辑器加载已有日记~~ ✅

 ## 变更记录

 | 日期 | 变更 |
 |------|------|
+| 2026-06-07 | 更新：TD-8/NEW-1/NEW-2 已修复，测试覆盖 ⭐⭐→⭐⭐⭐，编辑器 95%→98%，日历 85%→90% |
 | 2026-06-01 | 初始创建 — 基于 4 代理并行分析结果 |