From ab58186ab38568dccda3354e3a0dec3692010200 Mon Sep 17 00:00:00 2001 From: iven Date: Mon, 1 Jun 2026 18:33:38 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E5=85=A8=E9=87=8F=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=81=A5=E5=BA=B7=E5=BA=A6=E8=AF=84=E4=BC=B0=20+=20?= =?UTF-8?q?=E6=8A=80=E6=9C=AF=E5=80=BA=E5=85=A8=E6=99=AF=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 project-health.md — 项目评分/技术债全景/风险矩阵/改进路线图 - 更新 index.md — 代码量分布表/新发现技术债统计/新增症状条目 - 更新 architecture.md — Feature Flag 未实现状态/超大文件发现 - 更新 frontend.md — 状态管理不统一/SSE 端口/测试缺失等 11 项问题 - 更新 erp-diary.md — 代码量分布参考/班级码硬编码问题 基于 4 代理并行深度分析: 后端 Rust 51,459 行 + 前端 Flutter 18,398 行 --- wiki/architecture.md | 9 ++- wiki/erp-diary.md | 16 +++++- wiki/frontend.md | 11 ++++ wiki/index.md | 46 ++++++++++++--- wiki/project-health.md | 126 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 196 insertions(+), 12 deletions(-) create mode 100644 wiki/project-health.md diff --git a/wiki/architecture.md b/wiki/architecture.md index c9450da..05cec24 100644 --- 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 | 初始创建 — 架构决策、基座剥离记录、集成契约 | diff --git a/wiki/erp-diary.md b/wiki/erp-diary.md index 43ca667..bd7316d 100644 --- 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 端点、集成契约 | diff --git a/wiki/frontend.md b/wiki/frontend.md index bb1b83e..89d0d3c 100644 --- 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 模块地图、注入链、设计系统 | diff --git a/wiki/index.md b/wiki/index.md index 91f9e89..60bd713 100644 --- 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 | diff --git a/wiki/project-health.md b/wiki/project-health.md new file mode 100644 index 0000000..3c4cd0a --- /dev/null +++ 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 代理并行分析结果 |