From ed8252d7c801f6c4375497d1fca504d5e8f9be79 Mon Sep 17 00:00:00 2001 From: iven Date: Sun, 7 Jun 2026 10:44:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20Wiki=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=20=E2=80=94=20=E6=95=B0=E6=8D=AE=E5=B1=82/=E5=89=8D?= =?UTF-8?q?=E7=AB=AF/=E5=90=8E=E7=AB=AF/=E5=81=A5=E5=BA=B7/=E7=B4=A2?= =?UTF-8?q?=E5=BC=95=E5=90=8C=E6=AD=A5=E8=87=B3=E6=9C=80=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- wiki/data-layer.md | 5 ++-- wiki/erp-diary.md | 18 +++++++------ wiki/frontend.md | 57 +++++++++++++++++++++++++++++++++++++----- wiki/index.md | 16 ++++++------ wiki/project-health.md | 27 ++++++++++---------- 5 files changed, 87 insertions(+), 36 deletions(-) diff --git a/wiki/data-layer.md b/wiki/data-layer.md index f22c78f..788abd4 100644 --- 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 踩坑记录 | diff --git a/wiki/erp-diary.md b/wiki/erp-diary.md index bd7316d..8dfb940 100644 --- 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 端点、集成契约 | diff --git a/wiki/frontend.md b/wiki/frontend.md index 89d0d3c..5b887e8 100644 --- 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) | diff --git a/wiki/index.md b/wiki/index.md index ac93a9a..b5414f9 100644 --- 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 次 | ## 三端架构 diff --git a/wiki/project-health.md b/wiki/project-health.md index 3c4cd0a..cc1774d 100644 --- 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 代理并行分析结果 |