# 宁夏智慧养殖监管平台产品需求文档

## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2025-01-18 | 产品经理 | 初始版本 |

## 1. 项目概述

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

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

### 1.3 成功标准
- 用户日活跃度提升20%
- 养殖场管理效率提升30%
- 异常预警响应时间缩短至5分钟内
- 系统可用性达到99.9%

### 1.4 范围界定
**本版本包含：**
- 用户权限管理系统
- 养殖场信息管理
- 设备监控管理
- 动物健康管理
- 预警管理系统
- 数据可视化展示

**本版本不包含：**
- 移动端小程序功能（二期规划）
- 人工智能预警功能（三期规划）
- 微服务架构改造（后续版本）

## 2. 用户角色与用例

### 2.1 用户角色
| 角色 | 描述 | 权限范围 |
|------|------|----------|
| 系统管理员 | 负责系统整体管理和维护 | 全系统权限，用户管理，系统配置 |
| 养殖场管理员 | 负责具体养殖场的管理 | 养殖场信息管理，设备监控，动物管理 |
| 监管人员 | 负责区域养殖监管 | 数据查看，预警处理，报表分析 |
| 普通用户 | 基础系统使用者 | 个人信息管理，数据查看 |

### 2.2 核心用例

#### 用例1：用户登录认证
**As a** 系统用户  
**I want to** 通过账号密码登录系统  
**So that** 我可以访问系统功能

**验收标准：**
- Given 用户打开登录页面
- When 输入正确的用户名和密码
- Then 系统跳转到仪表盘页面
- And 显示欢迎信息

#### 用例2：养殖场信息管理
**As a** 养殖场管理员  
**I want to** 管理养殖场基本信息  
**So that** 我可以维护养殖场档案

**验收标准：**
- Given 用户有养殖场管理权限
- When 进入养殖场管理页面
- Then 可以查看养殖场列表
- And 可以新增、编辑、删除养殖场信息

#### 用例3：实时设备监控
**As a** 监管人员  
**I want to** 实时查看设备状态  
**So that** 我可以及时发现设备异常

**验收标准：**
- Given 用户有设备查看权限
- When 进入设备监控页面
- Then 可以查看设备实时状态
- And 设备异常时收到预警通知

## 3. 功能需求

### 3.1 用户管理模块

#### 3.1.1 用户认证
**用户故事：** As a 用户，I want to 通过安全的方式登录系统，so that 我的账户信息得到保护

**验收标准：**
- Given 用户访问登录页面
- When 输入正确的凭证
- Then 系统颁发JWT令牌
- And 令牌有效期24小时
- And 密码使用bcrypt加密存储

#### 3.1.2 权限管理
**用户故事：** As a 系统管理员，I want to 管理用户角色和权限，so that 我可以控制不同用户的访问范围

**验收标准：**
- Given 管理员进入权限管理页面
- When 分配用户角色
- Then 用户获得相应权限
- And 权限变更实时生效

### 3.2 养殖场管理模块

#### 3.2.1 养殖场信息维护
**用户故事：** As a 养殖场管理员，I want to 维护养殖场基本信息，so that 信息准确完整

**验收标准：**
- Given 管理员进入养殖场管理
- When 填写养殖场信息（名称、类型、位置、联系人等）
- Then 信息保存到数据库
- And 地理位置信息格式正确

#### 3.2.2 地图展示
**用户故事：** As a 监管人员，I want to 在地图上查看养殖场分布，so that 我可以直观了解区域养殖情况

**验收标准：**
- Given 用户有地图查看权限
- When 打开地图页面
- Then 显示所有养殖场位置标记
- And 点击标记显示养殖场基本信息

### 3.3 设备监控模块

#### 3.3.1 设备状态监控
**用户故事：** As a 监管人员，I want to 实时监控设备状态，so that 我可以确保设备正常运行

**验收标准：**
- Given 设备数据正常上报
- When 用户查看设备监控页面
- Then 显示设备实时状态（在线、离线、维护）
- And 状态更新间隔不超过30秒

#### 3.3.2 设备预警
**用户故事：** As a 系统用户，I want to 接收设备异常预警，so that 我可以及时处理问题

**验收标准：**
- Given 设备出现异常状态
- When 系统检测到异常
- Then 发送预警通知给相关用户
- And 预警级别根据异常程度划分

### 3.4 动物管理模块

#### 3.4.1 动物信息管理
**用户故事：** As a 养殖场管理员，I want to 管理动物基本信息，so that 我可以跟踪动物健康状况

**验收标准：**
- Given 管理员进入动物管理
- When 录入动物信息（类型、数量、健康状态）
- Then 信息保存到数据库
- And 健康状态可更新

#### 3.4.2 健康监测
**用户故事：** As a 监管人员，I want to 查看动物健康数据，so that 我可以评估养殖场健康状况

**验收标准：**
- Given 有动物健康数据
- When 用户查看健康报表
- Then 显示健康状态统计
- And 可以按时间范围筛选

### 3.5 数据分析模块

#### 3.5.1 数据可视化
**用户故事：** As a 用户，I want to 通过图表查看数据，so that 我可以更直观理解数据趋势

**验收标准：**
- Given 有统计数据
- When 用户打开数据看板
- Then 显示ECharts图表
- And 图表支持交互操作

#### 3.5.2 报表生成
**用户故事：** As a 监管人员，I want to 生成养殖统计报表，so that 我可以进行决策分析

**验收标准：**
- Given 用户有报表权限
- When 选择报表类型和时间范围
- Then 生成PDF格式报表
- And 报表包含关键指标数据

## 4. 非功能需求

### 4.1 性能要求
- 页面加载时间：<3秒
- API响应时间：<500ms
- 并发用户支持：1000+用户
- 数据查询性能：复杂查询<2秒

### 4.2 安全要求
- 数据传输：HTTPS加密
- 身份认证：JWT令牌机制
- 密码存储：bcrypt加密
- SQL注入防护：ORM参数化查询
- XSS防护：输入验证和转义

### 4.3 可靠性要求
- 系统可用性：99.9%
- 数据备份：每日自动备份
- 故障恢复：30分钟内恢复
- 监控告警：关键指标监控

### 4.4 兼容性要求
- 浏览器支持：Chrome、Firefox、Safari最新版本
- 移动端适配：响应式设计
- 分辨率支持：1920x1080及以上

## 5. 原型说明

### 5.1 界面布局
- **顶部导航栏**：系统logo、用户信息、通知中心、退出按钮
- **侧边菜单**：模块导航菜单，支持折叠展开
- **主内容区**：功能页面展示区域
- **底部信息**：版权信息、系统版本

### 5.2 关键页面

#### 5.2.1 登录页面
- 用户名/密码输入框
- 记住密码选项
- 登录按钮
- 忘记密码链接

#### 5.2.2 仪表盘页面
- 数据概览卡片（养殖场数、设备数、动物数、预警数）
- 实时监控图表
- 最新预警列表
- 快捷操作入口

#### 5.2.3 养殖场管理页面
- 养殖场列表表格
- 搜索筛选功能
- 新增/编辑表单
- 地图展示选项卡

#### 5.2.4 设备监控页面
- 设备状态卡片布局
- 实时数据图表
- 状态筛选功能
- 设备详情模态框

#### 5.2.5 数据报表页面
- 时间范围选择器
- 图表展示区域
- 报表类型切换
- 数据导出功能

### 5.3 交互流程

#### 5.3.1 登录流程
1. 用户访问系统 → 跳转到登录页面
2. 输入用户名密码 → 点击登录按钮
3. 验证通过 → 跳转到仪表盘页面
4. 验证失败 → 显示错误提示

#### 5.3.2 预警处理流程
1. 设备异常 → 系统生成预警
2. 预警通知 → 用户收到通知
3. 查看预警详情 → 进入预警处理页面
4. 处理预警 → 更新预警状态
5. 填写处理说明 → 完成预警处理

## 6. API规范

### 6.1 通用响应格式
```json
{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2025-01-18T10:30:00Z"
}
```

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

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

## 7. 数据字典

### 7.1 状态枚举
- 用户状态：active, inactive, banned
- 设备状态：online, offline, maintenance
- 预警级别：low, medium, high, critical
- 预警状态：active, acknowledged, resolved
- 健康状态：healthy, sick, quarantine

### 7.2 字段规范
- 时间格式：YYYY-MM-DD HH:mm:ss
- 金额单位：分（整数存储）
- 地理坐标：JSON格式 {latitude: 0, longitude: 0}

## 8. 依赖关系

### 8.1 第三方服务
- 百度地图API：地理位置服务
- 邮件服务：预警通知发送
- SMS服务：重要通知短信

### 8.2 基础设施
- MySQL数据库：数据存储
- Redis缓存：会话缓存
- 文件存储：图片文件存储
- CDN服务：静态资源加速

## 9. 约束条件

### 9.1 技术约束
- 前端：Vue 3.x + Ant Design Vue
- 后端：Node.js + Express + Sequelize
- 数据库：MySQL 8.0+
- 部署环境：Docker容器化

### 9.2 业务约束
- 数据隐私：养殖场数据权限隔离
- 监管合规：符合农业监管部门要求
- 数据准确性：关键数据必须验证

## 10. 待定问题

1. **移动端支持范围**：是否需要开发原生APP还是PWA即可？
2. **第三方集成**：需要集成哪些物联网设备厂商？
3. **数据保留策略**：历史数据保留多长时间？
4. **多语言支持**：是否需要支持英文版本？

---
*文档最后更新：2025年1月18日*