128 lines
4.3 KiB
Markdown
128 lines
4.3 KiB
Markdown
# HYApp 管理平台前端
|
||
|
||
基于 `React + Vite + MUI + ECharts` 从 `deploy-platform` 抽离出的白色主题 HYApp 管理平台前端。包管理器统一使用 `pnpm`。
|
||
|
||
## 用户要求
|
||
|
||
- 写代码不要猜：不确定的依赖、API、文件结构、现有约定，先查本地项目或依赖实际导出。
|
||
- 写前端或客户端项目时，不添加无意义的描述文案。
|
||
- 使用 `pnpm`。
|
||
- 页面包含：`总览`、`服务管理` 和 `用户管理`。
|
||
- 所有组件都要模块化，包括基础组件、布局组件、业务组件、图表组件。
|
||
- 基础 UI 使用 MUI，但整体风格必须统一为白色后台管理平台风格。
|
||
- 修改 MUI 组件颜色和样式时注意兼容性，优先通过主题和封装组件统一处理。
|
||
- 图表使用图表库，不手写业务图表。
|
||
- MUI、图标、图表能力尽量按需导入。
|
||
- 页面加载时需要占位图，占位图要有动画效果，并且刚好铺满内容区域。
|
||
- 动画效果要覆盖页面切换、按钮、菜单、弹窗、输入框、选择框、表格、图表等交互。
|
||
- Header 里的操作组件靠右，左侧只保留菜单收起按钮和当前页 tab。
|
||
- 时间筛选放在总览页面内容区，不放在 Header。
|
||
- 点击顶部搜索框打开大搜索弹窗，弹窗输入框展示可点击结果列表。
|
||
- 左侧菜单 hover 不能覆盖 active 视觉状态。
|
||
- 当前页 tab 需要有简单阴影效果。
|
||
- 总览旁边的菜单按钮负责展开/收起侧边栏，并且图标要跟随状态变化。
|
||
- Logo 区域和展开态侧边栏宽度要比初始版本更宽。
|
||
|
||
## 技术栈
|
||
|
||
- React 19
|
||
- Vite 8
|
||
- MUI 9
|
||
- ECharts 6
|
||
- pnpm
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
默认访问：
|
||
|
||
```text
|
||
http://localhost:7001
|
||
```
|
||
|
||
构建：
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
## 实现写法
|
||
|
||
- `src/App.jsx` 只负责应用状态、页面切换、抽屉挂载和数据分发。
|
||
- 页面模块放在 `src/pages/`：
|
||
- `OverviewPage.jsx`
|
||
- `ServicesPage.jsx`
|
||
- `UserManagementPage.jsx`
|
||
- 基础组件放在 `src/components/base/`，对 MUI 做项目级封装：
|
||
- `Button`
|
||
- `IconButton`
|
||
- `Card`
|
||
- `SearchBox`
|
||
- `FilterChip`
|
||
- `KpiCard`
|
||
- `SegmentControl`
|
||
- 布局组件放在 `src/components/layout/`：
|
||
- `Header`
|
||
- `Sidebar`
|
||
- `PageHead`
|
||
- `PageSkeleton`
|
||
- 图表组件放在 `src/components/charts/`，统一封装 ECharts：
|
||
- `EChart`
|
||
- `LineChart`
|
||
- `BarChart`
|
||
- `StatusDonut`
|
||
- `ChartCard`
|
||
- 服务业务组件放在 `src/components/service/`：
|
||
- `ServiceTable`
|
||
- `ServerRail`
|
||
- `DetailPanel`
|
||
- `RowActions`
|
||
- `ResourceCell`
|
||
- `StatusBadge`
|
||
- 常量、模拟数据和工具函数分别放在：
|
||
- `src/constants/`
|
||
- `src/data/`
|
||
- `src/utils/`
|
||
|
||
## 样式约定
|
||
|
||
- 全局设计 token 在 `src/styles/tokens.css`。
|
||
- 基础 reset 在 `src/styles/base.css`。
|
||
- 页面布局、模块样式、动画在 `src/styles/app.css`。
|
||
- MUI 主题集中在 `src/theme.js`，优先在主题层统一颜色、圆角、hover、focus 和组件兼容样式。
|
||
- 避免在页面里直接散落 MUI 组件样式；优先改项目封装组件。
|
||
- 状态色必须保持语义一致：
|
||
- 运行中：`--success`
|
||
- 警告：`--warning`
|
||
- 异常：`--danger`
|
||
- 已停止：`--stopped`
|
||
|
||
## 按需导入约定
|
||
|
||
- MUI 组件使用路径导入，例如 `@mui/material/Button`。
|
||
- MUI 图标使用路径导入，例如 `@mui/icons-material/Refresh`。
|
||
- 不使用 `@mui/material` 或 `@mui/icons-material` 总入口导入。
|
||
- ECharts 通过封装组件按需加载所需图表和组件能力。
|
||
- 页面使用 `React.lazy` 拆分：
|
||
- `OverviewPage`
|
||
- `ServicesPage`
|
||
- `DetailDrawer`
|
||
|
||
## 动画与加载
|
||
|
||
- 页面切换、卡片进入、表格行进入、图表进入、抽屉显示/消失都有统一动效。
|
||
- 按钮、菜单、输入框、选择框、筛选项、状态徽标、进度条都有 hover/focus/active 反馈。
|
||
- `PageSkeleton` 是页面加载占位图，使用 MUI `Skeleton`，铺满 `workspace` 内容区域。
|
||
- 支持 `prefers-reduced-motion: reduce` 降级。
|
||
- 顶部搜索弹窗按需加载，点击结果后打开服务详情。
|
||
- 侧边栏支持展开/收起状态，展开态宽度为 248px。
|
||
|
||
## 文案约定
|
||
|
||
- 不写无意义介绍、营销口号、功能解释文案。
|
||
- 只保留运维用户完成工作所需要的标签、状态、数据和操作。
|