# AGENTS.md

## 项目约束

1. 写代码不要猜。遇到不确定的依赖版本、导出名称、组件 API、项目结构、样式约定，先查本地文件、`node_modules` 或实际命令输出。
2. 写前端或客户端项目时，不要添加无意义的描述文案。
3. 包管理器固定使用 `pnpm`，不要生成 npm/yarn 锁文件。
4. 基础 UI 使用 MUI，但视觉风格必须保持当前白色 HYApp 管理平台风格。
5. 修改 MUI 组件颜色、尺寸、hover、focus、active 状态时，优先通过 `src/theme.js` 或项目封装组件处理，避免在页面里硬写零散覆盖。
6. 图表必须使用图表库。本项目使用 ECharts，不手写业务图表。
7. 组件必须模块化。不要把页面、基础组件、图表、业务表格、抽屉混在单个文件里。
8. 页面加载必须有动画占位图，并且占位图要铺满内容区域。
9. 动画要覆盖页面切换、按钮、菜单、输入框、选择框、表格、图表、弹窗/抽屉等交互，同时保留 `prefers-reduced-motion` 降级。
10. Header 右侧放操作组件，左侧只放菜单展开/收起按钮和当前页 tab。
11. 时间筛选属于总览页面内容，不属于 Header。
12. 顶部搜索框点击后打开大搜索弹窗，输入后展示列表，列表项必须可点击。
13. 左侧菜单 active 样式优先级必须高于 hover 样式。
14. 侧边栏展开/收起按钮必须跟随状态切换图标。
15. 展开态 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 组件必须路径导入，例如：

```js
import Button from "@mui/material/Button";
```

- MUI 图标必须路径导入，例如：

```js
import Refresh from "@mui/icons-material/Refresh";
```

- 不要使用总入口：

```js
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 细节。
- 不添加卡片套卡片。
- 不添加无业务意义的说明区、营销区、空泛介绍区。

## 验证要求

每次完成前端改动后至少运行：

```bash
pnpm build
```

如果需要本地预览：

```bash
pnpm dev
```