iven/nj

Files

iven d1a07229e2 docs: 项目 Wiki 知识库 — 7 文件覆盖架构/手写/数据/前端/后端/技术债

新增 wiki/ 知识库 (遵循 HMS wiki-methodology.md 5 节结构):
- index.md (84 行) — 症状导航 13 条 + 模块索引 + 系统数据流
- architecture.md (120 行) — 基座剥离 7 耦合点 + Feature Flag + PIPL 合规
- handwriting-engine.md (124 行) — 双层 Canvas + O(1) 点缓冲 + 光栅化缓存
- data-layer.md (127 行) — Isar + SyncEngine 离线同步 + 踩坑记录
- frontend.md (118 行) — 16 模块地图 + BLoC 注入链 + 设计系统
- erp-diary.md (101 行) — 15 Entity / 10 Service / 8 Handler + API 端点

新增 docs/:
- tech-debt-board.md (110 行) — 10 条技术债 + 偿还优先级排名

其他更新:
- .gitignore: 添加 .understand-anything/ (待初始化)
- CLAUDE.md §9: 添加 wiki 参考文档链接

2026-06-01 15:08:21 +08:00

3.5 KiB

Raw Blame History

暖记 (Nuanji) — 知识库

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

关键数字

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

指标	值
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 个
Flutter features	16 个
Isar Collection	3 个（JournalEntry / JournalElement / PendingOperation）
后端测试	~50 个通过
flutter analyze	0 error
Git 提交	17 次

系统数据流

用户手写/涂鸦
     │
     ▼
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 端点、权限码

症状导航

症状	先查	再查	常见根因
笔画卡顿 >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

文档	位置
产品设计规格 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`
基座仓库	https://git.stableeasy.com/iven/base.git

3.5 KiB Raw Blame History Unescape Escape

暖记 (Nuanji) — 知识库

关键数字

系统数据流

模块导航

症状导航

相关文档

3.5 KiB

Raw Blame History