# 宁夏智慧养殖监管平台详细设计文档

## 1. 项目概述

### 1.1 项目背景
宁夏回族自治区作为中国重要的畜牧业基地，养殖业在区域经济发展中占据重要地位。随着现代信息技术的快速发展，传统养殖业正逐步向智能化、数字化方向转型升级。为提升宁夏地区养殖业的管理水平和监管效率，建设一套完善的智慧养殖监管平台势在必行。

### 1.2 项目目标
宁夏智慧养殖监管平台旨在通过数字化手段实现对养殖全过程的监管，具体目标包括：
- 实现养殖场信息数字化管理
- 提供养殖环境实时监控功能
- 支持养殖过程数据记录与追溯
- 提供数据分析和决策支持
- 构建统一的养殖监管体系

### 1.3 项目范围
本项目主要涵盖以下功能模块：
- 用户权限管理
- 养殖场信息管理
- 养殖环境监控
- 养殖过程管理
- 产品信息管理
- 数据分析与报表
- 地理信息系统展示

## 2. 技术架构设计

### 2.1 整体架构
本项目采用前后端分离的架构设计模式，包含以下主要模块：
- **后端服务** (`backend/`): Node.js + Express + Sequelize ORM
- **管理后台** (`admin-system/`): Vue.js 3.x + Ant Design Vue
- **官网** (`website/`): Vue.js 3.x + 数据大屏展示
- **微信小程序** (`mini_program/`): React + TypeScript + Tailwind CSS
- **脚本工具** (`scripts/`): 数据库管理和维护脚本
- **文档** (`docs/`): 项目技术文档，包含API文档、部署指南、开发指南、故障排除、更新日志、贡献指南、安全指南、产品需求文档等
- **测试** (`test/`): 测试脚本和用例

### 2.2 前端技术栈
- **核心框架**: Vue.js 3.x
- **UI组件库**: Ant Design Vue
- **构建工具**: Vite
- **状态管理**: Pinia
- **路由管理**: Vue Router
- **地图服务**: 百度地图API
- **图表库**: ECharts

### 2.3 后端技术栈
- **运行环境**: Node.js
- **Web框架**: Express.js 4.18+
- **API风格**: RESTful API
- **认证授权**: JWT (jsonwebtoken 9.0+)
- **数据库访问**: Sequelize ORM 6.30+
- **数据库**: MySQL (mysql2 3.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



### 2.4 部署架构
- **开发环境**: 本地运行
- **生产环境**: Docker容器化部署

## 3. 数据库设计

### 3.1 数据库连接信息
- 数据库地址：http://192.168.0.240:3306
- 数据库用户名：root
- 数据库密码：aiot$Aiot123
- 数据库名称：nxxmdata

### 3.2 数据库连接失败解决方案
在开发过程中，可能会遇到数据库连接失败的问题，此时应采取以下措施：

1. **确认MySQL服务状态**:
   - 确保MySQL服务已经安装并正在运行
   - 检查MySQL是否在默认端口3306上运行和监听

2. **创建数据库**:
   - 可以执行项目中的SQL文件来创建数据库和表
   - 根据项目中的 schema.sql 文件，手动执行创建数据库和表的SQL语句

3. **提供正确的连接参数**:
   - 需要提供正确的数据库连接信息，包括主机地址（host）、端口号（port）、用户名（user）、密码（password）、数据库名（database）
   - 验证主机地址、端口号、用户名、密码等连接参数的正确性
   - 确保提供完整的数据库配置参数，检查参数格式是否符合MCP工具的要求

4. **连接验证参数**:
   - 主机: `localhost` 或 `127.0.0.1`
   - 端口: `3306` (MySQL默认端口)
   - 用户名: MySQL用户名 (例如: `root`)
   - 密码: MySQL密码
   - 数据库: `nxxmdata`

5. **处理未知数据库问题**:
   - 如果遇到"Unknown database"错误，应手动创建相应的数据库
   - 使用schema.sql文件创建数据库结构
   - 确保在连接数据库前完成数据库的初始化工作

6. **验证数据库连接**:
   - 在完成数据库创建和配置后，再次尝试连接数据库
   - 通过执行简单的数据库操作验证连接的有效性

当无法直接连接数据库时，可以通过创建完整的数据库设计文档和SQL脚本文件来提供替代方案。这种方法可以确保设计工作继续进行，并为后续的数据库部署提供可执行的起点。

### 3.3 数据表结构设计

#### 3.3.1 用户表 (users)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| email | VARCHAR(100) | UNIQUE, NOT NULL | 邮箱地址 |
| password | VARCHAR(255) | NOT NULL | 密码（加密后） |
| phone | VARCHAR(20) | NULL | 手机号 |
| avatar | VARCHAR(255) | NULL | 头像URL |
| status | ENUM('active','inactive','banned') | DEFAULT 'active' | 用户状态 |
| last_login | DATETIME | NULL | 最后登录时间 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 3.3.2 角色表 (roles)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 角色ID |
| name | VARCHAR(50) | UNIQUE, NOT NULL | 角色名称 |
| description | TEXT | NULL | 角色描述 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### 3.3.3 用户角色关联表 (user_roles)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| user_id | INT | FOREIGN KEY (users.id), NOT NULL | 用户ID |
| role_id | INT | FOREIGN KEY (roles.id), NOT NULL | 角色ID |
| assigned_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 分配时间 |

#### 3.3.4 产品表 (products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 产品ID |
| name | VARCHAR(100) | NOT NULL | 产品名称 |
| description | TEXT | NULL | 产品描述 |
| price | INT | NOT NULL | 产品价格（单位：分） |
| stock | INT | DEFAULT 0 | 库存数量 |
| image_url | VARCHAR(255) | NULL | 产品图片URL |
| is_active | TINYINT(1) | DEFAULT 1 | 是否激活 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 3.3.5 订单表 (orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | INT | FOREIGN KEY (users.id), NOT NULL | 用户ID |
| total_amount | INT | DEFAULT 0 | 订单总金额（单位：分） |
| status | ENUM('pending','processing','shipped','delivered','cancelled') | DEFAULT 'pending' | 订单状态 |
| payment_status | ENUM('unpaid','paid','refunded') | DEFAULT 'unpaid' | 支付状态 |
| shipping_address | TEXT | NULL | 收货地址 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 3.3.6 订单项表 (order_items)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单项ID |
| order_id | INT | FOREIGN KEY (orders.id), NOT NULL | 订单ID |
| product_id | INT | FOREIGN KEY (products.id), NOT NULL | 产品ID |
| quantity | INT | DEFAULT 1 | 数量 |
| price | INT | NOT NULL | 单价（单位：分） |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### 3.3.7 养殖场表 (farms)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 养殖场ID |
| name | VARCHAR(100) | NOT NULL | 养殖场名称 |
| type | VARCHAR(50) | NOT NULL | 养殖场类型 |
| location | JSON | NOT NULL | 地理位置信息 |
| address | VARCHAR(255) | NULL | 详细地址 |
| contact | VARCHAR(50) | NULL | 联系人 |
| phone | VARCHAR(20) | NULL | 联系电话 |
| status | ENUM('active','inactive','maintenance') | DEFAULT 'active' | 养殖场状态 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 3.3.8 动物表 (animals)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 动物ID |
| type | VARCHAR(50) | NOT NULL | 动物类型 |
| count | INT | DEFAULT 0 | 数量 |
| farm_id | INT | FOREIGN KEY (farms.id), NOT NULL | 所属养殖场ID |
| health_status | ENUM('healthy','sick','quarantine') | DEFAULT 'healthy' | 健康状态 |
| last_inspection | DATETIME | NULL | 最后检查时间 |
| notes | TEXT | NULL | 备注信息 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 3.3.9 设备表 (devices)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 设备ID |
| name | VARCHAR(100) | NOT NULL | 设备名称 |
| type | VARCHAR(50) | NOT NULL | 设备类型 |
| status | ENUM('online','offline','maintenance') | DEFAULT 'offline' | 设备状态 |
| farm_id | INT | FOREIGN KEY (farms.id), NOT NULL | 所属养殖场ID |
| last_maintenance | DATETIME | NULL | 最后维护时间 |
| installation_date | DATETIME | NULL | 安装日期 |
| metrics | JSON | NULL | 设备指标数据 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 3.3.10 预警表 (alerts)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 预警ID |
| type | VARCHAR(50) | NOT NULL | 预警类型 |
| level | ENUM('low','medium','high','critical') | DEFAULT 'medium' | 预警级别 |
| message | TEXT | NOT NULL | 预警消息 |
| status | ENUM('active','acknowledged','resolved') | DEFAULT 'active' | 预警状态 |
| farm_id | INT | FOREIGN KEY (farms.id), NOT NULL | 所属养殖场ID |
| device_id | INT | FOREIGN KEY (devices.id), NULL | 关联设备ID |
| resolved_at | DATETIME | NULL | 解决时间 |
| resolved_by | INT | FOREIGN KEY (users.id), NULL | 解决人ID |
| resolution_notes | TEXT | NULL | 解决说明 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

### 3.4 初始数据

#### 3.4.1 角色数据
系统初始化时会创建以下基础角色数据：
- admin: 系统管理员
- user: 普通用户
- guest: 访客

#### 3.4.2 用户数据
系统初始化时会创建以下示例用户数据：
- admin用户: admin@example.com
- 普通用户: john@example.com

#### 3.4.3 产品数据
系统初始化时会创建以下示例产品数据：
- 示例产品1: 价格99.99，库存100
- 示例产品2: 价格149.99，库存50

## 4. 功能模块详细设计

### 4.1 用户管理模块

#### 4.1.1 用户认证
- 用户登录/登出功能
- 密码加密存储
- JWT令牌管理
- 会话超时处理

#### 4.1.2 用户权限管理
- 基于角色的访问控制(RBAC)
- 权限分配与验证
- 用户角色管理
- 访问日志记录

### 4.2 养殖场信息管理模块

#### 4.2.1 养殖场基本信息
- 养殖场名称、地址、联系人等基本信息维护
- 养殖场资质证书管理
- 养殖场规模信息记录
- 养殖场照片上传与展示

#### 4.2.2 养殖场地理信息
- 基于百度地图API的养殖场位置标注
- 养殖场地理围栏设置
- 区域养殖密度可视化展示

### 4.3 养殖环境监控模块

#### 4.3.1 实时数据监控
- 温度、湿度等环境参数实时展示
- 异常数据预警功能
- 历史数据趋势分析

#### 4.3.2 设备管理
- 传感器设备信息管理
- 设备状态监控
- 设备故障报警

### 4.4 养殖过程管理模块

#### 4.4.1 饲料管理
- 饲料种类信息维护
- 饲料投喂记录管理
- 饲料库存管理

#### 4.4.2 疫苗管理
- 疫苗信息维护
- 疫苗接种记录管理
- 疫苗批次追踪

#### 4.4.3 养殖档案
- 养殖动物个体信息管理
- 生长过程记录
- 出栏信息管理

### 4.5 产品管理模块

#### 4.5.1 产品信息管理
- 产品基本信息维护
- 产品质量标准设定
- 产品批次管理

#### 4.5.2 库存管理
- 产品入库管理
- 产品出库管理
- 库存预警功能

### 4.6 数据分析与报表模块

#### 4.6.1 数据可视化
- 基于ECharts的数据图表展示
- 实时监控大屏
- 历史数据趋势分析

#### 4.6.2 报表生成
- 养殖统计报表
- 销售分析报表
- 监管合规报表
- 自定义报表功能

### 4.7 系统管理模块

#### 4.7.1 系统配置
- 系统参数配置
- 字典数据管理
- 系统日志管理

#### 4.7.2 权限管理
- 角色权限配置
- 菜单权限管理
- 数据权限控制

## 5. 接口设计

### 5.1 通用API规范
#### 5.1.1 响应格式
所有API响应遵循统一格式：
```json
{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2025-01-18T10:30:00Z"
}
```

#### 5.1.2 错误处理
- HTTP状态码：4xx客户端错误，5xx服务端错误
- 错误信息：中英文错误描述
- 错误日志：记录详细错误信息

#### 5.1.3 认证机制
- Authorization: Bearer <token>
- Token过期：401 Unauthorized
- 权限不足：403 Forbidden

### 5.2 用户认证接口
- **POST /api/auth/login** - 用户登录
  - 请求体：{username, password}
  - 响应：JWT令牌和用户信息
- **POST /api/auth/logout** - 用户登出
  - 请求头：Authorization: Bearer <token>
  - 响应：登出成功消息
- **POST /api/auth/register** - 用户注册
  - 请求体：{username, email, password}
  - 响应：注册成功消息

### 5.3 用户管理接口
- **GET /api/users** - 获取用户列表（需要admin权限）
  - 查询参数：page, limit, search
  - 响应：用户列表分页数据
- **GET /api/users/{id}** - 获取用户详情（需要认证）
  - 路径参数：用户ID
  - 响应：用户详细信息
- **POST /api/users** - 创建用户（需要admin权限）
  - 请求体：用户信息
  - 响应：创建的用户信息
- **PUT /api/users/{id}** - 更新用户信息（需要认证）
  - 路径参数：用户ID
  - 请求体：更新字段
  - 响应：更新后的用户信息
- **DELETE /api/users/{id}** - 删除用户（需要admin权限）
  - 路径参数：用户ID
  - 响应：删除成功消息

### 5.4 养殖场管理接口
- **GET /api/farms** - 获取养殖场列表（需要认证）
  - 查询参数：page, limit, type, status
  - 响应：养殖场列表分页数据
- **GET /api/farms/{id}** - 获取养殖场详情（需要认证）
  - 路径参数：养殖场ID
  - 响应：养殖场详细信息
- **POST /api/farms** - 创建养殖场（需要manager权限）
  - 请求体：养殖场信息（包含地理位置JSON）
  - 响应：创建的养殖场信息
- **PUT /api/farms/{id}** - 更新养殖场信息（需要manager权限）
  - 路径参数：养殖场ID
  - 请求体：更新字段
  - 响应：更新后的养殖场信息
- **DELETE /api/farms/{id}** - 删除养殖场（需要admin权限）
  - 路径参数：养殖场ID
  - 响应：删除成功消息

### 5.5 设备管理接口
- **GET /api/devices** - 获取设备列表（需要认证）
  - 查询参数：page, limit, farm_id, type, status
  - 响应：设备列表分页数据
- **GET /api/devices/{id}** - 获取设备详情（需要认证）
  - 路径参数：设备ID
  - 响应：设备详细信息（包含实时指标数据）
- **POST /api/devices** - 创建设备（需要manager权限）
  - 请求体：设备信息
  - 响应：创建设备信息
- **PUT /api/devices/{id}** - 更新设备信息（需要manager权限）
  - 路径参数：设备ID
  - 请求体：更新字段
  - 响应：更新后的设备信息
- **DELETE /api/devices/{id}** - 删除设备（需要admin权限）
  - 路径参数：设备ID
  - 响应：删除成功消息

### 5.6 预警管理接口
- **GET /api/alerts** - 获取预警列表（需要认证）
  - 查询参数：page, limit, farm_id, level, status
  - 响应：预警列表分页数据
- **GET /api/alerts/{id}** - 获取预警详情（需要认证）
  - 路径参数：预警ID
  - 响应：预警详细信息
- **PUT /api/alerts/{id}/acknowledge** - 确认预警（需要manager权限）
  - 路径参数：预警ID
  - 响应：确认成功消息
- **PUT /api/alerts/{id}/resolve** - 解决预警（需要manager权限）
  - 路径参数：预警ID
  - 请求体：解决说明
  - 响应：解决成功消息

### 5.7 产品管理接口
- **GET /api/products** - 获取产品列表（需要认证）
  - 查询参数：page, limit, search
  - 响应：产品列表分页数据
- **GET /api/products/{id}** - 获取产品详情（需要认证）
  - 路径参数：产品ID
  - 响应：产品详细信息
- **POST /api/products** - 创建产品（需要manager权限）
  - 请求体：产品信息
  - 响应：创建的产品信息
- **PUT /api/products/{id}** - 更新产品信息（需要manager权限）
  - 路径参数：产品ID
  - 请求体：更新字段
  - 响应：更新后的产品信息
- **DELETE /api/products/{id}** - 删除产品（需要admin权限）
  - 路径参数：产品ID
  - 响应：删除成功消息

### 5.8 统计分析接口
- **GET /api/stats/overview** - 获取系统概览统计（需要认证）
  - 响应：养殖场数、设备数、动物数、预警数等
- **GET /api/stats/farms/{id}** - 获取养殖场统计（需要认证）
  - 路径参数：养殖场ID
  - 响应：养殖场详细统计数据
- **GET /api/stats/alerts** - 获取预警统计（需要认证）
  - 查询参数：timeRange（今日、本周、本月）
  - 响应：预警级别分布统计
- **GET /api/stats/animals** - 获取动物健康统计（需要认证）
  - 查询参数：farm_id
  - 响应：动物健康状态分布

## 6. 安全设计

### 6.1 认证安全
- 用户密码加密存储（BCrypt等）
- JWT令牌机制
- 登录失败次数限制
- 会话超时管理

### 6.2 接口安全
- HTTPS协议支持
- 接口访问权限控制
- 请求参数校验
- SQL注入防护

### 6.3 数据安全
- 敏感数据加密存储
- 数据备份策略
- 数据访问日志记录

## 7. 性能优化

### 7.1 前端优化
- 组件懒加载
- 图片压缩与懒加载
- 数据缓存机制
- 防抖节流处理

### 7.2 后端优化
- 数据库索引优化
- 接口缓存机制
- 数据库连接池
- 异步任务处理

### 7.3 数据库优化
- 查询语句优化
- 表结构设计优化
- 分表分库策略

## 8. 部署方案

### 8.1 开发环境
- 本地开发环境搭建
- 开发调试工具配置
- 代码版本管理

### 8.2 生产环境
- Docker容器化部署
- Nginx反向代理配置
- 负载均衡方案
- 监控告警机制

## 9. 扩展性设计

### 9.1 模块化扩展
- 支持功能模块的独立开发和部署
- 微服务架构兼容性设计

### 9.2 第三方服务集成
- 易于集成物联网设备数据
- 支持与其他监管系统对接
- 开放API接口设计

## 10. 后续发展规划

1. 引入微服务架构，提升系统可扩展性
2. 优化性能监控，提升系统稳定性
3. 增强数据分析能力，提供更深入的业务洞察
4. 完善移动端支持，提供更便捷的操作体验
5. 集成人工智能技术，实现智能预警和决策支持