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

## 版本历史

| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2025-01-18 | 产品经理 | 初始版本 |
| v2.0 | 2025-01-19 | 产品经理 | 全面重构，增加多端支持 |

## 1. 项目概述

### 1.1 项目背景

宁夏回族自治区作为中国重要的畜牧业基地，养殖业在区域经济发展中占据重要地位。随着现代信息技术的快速发展和国家对食品安全、环境保护要求的不断提高，传统养殖业正面临数字化转型的迫切需求。

**行业痛点：**
- 养殖过程缺乏有效监管，食品安全风险较高
- 传统管理方式效率低下，数据记录不完整
- 缺乏统一的信息化平台，各部门信息孤岛严重
- 应急响应能力不足，疫情防控压力大
- 金融保险服务与养殖业结合不够紧密

### 1.2 项目目标

**总体目标：** 构建一个现代化、智能化的养殖监管平台，实现养殖全过程数字化管理，提升监管效率，保障食品安全，促进产业升级。

**具体目标：**
- 建立统一的养殖信息管理体系
- 实现养殖环境实时监控和预警
- 提供全程可追溯的养殖档案管理
- 构建多部门协同的监管机制
- 集成金融保险服务，支持产业发展

### 1.3 成功标准

**业务指标：**
- 养殖场数字化覆盖率达到90%以上
- 异常事件响应时间缩短至5分钟内
- 养殖档案完整性达到95%以上
- 用户满意度达到85%以上

**技术指标：**
- 系统可用性达到99.9%
- 接口响应时间小于500ms
- 支持1000+并发用户访问
- 数据准确性达到99.5%以上

### 1.4 范围界定

**本版本包含：**
- 核心养殖监管平台（Web端）
- 数据可视化大屏系统
- 银行端小程序（金融服务）
- 政府端小程序（监管服务）
- 保险端小程序（保险服务）
- 官方网站（信息展示）

**本版本不包含：**
- 移动端原生APP（后续版本规划）
- 人工智能预测分析（三期规划）
- 区块链溯源功能（四期规划）
- 国际化多语言支持（后续版本）

## 2. 用户角色与用例

### 2.1 用户角色定义

| 角色 | 描述 | 主要职责 | 权限范围 |
|------|------|----------|----------|
| **系统管理员** | 平台技术管理员 | 系统维护、用户管理、权限配置 | 全系统权限 |
| **监管部门用户** | 政府监管人员 | 监管政策制定、数据审核、异常处理 | 监管数据查看、政策发布 |
| **养殖场管理员** | 养殖场负责人 | 养殖场日常管理、数据录入、设备维护 | 本场数据管理权限 |
| **养殖场员工** | 一线养殖人员 | 日常养殖操作、数据记录、设备操作 | 基础操作权限 |
| **银行业务员** | 金融服务人员 | 贷款审批、风险评估、客户服务 | 金融数据查看权限 |
| **保险专员** | 保险服务人员 | 保险承保、理赔处理、风险评估 | 保险相关数据权限 |
| **技术支持** | 平台技术支持 | 系统维护、故障处理、用户培训 | 系统维护权限 |

### 2.2 核心用例场景

#### 2.2.1 养殖场管理场景
**用例：** 新建养殖场档案
- **参与者：** 养殖场管理员
- **前置条件：** 用户已登录系统，具有养殖场管理权限
- **主要流程：**
  1. 进入养殖场管理模块
  2. 填写基本信息（名称、地址、规模等）
  3. 上传相关证件和图片
  4. 设置地理围栏
  5. 配置设备信息
  6. 提交审核
- **后置条件：** 养殖场档案创建成功，等待审核

#### 2.2.2 设备监控场景
**用例：** 实时监控设备状态
- **参与者：** 养殖场管理员、员工
- **前置条件：** 设备已正常连接，用户有监控权限
- **主要流程：**
  1. 进入设备监控界面
  2. 查看设备实时状态
  3. 接收异常告警
  4. 处理异常情况
  5. 记录处理结果
- **后置条件：** 设备状态正常，异常已处理

#### 2.2.3 金融服务场景
**用例：** 申请养殖贷款
- **参与者：** 养殖场管理员、银行业务员
- **前置条件：** 养殖场已认证，具备贷款条件
- **主要流程：**
  1. 在银行小程序提交贷款申请
  2. 上传相关材料
  3. 系统自动评估风险
  4. 银行业务员审核
  5. 放款或拒绝
- **后置条件：** 贷款申请处理完成

## 3. 功能需求

### 3.1 核心业务功能

#### 3.1.1 养殖场管理模块

**功能描述：** 提供养殖场全生命周期管理功能

**用户故事：**
- As a 养殖场管理员, I want to 创建和管理养殖场档案, so that 可以规范化管理养殖场信息
- As a 监管人员, I want to 查看和审核养殖场信息, so that 确保养殖场符合监管要求
- As a 系统管理员, I want to 统计养殖场数据, so that 为决策提供数据支持

**验收标准：**
```gherkin
Given 用户是养殖场管理员
When 用户填写完整的养殖场信息并提交
Then 系统应该创建养殖场档案并生成唯一编号
And 系统应该发送审核通知给监管人员
And 养殖场状态应该设置为"待审核"
```

**详细功能点：**
- 养殖场基本信息管理（名称、地址、规模、类型等）
- 证件管理（营业执照、养殖许可证等）
- 地理位置标注和电子围栏设置
- 圈舍信息管理（数量、面积、容量等）
- 养殖场图片和视频管理
- 审核流程管理（提交、审核、通过、拒绝）

#### 3.1.2 动物健康管理模块

**功能描述：** 提供动物全生命周期健康管理

**用户故事：**
- As a 养殖场员工, I want to 记录动物健康信息, so that 及时发现和处理健康问题
- As a 兽医, I want to 查看动物健康历史, so that 制定合适的治疗方案
- As a 监管人员, I want to 监控疫情风险, so that 及时采取防控措施

**验收标准：**
```gherkin
Given 用户是养殖场员工
When 用户录入动物健康检查数据
Then 系统应该保存健康记录
And 如果发现异常指标，系统应该自动生成告警
And 系统应该更新动物健康状态
```

**详细功能点：**
- 动物档案管理（品种、年龄、来源、标识等）
- 健康检查记录（体温、体重、食欲等）
- 疫苗接种管理（疫苗类型、接种时间、有效期等）
- 疾病诊疗记录（症状、诊断、治疗方案等）
- 批次管理（进场、转移、出场记录）
- 死亡和淘汰记录管理

#### 3.1.3 IoT设备监控模块

**功能描述：** 实时监控养殖环境和设备状态

**用户故事：**
- As a 养殖场管理员, I want to 实时查看环境数据, so that 及时调整养殖环境
- As a 设备维护员, I want to 监控设备运行状态, so that 预防设备故障
- As a 系统管理员, I want to 管理设备配置, so that 确保监控系统正常运行

**验收标准：**
```gherkin
Given 设备已正常连接到系统
When 设备传感器检测到异常数据
Then 系统应该立即生成告警
And 系统应该通知相关责任人
And 系统应该记录异常事件
```

**详细功能点：**
- 环境监测（温度、湿度、氨气、二氧化碳等）
- 设备状态监控（在线状态、运行参数、故障信息）
- 实时数据展示（图表、仪表盘、趋势分析）
- 告警管理（阈值设置、告警规则、通知方式）
- 历史数据查询和分析
- 设备远程控制（开关、参数调节等）

#### 3.1.4 数据可视化模块

**功能描述：** 提供丰富的数据分析和可视化功能

**用户故事：**
- As a 管理者, I want to 查看数据统计报表, so that 了解养殖场运营状况
- As a 决策者, I want to 分析趋势数据, so that 制定科学的管理策略
- As a 监管人员, I want to 监控区域数据, so that 掌握整体监管情况

**验收标准：**
```gherkin
Given 用户有数据查看权限
When 用户选择查看统计报表
Then 系统应该展示相应的图表和数据
And 数据应该实时更新
And 用户应该能够导出报表
```

**详细功能点：**
- 实时数据大屏展示
- 统计报表生成（日报、周报、月报）
- 趋势分析图表（折线图、柱状图、饼图等）
- 地图可视化（养殖场分布、区域统计）
- 数据导出功能（Excel、PDF、图片）
- 自定义报表配置

### 3.2 多端应用功能

#### 3.2.1 银行端小程序

**功能描述：** 为银行提供养殖业金融服务支持

**核心功能：**
- 客户信息管理和风险评估
- 贷款申请和审批流程
- 还款管理和逾期提醒
- 养殖数据查看和分析
- 金融产品推荐

**用户故事：**
- As a 银行业务员, I want to 查看客户养殖数据, so that 评估贷款风险
- As a 养殖场主, I want to 在线申请贷款, so that 快速获得资金支持

#### 3.2.2 政府端小程序

**功能描述：** 为政府监管部门提供移动监管工具

**核心功能：**
- 养殖场监管和检查记录
- 政策发布和通知推送
- 应急事件处理和上报
- 统计数据查看和分析
- 证件审批和管理

**用户故事：**
- As a 监管人员, I want to 移动端查看监管数据, so that 随时掌握监管情况
- As a 政策制定者, I want to 发布政策通知, so that 及时传达政策信息

#### 3.2.3 保险端小程序

**功能描述：** 为保险公司提供养殖保险服务支持

**核心功能：**
- 保险产品展示和销售
- 投保申请和承保管理
- 理赔申请和处理流程
- 风险评估和定价
- 客户服务和咨询

**用户故事：**
- As a 保险专员, I want to 评估养殖风险, so that 制定合理的保险方案
- As a 养殖场主, I want to 在线申请理赔, so that 快速获得理赔服务

## 4. 非功能需求

### 4.1 性能需求

**响应时间要求：**
- 页面加载时间：≤ 3秒
- API接口响应时间：≤ 500ms
- 数据库查询时间：≤ 200ms
- 大屏数据刷新间隔：≤ 5秒

**并发性能要求：**
- 支持1000+并发用户访问
- 支持10000+设备同时在线
- 支持100万+历史数据查询
- 峰值QPS：1000+

**吞吐量要求：**
- 数据处理能力：10000条/秒
- 文件上传速度：≥ 1MB/s
- 数据导出速度：≥ 500KB/s

### 4.2 可靠性需求

**可用性要求：**
- 系统可用性：99.9%
- 计划内停机时间：≤ 4小时/月
- 故障恢复时间：≤ 30分钟
- 数据备份频率：每日备份

**容错性要求：**
- 支持服务降级和熔断
- 支持数据库主从切换
- 支持负载均衡和故障转移
- 支持异常情况下的数据恢复

### 4.3 安全性需求

**身份认证：**
- 支持多因子认证（MFA）
- 密码复杂度要求
- 登录失败锁定机制
- 会话超时管理

**数据安全：**
- 敏感数据加密存储
- 数据传输加密（HTTPS/TLS）
- 数据访问权限控制
- 数据脱敏和匿名化

**系统安全：**
- SQL注入防护
- XSS攻击防护
- CSRF攻击防护
- API访问频率限制

### 4.4 可扩展性需求

**水平扩展：**
- 支持微服务架构改造
- 支持容器化部署
- 支持云原生架构
- 支持多数据中心部署

**功能扩展：**
- 支持插件化架构
- 支持第三方系统集成
- 支持多租户模式
- 支持国际化扩展

## 5. 技术约束

### 5.1 技术栈要求

**后端技术栈：**
- 运行环境：Node.js 16.20.2+
- Web框架：Express.js 4.18+
- 数据库：MySQL 8.0+
- ORM框架：Sequelize 6.0+
- 缓存：Redis 6.0+

**前端技术栈：**
- 框架：Vue 3.4+ + Vite
- UI组件库：Ant Design Vue 4.0+
- 状态管理：Pinia 2.1+
- 图表库：ECharts 5.4+
- 地图服务：百度地图API

**小程序技术栈：**
- 框架：uni-app 3.0+
- UI组件库：uni-ui
- 状态管理：Pinia
- HTTP客户端：uni.request

### 5.2 部署环境要求

**硬件要求：**
- CPU：8核心以上
- 内存：16GB以上
- 存储：500GB SSD以上
- 网络：千兆网络

**软件环境：**
- 操作系统：Ubuntu 20.04 LTS / CentOS 8
- 容器：Docker 20.10+
- 反向代理：Nginx 1.20+
- 进程管理：PM2 5.0+

### 5.3 第三方服务依赖

**地图服务：**
- 百度地图API（主要）
- 高德地图API（备用）

**消息推送：**
- 微信公众号推送
- 短信服务（阿里云）
- 邮件服务（腾讯企业邮）

**文件存储：**
- 阿里云OSS（主要）
- 腾讯云COS（备用）

## 6. 数据模型设计

### 6.1 核心实体关系

```mermaid
erDiagram
    Farm ||--o{ Animal : contains
    Farm ||--o{ Device : has
    Farm ||--o{ Pen : includes
    Farm ||--o{ User : manages
    Animal }o--|| CattleType : belongs_to
    Animal }o--|| CattleBatch : belongs_to
    Device ||--o{ SensorData : generates
    Device ||--o{ Alert : triggers
    User }o--|| Role : has
    Order ||--o{ OrderItem : contains
    Product ||--o{ OrderItem : includes
```

### 6.2 主要数据表

#### 6.2.1 养殖场表 (farms)
| 字段名 | 类型 | 长度 | 必填 | 说明 |
|--------|------|------|------|------|
| id | INT | - | 是 | 主键ID |
| name | VARCHAR | 100 | 是 | 养殖场名称 |
| address | VARCHAR | 200 | 是 | 详细地址 |
| latitude | DECIMAL | 10,8 | 否 | 纬度 |
| longitude | DECIMAL | 11,8 | 否 | 经度 |
| scale | ENUM | - | 是 | 规模（小型/中型/大型） |
| type | VARCHAR | 50 | 是 | 养殖类型 |
| status | ENUM | - | 是 | 状态（正常/停用/审核中） |
| created_at | TIMESTAMP | - | 是 | 创建时间 |
| updated_at | TIMESTAMP | - | 是 | 更新时间 |

#### 6.2.2 动物表 (animals)
| 字段名 | 类型 | 长度 | 必填 | 说明 |
|--------|------|------|------|------|
| id | INT | - | 是 | 主键ID |
| farm_id | INT | - | 是 | 养殖场ID |
| ear_tag | VARCHAR | 50 | 是 | 耳标号 |
| breed | VARCHAR | 50 | 是 | 品种 |
| gender | ENUM | - | 是 | 性别 |
| birth_date | DATE | - | 否 | 出生日期 |
| weight | DECIMAL | 8,2 | 否 | 体重(kg) |
| health_status | ENUM | - | 是 | 健康状态 |
| created_at | TIMESTAMP | - | 是 | 创建时间 |
| updated_at | TIMESTAMP | - | 是 | 更新时间 |

#### 6.2.3 设备表 (devices)
| 字段名 | 类型 | 长度 | 必填 | 说明 |
|--------|------|------|------|------|
| id | INT | - | 是 | 主键ID |
| farm_id | INT | - | 是 | 养殖场ID |
| device_id | VARCHAR | 100 | 是 | 设备编号 |
| device_name | VARCHAR | 100 | 是 | 设备名称 |
| device_type | VARCHAR | 50 | 是 | 设备类型 |
| location | VARCHAR | 100 | 否 | 安装位置 |
| status | ENUM | - | 是 | 设备状态 |
| last_online | TIMESTAMP | - | 否 | 最后在线时间 |
| created_at | TIMESTAMP | - | 是 | 创建时间 |
| updated_at | TIMESTAMP | - | 是 | 更新时间 |

## 7. API设计规范

### 7.1 API设计原则

**RESTful设计：**
- 使用标准HTTP方法（GET、POST、PUT、DELETE）
- 资源导向的URL设计
- 统一的响应格式
- 合理的HTTP状态码使用

**版本控制：**
- URL路径版本控制：`/api/v1/`
- 向后兼容性保证
- 版本废弃通知机制

**安全性：**
- JWT Token认证
- API访问频率限制
- 请求参数验证
- 响应数据脱敏

### 7.2 核心API接口

#### 7.2.1 认证相关API
```
POST /api/v1/auth/login          # 用户登录
POST /api/v1/auth/logout         # 用户登出
POST /api/v1/auth/refresh        # 刷新Token
GET  /api/v1/auth/profile        # 获取用户信息
PUT  /api/v1/auth/profile        # 更新用户信息
POST /api/v1/auth/change-password # 修改密码
```

#### 7.2.2 养殖场管理API
```
GET    /api/v1/farms             # 获取养殖场列表
GET    /api/v1/farms/{id}        # 获取养殖场详情
POST   /api/v1/farms             # 创建养殖场
PUT    /api/v1/farms/{id}        # 更新养殖场信息
DELETE /api/v1/farms/{id}        # 删除养殖场
GET    /api/v1/farms/{id}/stats  # 获取养殖场统计数据
```

#### 7.2.3 动物管理API
```
GET    /api/v1/animals           # 获取动物列表
GET    /api/v1/animals/{id}      # 获取动物详情
POST   /api/v1/animals           # 添加动物
PUT    /api/v1/animals/{id}      # 更新动物信息
DELETE /api/v1/animals/{id}      # 删除动物记录
GET    /api/v1/animals/{id}/health # 获取健康记录
POST   /api/v1/animals/{id}/health # 添加健康记录
```

#### 7.2.4 设备监控API
```
GET    /api/v1/devices           # 获取设备列表
GET    /api/v1/devices/{id}      # 获取设备详情
POST   /api/v1/devices           # 添加设备
PUT    /api/v1/devices/{id}      # 更新设备信息
DELETE /api/v1/devices/{id}      # 删除设备
GET    /api/v1/devices/{id}/data # 获取设备数据
POST   /api/v1/devices/{id}/control # 设备控制
```

### 7.3 响应格式规范

**成功响应格式：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 具体数据内容
  },
  "timestamp": "2025-01-19T10:00:00Z"
}
```

**错误响应格式：**
```json
{
  "code": 400,
  "message": "参数错误",
  "error": {
    "type": "VALIDATION_ERROR",
    "details": [
      {
        "field": "name",
        "message": "名称不能为空"
      }
    ]
  },
  "timestamp": "2025-01-19T10:00:00Z"
}
```

**分页响应格式：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  },
  "timestamp": "2025-01-19T10:00:00Z"
}
```

## 8. 用户界面设计要求

### 8.1 设计原则

**用户体验原则：**
- 简洁直观的界面设计
- 一致的交互体验
- 快速响应的操作反馈
- 友好的错误提示

**可访问性原则：**
- 支持键盘导航
- 合理的颜色对比度
- 清晰的文字大小
- 响应式设计适配

### 8.2 界面布局要求

**管理后台布局：**
- 左侧导航菜单
- 顶部用户信息栏
- 主内容区域
- 底部状态栏

**数据大屏布局：**
- 全屏显示模式
- 多区域数据展示
- 实时数据更新
- 自适应屏幕尺寸

**小程序界面：**
- 底部Tab导航
- 顶部标题栏
- 主内容滚动区域
- 浮动操作按钮

### 8.3 交互设计要求

**操作反馈：**
- 加载状态提示
- 操作成功/失败提示
- 确认对话框
- 进度条显示

**数据展示：**
- 表格分页和排序
- 图表交互和筛选
- 搜索和过滤功能
- 数据导出功能

## 9. 测试要求

### 9.1 测试策略

**测试类型：**
- 单元测试：覆盖率≥80%
- 集成测试：API接口测试
- 系统测试：端到端功能测试
- 性能测试：负载和压力测试
- 安全测试：漏洞扫描和渗透测试

**测试环境：**
- 开发环境：开发人员自测
- 测试环境：QA团队测试
- 预生产环境：用户验收测试
- 生产环境：监控和回归测试

### 9.2 测试用例要求

**功能测试用例：**
- 正常流程测试
- 异常流程测试
- 边界值测试
- 兼容性测试

**性能测试用例：**
- 响应时间测试
- 并发用户测试
- 数据量测试
- 资源使用测试

## 10. 部署和运维要求

### 10.1 部署架构

**生产环境架构：**
- 负载均衡器：Nginx
- 应用服务器：Node.js集群
- 数据库：MySQL主从架构
- 缓存：Redis集群
- 文件存储：云存储服务

**容器化部署：**
- Docker容器化
- Docker Compose编排
- Kubernetes集群管理（可选）

### 10.2 监控和运维

**系统监控：**
- 服务器资源监控
- 应用性能监控
- 数据库性能监控
- 网络状态监控

**日志管理：**
- 应用日志收集
- 错误日志告警
- 访问日志分析
- 审计日志记录

**备份策略：**
- 数据库定时备份
- 文件定时备份
- 配置文件备份
- 灾难恢复预案

## 11. 项目里程碑

### 11.1 开发计划

| 阶段 | 时间节点 | 交付物 | 负责人 |
|------|----------|--------|--------|
| 需求确认 | 2025-01-25 | 需求规格说明书 | 产品经理 |
| 架构设计 | 2025-02-05 | 技术架构文档 | 架构师 |
| 数据库设计 | 2025-02-10 | 数据库设计文档 | 数据库工程师 |
| 后端开发 | 2025-03-15 | 后端API服务 | 后端团队 |
| 前端开发 | 2025-03-20 | 前端管理界面 | 前端团队 |
| 小程序开发 | 2025-03-25 | 三端小程序 | 小程序团队 |
| 集成测试 | 2025-04-05 | 测试报告 | 测试团队 |
| 用户验收 | 2025-04-15 | 验收报告 | 产品经理 |
| 上线部署 | 2025-04-20 | 生产环境 | 运维团队 |

### 11.2 风险管控

**技术风险：**
- 第三方API服务不稳定
- 数据库性能瓶颈
- 前端兼容性问题
- 小程序审核风险

**业务风险：**
- 需求变更频繁
- 用户接受度不高
- 竞品冲击
- 政策法规变化

**项目风险：**
- 人员流动
- 进度延期
- 质量问题
- 预算超支

**应对措施：**
- 制定详细的风险应对预案
- 建立风险监控机制
- 定期进行风险评估
- 及时调整项目计划

---

**文档维护说明：**
- 本文档将根据项目进展定期更新
- 所有变更需经过评审和批准
- 文档版本控制采用Git管理
- 相关干系人需及时同步文档变更

*最后更新时间：2025-01-19*
*文档版本：v2.0*
*维护人员：产品经理*