444 lines
14 KiB
Markdown
444 lines
14 KiB
Markdown
# 开发者参考指南
|
||
|
||
## 📖 快速开始
|
||
|
||
欢迎使用智慧农业生产管理系统开发者参考指南！本指南将帮助您快速了解项目的页面结构、开发规范和最佳实践。
|
||
|
||
### 🚀 开发前准备
|
||
|
||
1. **环境要求**
|
||
- Node.js 16+
|
||
- npm 或 yarn
|
||
- 现代浏览器 (Chrome, Firefox, Safari, Edge)
|
||
|
||
2. **项目启动**
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
3. **开发工具**
|
||
- VS Code (推荐)
|
||
- React Developer Tools
|
||
- Tailwind CSS IntelliSense
|
||
|
||
## 📁 项目结构概览
|
||
|
||
```
|
||
smart-crop-x/
|
||
├── 📂 docs/ # 项目文档
|
||
│ ├── 📄 Pages目录结构与开发规范.md # 详细开发规范
|
||
│ ├── 📄 AgriculturalMachinery模块页面结构示例.md
|
||
│ ├── 📄 LandInformation模块页面结构示例.md
|
||
│ ├── 📄 FarmingOperation模块页面结构示例.md
|
||
│ ├── 📄 其他业务模块页面结构示例.md
|
||
│ ├── 📄 Pages目录结构设计总结.md
|
||
│ └── 📄 开发者参考指南.md # 本文档
|
||
├── 📂 src/
|
||
│ ├── 📂 components/ # 全局组件
|
||
│ ├── 📂 pages/ # 🎯 页面组件（重点开发区域）
|
||
│ ├── 📂 types/ # 类型定义
|
||
│ ├── 📂 utils/ # 工具函数
|
||
│ ├── 📂 lib/ # 库文件
|
||
│ ├── 📂 App.tsx
|
||
│ └── 📂 main.tsx
|
||
├── 📂 public/
|
||
├── 📄 package.json
|
||
└── 📄 README.md
|
||
```
|
||
|
||
## 🎯 开发工作流
|
||
|
||
### Step 1: 查阅模块文档
|
||
开始开发前，请先查阅对应模块的页面结构文档：
|
||
|
||
| 模块 | 文档链接 | 主要功能 |
|
||
|------|----------|----------|
|
||
| 智能农机管理 | [AgriculturalMachinery模块页面结构示例.md](./AgriculturalMachinery模块页面结构示例.md) | 农机档案、驾驶员管理、设备监控等 |
|
||
| 地块信息管理 | [LandInformation模块页面结构示例.md](./LandInformation模块页面结构示例.md) | 地块档案、GIS地图、空间分析等 |
|
||
| 农事管理 | [FarmingOperation模块页面结构示例.md](./FarmingOperation模块页面结构示例.md) | 农事计划、任务管理、执行监控等 |
|
||
| 农资资产 | [其他业务模块页面结构示例.md](./其他业务模块页面结构示例.md#agriculturalasset-农资资产-模块) | 库存管理、采购、领用等 |
|
||
| AI模型 | [其他业务模块页面结构示例.md](./其他业务模块页面结构示例.md#aicro pmodel-ai模型-模块) | 数据感知、模型集成、决策支持等 |
|
||
| 水肥控制 | [其他业务模块页面结构示例.md](./其他业务模块页面结构示例.md#waterfertilizercontr ol-水肥控制-模块) | 智能灌溉、施肥配方等 |
|
||
| 中心配置 | [其他业务模块页面结构示例.md](./其他业务模块页面结构示例.md#centralconfig-中心配置-模块) | 租户管理、用户管理、系统监控等 |
|
||
|
||
### Step 2: 创建页面目录结构
|
||
按照规范创建标准的页面目录结构：
|
||
|
||
```bash
|
||
# 示例：创建农机档案录入页面
|
||
mkdir -p src/pages/AgriculturalMachinery/Archive/MachineryEntry
|
||
mkdir -p src/pages/AgriculturalMachinery/Archive/MachineryEntry/hooks
|
||
mkdir -p src/pages/AgriculturalMachinery/Archive/MachineryEntry/utils
|
||
mkdir -p src/pages/AgriculturalMachinery/Archive/MachineryEntry/components
|
||
```
|
||
|
||
### Step 3: 创建基础文件
|
||
创建标准的基础文件：
|
||
|
||
```bash
|
||
# 主组件
|
||
touch src/pages/AgriculturalMachinery/Archive/MachineryEntry/index.jsx
|
||
|
||
# 样式文件
|
||
touch src/pages/AgriculturalMachinery/Archive/MachineryEntry/index.css
|
||
|
||
# 类型定义
|
||
touch src/pages/AgriculturalMachinery/Archive/MachineryEntry/index.types.ts
|
||
|
||
# 常量定义
|
||
touch src/pages/AgriculturalMachinery/Archive/MachineryEntry/constants.js
|
||
```
|
||
|
||
### Step 4: 参考模板代码
|
||
从对应的模块文档中复制模板代码，并根据实际需求进行修改。
|
||
|
||
## 📋 快速参考速查表
|
||
|
||
### 1. 标准页面文件结构
|
||
```
|
||
PageName/
|
||
├── 📄 index.jsx # 主组件
|
||
├── 📄 index.css # 样式文件
|
||
├── 📄 index.types.ts # 类型定义
|
||
├── 📂 hooks/ # 页面专用Hooks
|
||
│ ├── 📄 usePageData.tsx # 数据管理
|
||
│ ├── 📄 usePageActions.tsx # 操作处理
|
||
│ └── 📄 use[Feature].tsx # 特定功能Hook
|
||
├── 📂 utils/ # 工具函数
|
||
│ ├── 📄 pageHelpers.tsx # 页面辅助函数
|
||
│ ├── 📄 validators.tsx # 表单验证
|
||
│ └── 📄 formatters.tsx # 数据格式化
|
||
├── 📄 constants.tsx # 页面常量
|
||
└── 📂 components/ # 子组件目录
|
||
└── 📂 [ComponentName]/ # 子组件
|
||
├── 📄 index.jsx
|
||
├── 📄 index.css
|
||
└── 📄 types.ts
|
||
```
|
||
|
||
### 2. 常用组件模板
|
||
|
||
#### 主组件模板
|
||
```jsx
|
||
import { useState, useEffect, useCallback } from 'react';
|
||
import { ComponentA } from './components/ComponentA';
|
||
import { ComponentB } from './components/ComponentB';
|
||
import { usePageData } from './hooks/usePageData';
|
||
import { usePageActions } from './hooks/usePageActions';
|
||
import './index.css';
|
||
|
||
export function PageName() {
|
||
const {
|
||
data,
|
||
loading,
|
||
error,
|
||
filters,
|
||
pagination,
|
||
handleFilterChange,
|
||
handlePageChange,
|
||
refreshData
|
||
} = usePageData();
|
||
|
||
const {
|
||
handleCreate,
|
||
handleEdit,
|
||
handleDelete,
|
||
handleExport
|
||
} = usePageActions(refreshData);
|
||
|
||
if (loading) return <div>加载中...</div>;
|
||
if (error) return <div>错误: {error}</div>;
|
||
|
||
return (
|
||
<div className="page-name">
|
||
<div className="page-header">
|
||
<h1>页面标题</h1>
|
||
<div className="page-actions">
|
||
<button onClick={handleCreate}>新增</button>
|
||
<button onClick={handleExport}>导出</button>
|
||
</div>
|
||
</div>
|
||
|
||
<ComponentA
|
||
filters={filters}
|
||
onFilterChange={handleFilterChange}
|
||
/>
|
||
|
||
<ComponentB
|
||
data={data}
|
||
pagination={pagination}
|
||
onPageChange={handlePageChange}
|
||
onEdit={handleEdit}
|
||
onDelete={handleDelete}
|
||
/>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Hook模板 (usePageData.js)
|
||
```javascript
|
||
import { useState, useEffect, useCallback } from 'react';
|
||
import { getApiData } from '@/apis/module';
|
||
import { showMessage } from '@/utils/message';
|
||
|
||
export function usePageData() {
|
||
const [data, setData] = useState([]);
|
||
const [loading, setLoading] = useState(false);
|
||
const [error, setError] = useState(null);
|
||
const [filters, setFilters] = useState({});
|
||
const [pagination, setPagination] = useState({
|
||
current: 1,
|
||
pageSize: 10,
|
||
total: 0
|
||
});
|
||
|
||
// 获取数据
|
||
const fetchData = useCallback(async () => {
|
||
setLoading(true);
|
||
setError(null);
|
||
|
||
try {
|
||
const params = {
|
||
...filters,
|
||
page: pagination.current,
|
||
pageSize: pagination.pageSize
|
||
};
|
||
|
||
const response = await getApiData(params);
|
||
setData(response.data.list);
|
||
setPagination(prev => ({
|
||
...prev,
|
||
total: response.data.total
|
||
}));
|
||
} catch (err) {
|
||
setError(err.message);
|
||
showMessage('error', '获取数据失败');
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
}, [filters, pagination.current, pagination.pageSize]);
|
||
|
||
// 初始加载
|
||
useEffect(() => {
|
||
fetchData();
|
||
}, [fetchData]);
|
||
|
||
// 处理筛选变化
|
||
const handleFilterChange = useCallback((newFilters) => {
|
||
setFilters(newFilters);
|
||
setPagination(prev => ({ ...prev, current: 1 }));
|
||
}, []);
|
||
|
||
// 处理分页变化
|
||
const handlePageChange = useCallback((page) => {
|
||
setPagination(prev => ({ ...prev, current: page }));
|
||
}, []);
|
||
|
||
return {
|
||
data,
|
||
loading,
|
||
error,
|
||
filters,
|
||
pagination,
|
||
handleFilterChange,
|
||
handlePageChange,
|
||
refreshData: fetchData
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 类型定义模板
|
||
```typescript
|
||
export interface RecordType {
|
||
id: string;
|
||
name: string;
|
||
status: StatusType;
|
||
createdAt: string;
|
||
updatedAt: string;
|
||
// ... 其他字段
|
||
}
|
||
|
||
export type StatusType = 'active' | 'inactive' | 'pending';
|
||
|
||
export interface Filters {
|
||
name?: string;
|
||
status?: StatusType;
|
||
dateRange?: [string, string];
|
||
}
|
||
|
||
export interface PaginationState {
|
||
current: number;
|
||
pageSize: number;
|
||
total: number;
|
||
}
|
||
|
||
export interface ComponentProps {
|
||
data: RecordType[];
|
||
loading: boolean;
|
||
error: string | null;
|
||
filters: Filters;
|
||
pagination: PaginationState;
|
||
onPageChange: (page: number) => void;
|
||
onEdit: (record: RecordType) => void;
|
||
onDelete: (id: string) => void;
|
||
}
|
||
```
|
||
|
||
### 3. 常用子组件类型
|
||
|
||
| 组件类型 | 功能描述 | 使用场景 |
|
||
|----------|----------|----------|
|
||
| Form | 表单组件 | 数据录入、编辑 |
|
||
| List | 列表组件 | 数据展示 |
|
||
| Table | 表格组件 | 结构化数据展示 |
|
||
| Filter | 筛选组件 | 数据过滤 |
|
||
| Search | 搜索组件 | 关键词搜索 |
|
||
| Modal | 弹窗组件 | 详情展示、编辑 |
|
||
| Card | 卡片组件 | 信息概览 |
|
||
| Chart | 图表组件 | 数据可视化 |
|
||
| Map | 地图组件 | 位置信息展示 |
|
||
| Timeline | 时间线组件 | 流程展示 |
|
||
| Status | 状态组件 | 状态标识 |
|
||
| Actions | 操作组件 | 按钮操作组 |
|
||
|
||
### 4. 常用Hook模式
|
||
|
||
| Hook名称 | 功能描述 | 使用示例 |
|
||
|----------|----------|----------|
|
||
| usePageData | 页面数据管理 | 获取列表数据、分页、筛选 |
|
||
| usePageActions | 页面操作处理 | 增删改查、导出 |
|
||
| useForm | 表单状态管理 | 表单数据、验证、提交 |
|
||
| useModal | 弹窗状态管理 | 显示/隐藏弹窗 |
|
||
| useTable | 表格状态管理 | 选择、排序、筛选 |
|
||
| useChart | 图表数据管理 | 数据处理、配置 |
|
||
| useMap | 地图状态管理 | 标记、图层、交互 |
|
||
| useWebSocket | WebSocket连接 | 实时数据更新 |
|
||
|
||
## 🛠️ 开发工具推荐
|
||
|
||
### VS Code 插件
|
||
```json
|
||
{
|
||
"recommendations": [
|
||
"bradlc.vscode-tailwindcss",
|
||
"esbenp.prettier-vscode",
|
||
"ms-vscode.vscode-typescript-next",
|
||
"formulahendry.auto-rename-tag",
|
||
"christian-kohler.path-intellisense",
|
||
"ms-vscode.vscode-json",
|
||
"yzhang.markdown-all-in-one"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 代码片段
|
||
创建 `.vscode/snippets.json`：
|
||
|
||
```json
|
||
{
|
||
"React Component Template": {
|
||
"prefix": "rfc",
|
||
"body": [
|
||
"import { useState, useEffect, useCallback } from 'react';",
|
||
"import { usePageData } from './hooks/usePageData';",
|
||
"import { usePageActions } from './hooks/usePageActions';",
|
||
"import './index.css';",
|
||
"",
|
||
"export function ${1:ComponentName}() {",
|
||
" const {",
|
||
" data,",
|
||
" loading,",
|
||
" error,",
|
||
" filters,",
|
||
" pagination,",
|
||
" handleFilterChange,",
|
||
" handlePageChange,",
|
||
" refreshData",
|
||
" } = usePageData();",
|
||
"",
|
||
" const {",
|
||
" handleCreate,",
|
||
" handleEdit,",
|
||
" handleDelete",
|
||
" } = usePageActions(refreshData);",
|
||
"",
|
||
" return (",
|
||
" <div className=\"${2:component-name}\">",
|
||
" ${3:// 组件内容}",
|
||
" </div>",
|
||
" );",
|
||
"}"
|
||
],
|
||
"description": "React Component with hooks template"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📝 开发检查清单
|
||
|
||
### ✅ 开发前检查
|
||
- [ ] 已查阅对应模块的页面结构文档
|
||
- [ ] 已了解功能需求和业务逻辑
|
||
- [ ] 已确认UI设计和交互规范
|
||
- [ ] 已准备好开发环境和工具
|
||
|
||
### ✅ 开发中检查
|
||
- [ ] 按照标准目录结构创建文件
|
||
- [ ] 使用TypeScript定义完整类型
|
||
- [ ] 遵循代码规范和命名约定
|
||
- [ ] 实现错误处理和加载状态
|
||
- [ ] 添加必要的注释和文档
|
||
- [ ] 编写单元测试
|
||
|
||
### ✅ 开发后检查
|
||
- [ ] 功能测试通过
|
||
- [ ] 样式在不同浏览器中正常
|
||
- [ ] 性能优化达标
|
||
- [ ] 无console错误信息
|
||
- [ ] 代码审查通过
|
||
- [ ] 文档更新完整
|
||
|
||
## 🔗 常用链接
|
||
|
||
### 📚 文档链接
|
||
- [Pages目录结构与开发规范](./Pages目录结构与开发规范.md) - 详细开发规范
|
||
- [AgriculturalMachinery模块示例](./AgriculturalMachinery模块页面结构示例.md) - 农机管理模块
|
||
- [LandInformation模块示例](./LandInformation模块页面结构示例.md) - 地块信息模块
|
||
- [FarmingOperation模块示例](./FarmingOperation模块页面结构示例.md) - 农事管理模块
|
||
- [其他业务模块示例](./其他业务模块页面结构示例.md) - 其他模块
|
||
- [设计总结](./Pages目录结构设计总结.md) - 完整设计总结
|
||
|
||
### 🛠️ 外部资源
|
||
- [React官方文档](https://react.dev/)
|
||
- [TypeScript官方文档](https://www.typescriptlang.org/)
|
||
- [Tailwind CSS官方文档](https://tailwindcss.com/)
|
||
- [shadcn/ui组件库](https://ui.shadcn.com/)
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 如何开始开发一个新页面？
|
||
A: 1. 查阅对应模块文档 → 2. 创建标准目录结构 → 3. 复制模板代码 → 4. 根据需求修改
|
||
|
||
### Q: 组件拆分的原则是什么？
|
||
A: 代码超过100行、承担多个职责、需要复用、逻辑复杂时考虑拆分
|
||
|
||
### Q: 如何处理API请求？
|
||
A: 使用自定义Hook封装API请求逻辑，参考usePageData模板
|
||
|
||
### Q: 类型定义应该放在哪里？
|
||
A: 页面级别类型放在index.types.ts，组件级别类型放在组件目录的types.ts
|
||
|
||
### Q: 如何进行样式开发？
|
||
A: 使用Tailwind CSS，页面级样式放在index.css，组件级样式放在组件目录的index.css
|
||
|
||
### Q: 遇到问题怎么办？
|
||
A: 1. 查阅相关文档 → 2. 查看现有代码示例 → 3. 咨询团队负责人 → 4. 记录解决方案
|
||
|
||
---
|
||
|
||
💡 **提示**: 建议将本指南添加到浏览器书签，开发时随时查阅！ |