feat(health): 添加 erp-health 健康管理模块骨架
Some checks failed
CI / rust-check (push) Has been cancelled
CI / rust-test (push) Has been cancelled
CI / frontend-build (push) Has been cancelled
CI / security-audit (push) Has been cancelled

新建 erp-health 原生 Rust crate,覆盖设计规格中定义的 5 大业务域:

- 16 个 SeaORM Entity(患者/家属/标签/医生/健康档案/体征/化验单/预约/排班/随访/咨询等)
- 16 表数据库迁移(含索引、外键、默认值、可回滚)
- 40+ API 路由骨架(患者管理/健康数据/预约排班/随访/咨询/医生管理)
- 12 个权限声明(health.patient/health-data/appointment/follow-up/consultation/doctor 各 .list/.manage)
- DTO / Service / Handler / Event 四层架构,Service 使用 todo!() 占位
- erp-server 集成:模块注册 + AppState FromRef 桥接 + 路由挂载

同步更新 CLAUDE.md 项目进度、wiki 知识库、设计规格文档。
This commit is contained in:
iven
2026-04-23 19:59:22 +08:00
parent 5ac8e18d74
commit ca50d32f6e
61 changed files with 6853 additions and 1208 deletions

View File

@@ -1,81 +1,103 @@
# frontend (Web 前端)
---
title: Web 前端
updated: 2026-04-23
status: stable
tags: [frontend, react, antd, vite, spa]
---
## 设计思想
# Web 前端
前端是一个 Vite + React SPA遵循 **UI 层只做展示** 的原则:
> 从 [[index]] 导航。关联: [[erp-server]] [[infrastructure]]
- **组件库优先** — 使用 Ant Design不自造轮子
- **状态集中** — Zustand 管理全局状态(主题、侧边栏、认证)
- **API 层分离** — HTTP 调用封装到 service 层,组件不直接 fetch
- **代理开发** — Vite 开发服务器代理 `/api` 到后端 3000 端口
## 1. 设计决策
版本实际使用情况(与设计规格有差异):
| 技术 | 规格 | 实际 |
|------|------|------|
| React | 18 | 19.2.4 |
| Ant Design | 5 | 6.3.5 |
| React Router | 7 | 7.14.0 |
- **组件库优先** — Ant Design 6不自造轮子
- **状态集中** — Zustand 管理全局状态4 个 store
- **API 层分离** — HTTP 调用封装到 `src/api/`21 个文件),组件不直接 fetch
- **代理开发** — Vite 代理 `/api` 到后端 3000 端口
- **HashRouter** — 不需要服务端 fallback 配置,部署更稳健
- **懒加载** — 除 Login 外所有页面使用 `lazy()` 按需加载
## 代码逻辑
### 版本(以实际 package.json 为准)
### 应用结构
```
main.tsx → App.tsx (ConfigProvider + HashRouter) → MainLayout → 各页面组件
```
React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.0.4 / TypeScript 6.0.2
### MainLayout 布局
经典 SaaS 后台管理布局:
- **左侧 Sidebar** — 可折叠暗色菜单,分组:首页/用户/权限/设置
- **顶部 Header** — 侧边栏切换 + 通知徽标(硬编码5) + 头像("Admin")
- **中间 Content** — React Router Outlet多标签页切换
- **底部 Footer** — 租户名 + 版本号
## 2. 关键文件 + 数据流
### 状态管理 (Zustand)
```typescript
appStore {
isLoggedIn: boolean // 未使用,无登录页
tenantName: string // 默认 "ERP Platform"
theme: 'light' | 'dark' // 切换 Ant Design 主题
sidebarCollapsed: boolean
toggleSidebar(), setTheme(), login(), logout()
}
```
### 开发服务器代理
```
http://localhost:5174/api/* → http://localhost:3000/* (API)
ws://localhost:5174/ws/* → ws://localhost:3000/* (WebSocket)
```
### 当前状态
- 布局壳体完整,暗色/亮色主题切换可用
- 只有一个路由 `/` → 占位 HomePage ("Welcome to ERP Platform")
- 无 API 调用、无认证流程、无真实数据
- 通知计数硬编码为 5用户名硬编码为 "Admin"
- 未实现 i18n代码中有 zh_CN locale 但文案硬编码)
## 关联模块
- **[[erp-server]]** — API 后端,通过 Vite proxy 连接
- **[[infrastructure]]** — Docker 提供 PostgreSQL + Redis
## 关键文件
### 核心文件
| 文件 | 职责 |
|------|------|
| `apps/web/src/main.tsx` | React 入口 |
| `apps/web/src/App.tsx` | 根组件ConfigProvider + 路由 |
| `apps/web/src/layouts/MainLayout.tsx` | 完整后台管理布局 |
| `apps/web/src/stores/app.ts` | Zustand 全局状态 |
| `apps/web/src/index.css` | TailwindCSS 导入 |
| `apps/web/src/App.tsx` | 路由定义(公开 + 受保护) |
| `apps/web/src/layouts/MainLayout.tsx` | SaaS 后台管理布局 |
| `apps/web/src/stores/` | 4 个 Zustand store |
| `apps/web/src/api/` | 21 个 API 服务文件 |
| `apps/web/vite.config.ts` | Vite 配置 + API 代理 |
| `apps/web/package.json` | 依赖声明 |
## 待实现 (按 Phase)
### 路由结构
| Phase | 内容 |
**公开**: `/login`
**受保护MainLayout 包裹)**:
| 路径 | 页面 |
|------|------|
| `/` | 首页 |
| `/users`, `/roles`, `/organizations` | 用户/角色/组织管理 |
| `/workflow` | 工作流 |
| `/messages` | 消息中心 |
| `/settings` | 系统设置 |
| `/plugins/admin`, `/plugins/market` | 插件管理/市场 |
| `/plugins/:pluginId/:entityName` | 插件 CRUD动态生成 |
| `/plugins/:pluginId/tabs|tree|graph|dashboard|kanban/:name` | 插件多视图页面 |
### 集成契约
| 方向 | 模块 | 接口 | 触发时机 |
|------|------|------|---------|
| 调用 → | [[erp-server]] | `/api/v1/*` REST | 所有数据操作 |
| 调用 → | [[erp-server]] | `ws://localhost:3000/ws/*` | WebSocket |
| 消费 ← | 插件系统 | `plugin.toml` schema | 动态生成插件页面 |
## 3. 代码逻辑
### 状态管理4 个 Zustand Store
| Store | 状态 |
|-------|------|
| Phase 2 | 登录页、用户管理页、角色权限页 |
| Phase 3 | 系统配置管理页 |
| Phase 4 | 工作流设计器、审批列表 |
| Phase 5 | 消息中心、通知设置 |
| `app.ts` | theme(light/dark), sidebarCollapsed |
| `auth.ts` | user, isAuthenticated, localStorage 持久化 |
| `message.ts` | unreadCount, recentMessages, 请求去重 |
| `plugin.ts` | plugins 列表, 动态菜单, schema 缓存, 请求去重 |
### 插件页面系统
插件通过 `plugin.toml` schema 声明页面,前端根据 schema 动态生成:
- `PluginCRUDPage` — 标准列表+表单
- `PluginTabsPage` — 标签页切换
- `PluginTreePage` — 树形展示
- `PluginGraphPage` — 关系图谱
- `PluginKanbanPage` — 看板视图
- `PluginDashboardPage` — 仪表盘
**不变量**: 插件菜单由 `plugin.ts` store 从 API 动态获取,不硬编码
**不变量**: API client 在请求前 30s 检查 token 过期,提前刷新避免 401
### 代理配置
```
http://localhost:5174/api/* → http://localhost:3000/* (API)
ws://localhost:5174/ws/* → ws://localhost:3000/* (WebSocket)
```
## 4. 活跃问题 + 陷阱
⚠️ Ant Design 6 废弃 API 警告(`valueStyle`/`Spin tip`/`trailColor`)已在历史版本中修复
⚠️ `antd.setScaleParam` 强制回流 64ms — antd 内部问题,无法直接修复
## 5. 变更记录
| 日期 | 变更 |
|------|------|
| 2026-04-23 | 重构为 5 节结构,更新为当前完整前端状态 |