# 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。
16. 所有逻辑功能配置默认打开；只有密钥、地址、三方账号等必须由环境提供的敏感值使用占位符或环境配置，不在默认配置里伪造可用凭证。
17. 所有业务逻辑、状态流转、权限判断、支付链路、异步流程都保持高密度逻辑注释，注释解释为什么这样处理和失败分支，不复述语法。

## 当前实现方式

- 框架：React + Vite。
- UI 组件库：MUI。
- 图表库：ECharts。
- 包管理器：pnpm。
- 页面：按业务放在 `src/features/*/pages/`。
- 应用壳：`src/app/App.jsx`、`src/app/layout/AdminLayout.jsx`、`src/app/router/routeConfig.ts`。
- 页面加载占位：`src/shared/ui/PageSkeleton.jsx`。
- 公共时间选择器：`src/shared/ui/TimeRangeFilter.jsx`，使用 `{ startMs, endMs }` 毫秒值作为输入输出。
- 全局资源组选择抽屉：`src/shared/ui/ResourceGroupSelectDrawer.jsx`，业务表单资源组字段统一使用其导出的 `ResourceGroupSelectField`，不在业务页面里重复手写普通下拉或资源组 ID 输入框。
- 顶部搜索弹窗：`src/features/search/components/SearchDialog.jsx`。
- MUI 主题：`src/theme.js`。
- CSS token：`src/styles/tokens.css`。
- 样式入口：`src/styles/app.css`，实际样式按 `src/styles/*.css`、`src/features/*/*.css` 和 `*.module.css` 拆分。
- 服务端状态：使用 `@tanstack/react-query`，共享入口在 `src/shared/query/` 和 `src/shared/hooks/useAdminQuery.js`。
- 接口契约：`contracts/admin-openapi.json` 是本仓库的前端 API 契约源；`pnpm gen:api` 只基于该契约生成 `src/shared/api/generated/schema.d.ts` 和 `src/shared/api/generated/endpoints.ts`。

## 目录规范

- `src/app/`：应用壳、Provider、鉴权上下文、路由守卫、统一路由配置和布局。
- `src/shared/`：跨业务共享的 API 基础层、UI 组件、hooks、工具和图表封装。
- `src/features/<module>/`：业务模块，内部放 `api.ts`、`routes.js`、`permissions.js`、`schema.ts`、`hooks/`、`components/`、`pages/`。
- 新增后台业务模块必须优先落在 `src/features/`，不要重新创建横向 `pages/`、`api/`、`components/` 目录。
- 新增模块优先复制 `admin-module.example.json`，改成业务配置后运行 `pnpm gen:module <config.json>`；它会生成 feature、权限常量、路由接入和 OpenAPI 契约。
- 只需要预览生成内容时运行 `pnpm gen:module <config.json> --dry-run`。
- `pnpm scaffold:feature <feature-name>` 是低层级骨架命令，只有在不需要权限/菜单/契约自动接入时使用。
- API 契约或权限变更后运行 `pnpm gen:api`。
- 前端 API 路径必须从 `src/shared/api/generated/endpoints.ts` 取，不要在 feature API 中重新手写路径。
- 表单提交前必须走模块内 `schema.ts` 或共享 schema 校验。

## 按需导入规则

- 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/shared/charts/` 内封装和加载，不要在页面里直接散落图表初始化逻辑。
- 页面和抽屉继续使用 `React.lazy` 做拆分加载。
- 顶部搜索弹窗继续使用 lazy 加载，不要静态塞进主入口。

## 样式规则

- 状态色不要随意改：
    - `--success`：运行中
    - `--warning`：警告
    - `--danger`：异常/危险操作
    - `--stopped`：已停止
- 新增颜色优先写入 token 或 theme，不要在多个组件里重复硬编码。
- 基础组件的视觉兼容优先改封装组件，不要让页面直接依赖 MUI 细节。
- 不添加卡片套卡片。
- 不添加无业务意义的说明区、营销区、空泛介绍区。

## 后台表格交互规则

- 表格空态只显示 `当前无数据`，创建入口放在页面工具栏，不放在空态里。
- 表格里的启用/禁用状态优先使用行内 Switch 快捷操作，不使用单独的启用/禁用图标按钮。
- 表格状态筛选使用 Select 下拉框，默认值为 `全部状态`，不使用状态 chip 组。
- 后台列表页的时间区间筛选必须使用统一的单入口时间区间筛选框（`src/shared/ui/TimeRangeFilter.jsx`）；不要在工具栏里并排放两个开始/结束时间输入框，也不要使用浏览器原生日期/时间输入样式。时间区间弹层内使用快捷项、日历和时分下拉点选，不使用手写时间文本框。
- 后台表单里的生效时间、有效期、投放时间等时间区间必须使用统一公共时间选择器（`src/shared/ui/TimeRangeFilter.jsx`）；不要并排放两个开始/结束时间输入框，也不要使用浏览器原生日期/时间输入样式。
- 资源组选择必须优先使用统一的 `src/shared/ui/ResourceGroupSelectDrawer.jsx` / `ResourceGroupSelectField`，点击输入框打开右侧资源组图标抽屉，点击资源组后自动回填并关闭，不要在业务页面里重复实现资源组 Select 下拉，也不要用普通文本框填写资源组 ID。
- 区域编辑弹窗必须同时包含区域基础字段和国家码字段；国家码使用可搜索多选下拉框，不再拆成独立“区域国家”弹窗。
- 头像、图片、封面等图片资源字段必须使用 `src/shared/ui/UploadField.jsx` 上传表单组件，不使用普通文本输入框承载 URL。
- 图片上传表单必须提供统一预览；`webp` 使用浏览器原生动效预览，`svga` 使用 SVGA 播放器预览，`pag` 使用 libpag + wasm 预览。
- BD Leader 创建弹窗不选择区域、不提交 `regionId`；创建结果按目标用户当前区域生成，若区域不对，先修复用户国家/区域映射，再创建 BD Leader。
- 区域创建和区域启用/禁用调用后台管理后端接口，不要求 user-service 新增对应 RPC。
- 国家创建和国家启用/禁用调用后台管理后端接口，不要求 user-service 新增对应 RPC。

## 验证要求

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

```bash
pnpm check:contracts
pnpm typecheck
pnpm lint
pnpm test
pnpm build
```

如果需要本地预览：

```bash
pnpm dev
```