nuwax / rules

---
description: 智能体平台前端项目开发规则和最佳实践
alwaysApply: false
---
# 智能体平台前端项目开发规则

## 项目概述
这是一个基于 React 18 + UmiJS Max + Ant Design 的智能体平台前端项目，提供智能体开发、管理和使用的完整解决方案。

## 技术栈规范

### 核心技术
- **前端框架**: React 18 (函数组件 + Hooks)
- **UI 组件库**: Ant Design 5.x + ProComponents
- **图形引擎**: AntV X6 (流程图、图可视化)
- **框架工具**: UmiJS Max 4.x (约定式路由、插件体系)
- **状态管理**: UmiJS 内置 model (主要方案)
- **类型检查**: TypeScript 5.x
- **样式方案**: CSS Modules + Less (禁止全局污染)
- **包管理**: pnpm (Node.js > 18.0.0)

### 代码规范

#### 文件命名
- 组件文件：PascalCase (如 `UserProfile.tsx`)
- 工具文件：camelCase (如 `formatDate.ts`)
- 样式文件：与组件同名 (如 `UserProfile.less`)
- 类型文件：camelCase + `.types.ts` 后缀

#### 组件开发规范
```typescript
// 组件必须包含详细注释
/**
 * 用户资料组件
 * @param {Object} props - 组件属性
 * @param {string} props.userId - 用户ID
 * @param {boolean} props.editable - 是否可编辑
 * @param {Function} props.onSave - 保存回调
 * @returns {JSX.Element} 用户资料组件
 */
interface UserProfileProps {
  userId: string;
  editable?: boolean;
  onSave?: (data: UserData) => void;
}

const UserProfile: React.FC<UserProfileProps> = ({ userId, editable = false, onSave }) => {
  // 组件实现
};
```

#### 性能优化要求
- 使用 `useMemo` 缓存计算结果
- 使用 `useCallback` 缓存函数引用
- 路由和组件必须懒加载
- 表单、表格优先使用 ProComponents
- 图形功能统一使用 AntV X6

#### 状态管理规范
- 全局状态使用 UmiJS model
- 局部状态使用 useState/useReducer
- 避免 props 层层传递
- 异步请求封装在 `services/` 目录

#### 样式规范
```less
// 使用 CSS Modules，避免全局污染
.userProfile {
  // 组件样式
  &__header {
    // 子元素样式
  }
  
  &--editable {
    // 修饰符样式
  }
}
```

## AppDev Web IDE 开发规范

### 文件结构规范
- **页面组件**: `pages/AppDev/components/` 目录下
- **自定义 Hooks**: `hooks/useAppDev*.ts` 命名规范
- **状态管理**: 使用 `models/appDev.ts` 中的 `useAppDevStore`
- **API 服务**: `services/appDev.ts` 统一管理

### 核心 Hooks 使用
```typescript
// 文件管理
const fileManagement = useAppDevFileManagement({
  projectId: workspace.projectId,
  onFileSelect: setActiveFile,
  onFileContentChange: updateFileContent,
});

// AI 聊天
const chat = useAppDevChat({
  projectId: workspace.projectId,
  onMessage: handleMessage,
});

// 开发服务器
const server = useAppDevServer({
  projectId: workspace.projectId,
  onStatusChange: handleServerStatus,
});
```

### 组件开发规范
- **Monaco Editor**: 使用 `pages/AppDev/components/MonacoEditor/`
- **文件树**: 使用 `pages/AppDev/components/FileTree/`
- **预览组件**: 使用 `pages/AppDev/components/Preview/`
- **页面头部**: 使用 `pages/AppDev/components/AppDevHeader.tsx`

### SSE 通信规范
- 使用 `utils/sseManager.ts` 管理连接
- 消息类型定义在 `types/interfaces/appDev.ts`
- 错误处理和重连机制必须实现
- 心跳检测间隔 30 秒

```
src/
├── components/          # 通用组件库
│   ├── base/           # 基础组件
│   ├── business-component/ # 业务组件
│   └── custom/         # 自定义组件
├── pages/              # 页面组件
│   ├── AppDev/         # 应用开发页面
│   │   ├── components/  # AppDev 专用组件
│   │   │   ├── FileTree/    # 文件树组件
│   │   │   ├── MonacoEditor/# Monaco 编辑器组件
│   │   │   ├── Preview/     # 预览组件
│   │   │   └── AppDevHeader.tsx # 页面头部组件
│   │   ├── index.tsx   # 主页面
│   │   └── index.less  # 页面样式
│   └── ...             # 其他页面
├── hooks/              # 自定义 Hooks
│   ├── useAppDevChat.ts      # AI 聊天功能
│   ├── useAppDevFileManagement.ts # 文件管理
│   ├── useAppDevServer.ts    # 开发服务器管理
│   └── ...             # 其他业务 Hooks
├── models/             # 数据模型和状态管理
│   └── appDev.ts       # 应用开发相关状态
├── services/           # API 服务层
│   ├── appDev.ts       # 应用开发相关 API
│   └── ...             # 其他业务 API
├── types/              # TypeScript 类型定义
│   ├── interfaces/     # 接口类型定义
│   └── ...             # 其他类型定义
├── utils/              # 工具函数
│   ├── monacoConfig.ts # Monaco Editor 配置
│   ├── sseManager.ts   # SSE 连接管理
│   └── ...             # 其他工具函数
├── constants/          # 常量定义
├── styles/             # 全局样式
└── examples/           # 功能演示页面
```

## 开发流程规范

### 1. 需求分析
- 充分理解用户需求，站在用户角度思考
- 作为产品经理，分析需求是否存在缺漏
- 选择最简单的解决方案满足需求

### 2. 代码实现
- 组件单一职责，文件不宜过大
- 所有异步请求封装在 services 目录
- 错误处理要完善，UI 友好提示
- 控制台输出详细日志

### 3. 测试验证
- 功能测试：确保功能正常运行
- 响应式测试：适配 PC 和移动端
- 性能测试：检查渲染性能
- 兼容性测试：确保浏览器兼容

### 4. 代码提交
- 使用 Prettier 格式化代码
- 通过 ESLint 检查规范
- 提交信息清晰明确
- 使用 Git 分支管理开发流程

## 特殊功能规范

### 主题背景切换
- 背景状态管理：`src/hooks/useGlobalSettings.ts`
- 背景选择器：`src/components/ThemeControlPanel/`
- 背景应用逻辑：`src/layouts/index.tsx`
- 支持8种预设背景，实时切换，状态持久化

### 图形功能开发
- 统一使用 AntV X6
- 封装为可复用组件
- 自适应容器大小
- 避免溢出或显示异常

### 响应式设计
- 优先使用 Ant Design 响应式布局
- 所有页面和组件必须适配主流设备
- 图形组件需自适应容器大小

## 代码质量要求

### 注释规范
- 每个组件、函数、服务方法都要有注释
- 注释内容包括：功能描述、参数说明、返回值说明、注意事项
- 复杂逻辑需额外说明实现思路

### 错误处理
- 完善的错误边界处理
- UI 友好的错误提示
- 控制台输出详细错误日志
- 重要操作需二次确认

### 性能监控
- 使用 React Profiler 检查性能瓶颈
- 定期使用 UmiJS 分析工具
- 优化首次加载时间
- 合理拆分业务模块

## 部署和运维

### 环境配置
- 开发环境：`config.development.ts`
- 生产环境：`config.production.ts`
- 支持多环境部署

### 构建优化
- 路由懒加载
- 组件懒加载
- 图片懒加载和压缩
- 代码分割和按需加载

## 注意事项

1. **全局UI提供者**：必须在 `app.tsx` 中放置全局UI提供者（如 Ant Design 的 ConfigProvider），因为某些页面没有布局
2. **依赖管理**：优先使用最新版本，使用 pnpm 管理依赖
3. **类型安全**：所有 Props、State 必须有类型注解
4. **代码复用**：善用 Ant Design ProComponents 提高开发效率
5. **文档更新**：新增功能及时更新 README.md 和项目文档

## 参考资源

- [React 官方文档](https://react.dev)
- [Ant Design 文档](https://ant.design)
- [UmiJS 文档](https://umijs.org)
- [AntV X6 文档](https://x6.antv.antgroup.com)

More agent context in nuwax-ai/nuwax

2 other files this repository gives its agents.