0bf1822fa9
- refactor(web): PatientDetail.tsx 拆分为 4 个子组件(737→334行) - refactor(web): 提取 usePaginatedData hook 消除重复分页状态 - feat(db): patient.id_number varchar(20)→varchar(255) 容纳加密值 - test(health): 添加预约模块集成测试(创建/列表/租户隔离) - test(plugin): 添加 6 个 SQL 注入 sanitize 测试 - fix(miniprogram): 7 个 service 文件 URL 构建规范化(params 对象) - fix(miniprogram): 跨平台字段名对齐(birth_date/start_time/end_time)
107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
---
|
||
title: Web 前端
|
||
updated: 2026-04-23
|
||
status: stable
|
||
tags: [frontend, react, antd, vite, spa]
|
||
---
|
||
|
||
# Web 前端
|
||
|
||
> 从 [[index]] 导航。关联: [[erp-server]] [[infrastructure]]
|
||
|
||
## 1. 设计决策
|
||
|
||
- **组件库优先** — Ant Design 6，不自造轮子
|
||
- **状态集中** — Zustand 管理全局状态（4 个 store）
|
||
- **API 层分离** — HTTP 调用封装到 `src/api/`（21 个文件），组件不直接 fetch
|
||
- **代理开发** — Vite 代理 `/api` 到后端 3000 端口
|
||
- **HashRouter** — 不需要服务端 fallback 配置，部署更稳健
|
||
- **懒加载** — 除 Login 外所有页面使用 `lazy()` 按需加载
|
||
|
||
### 版本（以实际 package.json 为准）
|
||
|
||
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
|
||
|
||
## 2. 关键文件 + 数据流
|
||
|
||
### 核心文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `apps/web/src/main.tsx` | React 入口 |
|
||
| `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 代理 |
|
||
|
||
> 微信小程序（患者端）是独立前端项目，详见 [[miniprogram]]
|
||
|
||
### 路由结构
|
||
|
||
**公开**: `/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 | 状态 |
|
||
|-------|------|
|
||
| `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-24 | 添加小程序交叉引用 |
|
||
| 2026-04-23 | 重构为 5 节结构，更新为当前完整前端状态 |
|