# smart-farm-software-development

**Repository Path**: hewang_1_0/smart-farm-software-development

## Basic Information

- **Project Name**: smart-farm-software-development
- **Description**: 基于 Spring Boot、Spring AI、Vue 3、MySQL 与 WebSocket 的智慧农场数字孪生管控平台，支持 2.5D 大棚热力图可视化、时序环境监测、AI 农情日报生成与主动推送、供应链管理及权限控制。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧农场数字孪生管控平台

## 项目简介

本项目为软件开发实训项目，主题为“基于 Spring AI 与时序数据的智慧农场数字孪生管控平台”。
项目面向农场管理员与农技专家，围绕农场环境监测、种植计划、农资供应链、作业记录和 AI 农情分析，建设一个集业务管理、数据可视化、智能诊断与主动推送于一体的轻量级数字农场系统。

## 项目目标

本项目重点解决传统农业物联网平台“只展示、不分析、缺乏空间感和主动预警”的问题，建设以下核心能力：

- 基于 2.8 万条时序测试数据，完成农场环境数据的统一接入、查询和可视化展示
- 通过 2.5D 大棚热力图，直观反映温湿度等微气候的空间分布状态
- 通过 Spring AI 对近 24 小时环境数据进行聚合分析，生成结构化农情摘要
- 通过 WebSocket 将 AI 日报和告警结果主动推送给在线用户
- 在供应商、库存、计划、日志、产量等业务域内完成规范化 CRUD 与统计分析能力

## 目标用户

- 农场管理员：关注供应链、库存、日志、设备状态、异常预警和业务可追溯性
- 农技专家：关注温湿度波动、大棚空间分布、种植计划和 AI 辅助诊断结果

## 核心功能范围

### P0 核心功能

1. 数字孪生大屏可视化
   - 以 CSS Grid 或 Canvas 构建 2.5D 大棚视图
   - 根据实时温度动态映射大棚颜色
   - 点击大棚后展示近 24 小时温湿度双 Y 轴图表

2. AI 农情日报主动推送
   - 后端通过 `@Scheduled` 每天定时聚合近 24 小时极值与告警信息
   - 使用 Spring AI 生成结构化农情诊断内容
   - 通过 WebSocket 向在线用户实时推送日报和通知

### P1 业务功能

1. 农资供应链管理
   - 供应商档案管理
   - 农资库存管理
   - 采购入库流水管理
   - 逻辑删除与历史单据追溯

2. 农场生产管理
   - 地块台账管理
   - 作物字典管理
   - 种植计划管理
   - 农事日志与灌溉记录管理
   - 产量统计与经营看板

## 非目标范围

- 不接入真实硬件设备、传感器协议或单片机联调
- 不开发面向 C 端的电商交易、支付和物流模块
- 不处理摄像头视频流或流媒体解析

## 成功标准

- 在 2.8 万条底层数据支撑下，2.5D 热力图及初始数据首次内容绘制时间小于 1.5 秒
- 每日 7:00 生成的《农情微气候日报》推送成功率不低于 95%
- 核心数据流接口在不含外部大模型调用时，P99 响应延迟小于 200ms

## 技术栈

### 后端

- Spring Boot 3.x
- MyBatis-Plus
- Sa-Token
- Spring AI
- WebSocket
- MySQL 8.x

### 前端

- Vue 3
- Vite
- Element Plus
- Pinia
- Vue Router
- ECharts
- CSS Grid / Canvas / 3D Transform

### 开发与协作

- Swagger 3 / Knife4j 或 Apifox
- Git 分支协作
- 统一数据库初始化脚本

## 系统架构

项目采用前后端分离的单体架构，并通过调度和消息推送形成主动服务链路：

1. 前端层：负责登录鉴权、业务页面、2.5D 热力图、统计图表与消息通知
2. 后端层：负责 RESTful API、权限控制、业务编排、数据校验和异常处理
3. AI 与调度层：负责定时聚合环境数据、生成日报、调用大模型并下发通知
4. 数据层：负责承载结构化业务数据、时序数据、统计分析结果与初始化脚本

## AI 与时序数据要求

- 使用 Spring AI 对接稳定的大模型服务
- 统一封装 System Prompt，要求模型输出结构化结果，禁止无关寒暄
- 准备边界测试数据，验证 AI 摘要对极值和异常信息的准确提取
- 实现失败重试与降级文案，避免 AI 接口异常阻塞主业务链路

## 阶段路线图

| 阶段 | 目标 | 交付内容 |
| --- | --- | --- |
| Phase 1 | MVP 基础业务与权限基石 | Spring Boot 骨架、登录鉴权、供应商 CRUD、基础图表渲染 |
| Phase 2 | 数字孪生视觉化 | 2.5D 大棚热力图、颜色映射、空间交互与侧边栏联动 |
| Phase 3 | AI 智能与自动化 | Spring AI、Prompt 工程、定时聚合、WebSocket 推送 |

## 团队分工

项目按业务域进行 5 人全栈垂直切分，每位成员均负责对应模块的前端、后端与数据库接口联调工作。

### 成员 1：系统基建与空间资产负责人

- 业务域：`user`、`plot`
- 后端职责：登录鉴权、Token 下发、RBAC 拦截、全局异常处理、用户与地块 CRUD、WebSocket 服务端基础设施
- 前端职责：Vue 3 工程基建、登录页、主 Layout、动态菜单、路由守卫、用户权限管理、地块台账管理
- 高阶贡献：搭建系统安全底座和前后端基建规范

### 成员 2：实时调度与生命周期负责人

- 业务域：`crop`、`planting_plan`
- 后端职责：定时任务调度、作物生长周期计算、作物与种植计划 CRUD、计划联动校验
- 前端职责：种植计划日历/甘特视图、WebSocket 客户端通知、作物字典管理
- 高阶贡献：打通“数据库 -> 定时任务 -> WebSocket -> 前端通知”的自动化链路

### 成员 3：IoT 孪生与 AI 算法负责人

- 业务域：`sensor`、`sensor_data`、`device_alert`
- 后端职责：Spring AI 接入、日报生成、告警推送、时序数据性能优化、传感器与告警管理接口
- 前端职责：2.5D 大棚热力图、双 Y 轴折线图、时序数据查询、告警记录管理、WebSocket 消息接收
- 高阶贡献：负责项目最核心的 AI 与数字孪生能力落地

### 成员 4：农资供应链与核心业务负责人

- 业务域：`agri_material_supplier`、`agri_material`、`agri_purchase_record`
- 后端职责：供应商、库存、采购入库全套 CRUD，事务一致性控制，库存变更与阈值预警
- 前端职责：供应商档案、农资字典、采购入库高级表单与级联交互
- 高阶贡献：保障库存、采购和资金相关业务数据的一致性与准确性

### 成员 5：农场作业与可视化大屏负责人

- 业务域：`irrigation_record`、`farm_log`、`yield_stat`
- 后端职责：灌溉、农事、产量相关 CRUD，多表聚合统计，经营看板 API，统计查询性能优化
- 前端职责：农事打卡页面、灌溉流水录入、产能与能耗大屏、图表联动与下钻
- 高阶贡献：将生产记录转化为可视化经营分析结果

## 协作规范

### 环境统一

- JDK 17
- MySQL 8.0.x
- Node.js 18.x

### 数据库规范

- 全组统一使用同一个初始化脚本
- 首次拉取代码后，必须先执行 `init_schema.sql`
- 禁止私自修改主库字段，如需调整由架构负责人统一维护

### Git 规范

- 禁止直接推送主分支
- 所有人使用独立 `feat-*` 分支开发
- 提交信息统一采用类型前缀，例如：
  - `feat: 新增农资入库接口`
  - `fix: 修复登录页路由越权问题`
- 由架构负责人统一处理分支合并，确保主分支始终可运行

### 前后端目录规范

- 后端按业务域划分顶级包：`system`、`plan`、`iot`、`supply`、`operation`
- 前端按业务域划分 `views` 目录
- 严禁跨模块随意耦合，跨域调用必须通过清晰接口完成

### 接口文档规范

- 后端所有 Controller、DTO 必须补充注解说明
- 接口完成后需保证 Swagger / Knife4j 或 Apifox 可联调、可测试

## 重点风险与缓解策略

- AI 接口超时：采用异步线程池、超时限制、失败重试和降级文案
- WebSocket 假死或断连：前端实现心跳保活与指数退避重连
- 大量时序数据查询性能不足：通过索引设计、范围查询优化和分页策略控制查询成本
- 核心业务数据误删：严格执行逻辑删除，保护历史数据和外键关联完整性

## 当前仓库说明

- 当前仓库为本项目统一代码仓库
- 数据库初始化脚本位于 `packages/servrer/db/init_schema.sql`
- Windows 一键启动脚本位于 `scripts/start-dev.ps1` 与 `scripts/start-dev.cmd`
- 后续开发应围绕统一 PRD、统一分工、统一数据库脚本和统一分支规范推进

## 本地启动

### 环境要求

- JDK 17
- Maven
- Node.js 18.x
- MySQL 8.x

### 启动前准备

- 确保 MySQL 已启动，并已导入 `smart_farm` 数据库
- 默认后端端口为 `8080`
- 默认前端 Vite 端口为 `5173`，若被占用会顺延到其他可用端口

### Windows 一键启动

- 双击 `scripts/start-dev.cmd`
- 或在 PowerShell 中执行 `scripts/start-dev.ps1`

脚本会自动：

- 后台启动后端 `packages/server`
- 后台启动前端 `packages/web`
- 检测启动状态并输出前端访问地址
- 将日志写入 `scripts/logs`

常见日志文件：

- `scripts/logs/server.out.log`
- `scripts/logs/server.err.log`
- `scripts/logs/web.out.log`
- `scripts/logs/web.err.log`