nj/wiki/index.md

title, updated, status

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

暖记 (Nuanji) — 知识库

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

关键数字

最后更新: 2026-06-07 | 基线: main (4cb91f3)

指标	值
Rust crate	8 个（6 基座 + 1 入口 + erp-diary）
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）
后端测试	88 个通过 ✅
前端测试	15 个文件、203 个用例通过 ✅（1 个失败待修）
flutter analyze	0 error ✅
Git 提交	107 次

三端架构

┌─────────────────────────────────────────────────────┐
│                    暖记系统                           │
├──────────┬──────────────────┬───────────────────────┤
│ 后端 API  │ 管理端 Web       │ 学生端 App            │
│ Rust/Axum │ React/Ant Design │ Flutter               │
│ :3000     │ :5174            │ :8080                  │
│           │                  │                        │
│ erp-diary │ 用户管理         │ 手写日记               │
│ erp-auth  │ 角色权限         │ 日历/心情              │
│ erp-core  │ 审计日志         │ 班级/分享              │
│ erp-config│ 系统配置         │ 贴纸/模板              │
│ ...       │ 插件管理         │ 成就/设置              │
├──────────┴──────────────────┴───────────────────────┤
│           PostgreSQL 16 + Redis 7                    │
└─────────────────────────────────────────────────────┘

系统数据流

用户手写/涂鸦
     │
     ▼
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

一键启动

./scripts/dev.sh          # 启动全部 (后端 + 管理端 + 学生端)
./scripts/dev.sh backend  # 只启动后端 API
./scripts/dev.sh admin    # 只启动管理端 (React, :5174)
./scripts/dev.sh app      # 只启动学生端 (Flutter, :8080)
./scripts/dev.sh stop     # 停止所有服务

管理端默认账号: admin / admin123

模块导航

• architecture — 仓库拓扑、基座继承、Feature Flag、多租户、安全合规、三端架构
• admin-web — 🆕 管理端 React 前端、Ant Design、从 HMS 基座复用
• 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 未初始化
同步版本冲突	data-layer	乐观锁	version 不匹配
深色模式颜色异常	frontend	AppTheme	token 未适配深色值
API 返回 403	erp-diary	权限守卫	权限码不匹配
管理端登录白屏	admin-web	Vite proxy	后端未启动或端口不对
CORS 跨域错误	architecture	config/default.toml	allowed_origins 未包含前端端口
端口占用启动失败	scripts/dev.sh stop	netstat	旧进程未清理
班级码验证失败	frontend	auth_bloc	班级码后端验证 TODO
Profile 页白屏	frontend	UserRoleType	.name 应改为 .code

相关文档

文档	位置
产品设计规格 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
HMS 源码 (只读)	G:\hms