# 开发指南 本文档为智慧农业生产管理系统的开发指南，帮助开发者快速了解项目结构、开发规范和最佳实践。 ## 📋 目录 - [环境准备](#环境准备) - [项目结构](#项目结构) - [开发规范](#开发规范) - [组件开发](#组件开发) - [状态管理](#状态管理) - [样式指南](#样式指南) - [API集成](#api集成) - [测试指南](#测试指南) - [调试技巧](#调试技巧) - [常见问题](#常见问题) ## 🛠️ 环境准备 ### 必需软件 - **Node.js**: >= 18.0.0 - **npm**: >= 8.0.0 或 **yarn**: >= 1.22.0 - **Git**: 最新版本 ### 推荐工具 - **IDE**: Visual Studio Code - **浏览器**: Chrome/Firefox (最新版本) - **Node管理**: nvm (可选) ### VSCode扩展推荐 项目已配置 `.vscode/extensions.json`，安装以下扩展获得最佳开发体验： ```json { "recommendations": [ "esbenp.prettier-vscode", "dbaeumer.vscode-eslint", "bradlc.vscode-tailwindcss", "ms-vscode.vscode-typescript-next", "formulahendry.auto-rename-tag", "christian-kohler.path-intellisense" ] } ``` ## 📁 项目结构详解 ### 核心目录 ``` src/ ├── components/ # 组件库 │ ├── ui/ # shadcn/ui基础组件 │ ├── common/ # 通用业务组件 │ └── layouts/ # 布局组件 ├── pages/ # 页面组件 ├── hooks/ # 自定义Hooks ├── lib/ # 工具库 ├── config/ # 配置文件 ├── types/ # TypeScript类型 ├── utils/ # 工具函数 ├── styles/ # 样式文件 └── assets/ # 静态资源 ``` ### 组件组织原则 1. **UI组件** (`components/ui/`): 纯UI组件，无业务逻辑 2. **业务组件** (`components/common/`): 包含业务逻辑的复用组件 3. **页面组件** (`pages/`): 具体页面实现，组合业务组件 4. **布局组件** (`components/layouts/`): 页面布局结构 ## 📏 开发规范 ### 代码规范 #### TypeScript规范 ```typescript // ✅ 使用类型注解 interface UserData { id: string name: string email: string } const getUser = async (id: string): Promise => { // 实现 } // ✅ 使用泛型 interface ApiResponse { data: T success: boolean } // ✅ 枚举使用 enum UserRole { ADMIN = 'admin', USER = 'user' } ``` #### React组件规范 ```typescript // ✅ 函数式组件 + Hooks interface UserCardProps { user: UserData onEdit?: (user: UserData) => void className?: string } export const UserCard: React.FC = ({ user, onEdit, className }) => { const [isEditing, setIsEditing] = useState(false) const handleEdit = useCallback(() => { onEdit?.(user) setIsEditing(true) }, [user, onEdit]) return (
{/* 组件内容 */}
) } ``` #### 命名规范 - **文件名**: kebab-case (`user-card.tsx`) - **组件名**: PascalCase (`UserCard`) - **变量名**: camelCase (`userName`) - **常量名**: UPPER_SNAKE_CASE (`API_BASE_URL`) - **类型名**: PascalCase (`UserData`) ### Git提交规范 使用 [Conventional Commits](https://conventionalcommits.org/) 规范： ``` ():