# 开发者参考指南

## 📖 快速开始

欢迎使用智慧农业生产管理系统开发者参考指南！本指南将帮助您快速了解项目的页面结构、开发规范和最佳实践。

### 🚀 开发前准备

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. 记录解决方案

---

💡 **提示**: 建议将本指南添加到浏览器书签，开发时随时查阅！