diff --git a/CLAUDE.md b/CLAUDE.md index 254e999..75364b6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,8 +36,13 @@ nj/ (一个仓库) │ ├── src/service/ # ~12 Service │ ├── src/handler/ # ~10 Handler │ └── src/{dto,error,event,state}.rs -├── app/ # Flutter 前端 -├── config/ # 服务器配置 +├── apps/ # 🆕 管理端前端 (从 HMS 基座复用) +│ └── web/ # React + Ant Design + Vite (:5174) +│ ├── src/pages/ # 管理页面 (用户/角色/权限/审计...) +│ └── vite.config.ts # API 代理 → localhost:3000 +├── app/ # Flutter 学生端 (:8080) +├── scripts/dev.sh # 🆕 统一启动脚本 (自动清理端口) +├── config/ # 服务器配置 (CORS=*) ├── docker/ # Docker Compose (PG + Redis) ├── docs/ # 产品文档 │ └── superpowers/specs/ # 设计规格 v1.2 @@ -62,6 +67,7 @@ nj/ (一个仓库) | BPMN 工作流 | erp-workflow 继承 | 零开发 | | SeaORM 迁移框架 | erp-server 继承 | 零开发 | | OpenAPI 文档 | utoipa 继承 | 零开发 | +| 管理端 Web 前端 | HMS apps/web/ 复用 | 零开发 (品牌替换待做) | | student/teacher/parent 角色 | erp-auth 扩展 | 🆕 ~200 行 | | 班级码认证 | erp-auth 扩展 | 🆕 ~500 行 | | 日记 CRUD + 同步 | erp-diary 新增 | 🆕 ~2000 行 | @@ -321,9 +327,12 @@ chore(docker): 添加 PostgreSQL 16 + Redis 7 开发环境 - 当遇到**新增数据表** → 创建 SeaORM migration + Entity，包含所有标准字段 - 当遇到**跨模块通信** → 定义事件类型到 erp-diary/src/event.rs，通过 EventBus 发布 - 当遇到**新增 Flutter 功能** → 创建 features/{name}/ 目录，bloc/views/widgets 分层 +- 当遇到**管理端修改** → 在 apps/web/ 中修改 React 组件，`pnpm dev` 启动开发服务器 +- 当遇到**管理端新增页面** → 在 apps/web/src/pages/ 添加，更新 routeConfig.ts + 侧边栏菜单 - 当遇到**手写性能问题** → 检查 shouldRepaint 守卫 + 笔画光栅化缓存 + Listener 替代 GestureDetector - 当遇到**同步冲突** → 版本号比对，Phase 1 使用"本地优先"简单策略 - 当遇到**儿童数据** → 确认 PIPL 合规检查清单（家长授权/最小数据/加密/注销机制） +- 当遇到**启动端口占用** → `./scripts/dev.sh stop` 清理所有旧进程 --- @@ -419,6 +428,7 @@ chore(docker): 添加 PostgreSQL 16 + Redis 7 开发环境 | 手写引擎 | `wiki/handwriting-engine.md` — 双层 Canvas + 光栅化缓存 | | 数据层 | `wiki/data-layer.md` — Isar + SyncEngine 离线同步 | | Flutter 前端 | `wiki/frontend.md` — 16 模块 + BLoC + 设计系统 | +| 管理端前端 | `wiki/admin-web.md` — React + Ant Design + 品牌定制清单 | | 后端模块 | `wiki/erp-diary.md` — Entity/Service/Handler 清单 | | 技术债看板 | `docs/tech-debt-board.md` — 10 条待偿还债务 | | 产品设计规格 v1.2 | `docs/superpowers/specs/2026-05-31-nuanji-warm-notes-design.md` | @@ -431,6 +441,35 @@ chore(docker): 添加 PostgreSQL 16 + Redis 7 开发环境 ## 10. 开发环境 +### 三端启动 + +```bash +# 一键启动全部 (后端 + 管理端 + 学生端) +./scripts/dev.sh + +# 单独启动 +./scripts/dev.sh backend # Rust Axum → :3000 +./scripts/dev.sh admin # React Vite → :5174 +./scripts/dev.sh app # Flutter Web → :8080 + +# 停止所有 (自动清理端口) +./scripts/dev.sh stop +``` + +管理端默认账号: `admin / admin123` + +### 环境依赖 + +| 服务 | 地址 | 说明 | +|------|------|------| +| PostgreSQL 16 | localhost:5432 | 数据库 `nuanji` | +| Redis 7 | localhost:6379 | 缓存/速率限制 | +| Flutter SDK | D:\flutter\bin\flutter.bat | 学生端 | +| Node.js + pnpm | - | 管理端 | +| Rust toolchain | stable | 后端 | + +### 参考文档 + | 文档 | 位置 | |------|------| | 产品设计规格 v1.2 | `docs/superpowers/specs/2026-05-31-nuanji-warm-notes-design.md` | diff --git a/wiki/admin-web.md b/wiki/admin-web.md new file mode 100644 index 0000000..dbbf7e7 --- /dev/null +++ b/wiki/admin-web.md @@ -0,0 +1,126 @@ +--- +title: 管理端 Web 前端 +updated: 2026-06-02 +status: active +tags: [react, antd, vite, admin, typescript] +--- + +# 管理端 Web 前端 + +> 从 [[index]] 导航。关联: [[architecture]] [[erp-diary]] + +## 1. 设计决策 + +### Q: 管理端从哪里来？ + +从 HMS 基座 (G:\hms/apps/web/) 复制而来，避免重复开发。HMS 已有完整的 React 管理面板（用户/角色/权限/组织/审计等），暖记直接复用。 + +### Q: 管理端技术栈？ + +React 19 + Ant Design 6 + Vite 8 + TypeScript + Zustand + Tailwind CSS 4。与基座后端 API 完全对接。 + +### Q: 为什么不和学生端一起用 Flutter？ + +管理端面向管理员/老师，Web 浏览器操作更高效。学生端面向小学生，需要触摸友好的移动端体验。 + +## 2. 关键结构 + +``` +apps/web/ +├── src/ +│ ├── api/ # API 调用层 (Axios) +│ │ ├── client.ts # 基础配置, baseURL=/api/v1 +│ │ ├── ai/ # AI 分析 API +│ │ └── health/ # 健康检查 API +│ ├── components/ # 通用组件 +│ │ ├── Copilot/ # AI 助手 +│ │ └── MediaPicker/# 媒体选择器 +│ ├── hooks/ # 自定义 Hooks +│ ├── layouts/ # 布局组件 (侧边栏+顶栏) +│ ├── pages/ # 页面 +│ │ ├── dashboard/ # 仪表盘 +│ │ ├── settings/ # 系统配置 +│ │ ├── plugins/ # 插件管理 +│ │ ├── workflow/ # 工作流 +│ │ ├── messages/ # 消息管理 +│ │ └── graph/ # 图形编辑器 +│ ├── stores/ # Zustand 状态 +│ ├── constants/ # 常量定义 +│ └── utils/ # 工具函数 +├── vite.config.ts # Vite 配置 (proxy → localhost:3000) +└── package.json # 依赖管理 (pnpm) +``` + +## 3. API 代理配置 + +`vite.config.ts` 已配置开发代理，所有 `/api` 请求转发到后端： + +```typescript +proxy: { + "/api": { target: "http://localhost:3000", changeOrigin: true }, + "/uploads": { target: "http://localhost:3000", changeOrigin: true }, + "/ws": { target: "ws://localhost:3000", ws: true }, +} +``` + +无需额外 CORS 配置（同源代理）。 + +## 4. 功能模块映射 + +### 已验证的基座功能 + +| 管理端页面 | 后端 API | 状态 | +|-----------|---------|------| +| 登录 | POST /auth/login | ✅ | +| 仪表盘 | GET /health + 统计 | ✅ 部分数据待适配 | +| 用户管理 | CRUD /users | ✅ | +| 角色权限 | CRUD /roles + /permissions | ✅ | +| 审计日志 | GET /audit-logs | ✅ | +| 系统配置 | CRUD /config/settings | ✅ | +| 菜单管理 | /config/menus | ✅ | +| 数据字典 | /config/dictionaries | ✅ | +| 插件管理 | /admin/plugins | ✅ | +| 消息管理 | /messages | ✅ | + +### 待添加的暖记专用功能 + +| 页面 | 说明 | 优先级 | +|------|------|--------| +| 班级管理 | 查看/创建/管理班级 | HIGH | +| 日记审核 | 查看学生日记 + 点评 | HIGH | +| 贴纸管理 | 上传/管理贴纸包 | MEDIUM | +| 主题管理 | 布置写作主题 | MEDIUM | +| 心情统计 | 全校/班级心情趋势 | LOW | + +## 5. 品牌定制清单 + +管理端目前仍显示 HMS 品牌，需要替换为暖记品牌： + +| 位置 | 当前值 | 替换为 | +|------|--------|--------| +| 登录页标题 | "HMS 健康管理平台" | "暖记管理后台" | +| 登录页副标题 | "患者管理·健康监测..." | "班级管理·日记审核·成长追踪" | +| 侧边栏标题 | "HMS 健康管理平台" | "暖记 Nuanji" | +| 底部版权 | "HMS 健康管理平台" | "暖记 Nuanji" | +| 页面 title | index.html | "暖记管理后台" | +| Logo | HMS logo | 暖记 Logo | +| 主题色 | 蓝色系 (Ant Design 默认) | 珊瑚色 (#E07A5F) | +| 不需要的页面 | 健康管理/AI分析 | 隐藏或移除 | + +## 6. 启动方式 + +```bash +# 方式一：统一启动脚本 +./scripts/dev.sh admin + +# 方式二：手动启动 +cd apps/web +pnpm install # 首次需要安装依赖 +pnpm dev # 启动开发服务器 → http://localhost:5174 +``` + +## 7. 变更记录 + +| 日期 | 变更 | +|------|------| +| 2026-06-02 | 初始创建 — 从 HMS 基座复制管理端前端 | diff --git a/wiki/architecture.md b/wiki/architecture.md index 05cec24..014d80a 100644 --- a/wiki/architecture.md +++ b/wiki/architecture.md @@ -1,8 +1,8 @@ --- title: 架构决策 -updated: 2026-06-01 +updated: 2026-06-02 status: active -tags: [architecture, base, multi-tenant, security] +tags: [architecture, base, multi-tenant, security, three-tier] --- # 架构决策 @@ -48,9 +48,35 @@ Android + iOS 跨平台首发。CustomPainter + Listener 手写性能满足 <16m ``` HMS (G:\hms) [只读] └─复制→ base.git (https://git.stableeasy.com/iven/base.git) - └─克隆→ nj.git (暖记 = 基座 + erp-diary + Flutter) + └─克隆→ nj.git (暖记 = 基座 + erp-diary + Flutter + 管理端) ``` +### 三端架构 + +``` +nj/ +├── crates/ # 后端 (Rust Axum, :3000) +│ ├── erp-server/ # 入口 + diary feature flag +│ └── erp-diary/ # 暖记业务模块 +├── apps/ +│ └── web/ # 管理端 (React + Ant Design, :5174) +│ └── vite.config.ts # proxy /api → :3000 +├── app/ # 学生端 (Flutter, :8080) +│ └── lib/features/ # 16 功能模块 +├── scripts/dev.sh # 统一启动脚本 (自动清理端口) +└── config/default.toml # 环境配置 (CORS=*) +``` + +### 来源追溯 + +| 组件 | 来源 | 说明 | +|------|------|------| +| crates/erp-* (基座 6 个) | base.git | 零开发 | +| crates/erp-diary | 新增 | ~5100 行 Rust | +| apps/web/ | HMS apps/web/ | React 管理面板复用 | +| app/ (Flutter) | 新增 | ~19500 行 Dart | +| scripts/dev.sh | 新增 | 三端统一启动 | + ### Cargo Workspace ``` @@ -104,12 +130,13 @@ nj/crates/ | 问题 | 级别 | 状态 | 说明 | |------|------|------|------| -| Feature Flag 未实现 | HIGH | 待做 | erp-server/Cargo.toml 无 `[features]` 段，所有模块无条件编译 | -| Docker 部署未验证 | HIGH | 待做 | docker/ 配置完善但 Dockerfile 不存在，未实际运行 | +| 管理端品牌仍是 HMS | HIGH | 待做 | 标题/Logo/颜色需替换为暖记品牌 | +| 管理端缺少暖记专用页面 | HIGH | 待做 | 班级管理/日记审核/贴纸管理等页面待添加 | +| Docker 部署未验证 | HIGH | 待做 | docker/ 配置完善但 Dockerfile 不存在 | | 上下文窗口耗尽 | MEDIUM | 已缓解 | CLAUDE.md §8 会话交接机制 | | Windows Defender 锁定 exe | MEDIUM | 需手动 | 排除 target/ 目录 | -| erp-plugin 超大文件 | LOW | 待重构 | manifest.rs (1809行) + data_service.rs (1907行) 超过 800 行限制 | -| erp-message module.rs 过大 | LOW | 待重构 | 1283 行，事件监听逻辑可拆分 | +| erp-plugin 超大文件 | LOW | 待重构 | manifest.rs 1809行 + data_service.rs 1907行 | +| Dashboard 部分数据加载失败 | LOW | 待做 | 统计 API 需适配暖记数据模型 | ### 历史教训 @@ -121,5 +148,6 @@ nj/crates/ | 日期 | 变更 | |------|------| +| 2026-06-02 | 补充三端架构、管理端复用说明、更新活跃问题 | | 2026-06-01 | 补充 Feature Flag 状态、超大文件发现 | | 2026-06-01 | 初始创建 — 架构决策、基座剥离记录、集成契约 | diff --git a/wiki/index.md b/wiki/index.md index 60bd713..ac93a9a 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,6 +1,6 @@ --- title: 暖记知识库首页 -updated: 2026-06-01 +updated: 2026-06-02 status: active --- @@ -10,39 +10,41 @@ status: active ## 关键数字 -> 最后更新: 2026-06-01 | 基线: main (c2a9579) +> 最后更新: 2026-06-02 | 基线: main (8111471) | 指标 | 值 | |------|-----| | Rust crate | 8 个（6 基座 + 1 入口 + erp-diary） | -| Rust 总代码 | ~51,459 行（256 个 .rs 文件） | +| Rust 总代码 | ~51,500 行 | | erp-diary 新增 | 5,108 行（41 个文件） | -| Dart 文件 | 70 个（~18,398 行，含生成代码 6,128 行） | +| Dart 文件 | 74 个（~19,500 行） | +| 管理端前端 (React) | ~317 个 TypeScript 文件 | | 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 新发现 | +| 数据库迁移 | 58 个（42 基座 + 15 diary + 1 role seed） | +| 后端测试 | 77 个通过 ✅ | +| 前端 BLoC 测试 | 84 个通过 ✅ | +| flutter analyze | 0 error ✅ | +| Git 提交 | 22 次 | -## 代码量分布 +## 三端架构 -| 组件 | 代码行数 | 文件数 | 占比 | -|------|---------|--------|------| -| 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%** | +``` +┌─────────────────────────────────────────────────────┐ +│ 暖记系统 │ +├──────────┬──────────────────┬───────────────────────┤ +│ 后端 API │ 管理端 Web │ 学生端 App │ +│ Rust/Axum │ React/Ant Design │ Flutter │ +│ :3000 │ :5174 │ :8080 │ +│ │ │ │ +│ erp-diary │ 用户管理 │ 手写日记 │ +│ erp-auth │ 角色权限 │ 日历/心情 │ +│ erp-core │ 审计日志 │ 班级/分享 │ +│ erp-config│ 系统配置 │ 贴纸/模板 │ +│ ... │ 插件管理 │ 成就/设置 │ +├──────────┴──────────────────┴───────────────────────┤ +│ PostgreSQL 16 + Redis 7 │ +└─────────────────────────────────────────────────────┘ +``` ## 系统数据流 @@ -71,14 +73,27 @@ JournalEntry RemoteJournalRepository 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、多租户、安全合规 +- [[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]] — 🆕 项目健康度评估、技术债全景、风险矩阵、改进建议 +- [[project-health]] — 项目健康度评估、技术债全景、风险矩阵、改进建议 ## 症状导航 @@ -86,19 +101,14 @@ JournalEntry RemoteJournalRepository |------|------|------|----------| | 笔画卡顿 >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 未实现 | +| 管理端登录白屏 | [[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 | ## 相关文档 @@ -110,3 +120,4 @@ JournalEntry RemoteJournalRepository | 技术债看板 | `docs/tech-debt-board.md` | | OpenDesign 原型 | `docs/opendesign/warm-notes-journal-app.md` | | 基座仓库 | https://git.stableeasy.com/iven/base.git | +| HMS 源码 (只读) | G:\hms |