nxxmdata/design.md

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

## 1. 项目概述

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

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

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

## 2. 技术架构设计

### 2.1 整体架构
本项目采用前后端分离的架构设计模式，前端使用Vue.js框架，后端采用Python技术栈，数据库使用MySQL进行数据存储。

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

### 2.3 后端技术栈
- **运行环境**: Python 3.8+
- **Web框架**: FastAPI 或 Flask（可选）
- **API风格**: RESTful API
- **认证授权**: JWT
- **数据库访问**: SQLAlchemy 或 Peewee ORM
- **依赖管理**: uv 工具

#### 2.3.1 Python环境配置与依赖管理
1. `uv` 是一个快速的 Python 包和虚拟环境管理工具
2. MCP Server 依赖 `uv` 工具运行，必须确保系统环境中已安装 uv
3. 安装 `uv` 的推荐方法：
   - 使用官方安装脚本：`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
   - 或通过 pip 安装：`pip install uv`
4. 设置国内镜像源加速下载：
   ```bash
   $env:UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"
   ```

### 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 | 密码（加密后） |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 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 |  | 角色描述 |
| created_at | TIMESTAMP | 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 | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 分配时间 |

#### 3.3.4 产品表 (products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 产品ID |
| name | VARCHAR(100) | NOT NULL | 产品名称 |
| description | TEXT |  | 产品描述 |
| price | DECIMAL(10,2) | NOT NULL | 产品价格 |
| stock | INT | DEFAULT 0 | 库存数量 |
| status | ENUM('active', 'inactive') | DEFAULT 'active' | 产品状态 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 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 | DECIMAL(10,2) | NOT NULL | 订单总金额 |
| status | ENUM('pending', 'paid', 'shipped', 'delivered', 'cancelled') | DEFAULT 'pending' | 订单状态 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 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 | NOT NULL | 数量 |
| price | DECIMAL(10,2) | NOT NULL | 单价 |

### 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 用户认证接口
- POST /api/auth/login - 用户登录
- POST /api/auth/logout - 用户登出
- POST /api/auth/register - 用户注册

### 5.2 用户管理接口
- GET /api/users - 获取用户列表
- GET /api/users/{id} - 获取用户详情
- POST /api/users - 创建用户
- PUT /api/users/{id} - 更新用户信息
- DELETE /api/users/{id} - 删除用户

### 5.3 养殖场管理接口
- GET /api/farms - 获取养殖场列表
- GET /api/farms/{id} - 获取养殖场详情
- POST /api/farms - 创建养殖场
- PUT /api/farms/{id} - 更新养殖场信息
- DELETE /api/farms/{id} - 删除养殖场

### 5.4 产品管理接口
- GET /api/products - 获取产品列表
- GET /api/products/{id} - 获取产品详情
- POST /api/products - 创建产品
- PUT /api/products/{id} - 更新产品信息
- DELETE /api/products/{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. 集成人工智能技术，实现智能预警和决策支持