hyapp-admin-platform/README.md

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

运行

pnpm install
pnpm dev

默认访问：

http://localhost:7001

构建：

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/shared/ui/；资源组字段统一使用 ResourceGroupSelectDrawer.jsx 导出的 ResourceGroupSelectField，点击输入框打开右侧资源组图标抽屉，选择后自动回填，不在业务页面里手写资源组下拉或资源组 ID 输入框。
• 布局组件放在 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。

文案约定

• 不写无意义介绍、营销口号、功能解释文案。
• 只保留运维用户完成工作所需要的标签、状态、数据和操作。