---
title: 暖记知识库首页
updated: 2026-06-01
status: active
---

# 暖记 (Nuanji) — 知识库

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

## 关键数字

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

| 指标 | 值 |
|------|-----|
| 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 个通过 |
| 前端测试 | **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%** |

## 系统数据流

```
用户手写/涂鸦
     │
     ▼
HandwritingCanvas (Listener → StrokePoint)
     │ Stroke
     ▼
EditorBloc (strokes + elements)
     │ onSave (2s debounce)
     ▼
IsarJournalRepository ──→ Isar 本地数据库
     │                       │
     │                       ▼ (启动恢复)
     │                 SyncEngine (pending queue)
     │                       │ WiFi 可用
     ▼                       ▼
JournalEntry           RemoteJournalRepository
+ JournalElement            │
                            ▼
                      API Client (Dio)
                            │
                            ▼
                      Axum → erp-diary → PostgreSQL
```

## 模块导航

- [[architecture]] — 仓库拓扑、基座继承、Feature Flag、多租户、安全合规
- [[handwriting-engine]] — 双层 Canvas、光栅化缓存、perfect_freehand、4 种画笔
- [[data-layer]] — Isar 本地存储、Repository 模式、SyncEngine 离线同步
- [[frontend]] — Flutter BLoC、16 个功能模块、设计系统、响应式布局
- [[erp-diary]] — Rust 后端业务模块、Entity/Service/Handler、API 端点、权限码
- [[project-health]] — 🆕 项目健康度评估、技术债全景、风险矩阵、改进建议

## 症状导航

| 症状 | 先查 | 再查 | 常见根因 |
|------|------|------|----------|
| 笔画卡顿 >16ms | [[handwriting-engine]] | 光栅化缓存 | shouldRepaint 守卫失效 / 未用 Listener |
| 编辑器保存失败 | [[data-layer]] | IsarDatabase | Isar 未初始化 |
| Isar `findAll` 未定义 | [[data-layer]] | 扩展方法 | 缺少 `import 'package:isar/isar.dart'` |
| 同步版本冲突 | [[data-layer]] | 乐观锁 | version 不匹配 |
| 深色模式颜色异常 | [[frontend]] | AppTheme | token 未适配深色值 |
| API 返回 403 | [[erp-diary]] | 权限守卫 | 权限码不匹配 |
| 迁移执行失败 | [[architecture]] | 多租户 | 表冲突 / 缺失迁移 |
| 上下文窗口耗尽 | CLAUDE.md §8 | 会话交接 | 长会话未及时交接 |
| 手写穿透背景 | [[handwriting-engine]] | 橡皮擦 | 未用 saveLayer + dstOut |
| 模式切换卡顿 | [[handwriting-engine]] | IgnorePointer | if/else 销毁重建 Widget |
| 热重载后 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 未实现 |

## 相关文档

| 文档 | 位置 |
|------|------|
| 产品设计规格 v1.2 | `docs/superpowers/specs/2026-05-31-nuanji-warm-notes-design.md` |
| 实施规划 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 |