feat: add TaskBoard demo and refactor project structure
This commit is contained in:
ken
85
.agent/skills/design/visual-standards/SKILL.md
Normal file
85
.agent/skills/design/visual-standards/SKILL.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
name: visual-standards
|
||||
description: 中后台应用视觉规范（Ant Design Pro 标准）。涵盖主题色、布局、排版、间距系统及操作区规范。所有 UI 界面必须严格遵循。
|
||||
---
|
||||
|
||||
# 视觉设计与交互规范 (Design System)
|
||||
|
||||
## 1. 原则与理念
|
||||
|
||||
- **Ant Design Only**: 严格遵循 Ant Design 5.0+ 默认视觉风格。
|
||||
- **High Density**: 适用于信息密集型中后台场景，优先紧凑布局。
|
||||
- **Consistency**: 同类操作必须使用相同的视觉表现。
|
||||
|
||||
## 2. 主题配置 (Theme)
|
||||
|
||||
全站统一采用 **Volcano (火山红)** 主题色，强调操作引导性与警示性。
|
||||
|
||||
```json
|
||||
{
|
||||
"token": {
|
||||
"colorPrimary": "#fa541c",
|
||||
"colorInfo": "#fa541c",
|
||||
"wireframe": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 布局规范 (Layout)
|
||||
|
||||
### 3.1 页面容器
|
||||
|
||||
- 所有页面必须使用 `PageContainer` 包裹。
|
||||
- **禁止双内边距**: 严禁在 `ProTable`、`ProForm` 外层再包裹 `Card`。ProComponents 自带卡片样式。
|
||||
- **错误示例**: `<Card><ProTable /></Card>` ❌
|
||||
|
||||
### 3.2 搜索筛选区
|
||||
|
||||
- **< 4 个字段**: 使用 ProTable 内置 Search (LightFilter 风格)。(Label 左对齐)
|
||||
- **>= 4 个字段**: 使用 `QueryFilter` 独立组件，配置 `layout="vertical"` (Label 在上)。
|
||||
- **视觉风格**: Search 区域必须与 Table 区域在视觉上分离 (Separated Mode)，中间有间隔 (`marginLG`)。
|
||||
|
||||
### 3.3 数据表格
|
||||
|
||||
- **列对齐**:
|
||||
- 文本 (Text): **左对齐** (默认)。
|
||||
- 数字/金额 (Money/Number): **右对齐** (必须设置 `align: 'right'`)。
|
||||
- 操作 (Action): **右对齐** 或固定在右侧。
|
||||
- 状态 (Status): **左对齐**，必须使用 `Tag` 或 `Badge`。
|
||||
- **操作栏**:
|
||||
- **通用规则**: 所有操作按钮必须带有 **Icon** 和 **边框** (type="default"/"primary"/"dashed")。**严禁**使用纯文本链接 (`<a>`)。
|
||||
- 主要操作 (Primary Action): 位于左上角/右上角，推荐 `type="primary"`。
|
||||
- 批量操作 (Batch Action): 位于左下角 (Alert 区域)。
|
||||
- 行操作 (Row Action): 必须使用 `Button` 组件，推荐 `type="text"` (无边框中性色，避免与红色 Delete 冲突)。若主题色为冷色调，可使用 `type="link"`。禁止直接使用 `<a>` 标签。
|
||||
|
||||
### 3.4 表单规范
|
||||
|
||||
- **模态框表单 (ModalForm)**:
|
||||
- 默认使用 **垂直布局** (`layout="vertical"`)，以适应移动端及长 Label。
|
||||
- 宽度建议：`width="600px"` (中型表单)，`width="400px"` (小型表单/简单修改)。
|
||||
- **页面级表单 (ProForm)**:
|
||||
- 使用 `Grid` 布局。
|
||||
- 分组标题：使用 `ProCard` 或 `ProForm.Group`。
|
||||
|
||||
## 4. 样式系统 (Styling)
|
||||
|
||||
### 4.1 零 CSS 策略 (Zero CSS)
|
||||
|
||||
- **绝对禁止**创建 `.css`, `.less`, `.scss` 文件。
|
||||
- **所有样式**必须通过 `theme.useToken()` 获取 Design Token 并在 JSX 中内联。
|
||||
- **常用 Token**:
|
||||
- 间距: `token.margin`, `token.padding`
|
||||
- 颜色: `token.colorBgContainer`, `token.colorTextSecondary`
|
||||
- 边框: `token.borderRadius`
|
||||
|
||||
### 4.2 排版 (Typography)
|
||||
|
||||
- 数字必须使用**等宽字体**或千分位格式化。
|
||||
- 金额必须保留 2 位小数，右对齐。
|
||||
- 二级文本使用 `token.colorTextSecondary`。
|
||||
|
||||
## 5. 交互反馈
|
||||
|
||||
- **危险操作** (删除/重置): 必须使用红色 (`danger`), 且必须有二次确认 (`Popconfirm` 或 `Modal`).
|
||||
- **成功/失败**: 操作后必须有 `message.success` 或 `message.error` 反馈。
|
||||
- **Loading**: 所有异步操作按钮必须带有 `loading` 状态。
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: umijs-procomponents
|
||||
description: UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖技术栈约束、组件用法、样式系统、服务层架构、国际化和图标管理。当项目使用 UmiJS + ProComponents 技术栈时，PM 必须将本 Skill 的要点注入给所有子 Agent。
|
||||
description: UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖技术栈约束、组件用法、服务层架构、国际化和图标管理。
|
||||
---
|
||||
|
||||
# UmiJS + ProComponents 开发规范
|
||||
@@ -30,97 +30,66 @@ description: UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖
|
||||
| 布局 | `ProLayout` / `PageContainer` |
|
||||
| 详情 | `ProDescriptions` |
|
||||
|
||||
### 2.3 ⚠️ 禁止双内边距
|
||||
## 3. 样式与视觉规范
|
||||
|
||||
- **严禁**在 `ProTable`、`QueryFilter`、`ProForm` 外层包裹 `Card` 组件。
|
||||
- **原因**: ProComponents 自带卡片样式，额外包裹导致双内边距问题。
|
||||
- **错误示例**: `<Card><ProTable /></Card>` ❌
|
||||
- **正确示例**: `<ProTable style={{ marginBottom: token.marginLG }} />` ✅
|
||||
**⚠️ 重要**: 本项目遵循严格的视觉设计系统。所有样式、布局、主题色定义请查阅 **[Visual Standards](../design/visual-standards/SKILL.md)**。
|
||||
|
||||
## 3. 搜索区域规范（Separated Card 模式）
|
||||
### 3.1 零 CSS 策略 (Zero CSS)
|
||||
|
||||
### 3.1 复杂度规则
|
||||
- **技术约束**: 禁止创建 CSS/Less/SCSS 文件。
|
||||
- 所有样式必须使用 Ant Design Design Token (`theme.useToken`).
|
||||
- 详见 Visual Standards 文档。
|
||||
|
||||
- **< 4 个搜索字段**: 使用 `ProTable` 内置 `search` 属性。
|
||||
- **>= 4 个搜索字段**: 使用独立 `QueryFilter` 组件，配置 `layout="vertical"`。
|
||||
## 4. 服务层架构
|
||||
|
||||
### 3.2 视觉结构
|
||||
|
||||
- 搜索区域: 直接使用 `QueryFilter`（自带白色背景和内边距）。
|
||||
- 背景色: `QueryFilter` **必须**设置白色背景（`token.colorBgContainer`）。
|
||||
- 表格区域: 直接使用 `ProTable`（自带卡片样式）。
|
||||
- 间距: `QueryFilter` 使用 `style={{ marginBottom: token.marginLG }}`。
|
||||
- **⚠️ 避免双内边距**: 不要在 `QueryFilter` 或 `ProTable` 外层再包裹 `div` 或 `Card` 添加 padding。
|
||||
|
||||
## 4. 样式系统
|
||||
|
||||
### 4.1 零 CSS 文件
|
||||
|
||||
- **严格**使用 Ant Design Design Tokens 内联样式。
|
||||
- 使用 `const { token } = theme.useToken()` 获取 token。
|
||||
- 间距调整: 使用 `style={{ marginBottom: token.marginLG }}` 而非外层容器。
|
||||
- **禁止**导入 `.module.css` 或外部样式表。
|
||||
|
||||
### 4.2 图标
|
||||
|
||||
- **统一**使用 `@ant-design/icons`。
|
||||
- 除非明确要求或用于特定品牌标志，否则不使用外部图标库、SVG 或 emoji。
|
||||
|
||||
### 4.3 UI 框架
|
||||
|
||||
- **严格**使用原生 Ant Design ProComponents。禁止自定义 UI/UX 设计工具。
|
||||
- 表单布局: 输入标签放在输入框上方（`layout="vertical"`）。
|
||||
|
||||
## 5. 服务层架构
|
||||
|
||||
### 5.1 真实服务层
|
||||
### 4.1 真实服务层
|
||||
|
||||
- 所有页面逻辑必须调用 `src/services/`。禁止在 JSX 中内联 mock 数据或逻辑。
|
||||
- **强制使用 useRequest**: 所有数据交互（包括查询、提交、删除）**必须**通过 `useRequest` hook 发起。
|
||||
- **禁止直接 request**: 严禁在组件内直接手动调用 `request` 方法（除非在极特殊的底层封装中）。`useRequest` 提供了标准化的 loading、error 和 data 状态管理，手动 `request` 会导致状态管理不一致。
|
||||
|
||||
### 5.2 统一 Mocking
|
||||
### 4.2 统一 Mocking
|
||||
|
||||
- 使用 UmiJS `mock/` 目录存放所有 mock 数据。禁止在组件中硬编码对象。
|
||||
|
||||
### 5.3 类型定义
|
||||
### 4.3 类型定义
|
||||
|
||||
- TypeScript 接口统一在 `data.d.ts` 中定义。
|
||||
|
||||
### 5.4 菜单配置
|
||||
### 4.4 菜单配置
|
||||
|
||||
- 菜单图标必须在 `src/app.ts` 中配置渲染逻辑（确保图标显示为图形而非文本）。
|
||||
- 菜单文案必须配置在 `src/locales/` 中，Key 以 `menu.` 开头（如 `menu.system.user`）。
|
||||
|
||||
## 6. 国际化 (i18n)
|
||||
## 5. 国际化 (i18n)
|
||||
|
||||
### 6.1 强制规则
|
||||
### 5.1 强制规则
|
||||
|
||||
- 所有面向用户的字符串**必须**使用 `intl.formatMessage` 或 `<FormattedMessage>`。
|
||||
- **每个** `formatMessage` 或 `FormattedMessage` 调用**必须**包含 `defaultMessage` 作为后备。
|
||||
- 示例: `intl.formatMessage({ id: 'key', defaultMessage: '默认文案' })`
|
||||
- 在 `src/locales/` 中维护翻译。
|
||||
|
||||
### 6.2 双语同步
|
||||
### 5.2 双语同步
|
||||
|
||||
- **必须**同时在 `src/locales/zh-CN.ts` 和 `en-US.ts` 中定义所有使用的 Key。
|
||||
- **严禁**仅添加中文而忽略英文，或仅添加英文而忽略中文。
|
||||
|
||||
### 6.3 QA 验证
|
||||
### 5.3 QA 验证
|
||||
|
||||
- 测试时必须在两种语言环境下验证页面显示。
|
||||
- 浏览器控制台不得出现 `[React Intl] Missing message` 警告。
|
||||
|
||||
## 7. Figma 图标导出规范
|
||||
## 6. Figma 图标导出规范
|
||||
|
||||
当 Figma 设计稿中包含图标元素时：
|
||||
|
||||
### 7.1 优先级原则
|
||||
### 6.1 优先级原则
|
||||
|
||||
1. **优先匹配 Ant Design Icons**: 检查设计稿中的图标是否可用 `@ant-design/icons` 替代。如果视觉上高度一致，**必须使用 Ant Design 图标**。
|
||||
2. **自定义图标导出**: 仅当 Ant Design Icons 中**没有匹配或视觉差异明显**时，才从 Figma 导出。
|
||||
|
||||
### 7.2 导出流程
|
||||
### 6.2 导出流程
|
||||
|
||||
1. 使用 Figma MCP 获取图标设计详情。
|
||||
2. 导出为 **SVG 格式**，保存到 `src/assets/icons/`。
|
||||
@@ -128,7 +97,7 @@ description: UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖
|
||||
4. 封装为 React 组件存放 `src/components/Icons/`。
|
||||
5. 在 `src/components/Icons/index.ts` 中统一导出。
|
||||
|
||||
### 7.3 目录结构
|
||||
### 6.3 目录结构
|
||||
|
||||
```
|
||||
src/
|
||||
@@ -140,9 +109,3 @@ src/
|
||||
├── CustomChartIcon.tsx
|
||||
└── DataFlowIcon.tsx
|
||||
```
|
||||
|
||||
## 8. Ant Design 5 兼容性
|
||||
|
||||
- 使用 `open` 而非 `visible`。
|
||||
- 使用 `onOpenChange` 而非 `onVisibleChange`。
|
||||
- 对 Ant Design 5 更新极为警惕，避免使用废弃 API。
|
||||
|
||||
Reference in New Issue
Block a user