# smart-agriculture-framework

**Repository Path**: edu360cloud/smart-agriculture-framework

## Basic Information

- **Project Name**: smart-agriculture-framework
- **Description**: 公司内部使用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-05
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧农业监控系统

一个基于现代Web技术栈构建的智慧农业环境监控系统，支持实时数据采集、设备管理、环境控制和数据可视化。

## 🌟 功能特性

### 核心功能
- **实时环境监控**: 温度、湿度、土壤湿度、光照强度等多维度数据监控
- **设备管理**: 支持传感器设备的添加、删除、状态监控和信息管理
- **数据可视化**: 实时图表展示、历史数据分析、数据统计报表
- **数据分析**: 支持数据筛选、排序、分页查看和导出功能
- **温室管理**: 20个大棚的环境监控和设备状态管理
- **自动控制记录**: 灌溉、补光、通风等自动化控制记录查看
- **响应式设计**: 适配桌面端、平板和移动设备的多终端访问

### 技术特性
- **轻量级架构**: 基于FastAPI + 原生JavaScript的简洁架构
- **RESTful API**: 标准化的API接口，支持数据采集和设备管理
- **实时数据**: 实时数据采集和展示，定时刷新机制
- **数据持久化**: 基于SQLite数据库的本地数据存储
- **设备模拟**: 多设备数据模拟器，支持真实环境数据生成
- **模块化设计**: 前后端分离，组件化JavaScript开发

## 🏗️ 系统架构

### 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        智慧农业监控系统                          │
├─────────────────────────────────────────────────────────────────┤
│                          用户界面层                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│  │   主仪表盘   │ │  设备管理   │ │  数据分析   │ │  温室概览   │ │
│  │  (index)    │ │ (device-mgmt)│ │(data-analysis)│(greenhouse) │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                          前端服务层                              │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Python HTTP Server (Port: 3000)             │ │
│  │  • 静态资源服务    • HTML/CSS/JS    • 响应式设计             │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                          应用服务层                              │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   FastAPI (Port: 8001)                     │ │
│  │  • RESTful API     • 数据处理     • 业务逻辑                │ │
│  │  • 设备管理API     • 数据采集API  • 统计分析API             │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                          数据服务层                              │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    SQLite Database                         │ │
│  │  • 设备信息存储    • 传感器数据    • 控制记录               │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                          设备接入层                              │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   设备模拟器 (Python)                       │ │
│  │  • 多设备模拟     • 传感器数据生成  • 实时数据推送            │ │
│  │  • 温室设备       • 农田设备       • 环境传感器              │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

### 核心模块架构

#### 1. 前端模块 (Frontend)
```
frontend/
├── index.html              # 主仪表盘 - 系统概览和实时数据展示
├── device-management.html  # 设备管理 - 设备列表、状态监控、配置
├── data-analysis.html      # 数据分析 - 历史数据、图表分析、报告
├── greenhouse-overview.html # 温室概览 - 温室管理、采收计划
├── add-device.html         # 设备添加 - 新设备注册和配置
├── css/
│   └── style.css          # 全局样式和主题配置
├── js/
│   ├── main.js            # 主页面逻辑和数据管理
│   ├── device-management.js # 设备管理功能
│   ├── data-analysis.js   # 数据分析和图表
│   ├── greenhouse-overview.js # 温室管理功能
│   ├── add-device.js      # 设备添加功能
│   └── config.js          # 前端配置和API地址
└── nginx.conf             # Nginx服务器配置
```

**功能特点:**
- 响应式设计，支持多设备访问
- 实时数据展示和图表可视化
- 模块化JavaScript架构
- 统一的UI组件和样式系统

#### 2. 后端模块 (Backend)
```
backend/
├── app.py                 # FastAPI主应用 - 路由定义和业务逻辑
├── config.py              # 配置管理 - 数据库、云服务配置
├── requirements.txt       # Python依赖包列表
└── Dockerfile            # 后端容器化配置
```

**API端点架构:**
```
/api/
├── /devices              # 设备管理API
│   ├── GET /             # 获取设备列表
│   ├── POST /            # 添加新设备
│   ├── PUT /{id}         # 更新设备信息
│   └── DELETE /{id}      # 删除设备
├── /data                 # 数据管理API
│   ├── GET /latest       # 获取最新数据
│   ├── GET /recent       # 获取近期数据
│   ├── GET /history/{device_id} # 获取历史数据
│   └── POST /            # 接收传感器数据
├── /automation           # 自动化控制API
│   ├── GET /status       # 获取控制状态
│   ├── POST /mode        # 设置控制模式
│   ├── POST /control     # 设备控制命令
│   ├── POST /thresholds  # 设置阈值参数
│   └── GET /stats        # 获取统计数据
└── /health               # 健康检查端点
```

#### 3. 设备模拟器 (Device Simulator)
```
device_simulator/
├── multi_device_simulator.py # 多设备数据模拟主程序
├── sensor_simulator.py       # 单设备传感器模拟
├── config.py                 # 模拟器配置参数
├── requirements.txt          # Python依赖
└── Dockerfile               # 模拟器容器配置
```

**模拟设备类型:**
- **device_001**: A区温室大棚 - 温室环境模拟
- **device_002**: B区温室大棚 - 温室环境模拟  
- **device_003**: 农田A区中央 - 户外农田环境模拟

**传感器数据类型:**
- 温度 (°C)
- 湿度 (%)
- 土壤湿度 (%)
- 光照强度 (lux)
- 时间戳和设备ID

## 🚀 快速开始

### 环境要求
- Python 3.8+
- Git

### 开发模式部署

1. **克隆项目**
```bash
git clone <repository-url>
cd smart-agriculture-framework
```

2. **启动后端服务**
```bash
cd backend
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8001 --reload
```

3. **启动前端服务**
```bash
cd frontend
python -m http.server 3000
```

4. **启动设备模拟器**
```bash
cd device_simulator
pip install -r requirements.txt
python multi_device_simulator.py
```

5. **访问应用**
- 🌐 前端界面: http://localhost:3000
- 📊 API文档: http://localhost:8001/docs

## 📁 项目结构详解

```
smart-agriculture-framework/
├── 📁 backend/                    # 后端API服务
│   ├── 🐍 app.py                 # FastAPI应用主文件
│   ├── ⚙️ config.py              # 配置管理
│   ├── 📋 requirements.txt       # Python依赖包
│   ├── 🗄️ smart_agriculture.db   # SQLite数据库文件
│   └── 📁 __pycache__/           # Python缓存文件
├── 📁 frontend/                   # 前端Web应用
│   ├── 🏠 index.html             # 主仪表盘页面
│   ├── 🔧 device-management.html # 设备管理页面
│   ├── 📊 data-analysis.html     # 数据分析页面
│   ├── 🏡 greenhouse-overview.html # 温室概览页面
│   ├── ➕ add-device.html        # 设备添加页面
│   ├── 📁 css/
│   │   └── 🎨 style.css          # 全局样式文件
│   └── 📁 js/
│       ├── 🏠 main.js            # 主页面逻辑
│       ├── 🔧 device-management.js # 设备管理功能
│       ├── 📊 data-analysis.js   # 数据分析功能
│       ├── 🏡 greenhouse-overview.js # 温室管理功能
│       ├── ➕ add-device.js      # 设备添加功能
│       ├── 🚨 alert-system.js    # 告警系统功能
│       └── ⚙️ config.js          # 前端配置文件
├── 📁 device_simulator/           # 设备模拟器
│   ├── 🎯 multi_device_simulator.py # 多设备模拟主程序
│   ├── 📡 sensor_simulator.py    # 单设备传感器模拟
│   ├── ⚙️ config.py              # 模拟器配置参数
│   └── 📋 requirements.txt       # Python依赖
├── 📁 database/                   # 数据库相关脚本
│   ├── 📄 schema.sql             # 数据库结构定义
│   ├── 🗄️ smart_agriculture.db   # SQLite数据库备份
│   └── 📁 各种数据库管理脚本/
├── 📁 venv/                      # Python虚拟环境
├── 🐳 docker-compose.yml         # 容器编排配置
├── 📝 .dockerignore              # Docker忽略文件
├── 📄 文档.txt                   # 项目说明文档
└── 📖 README.md                  # 项目文档
```

## 🔧 配置说明

### 环境变量配置

```bash
# 后端API配置
CORS_ORIGINS=http://localhost:3000    # 允许的跨域来源
API_BASE_URL=http://localhost:8001    # API基础URL
```

### 前端配置 (config.js)

```javascript
const config = {
    apiBaseUrl: "http://localhost:8001",  // 后端API地址
    chart: {
        updateInterval: 30000,            // 图表更新间隔(毫秒)
        colors: {
            temperature: '#f59e0b',       // 温度图表颜色
            humidity: '#0ea5e9',          // 湿度图表颜色
            soilMoisture: '#22c55e',      // 土壤湿度颜色
            lightIntensity: '#8b5cf6'     // 光照强度颜色
        }
    },
    alertThresholds: {                    // 告警阈值配置
        temperature: { min: 15, max: 30 },
        humidity: { min: 40, max: 85 },
        soilMoisture: { min: 30, max: 70 }
    }
};
```

### 设备配置

系统支持多种类型的传感器设备：

| 设备类型 | 传感器 | 监测参数 | 控制功能 |
|---------|--------|----------|----------|
| **温室设备** | 环境传感器 | 温度、湿度、光照 | 补光、通风、加热 |
| **土壤设备** | 土壤传感器 | 土壤湿度、pH值、EC值 | 灌溉、施肥 |
| **气象设备** | 气象传感器 | 风速、降雨、气压 | 遮阳、排水 |
| **控制设备** | 执行器 | 设备状态监控 | 远程开关控制 |

## 📊 API接口文档

### 核心API端点

#### 设备管理API
```http
GET    /api/devices              # 获取设备列表
POST   /api/devices              # 添加新设备
PUT    /api/devices/{id}         # 更新设备信息
DELETE /api/devices/{id}         # 删除设备
```

#### 数据采集API
```http
GET  /api/data/latest            # 获取最新传感器数据
GET  /api/data/recent?hours=24   # 获取近期数据
GET  /api/data/stats             # 获取数据统计信息
POST /api/data                   # 接收传感器数据上报
```

#### 自动化控制API
```http
GET    /api/automation/status    # 获取自动化控制状态
POST   /api/automation/mode      # 设置控制模式(auto/manual)
POST   /api/automation/control   # 发送设备控制命令
DELETE /api/automation/history   # 清空控制历史
```

#### 系统监控API
```http
GET /health                      # 系统健康检查
```

详细的API文档可以通过访问 http://localhost:8001/docs 查看Swagger UI界面。

## 🛠️ 开发指南

### 技术栈

| 层级 | 技术选型 | 版本 | 说明 |
|------|----------|------|------|
| **前端** | HTML5 + CSS3 + JavaScript | ES6+ | 原生Web技术栈 |
| **UI框架** | Tailwind CSS | 3.x | 实用优先的CSS框架 |
| **图表库** | Chart.js | 4.4.8 | 数据可视化 |
| **后端** | FastAPI | 0.104+ | 高性能Python Web框架 |
| **数据库** | SQLite | 3.x | 轻量级关系型数据库 |
| **设备模拟** | Python | 3.8+ | 多设备数据模拟器 |

### 开发环境搭建

1. **安装依赖**
```bash
# Python环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r backend/requirements.txt
pip install -r device_simulator/requirements.txt

# 前端依赖 (CDN方式，无需安装)
# Tailwind CSS, Chart.js, Font Awesome 通过CDN引入
```

2. **启动开发服务**
```bash
# 启动后端 (终端1)
cd backend && uvicorn app:app --host 0.0.0.0 --port 8001 --reload

# 启动前端 (终端2)  
cd frontend && python -m http.server 3000

# 启动设备模拟器 (终端3)
cd device_simulator && python multi_device_simulator.py
```

### 添加新功能

#### 1. 添加新的API端点

```python
# backend/app.py
@app.get("/api/new-feature")
async def new_feature_endpoint():
    """新功能API端点"""
    return {"status": "success", "data": "new feature data"}
```

#### 2. 添加前端页面

```html
<!-- frontend/new-page.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <title>新功能页面</title>
    <script src="js/config.js"></script>
</head>
<body>
    <!-- 页面内容 -->
    <script src="js/new-page.js"></script>
</body>
</html>
```

#### 3. 添加JavaScript功能模块

```javascript
// frontend/js/new-page.js
const newPageManager = {
    async loadData() {
        const response = await fetch(`${config.apiBaseUrl}/api/new-feature`);
        return await response.json();
    },
    
    init() {
        // 初始化逻辑
    }
};

document.addEventListener('DOMContentLoaded', newPageManager.init);
```

### 代码规范

- **Python**: 遵循PEP 8规范，使用类型注解
- **JavaScript**: 使用ES6+语法，采用模块化设计
- **HTML**: 使用语义化标签，支持无障碍访问
- **CSS**: 使用Tailwind CSS类名，保持一致性
- **API**: 遵循RESTful设计原则，使用标准HTTP状态码

## 🤝 贡献指南

### 参与贡献

1. **Fork项目** - 点击右上角Fork按钮
2. **创建分支** - `git checkout -b feature/amazing-feature`
3. **提交代码** - `git commit -m 'Add amazing feature'`
4. **推送分支** - `git push origin feature/amazing-feature`
5. **创建PR** - 在GitHub上创建Pull Request

### 问题反馈

- 🐛 **Bug报告**: 使用Issue模板报告问题
- 💡 **功能建议**: 提交Feature Request
- 📖 **文档改进**: 帮助完善文档
- 🧪 **测试用例**: 添加单元测试和集成测试

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持与联系

如果您在使用过程中遇到问题或有改进建议：

- 📧 **邮箱**: support@smart-agriculture.com
- 🐛 **问题反馈**: [GitHub Issues](https://github.com/your-repo/issues)
- 📚 **在线文档**: [项目文档](https://docs.smart-agriculture.com)
- 💬 **技术交流**: 加入我们的技术交流群

---

**智慧农业监控系统** - 让农业更智能，让管理更简单！ 🌱🚀

*Built with ❤️ by Smart Agriculture Team*