agent/.agent/skills/tech-stack/umijs-procomponents/SKILL.md

---
name: umijs-procomponents
description: UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖技术栈约束、组件用法、服务层架构、国际化和图标管理。
---

# UmiJS + ProComponents 开发规范

## 1. 技术栈

- **框架**: UmiJS 4 + React 18 + TypeScript（严格模式）
- **Visual**: **必须** 使用 `Ant Design Pro` 视觉标准 (`design/antd-visual-standards`)。
- **Type Safety**: 必须定义完整的 TypeScript 接口（API 请求/响应）。
- **Mock**: 必须使用 `src/mock` 目录下的 mock 文件，禁止组件内写死数据。
- **UI 库**: Ant Design 5 + ProComponents（ProTable, ProForm, ProLayout 等）
- **数据流**: `useRequest`（ahooks / Umi 内置）、Umi Models
- **路由/权限**: Umi Max 内置插件 — `access`、`initialState`、`request`、`model`、`locale`

## 2. ProComponents 使用规范

### 2.1 组件选型原则

- **配置优于代码**: 始终优先使用 ProComponents 的 `request` 属性处理数据加载。
- 利用 `valueType` 进行字段自动格式化。
- 只有在 ProComponents 无法满足极度复杂需求时才使用原生 Antd 或手动实现。

### 2.2 组件映射

| 场景      | 组件                                   |
| :-------- | :------------------------------------- |
| 列表/表格 | `ProTable`                             |
| 表单      | `ProForm` / `ModalForm` / `DrawerForm` |
| 搜索/筛选 | `QueryFilter` / `LightFilter`          |
| 布局      | `ProLayout` / `PageContainer`          |
| 详情      | `ProDescriptions`                      |

## 3. 样式与视觉规范

**⚠️ 重要**: 本项目遵循严格的视觉设计系统。所有样式、布局、主题色定义请查阅 **[Visual Standards](../design/visual-standards/SKILL.md)**。

### 3.1 零 CSS 策略 (Zero CSS)

- **技术约束**: 禁止创建 CSS/Less/SCSS 文件。
- 所有样式必须使用 Ant Design Design Token (`theme.useToken`).
- 详见 Visual Standards 文档。

## 4. 服务层架构

### 4.1 真实服务层

- 所有页面逻辑必须调用 `src/services/`。禁止在 JSX 中内联 mock 数据或逻辑。
- **强制使用 useRequest**: 所有数据交互（包括查询、提交、删除）**必须**通过 `useRequest` hook 发起。
- **禁止直接 request**: 严禁在组件内直接手动调用 `request` 方法（除非在极特殊的底层封装中）。`useRequest` 提供了标准化的 loading、error 和 data 状态管理，手动 `request` 会导致状态管理不一致。

### 4.2 统一 Mocking

- 使用 UmiJS `mock/` 目录存放所有 mock 数据。禁止在组件中硬编码对象。

### 4.3 类型定义

- TypeScript 接口统一在 `data.d.ts` 中定义。

### 4.4 菜单配置

- 菜单图标必须在 `src/app.ts` 中配置渲染逻辑（确保图标显示为图形而非文本）。
- 菜单文案必须配置在 `src/locales/` 中，Key 以 `menu.` 开头（如 `menu.system.user`）。

## 5. 国际化 (i18n)

### 5.1 强制规则

- 所有面向用户的字符串**必须**使用 `intl.formatMessage` 或 `<FormattedMessage>`。
- **每个** `formatMessage` 或 `FormattedMessage` 调用**必须**包含 `defaultMessage` 作为后备。
  - 示例: `intl.formatMessage({ id: 'key', defaultMessage: '默认文案' })`
- 在 `src/locales/` 中维护翻译。

### 5.2 双语同步

- **必须**同时在 `src/locales/zh-CN.ts` 和 `en-US.ts` 中定义所有使用的 Key。
- **严禁**仅添加中文而忽略英文，或仅添加英文而忽略中文。

### 5.3 QA 验证

- 测试时必须在两种语言环境下验证页面显示。
- 浏览器控制台不得出现 `[React Intl] Missing message` 警告。

## 6. Figma 图标导出规范

当 Figma 设计稿中包含图标元素时：

### 6.1 优先级原则

1. **优先匹配 Ant Design Icons**: 检查设计稿中的图标是否可用 `@ant-design/icons` 替代。如果视觉上高度一致，**必须使用 Ant Design 图标**。
2. **自定义图标导出**: 仅当 Ant Design Icons 中**没有匹配或视觉差异明显**时，才从 Figma 导出。

### 6.2 导出流程

1. 使用 Figma MCP 获取图标设计详情。
2. 导出为 **SVG 格式**，保存到 `src/assets/icons/`。
3. 文件命名: `icon-{功能名称}.svg`（全小写，中划线分隔）。
4. 封装为 React 组件存放 `src/components/Icons/`。
5. 在 `src/components/Icons/index.ts` 中统一导出。

### 6.3 目录结构

```
src/
├── assets/icons/
│   ├── icon-custom-chart.svg
│   └── icon-data-flow.svg
└── components/Icons/
    ├── index.ts
    ├── CustomChartIcon.tsx
    └── DataFlowIcon.tsx
```