nxxmdata/arch.md

项目架构文档

1. 项目概述

本项目是宁夏智慧养殖监管平台，一个现代化的农场管理系统，包含以下核心功能：

• 农场设备监控: 实时监控农场设备状态和运行数据
• 动物健康管理: 跟踪和管理动物健康状况
• 地图可视化: 基于百度地图的农场地理信息展示
• 数据分析与可视化: 提供丰富的图表和统计分析
• 用户权限管理: 基于角色的用户认证和授权系统
• 订单管理: 产品销售和订单处理功能
• 预警管理: 实时告警监控和预警处理
• 性能监控: 实时系统性能监控和分析

2. 目录结构

2.1 后端 (backend/)

• config/: 配置文件
  • database.js: MySQL数据库连接配置
  • database-pool.js: 数据库连接池管理
  • performance-config.js: 性能监控配置
  • swagger.js: API文档配置
• controllers/: 业务逻辑控制器
  • farmController.js: 农场管理
  • animalController.js: 动物管理
  • deviceController.js: 设备管理
  • alertController.js: 告警管理
  • statsController.js: 统计分析
  • mapController.js: 地图服务
  • userController.js: 用户管理
  • productController.js: 产品管理
  • orderController.js: 订单管理
• models/: 数据模型定义（Sequelize ORM）
  • Farm.js: 农场模型
  • Animal.js: 动物模型
  • Device.js: 设备模型
  • Alert.js: 告警模型
  • User.js: 用户模型
  • Role.js: 角色模型
  • Product.js: 产品模型
  • Order.js: 订单模型
  • OrderItem.js: 订单项模型
  • UserRole.js: 用户角色关联模型
  • SensorData.js: 传感器数据模型
  • BaseModel.js: 基础模型
  • index.js: 模型入口文件
• routes/: API路由定义
  • auth.js: 认证路由
  • users.js: 用户管理路由
  • products.js: 产品管理路由
  • orders.js: 订单管理路由
  • farms.js: 农场管理路由
  • animals.js: 动物管理路由
  • devices.js: 设备管理路由
  • alerts.js: 告警管理路由
  • stats.js: 统计分析路由
  • map.js: 地图服务路由
  • performance-routes.js: 性能监控路由
• middleware/: 中间件
  • auth.js: 认证中间件
  • performance-middleware.js: 性能监控中间件
• scripts/: 数据库管理脚本
  • init-db.js: 数据库初始化
  • migration-manager.js: 迁移管理
  • seed-manager.js: 种子数据管理
  • test-connection.js: 连接测试
  • test-map-api.js: 地图API测试
• utils/: 工具类
  • logger.js: 日志工具
  • performance-monitor.js: 性能监控
  • db-monitor.js: 数据库监控
  • query-optimizer.js: 查询优化器
• migrations/: 数据库迁移文件
• seeds/: 种子数据文件
• logs/: 日志文件目录

2.2 前端 (frontend/)

• src/components/: 可复用的UI组件
  • BaiduMap.vue: 百度地图组件
  • EChart.vue: 图表组件
  • Menu.vue: 导航菜单
  • Dashboard.vue: 仪表盘组件
  • AlertStats.vue: 告警统计组件
  • AnimalStats.vue: 动物统计组件
  • DeviceStats.vue: 设备统计组件
  • FarmDetail.vue: 农场详情组件
  • MonitorChart.vue: 监控图表组件
  • ChartPerformanceMonitor.vue: 性能监控图表
  • VirtualScrollChart.vue: 虚拟滚动图表
• src/views/: 页面级组件
  • Home.vue: 首页
  • Dashboard.vue: 系统概览
  • MapView.vue: 地图监控
  • Analytics.vue: 数据分析
  • Monitor.vue: 实时监控
  • Login.vue: 登录页面
  • Users.vue: 用户管理
  • Products.vue: 产品管理
  • Orders.vue: 订单管理
  • Devices.vue: 设备管理
  • Animals.vue: 动物管理
  • Alerts.vue: 预警管理
  • TestAnalytics.vue: 测试分析页面
  • MapZoomDemo.vue: 地图缩放演示
  • NotFound.vue: 404页面
• src/stores/: 状态管理（Pinia）
  • user.js: 用户状态管理
  • data.js: 数据状态管理
  • settings.js: 设置状态管理
  • index.js: 状态管理入口
• src/router/: 路由配置
  • index.js: 路由实例和守卫
  • routes.js: 路由定义
• src/utils/: 工具类（API调用、图表服务等）
  • api.js: API请求封装
• src/config/: 配置文件
• public/: 静态资源和测试页面
  • debug-devices.html: 设备调试页面
  • debug-users.html: 用户调试页面
  • map-test.html: 地图测试页面
  • test-auto-login.html: 自动登录测试
  • test-users-display.html: 用户显示测试

2.3 其他

• docs/: 项目文档
  • baidu-map-license.md: 百度地图许可文档
  • performance-monitoring.md: 性能监控文档
• tests/: 测试脚本
  • performance-monitor-test.js: 性能监控测试
• examples/: 示例代码
  • performance-monitor-integration.js: 性能监控集成示例
• create_tables.sql: 数据库表创建脚本
• schema.sql: 数据库架构脚本
• design.md: 详细设计文档
• dev-plan.md: 开发计划文档
• task.md: 任务列表文档

3. 模块划分

3.1 后端模块

• 农场管理模块: 农场信息管理、地理位置管理
• 设备管理模块: 监控农场设备状态、设备数据采集
• 动物管理模块: 跟踪动物健康数据、动物档案管理
• 告警管理模块: 系统告警处理、告警规则配置
• 用户管理模块: 用户认证、角色权限管理
• 订单管理模块: 产品销售、订单处理流程
• 统计分析模块: 数据统计、报表生成
• 地图服务模块: 地理信息服务、位置数据处理
• 性能监控模块: 系统性能监控、API性能分析

3.2 前端模块

• 首页模块: 系统入口、快速导航
• 仪表盘模块: 关键指标展示、数据概览
• 地图模块: 基于百度地图的可视化展示、地图缩放演示
• 数据分析模块: 图表展示、数据分析工具、测试分析功能
• 实时监控模块: 实时数据监控、告警展示、性能监控图表
• 用户管理模块: 用户信息管理、权限配置
• 产品管理模块: 产品信息维护、库存管理
• 订单管理模块: 订单处理、订单状态跟踪
• 设备管理模块: 设备状态监控、设备信息管理
• 动物管理模块: 动物健康档案、动物信息管理
• 预警管理模块: 告警规则配置、预警信息处理
• 认证模块: 用户登录、权限验证、自动登录

4. 核心架构

4.1 技术栈

后端技术栈:

• 运行环境: Node.js
• Web框架: Express.js 4.18+
• ORM框架: Sequelize 6.30+
• 数据库: MySQL (mysql2 3.0+)
• 认证: JWT (jsonwebtoken 9.0+)
• 密码加密: bcrypt 5.1+
• API文档: Swagger (swagger-jsdoc + swagger-ui-express)
• 日志管理: Winston 3.17+
• 开发工具: nodemon 3.0+
• 跨域处理: CORS 2.8+
• 数据验证: express-validator 7.2+
• 环境变量: dotenv 16.0+
• HTTP客户端: Axios 1.4+
• 服务器端口: 5350

前端技术栈:

• 框架: Vue.js 3.4+
• 构建工具: Vite 5.0+
• 路由管理: Vue Router 4.0+
• 状态管理: Pinia 2.0+
• UI组件库: Ant Design Vue 4.0+
• 图表库: ECharts 5.4+
• 地图服务: 百度地图API
• HTTP客户端: Axios 1.11+
• 开发服务器: Vite Dev Server (端口: 5300)
• 代理配置: API代理到后端服务器

数据库设计:

• 主数据库: MySQL (生产环境)
• 连接池: 数据库连接池管理
• 字符集: UTF8MB4
• 时区: +08:00 (北京时间)

4.2 数据流架构

1. 前端请求流程:
   • 用户操作 → Vue组件 → Pinia状态管理 → API调用
2. 后端处理流程:
   • API路由 → 中间件验证 → 控制器处理 → 模型操作 → 数据库
3. 响应返回流程:
   • 数据库结果 → 模型封装 → 控制器响应 → 前端状态更新 → UI渲染
4. 实时数据流:
   • 设备数据采集 → 后端处理 → 数据库存储 → 前端轮询/推送更新

5. 数据模型关系

5.1 核心实体关系

• Farm (农场) ← 一对多 → Animal (动物)
• Farm (农场) ← 一对多 → Device (设备)
• Farm (农场) ← 一对多 → Alert (告警)
• Device (设备) ← 一对多 → Alert (告警)
• User (用户) ← 多对多 → Role (角色) (通过UserRole中间表)
• User (用户) ← 一对多 → Order (订单)
• Order (订单) ← 一对多 → OrderItem (订单项)
• Product (产品) ← 一对多 → OrderItem (订单项)

5.2 数据库约束

• 外键约束: 确保数据完整性
• 级联删除: Farm删除时级联删除相关Animal、Device、Alert
• 级联更新: 主键更新时自动更新外键
• 限制删除: Product被OrderItem引用时限制删除

6. API设计规范

6.1 RESTful API结构

/api/farms          - 农场管理
/api/animals        - 动物管理
/api/devices        - 设备管理
/api/alerts         - 告警管理
/api/users          - 用户管理
/api/products       - 产品管理
/api/orders         - 订单管理
/api/stats          - 统计数据
/api/map            - 地图服务
/api/auth           - 认证服务

6.2 响应格式标准

{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2025-01-18T10:30:00Z"
}

7. 安全架构

7.1 认证与授权

• JWT Token: 无状态身份验证
• 角色权限: 基于RBAC的权限控制
• 路由守卫: 前端路由级别的权限验证
• API中间件: 后端接口级别的权限验证

7.2 数据安全

• 密码加密: bcrypt哈希加密
• SQL注入防护: Sequelize ORM参数化查询
• XSS防护: 前端输入验证和转义
• CORS配置: 跨域请求安全控制

8. 性能优化

8.1 后端性能

• 数据库连接池: 优化数据库连接管理
• 查询优化: 数据库查询性能监控
• API性能监控: 接口响应时间监控
• 内存监控: 系统资源使用监控

8.2 前端性能

• 组件懒加载: 路由级别的代码分割
• 图表优化: ECharts按需加载
• 状态管理: Pinia轻量级状态管理
• 构建优化: Vite快速构建和热更新

9. 部署架构

9.1 开发环境

• 前端: Vite开发服务器 (http://localhost:5300)
• 后端: Node.js开发服务器 (http://localhost:5350)
• 数据库: MySQL本地实例

9.2 生产环境建议

• 前端: 静态文件部署 (Nginx)
• 后端: PM2进程管理
• 数据库: MySQL主从复制
• 负载均衡: Nginx反向代理
• 容器化: Docker部署支持

10. 依赖关系

10.1 后端主要依赖

{
  "express": "^4.18.0",
  "sequelize": "^6.30.0",
  "mysql2": "^3.0.0",
  "jsonwebtoken": "^9.0.0",
  "bcrypt": "^5.1.0",
  "swagger-ui-express": "^5.0.0",
  "swagger-jsdoc": "^6.2.8",
  "winston": "^3.17.0",
  "cors": "^2.8.5",
  "express-validator": "^7.2.1",
  "dotenv": "^16.0.0",
  "axios": "^1.4.0",
  "nodemon": "^3.0.0"
}

10.2 前端主要依赖

{
  "vue": "^3.4.0",
  "vue-router": "^4.0.0",
  "pinia": "^2.0.0",
  "ant-design-vue": "^4.0.0",
  "echarts": "^5.4.0",
  "axios": "^1.11.0",
  "@vitejs/plugin-vue": "^5.0.0",
  "vite": "^5.0.0"
}

10.3 外部服务

• 百度地图API: 地理信息可视化服务
• MySQL数据库: 数据持久化存储

11. 扩展性设计

11.1 模块化架构

• 前端组件化: 可复用的Vue组件
• 后端模块化: 控制器、模型、路由分离
• 配置外部化: 环境变量配置管理

11.2 未来扩展方向

• 微服务架构: 服务拆分和独立部署
• 消息队列: 异步任务处理
• 缓存系统: Redis缓存优化
• 实时通信: WebSocket实时数据推送
• 移动端支持: 响应式设计和PWA

12. 项目特色功能

12.1 性能监控系统

• 实时性能监控: 监控API响应时间、系统资源使用情况
• 性能分析图表: 基于ECharts的性能数据可视化
• 虚拟滚动优化: 大数据量图表的性能优化
• 数据库查询优化: 查询性能监控和优化建议

12.2 地图可视化系统

• 百度地图集成: 农场地理位置可视化展示
• 地图缩放演示: 多级缩放功能演示
• 地理信息服务: 位置数据处理和展示

12.3 数据分析系统

• 多维度统计: 设备、动物、告警等多维度数据统计
• 实时图表: 基于ECharts的实时数据图表
• 测试分析功能: 专门的测试分析页面

12.4 认证与权限系统

• JWT无状态认证: 基于Token的身份验证
• 自动登录功能: 智能的自动登录和Token验证
• 路由权限守卫: 前端路由级别的权限控制
• 角色权限管理: 基于RBAC的权限控制

12.5 开发与调试工具

• API调试页面: 专门的API测试和调试页面
• 性能测试工具: 内置的性能测试和监控工具
• 数据库管理脚本: 完整的数据库管理和维护脚本

---

最后更新: 2025-01-18 版本: v2.1 分析基于实际代码结构