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

name, description

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

UmiJS + ProComponents 开发规范

1. 技术栈

• 框架: UmiJS 4 + React 18 + TypeScript（严格模式）
• 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。

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