docs(wiki): 全量项目健康度评估 + 技术债全景更新

- 新增 project-health.md — 项目评分/技术债全景/风险矩阵/改进路线图 - 更新 index.md — 代码量分布表/新发现技术债统计/新增症状条目 - 更新 architecture.md — Feature Flag 未实现状态/超大文件发现 - 更新 frontend.md — 状态管理不统一/SSE 端口/测试缺失等 11 项问题 - 更新 erp-diary.md — 代码量分布参考/班级码硬编码问题基于 4 代理并行深度分析: 后端 Rust 51,459 行 + 前端 Flutter 18,398 行
2026-06-01 18:33:38 +08:00
parent c2a95798bd
commit ab58186ab3
5 changed files with 196 additions and 12 deletions
--- a/wiki/architecture.md
+++ b/wiki/architecture.md
@@ -104,17 +104,22 @@ nj/crates/

 | 问题 | 级别 | 状态 | 说明 |
 |------|------|------|------|
-| 上下文窗口耗尽 | HIGH | 已缓解 | CLAUDE.md §8 会话交接机制 |
+| Feature Flag 未实现 | HIGH | 待做 | erp-server/Cargo.toml 无 `[features]` 段，所有模块无条件编译 |
+| Docker 部署未验证 | HIGH | 待做 | docker/ 配置完善但 Dockerfile 不存在，未实际运行 |
+| 上下文窗口耗尽 | MEDIUM | 已缓解 | CLAUDE.md §8 会话交接机制 |
 | Windows Defender 锁定 exe | MEDIUM | 需手动 | 排除 target/ 目录 |
-| Docker 部署未验证 | MEDIUM | 待做 | docker/ 目录存在但未测试 |
+| erp-plugin 超大文件 | LOW | 待重构 | manifest.rs (1809行) + data_service.rs (1907行) 超过 800 行限制 |
+| erp-message module.rs 过大 | LOW | 待重构 | 1283 行，事件监听逻辑可拆分 |

 ### 历史教训

 - 基座剥离耗时比预期长（7 个耦合点需逐一解耦）
 - Isar 3.x 扩展方法不随传递 import 传播，必须显式 import
+- Feature Flag 在基座剥离规划中设计完善，但实际实施时未落地到 Cargo.toml

 ## 5. 变更记录

 | 日期 | 变更 |
 |------|------|
+| 2026-06-01 | 补充 Feature Flag 状态、超大文件发现 |
 | 2026-06-01 | 初始创建 — 架构决策、基座剥离记录、集成契约 |
--- a/wiki/erp-diary.md
+++ b/wiki/erp-diary.md
@@ -90,12 +90,26 @@ journal, class, comment, content_safety, achievement, mood_stats, notification,

 | 问题 | 级别 | 状态 | 说明 |
 |------|------|------|------|
-| Docker 部署未验证 | HIGH | 待做 | docker/ 目录存在但未实际运行 |
+| Docker 部署未验证 | HIGH | 待做 | docker/ 配置完善但 Dockerfile 不存在 |
 | CI/CD 未建立 | MEDIUM | 待做 | 无自动化构建/测试/部署 |
 | 文件上传未实现 | MEDIUM | 待做 | 照片/贴纸文件上传参考健康模块 |
+| 代码分布 | INFO | 参考 | service 层 51.7%、handler 20.1%、entity 15.6%、dto 11.1% |
+| 班级码硬编码 | LOW | 待修 | 前端 teacher 模块班级码 'a1b2c3' 未接入后端 |
+
+### 代码量参考
+
+| 层 | 行数 | 占比 |
+|---|---:|---:|
+| entity/ | 796 | 15.6% |
+| handler/ | 1,029 | 20.1% |
+| service/ | 2,641 | 51.7% |
+| dto.rs | 569 | 11.1% |
+| 其他 | 473 | 9.3% |
+| **合计** | **5,108** | **100%** |

 ## 5. 变更记录

 | 日期 | 变更 |
 |------|------|
+| 2026-06-01 | 补充代码量分布、班级码硬编码问题 |
 | 2026-06-01 | 初始创建 — Entity/Service/Handler 清单、API 端点、集成契约 |
--- a/wiki/frontend.md
+++ b/wiki/frontend.md
@@ -101,18 +101,29 @@ AppTheme.light() / AppTheme.dark()
 | 问题 | 级别 | 状态 | 说明 |
 |------|------|------|------|
 | 编辑器不加载已有数据 | HIGH | 待做 | journalId 非空时需从 Isar 读取 |
+| SSE 端口不一致 | HIGH | 待修 | SSE 用 8080，API 用 3000，推送必然失败 |
+| API base URL 硬编码 | HIGH | 待修 | localhost:3000 硬编码，生产环境需配置化 |
+| 前端测试为零 | HIGH | 待做 | 70 个 Dart 文件无任何测试覆盖 |
+| 状态管理不统一 | MEDIUM | 待规划 | 5 模块用 BLoC，5 模块用 ChangeNotifier |
+| freezed 声明未使用 | MEDIUM | 待清理 | pubspec 声明了但全部手写不可变类 |
+| SyncEngine 缺少网络监听 | MEDIUM | 待做 | 只有 trySync() 方法，无自动触发 |
 | 搜索功能空壳 | MEDIUM | 待做 | Isar FTS 未实现 |
+| 家长/教师页面占位 | LOW | 持续 | 多处 onTap 为 SnackBar 提示 |
+| core/utils/ 空目录 | LOW | 待填充 | 缺少日期格式化、颜色解析等通用工具 |
 | 深色模式细节 | LOW | 持续 | 部分组件深色适配需检查 |

 ### 历史教训

 - F11 深色模式修复需要 bloat bloc 测试套件同步更新 (05317d5)
 - NuanjiApp 是 StatelessWidget，build() 可被调用多次 → 全局依赖应在 build() 中创建单例
+- 25 处通用 catch(e) 静默吞异常，排查问题时需注意
+- 班级码在 teacher 模块硬编码为 'a1b2c3'，需接入后端 API

 ## 5. 变更记录

 | 日期 | 变更 |
 |------|------|
+| 2026-06-01 | 补充状态管理不统一、SSE 端口问题、测试缺失等新发现 |
 | 2026-06-01 | IsarJournalRepository 注入为主 JournalRepository (2481c8f) |
 | 2026-06-01 | 设置页 UI + Mood/成就/贴纸 BLoC (8331db6) |
 | 2026-06-01 | 初始创建 — 16 模块地图、注入链、设计系统 |
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -1,24 +1,48 @@
+---
+title: 暖记知识库首页
+updated: 2026-06-01
+status: active
+---
+
 # 暖记 (Nuanji) — 知识库

 > **温暖治愈风格的手写手账日记 App**，面向小学生首发，核心价值是保留真实笔迹。从 [[architecture]] 导航。

 ## 关键数字

-> 最后更新: 2026-06-01 | 基线: main (2481c8f)
+> 最后更新: 2026-06-01 | 基线: main (c2a9579)

 | 指标 | 值 |
 |------|-----|
-| Rust crate | 8 个（6 基座 + 1 入口 + erp-diary 新增） |
-| Rust 新增代码 | ~5,500 行（erp-diary） |
-| Dart 文件 | 70 个（~18,200 行，含生成代码） |
-| SeaORM Entity | 15 个（erp-diary） |
-| 数据库迁移 | 15 个（diary 相关） |
-| BLoC 模块 | 12 个 |
+| Rust crate | 8 个（6 基座 + 1 入口 + erp-diary） |
+| Rust 总代码 | ~51,459 行（256 个 .rs 文件） |
+| erp-diary 新增 | 5,108 行（41 个文件） |
+| Dart 文件 | 70 个（~18,398 行，含生成代码 6,128 行） |
+| SeaORM Entity | 15 个（erp-diary） + 50+（基座） |
+| 数据库迁移 | 56 个（41 基座 + 15 diary） |
+| BLoC 模块 | 12 个（5 flutter_bloc + 5 ChangeNotifier + 2 混合） |
 | Flutter features | 16 个 |
 | Isar Collection | 3 个（JournalEntry / JournalElement / PendingOperation） |
 | 后端测试 | ~50 个通过 |
-| flutter analyze | 0 error |
-| Git 提交 | 17 次 |
+| 前端测试 | **0 个**（最大技术债） |
+| flutter analyze | 0 error / 1 warning / 18 info |
+| Git 提交 | 20 次 |
+| 技术债 | 10 已记录 + 9 新发现 |
+
+## 代码量分布
+
+| 组件 | 代码行数 | 文件数 | 占比 |
+|------|---------|--------|------|
+| erp-plugin (WASM 插件运行时) | 11,312 | 28 | 16.2% |
+| erp-auth (认证/权限) | 7,458 | 39 | 10.6% |
+| erp-workflow (BPMN 引擎) | 5,410 | 27 | 7.7% |
+| erp-config (字典/菜单/设置) | 5,111 | 23 | 7.3% |
+| erp-diary (暖记业务) | 5,108 | 41 | 7.3% |
+| erp-server (入口/迁移) | ~10,414 | 72 | 14.9% |
+| erp-core (事件/加密/审计) | 2,774 | 27 | 4.0% |
+| erp-message (通知/SSE) | 3,872 | 19 | 5.5% |
+| Flutter 前端 | ~18,398 | 70 | 26.3% |
+| **合计** | **~69,857** | **~346** | **100%** |

 ## 系统数据流

@@ -54,6 +78,7 @@ JournalEntry           RemoteJournalRepository
 - [[data-layer]] — Isar 本地存储、Repository 模式、SyncEngine 离线同步
 - [[frontend]] — Flutter BLoC、16 个功能模块、设计系统、响应式布局
 - [[erp-diary]] — Rust 后端业务模块、Entity/Service/Handler、API 端点、权限码
+- [[project-health]] — 🆕 项目健康度评估、技术债全景、风险矩阵、改进建议

 ## 症状导航

@@ -72,6 +97,8 @@ JournalEntry           RemoteJournalRepository
 | 热重载后 Isar 崩溃 | [[data-layer]] | 初始化 | 未 close 就 re-open |
 | 编辑器加载空白 | [[frontend]] | EditorBloc | journalId 有值但未加载 Isar 数据 |
 | SyncEngine 队列丢失 | [[data-layer]] | 持久化 | 退出时未调 persistPendingQueue |
+| SSE 推送不工作 | [[frontend]] | 端口配置 | SSE 端口 8080 vs API 端口 3000 |
+| 班级码验证失败 | [[frontend]] | auth_bloc | 班级码后端验证 TODO 未实现 |

 ## 相关文档

@@ -81,4 +108,5 @@ JournalEntry           RemoteJournalRepository
 | 实施规划 v2.1 | `plans/hazy-petting-lampson.md` |
 | 项目协作规则 | `CLAUDE.md` |
 | 技术债看板 | `docs/tech-debt-board.md` |
+| OpenDesign 原型 | `docs/opendesign/warm-notes-journal-app.md` |
 | 基座仓库 | https://git.stableeasy.com/iven/base.git |
--- a/wiki/project-health.md
+++ b/wiki/project-health.md
@@ -0,0 +1,126 @@
+---
+title: 项目健康度评估
+updated: 2026-06-01
+status: active
+tags: [health, tech-debt, risk, improvement]
+---
+
+# 项目健康度评估
+
+> 从 [[index]] 导航。本文档基于 2026-06-01 全量代码分析生成。
+
+## 总体评分
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 架构设计 | ⭐⭐⭐⭐⭐ | 模块化 ErpModule trait、分层清晰、基座复用 |
+| 代码质量 | ⭐⭐⭐⭐ | Rust 错误处理规范、Flutter 注释质量高、分层一致 |
+| 测试覆盖 | ⭐⭐ | 后端 ~50 测试尚可、前端 **0 测试** 是最大短板 |
+| 安全合规 | ⭐⭐⭐⭐⭐ | PIPL 合规框架完整、PII 加密、RLS 多租户隔离 |
+| 文档维护 | ⭐⭐⭐⭐⭐ | wiki 6 页 + 技术债看板 + CLAUDE.md，同步度高 |
+| DevOps | ⭐⭐ | Docker 配置完善但未验证、CI/CD 缺失、无自动化 |
+| 功能完整度 | ⭐⭐⭐⭐ | 后端完整闭环、前端核心模块 85%+、班级/家长模块待完善 |
+
+## 技术债全景
+
+### 已记录（10 条）
+
+| 编号 | 债务 | 优先级 | 预估 |
+|------|------|--------|------|
+| TD-1 | authorId 硬编码 'local' | P0 | 0.5 天 |
+| TD-3 | Docker 部署未验证 | P0 | 0.5 天 |
+| TD-7 | Settings 持久化未实现 | P1 | 0.5 天 |
+| TD-8 | 编辑器不加载已有日记 | P1 | 1 天 |
+| TD-4 | toImage() 同步阻塞主线程 | P1 | 1 天 |
+| TD-2 | CI/CD 未建立 | P2 | 1 天 |
+| TD-5 | 前端测试为零 | P2 | 3 天 |
+| TD-6 | 画布尺寸变化缓存过渡 | P2 | 1 天 |
+| TD-9 | Isar FTS 搜索未实现 | P2 | 1 天 |
+| TD-10 | SyncEngine 蜂窝数据未支持 | P3 | 0.5 天 |
+
+### 新发现（9 条）
+
+| 编号 | 债务 | 优先级 | 预估 | 位置 |
+|------|------|--------|------|------|
+| NEW-1 | 前端测试缺失（TD-5 补充：0 回归保护） | **Critical** | 3 天 | `app/test/` |
+| NEW-2 | SSE 端口不一致 (8080 vs 3000) | **Critical** | 0.5 天 | `sse_notification_service.dart:42` |
+| 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 |
+| NEW-6 | Prometheus exporters 未定义 | **Medium** | 0.5 天 | `prometheus.yml` 引用 |
+| NEW-7 | 25 处通用 catch(e) 静默吞异常 | **Medium** | 1 天 | 各 BLoC 文件 |
+| NEW-8 | Feature Flag 未实现（计划中有但未落地） | **Medium** | 2 天 | `erp-server/Cargo.toml` |
+| NEW-9 | 状态管理不统一（BLoC vs ChangeNotifier） | **Low** | 2 天 | 5 个功能模块 |
+
+## 前端模块完成度矩阵
+
+| 模块 | 完成度 | 关键缺失 |
+|------|--------|---------|
+| 手写引擎 | **95%** | toImage 异步化 |
+| 编辑器 | **95%** | 文字输入/图片上传为占位 |
+| 认证 | **85%** | 班级码后端验证 TODO |
+| 首页 | **90%** | — |
+| 设计系统 | **90%** | `core/utils/` 空目录 |
+| 设置 | **85%** | 持久化未实现 |
+| 日历 | **85%** | 周视图/时间线未实现 |
+| 数据层 | **85%** | SyncEngine 缺少网络监听 |
+| 班级 | **80%** | — |
+| 心情统计 | **80%** | — |
+| 个人中心 | **80%** | — |
+| 贴纸 | **70%** | 应用贴纸为 SnackBar 占位 |
+| 模板 | **65%** | 应用模板为 SnackBar 占位 |
+| 成就 | **65%** | 视图页面空壳 |
+| 教师 | **60%** | 班级码硬编码 'a1b2c3' |
+| 家长 | **40%** | 全部为 SnackBar 占位 |
+| 搜索 | **30%** | Isar FTS 未集成 |
+
+## 后端 Crate 依赖图
+
+```
+erp-core ← erp-auth ← erp-server
+         ← erp-config ← erp-server
+         ← erp-message ← erp-server
+         ← erp-workflow ← erp-server
+         ← erp-plugin ← erp-server
+         ← erp-diary ← erp-server
+```
+
+**依赖健康度**: 无循环依赖、无跨业务 crate 直接依赖、通过 EventBus 模块间通信 ✅
+
+## 风险矩阵
+
+| 风险 | 概率 | 影响 | 缓解 |
+|------|------|------|------|
+| 前端无测试导致回归 | 高 | 高 | TD-5: 建立核心 BLoC/Repository 单元测试 |
+| Feature Flag 未实现限制扩展 | 中 | 中 | NEW-8: 补充 Cargo features 配置 |
+| Docker 生产部署无法构建 | 高 | 高 | NEW-3: 创建 Dockerfile + 验证 |
+| SSE 端口不匹配致推送失败 | 确定 | 中 | NEW-2: 统一为 3000 端口 |
+| 手写 toImage 卡 UI | 中 | 中 | TD-4: compute() isolate 异步光栅化 |
+| 大文件超 800 行限制 | 中 | 低 | erp-plugin manifest.rs(1809) + data_service.rs(1907) 需拆分 |
+
+## 改进建议路线图
+
+### 第一阶段（1-2 天）— 紧急修复
+
+1. **NEW-2**: SSE 端口统一为 3000
+2. **TD-1**: authorId 接入 AuthBloc
+3. **NEW-4**: API base URL 环境配置化
+
+### 第二阶段（3-5 天）— 基础设施
+
+4. **TD-2**: CI/CD 基础流水线
+5. **TD-3 + NEW-3**: Docker 部署验证 + Dockerfile 创建
+6. **TD-5**: 核心模块单元测试（AuthBloc, EditorBloc, JournalRepository）
+
+### 第三阶段（持续）— 质量提升
+
+7. **NEW-7**: 通用 catch(e) → 类型化异常处理
+8. **NEW-8**: Feature Flag 配置落地
+9. **TD-4**: toImage() 异步光栅化
+10. **TD-8**: 编辑器加载已有日记
+
+## 变更记录
+
+| 日期 | 变更 |
+|------|------|
+| 2026-06-01 | 初始创建 — 基于 4 代理并行分析结果 |