204 lines
8.3 KiB
Markdown
204 lines
8.3 KiB
Markdown
---
|
||
title: Web 前端
|
||
updated: 2026-04-25
|
||
status: stable
|
||
tags: [frontend, react, antd, vite, spa]
|
||
---
|
||
|
||
# Web 前端
|
||
|
||
> 从 [[index]] 导航。关联: [[erp-server]] [[infrastructure]] [[erp-health]]
|
||
|
||
## 1. 设计决策
|
||
|
||
- **组件库优先** — Ant Design 6，不自造轮子
|
||
- **状态集中** — Zustand 管理全局状态（4 个 store）
|
||
- **API 层分离** — HTTP 调用封装到 `src/api/`（28 个文件），组件不直接 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. UI 规范
|
||
|
||
### SaaS 后台布局
|
||
|
||
经典 SaaS 后台管理布局（响应式，支持移动端）：
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────┐
|
||
│ LOGO 搜索... 🔔 5 👤 Admin ▾ │ ← 顶部导航栏
|
||
├─────────┬───────────────────────────────────┤
|
||
│ 📊 首页 │ │
|
||
│ 👥 用户 │ 主内容区域 │
|
||
│ 🔐 权限 │ (多标签页切换) │
|
||
│ 📋 流程 │ │
|
||
│ 💬 消息 │ │
|
||
│ ⚙️ 设置 │ │
|
||
│─────────│ │
|
||
│ 📦 进销存│ │
|
||
│ 🏭 生产 │ │
|
||
│ 💰 财务 │ │
|
||
│─────────│ │
|
||
│ ▸ 更多 │ │
|
||
└─────────┴───────────────────────────────────┘
|
||
```
|
||
|
||
### UI 规则
|
||
|
||
- 使用 Ant Design 组件库，不自造轮子
|
||
- 中文优先，所有文案通过 i18n key 引用
|
||
- 支持暗色/亮色主题切换
|
||
- 侧边栏按模块分组：基础模块 / 行业模块
|
||
- 表单验证使用 Ant Design Form 的 validateRules
|
||
|
||
## 3. 关键文件 + 数据流
|
||
|
||
### 核心文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `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/` | 28 个 API 服务文件（含 7 个健康模块 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` | 插件多视图页面 |
|
||
|
||
**健康管理路由（10 条）**:
|
||
|
||
| 路径 | 页面 |
|
||
|------|------|
|
||
| `/health/patients` | 患者列表 |
|
||
| `/health/patients/:id` | 患者详情（5 个标签页：基本信息/体征/化验/健康档案/随访） |
|
||
| `/health/patient-tags` | 患者标签管理 |
|
||
| `/health/doctors` | 医护管理 |
|
||
| `/health/schedules` | 排班管理（含日历视图） |
|
||
| `/health/appointments` | 预约管理（含状态流转） |
|
||
| `/health/follow-up-tasks` | 随访任务列表 |
|
||
| `/health/follow-up-records` | 随访记录 |
|
||
| `/health/consultations` | 咨询会话列表 |
|
||
| `/health/consultations/:id` | 咨询详情（含消息 + 导出） |
|
||
|
||
### 健康模块共享组件（12 个）
|
||
|
||
| 组件 | 用途 |
|
||
|------|------|
|
||
| `StatusTag` | 预约/随访/咨询状态标签（含单元测试） |
|
||
| `PatientSelect` | 患者搜索选择器（远程搜索） |
|
||
| `DoctorSelect` | 医护搜索选择器（远程搜索） |
|
||
| `CalendarView` | 排班日历视图 |
|
||
| `ExportButton` | 咨询记录导出按钮 |
|
||
| `VitalSignsChart` | 多指标趋势图：概览卡片条(5 指标 sparkline) + 点击展开详情折线图 |
|
||
| `VitalSignsTab` | 患者详情-体征标签页 |
|
||
| `LabReportsTab` | 患者详情-化验报告标签页 |
|
||
| `HealthRecordsTab` | 患者详情-健康档案标签页 |
|
||
| `FollowUpTab` | 患者详情-随访标签页 |
|
||
| `ImagePreview` | 图片预览组件 |
|
||
|
||
### 集成契约
|
||
|
||
| 方向 | 模块 | 接口 | 触发时机 |
|
||
|------|------|------|---------|
|
||
| 调用 → | [[erp-server]] | `/api/v1/*` REST | 所有数据操作 |
|
||
| 调用 → | [[erp-server]] | `ws://localhost:3000/ws/*` | WebSocket |
|
||
| 消费 ← | 插件系统 | `plugin.toml` schema | 动态生成插件页面 |
|
||
| 调用 → | [[erp-health]] | `/api/v1/health/*` | 健康模块所有数据操作 |
|
||
|
||
## 4. 代码逻辑
|
||
|
||
### 状态管理（4 个 Zustand Store）
|
||
|
||
| Store | 状态 |
|
||
|-------|------|
|
||
| `app.ts` | theme(light/dark), sidebarCollapsed |
|
||
| `auth.ts` | user, isAuthenticated, localStorage 持久化 |
|
||
| `message.ts` | unreadCount, recentMessages, 请求去重 |
|
||
| `plugin.ts` | plugins 列表, 动态菜单, schema 缓存, 请求去重 |
|
||
|
||
### 健康模块 API 文件（7 个）
|
||
|
||
| 文件 | 覆盖端点 |
|
||
|------|---------|
|
||
| `patients.ts` | 患者 CRUD + 标签 + 健康摘要 + 家庭成员 |
|
||
| `doctors.ts` | 医护档案 CRUD |
|
||
| `appointments.ts` | 预约 CRUD + 状态流转 |
|
||
| `healthData.ts` | 体征/化验/健康档案/趋势 |
|
||
| `followUp.ts` | 随访任务 + 记录 |
|
||
| `consultations.ts` | 咨询会话 + 消息 + 导出 |
|
||
| `articles.ts` | 健康文章 |
|
||
|
||
### 前端单元测试（3 个）
|
||
|
||
| 文件 | 测试内容 |
|
||
|------|---------|
|
||
| `constants/health.test.ts` | 健康常量定义验证 |
|
||
| `hooks/useThemeMode.test.ts` | 暗色模式 hook |
|
||
| `pages/health/components/StatusTag.test.tsx` | 状态标签渲染 |
|
||
|
||
### 插件页面系统
|
||
|
||
插件通过 `plugin.toml` schema 声明页面，前端根据 schema 动态生成：
|
||
- `PluginCRUDPage` — 标准列表+表单
|
||
- `PluginTabsPage` — 标签页切换
|
||
- `PluginTreePage` — 树形展示
|
||
- `PluginGraphPage` — 关系图谱
|
||
- `PluginKanbanPage` — 看板视图
|
||
- `PluginDashboardPage` — 仪表盘
|
||
|
||
⚡ **不变量**: 插件菜单由 `plugin.ts` store 从 API 动态获取，不硬编码
|
||
⚡ **不变量**: API client 在请求前 30s 检查 token 过期，提前刷新避免 401
|
||
⚡ **不变量**: DatePicker 返回 dayjs 对象，提交前必须 `.format('YYYY-MM-DD')` 转字符串
|
||
|
||
### 代理配置
|
||
|
||
```
|
||
http://localhost:5174/api/* → http://localhost:3000/* (API)
|
||
ws://localhost:5174/ws/* → ws://localhost:3000/* (WebSocket)
|
||
```
|
||
|
||
## 5. 活跃问题 + 陷阱
|
||
|
||
⚠️ Ant Design 6 废弃 `destroyOnClose`，应使用 `destroyOnHidden`
|
||
⚠️ Ant Design 6 废弃 API 警告（`valueStyle`/`Spin tip`/`trailColor`）已在历史版本中修复
|
||
⚠️ `antd.setScaleParam` 强制回流 64ms — antd 内部问题，无法直接修复
|
||
|
||
### 历史教训
|
||
|
||
- DatePicker 提交 dayjs 对象而非字符串 → 后端 422 `birth_date trailing input` — 必须调用 `.format('YYYY-MM-DD')`
|
||
- 预约表单医护字段标为可选但后端必填 → 400 `doctor_id is required` — 医护为必填（CAS 排班需要）
|
||
- 趋势图后端 DTO `Vec<(NaiveDate, f64)>` 序列化为 JSON 数组 `[[date, value]]` 而非对象 `[{date, value}]` → 改用 `Vec<DataPoint>` 修复；前端 `extractData` 需同时处理 `ApiResponse` 包装和裸数组两种响应格式
|
||
- `IndicatorTimeseriesResp` 返回 `{ indicator, data: [...] }` 包装对象，不是裸数组 — `Array.isArray(res)` 为 false，必须从 `res.data` 取值
|
||
|
||
## 6. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|------|------|
|
||
| 2026-04-26 | 从 CLAUDE.md 迁移：UI 布局规范（§8） |
|
||
| 2026-04-26 | VitalSignsChart 重设计：概览卡片条 + 点击展开详情图，5 指标独立 Y 轴 |
|
||
| 2026-04-25 | 全面更新：10 条健康路由、12 个共享组件、7 个健康 API 文件、3 个单元测试 |
|
||
| 2026-04-24 | 添加小程序交叉引用 |
|
||
| 2026-04-23 | 重构为 5 节结构，更新为当前完整前端状态 |
|