# AGENTS.md

## fan-standard-comp 使用规范

本项目使用 `fan-standard-comp@6.x` 作为主要业务组件库。该组件库基于 React 18 和 Ant Design 6。

开发或修改页面、表单、表格、筛选器、弹窗、抽屉以及页面布局时，应优先复用 `fan-standard-comp` 已提供的组件，不要重复实现相同能力。

### 组件资料读取顺序

优先读取当前安装版本中的资料：

1. `node_modules/fan-standard-comp/llms.txt`
2. `node_modules/fan-standard-comp/ai/component-index.json`
3. 索引中 `docs` 字段指向的组件文档
4. 必要时读取 `node_modules/fan-standard-comp/llms-full.txt`
5. 文档仍不足时读取当前安装版本的 TypeScript 类型声明

如果当前环境无法访问 `node_modules`，再读取在线文档：

1. `http://47.113.227.251:1203/doc-v6/`
2. `http://47.113.227.251:1203/doc-v6/llms.txt`
3. `http://47.113.227.251:1203/doc-v6/llms-full.txt`
4. `http://47.113.227.251:1203/doc-v6/ai/component-index.json`

在线资料仅作为兜底。使用在线资料时，应确认其内容与项目安装的 `fan-standard-comp` 版本一致；若版本不一致，以本地 npm 包内文档和 TypeScript 类型声明为准。

不要在任务开始时加载全部文档。先通过 `component-index.json` 按用途定位组件，再读取对应文档。

### 组件选择原则

- 基础表单控件优先使用 `Field`。
- 需要独立树选择控件时可使用 6.x 新增公共导出 `RefactorTreeSelect`。
- 配置化表单项和栅格布局优先使用 `ItemGroup`。
- 普通表单优先使用 `StandardForm`。
- 分步表单使用 `StepForm`，分页签表单使用 `TabForm`。
- 查询条件区域优先使用 `StandardFilter`。
- 普通业务表格优先使用 `StandardTable`。
- 需要接口请求、查询条件或实例操作的表格优先使用 `StandardTablePro`。
- 操作弹窗优先使用 `StandardModal`，侧边操作面板使用 `StandardDrawer`。
- `StandardDragModal` 已从 6.x 包根公共导出中移除，不要深层导入。
- 页面内容结构优先复用 `WrapperContent`、`SubfieldContent`、`SideCard` 和 `SplitterLayout`。
- 权限按钮组和表格操作列优先使用 `ButtonGroup`。
- 文件或图片上传优先使用 `Uploader`。
- 读取全局配置和 Ant Design 反馈实例时使用 `useFanContext`。
- 不要仅因为熟悉 Ant Design，就绕过组件库重新组合一套相同业务能力。

### 导入规范

组件、上下文 Hook 和工具统一从包根路径导入：

```tsx
import {
  Field,
  ItemGroup,
  RefactorTreeSelect,
  StandardFilter,
  StandardTable,
  StandardModal,
  useFanContext,
} from 'fan-standard-comp';
```

除非包根路径没有公开导出，否则不要从 `fan-standard-comp/es/...` 或 `fan-standard-comp/lib/...` 深层导入。

注意以下导出别名：

- `FieldComponent` 与 `Field` 指向同一组件，新增代码优先使用 `Field`。
- `RenderItemGroup` 与 `ItemGroup` 指向同一组件，新增代码优先使用 `ItemGroup`。

### 实现要求

使用组件前应检查对应文档中的：

- API 参数和默认值
- 示例代码
- 与 Ant Design 原始属性的关系
- 全局 `FanProvider` 配置
- 已知问题、实验状态和版本限制

配置化表单应尽量复用项目中现有的字段结构和转换逻辑，不要自行发明另一套字段协议。

当文档、类型声明和现有代码不一致时：

1. 优先参考当前安装版本的 TypeScript 声明。
2. 再检查项目中已经正常运行的同类用法。
3. 必要时检查组件实现源码。
4. 不确定的行为应明确说明，不要猜测不存在的属性。

修改完成后，应执行项目已有的类型检查、测试或构建命令。