# 项目架构文档

## 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`: 性能监控中间件
- `utils/`: 工具类
  - `logger.js`: 日志工具
  - `performance-monitor.js`: 性能监控
  - `db-monitor.js`: 数据库监控
  - `query-optimizer.js`: 查询优化器
- `migrations/`: 数据库迁移文件
- `seeds/`: 种子数据文件
- `logs/`: 日志文件目录

### 2.2 管理后台 (`admin-system/`)
- `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 官网 (`website/`)
- `data-screen/`: 官网前端项目
  - 包含官网展示页面和数据大屏功能

### 2.4 微信小程序 (`mini_program/`)
- `farm-monitor-dashboard/`: 微信小程序项目
  - 包含移动端监控仪表盘功能

### 2.5 脚本目录 (`scripts/`)
- `init-db.js`: 数据库初始化
- `migration-manager.js`: 迁移管理
- `seed-manager.js`: 种子数据管理
- `test-connection.js`: 连接测试
- `test-map-api.js`: 地图API测试

### 2.6 文档目录 (`docs/`)
- `API.md`: API 文档
- `DEPLOYMENT.md`: 部署指南
- `DEVELOPMENT.md`: 开发指南
- `TROUBLESHOOTING.md`: 故障排除
- `CHANGELOG.md`: 更新日志
- `CONTRIBUTING.md`: 贡献指南
- `SECURITY.md`: 安全指南
- `PRD.md`: 产品需求文档
- `baidu-map-license.md`: 百度地图许可文档
- `performance-monitoring.md`: 性能监控文档
- `FINAL_STRUCTURE_REPORT.md`: 项目结构报告
- `PROJECT_CLEANUP_REPORT.md`: 项目清理报告
- `arch.md`: 架构文档
- `design.md`: 详细设计
- `schema.sql`: 数据库架构脚本
- `create_tables.sql`: 数据库表创建脚本

### 2.7 测试目录 (`test/`)
- `performance-monitor-test.js`: 性能监控测试

### 2.8 其他文件
- `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 18.0+
- **Web框架**: Express.js 4.18+
- **API风格**: RESTful API
- **ORM框架**: Sequelize 6.30+
- **数据库**: MySQL 8.0+ (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+
- **响应式设计**: 支持Chrome、Firefox、Safari最新版本
- **分辨率支持**: 1920x1080及以上

### 4.2 性能要求
- **页面加载时间**: <3秒
- **API响应时间**: <500ms
- **并发用户支持**: 1000+用户
- **数据查询性能**: 复杂查询<2秒
- **系统可用性**: 99.9%

### 4.3 安全要求
- **数据传输**: HTTPS加密
- **身份认证**: JWT令牌机制
- **密码存储**: bcrypt加密
- **SQL注入防护**: ORM参数化查询
- **XSS防护**: 输入验证和转义
- **访问控制**: 基于角色的权限管理(RBAC)
- **会话管理**: Token过期机制

### 4.4 可靠性要求
- **数据备份**: 每日自动备份
- **故障恢复**: 30分钟内恢复
- **监控告警**: 关键指标监控
- **日志记录**: 完整的操作日志和错误日志
- **开发服务器**: 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 响应格式标准
```json
{
  "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 后端主要依赖
```json
{
  "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 前端主要依赖
```json
{
  "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*
*分析基于实际代码结构*