96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# 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
|
||
```
|