124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
---
|
||
title: 暖记知识库首页
|
||
updated: 2026-06-07
|
||
status: 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
|
||
```
|
||
|
||
## 一键启动
|
||
|
||
```bash
|
||
./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 |
|