提交1 bmad搭建与项目启动 - ok
This commit is contained in:
444
docs/开发者参考指南.md
Normal file
444
docs/开发者参考指南.md
Normal file
@@ -0,0 +1,444 @@
|
||||
# 开发者参考指南
|
||||
|
||||
## 📖 快速开始
|
||||
|
||||
欢迎使用智慧农业生产管理系统开发者参考指南！本指南将帮助您快速了解项目的页面结构、开发规范和最佳实践。
|
||||
|
||||
### 🚀 开发前准备
|
||||
|
||||
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. 记录解决方案
|
||||
|
||||
---
|
||||
|
||||
💡 **提示**: 建议将本指南添加到浏览器书签，开发时随时查阅！
|
||||
Reference in New Issue
Block a user