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/features/*/pages/。
应用壳：src/app/App.jsx、src/app/layout/AdminLayout.jsx、src/app/router/routeConfig.ts。
页面加载占位：src/shared/ui/PageSkeleton.jsx。
顶部搜索弹窗：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。
接口契约：pnpm gen:api 会先从 ../hyapp-server/server/admin 路由同步 contracts/admin-openapi.json，再生成 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 契约和后端 seed/routes 片段。
只需要预览生成内容时运行 pnpm gen:module <config.json> --dry-run。
pnpm scaffold:feature <feature-name> 是低层级骨架命令，只有在不需要权限/菜单/契约自动接入时使用。
后端路由或权限变更后先运行 pnpm gen:api，只需要同步契约时运行 pnpm sync:contract。
前端 API 路径必须从 src/shared/api/generated/endpoints.ts 取，不要在 feature API 中重新手写路径。
表单提交前必须走模块内 schema.ts 或共享 schema 校验。

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

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

import { Button } from "@mui/material";
import { Refresh } from "@mui/icons-material";

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

表格空态只显示 当前无数据，创建入口放在页面工具栏，不放在空态里。
表格里的启用/禁用状态优先使用行内 Switch 快捷操作，不使用单独的启用/禁用图标按钮。
表格状态筛选使用 Select 下拉框，默认值为 全部状态，不使用状态 chip 组。
区域编辑弹窗必须同时包含区域基础字段和国家码字段；国家码使用可搜索多选下拉框，不再拆成独立“区域国家”弹窗。
头像、图片、封面等图片资源字段必须使用 src/shared/ui/UploadField.jsx 上传表单组件，不使用普通文本输入框承载 URL。
图片上传表单必须提供统一预览；webp 使用浏览器原生动效预览，svga 使用 SVGA 播放器预览，pag 使用 libpag + wasm 预览。
BD Leader 创建弹窗必须使用区域下拉选择 regionId；目标用户原区域可以不同，创建成功后后端会把目标用户当前区域同步到所选区域。
区域创建和区域启用/禁用调用后台管理后端接口，不要求 user-service 新增对应 RPC。
国家创建和国家启用/禁用调用后台管理后端接口，不要求 user-service 新增对应 RPC。

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

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

如果需要本地预览：

pnpm dev