3.6 KiB
3.6 KiB
AGENTS.md
项目约束
- 写代码不要猜。遇到不确定的依赖版本、导出名称、组件 API、项目结构、样式约定，先查本地文件、
node_modules或实际命令输出。 - 写前端或客户端项目时，不要添加无意义的描述文案。
- 包管理器固定使用
pnpm，不要生成 npm/yarn 锁文件。 - 基础 UI 使用 MUI，但视觉风格必须保持当前白色 HYApp 管理平台风格。
- 修改 MUI 组件颜色、尺寸、hover、focus、active 状态时，优先通过
src/theme.js或项目封装组件处理，避免在页面里硬写零散覆盖。 - 图表必须使用图表库。本项目使用 ECharts，不手写业务图表。
- 组件必须模块化。不要把页面、基础组件、图表、业务表格、抽屉混在单个文件里。
- 页面加载必须有动画占位图，并且占位图要铺满内容区域。
- 动画要覆盖页面切换、按钮、菜单、输入框、选择框、表格、图表、弹窗/抽屉等交互，同时保留
prefers-reduced-motion降级。 - Header 右侧放操作组件，左侧只放菜单展开/收起按钮和当前页 tab。
- 时间筛选属于总览页面内容，不属于 Header。
- 顶部搜索框点击后打开大搜索弹窗，输入后展示列表，列表项必须可点击。
- 左侧菜单 active 样式优先级必须高于 hover 样式。
- 侧边栏展开/收起按钮必须跟随状态切换图标。
- 展开态 Logo 区域和侧边栏宽度保持 248px。
当前实现方式
- 框架：React + Vite。
- UI 组件库：MUI。
- 图表库：ECharts。
- 包管理器：pnpm。
- 页面：
src/pages/OverviewPage.jsx、src/pages/ServicesPage.jsx和src/pages/UserManagementPage.jsx。 - 应用壳：
src/App.jsx，只做状态编排、懒加载页面、抽屉挂载和事件分发。 - 页面加载占位：
src/components/layout/PageSkeleton.jsx。 - 顶部搜索弹窗：
src/components/search/SearchDialog.jsx。 - MUI 主题：
src/theme.js。 - CSS token：
src/styles/tokens.css。 - 主要样式和动画：
src/styles/app.css。
目录规范
src/components/base/：项目基础组件封装，内部可以使用 MUI。src/components/layout/：布局组件。src/components/charts/：ECharts 封装和图表组件。src/components/service/：服务管理相关业务组件。src/pages/：页面级模块。src/constants/：导航、状态等常量。src/data/：演示数据。src/utils/：工具函数。
按需导入规则
- MUI 组件必须路径导入，例如：
import Button from "@mui/material/Button";
- MUI 图标必须路径导入，例如：
import Refresh from "@mui/icons-material/Refresh";
- 不要使用总入口：
import { Button } from "@mui/material";
import { Refresh } from "@mui/icons-material";
- ECharts 只在
src/components/charts/内封装和加载，不要在页面里直接散落图表初始化逻辑。 - 页面和抽屉继续使用
React.lazy做拆分加载。 - 顶部搜索弹窗继续使用 lazy 加载，不要静态塞进主入口。
样式规则
- 状态色不要随意改：
--success：运行中--warning：警告--danger：异常/危险操作--stopped：已停止
- 新增颜色优先写入 token 或 theme，不要在多个组件里重复硬编码。
- 基础组件的视觉兼容优先改封装组件，不要让页面直接依赖 MUI 细节。
- 不添加卡片套卡片。
- 不添加无业务意义的说明区、营销区、空泛介绍区。
验证要求
每次完成前端改动后至少运行：
pnpm build
如果需要本地预览：
pnpm dev