diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..aa2e61b --- /dev/null +++ b/PRD.md @@ -0,0 +1,340 @@ +# 宁夏智慧养殖监管平台产品需求文档 + +## 版本历史 +| 版本 | 日期 | 作者 | 描述 | +|------|------|------|------| +| 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过期: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日* \ No newline at end of file diff --git a/README.md b/README.md index b5ced52..3ba057f 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ nxxmdata/ └── 配置文件 ├── arch.md # 架构文档 ├── design.md # 详细设计 + ├── PRD.md # 产品需求文档 ├── dev-plan.md # 开发计划 ├── task.md # 任务列表 ├── schema.sql # 数据库架构 diff --git a/arch.md b/arch.md index 9cc2267..0d5c24b 100644 --- a/arch.md +++ b/arch.md @@ -176,9 +176,10 @@ **后端技术栈:** - **运行环境**: Node.js 18.0+ - **Web框架**: Express.js 4.18+ +- **API风格**: RESTful API - **ORM框架**: Sequelize 6.30+ -- **数据库**: MySQL (mysql2 3.0+) -- **认证**: JWT (jsonwebtoken 9.0+) +- **数据库**: MySQL 8.0+ (mysql2 3.0+) +- **认证授权**: JWT (jsonwebtoken 9.0+) - **密码加密**: bcrypt 5.1+ - **API文档**: Swagger (swagger-jsdoc + swagger-ui-express) - **日志管理**: Winston 3.17+ @@ -198,6 +199,30 @@ - **图表库**: 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代理到后端服务器 diff --git a/create_tables.sql b/create_tables.sql index f05124e..96b2aa4 100644 --- a/create_tables.sql +++ b/create_tables.sql @@ -205,15 +205,43 @@ INSERT IGNORE INTO `roles` (`name`, `description`) VALUES ('operator', '操作员'), ('viewer', '查看者'); --- 插入默认管理员用户(密码: admin123,需要在应用中加密) -INSERT IGNORE INTO `users` (`username`, `email`, `password`, `status`) VALUES -('admin', 'admin@nxxmdata.com', '$2b$10$placeholder_hash_for_admin123', 'active'); +-- 插入默认管理员用户(密码: admin123,使用bcrypt加密) +INSERT IGNORE INTO `users` (`username`, `email`, `password`, `phone`, `avatar`, `status`) VALUES +('admin', 'admin@nxxmdata.com', '$2b$10$kWV4BQk3P4iSn79kQEEoduByeVo8kv41r7FI04mON1/zcrpF7.kn6', '13800138000', '/uploads/avatars/default.png', 'active'), +('manager', 'manager@nxxmdata.com', '$2b$10$kWV4BQk3P4iSn79kQEEoduByeVo8kv41r7FI04mON1/zcrpF7.kn6', '13800138001', '/uploads/avatars/default.png', 'active'), +('user', 'user@nxxmdata.com', '$2b$10$kWV4BQk3P4iSn79kQEEoduByeVo8kv41r7FI04mON1/zcrpF7.kn6', '13800138002', '/uploads/avatars/default.png', 'active'); --- 为管理员分配admin角色 +-- 为用户分配角色 INSERT IGNORE INTO `user_roles` (`user_id`, `role_id`) SELECT u.id, r.id FROM `users` u, `roles` r -WHERE u.username = 'admin' AND r.name = 'admin'; +WHERE (u.username = 'admin' AND r.name = 'admin') + OR (u.username = 'manager' AND r.name = 'manager') + OR (u.username = 'user' AND r.name = 'viewer'); + +-- 插入示例养殖场数据 +INSERT IGNORE INTO `farms` (`name`, `type`, `location`, `address`, `contact`, `phone`, `status`) VALUES +('宁夏示范养殖场', '奶牛养殖', '{"latitude": 38.46667, "longitude": 106.26667}', '宁夏回族自治区银川市金凤区', '张经理', '13800138000', 'active'), +('银川现代化养殖基地', '肉牛养殖', '{"latitude": 38.48779, "longitude": 106.22541}', '宁夏回族自治区银川市兴庆区', '李主任', '13800138001', 'active'), +('吴忠生态养殖园', '综合养殖', '{"latitude": 37.98629, "longitude": 106.19273}', '宁夏回族自治区吴忠市利通区', '王场长', '13800138002', 'active'); + +-- 插入示例动物数据 +INSERT IGNORE INTO `animals` (`type`, `count`, `farm_id`, `health_status`, `last_inspection`) VALUES +('奶牛', 500, 1, 'healthy', '2025-01-18 10:00:00'), +('肉牛', 300, 2, 'healthy', '2025-01-18 09:30:00'), +('绵羊', 1000, 3, 'healthy', '2025-01-18 11:00:00'); + +-- 插入示例设备数据 +INSERT IGNORE INTO `devices` (`name`, `type`, `status`, `farm_id`, `installation_date`, `metrics`) VALUES +('温度传感器001', '温度传感器', 'online', 1, '2024-01-01', '{"temperature": 25.5, "humidity": 60}'), +('湿度传感器001', '湿度传感器', 'online', 1, '2024-01-01', '{"temperature": 25.3, "humidity": 62}'), +('监控摄像头001', '摄像头', 'online', 2, '2024-02-01', '{"status": "normal", "resolution": "1080p"}'); + +-- 插入示例产品数据 +INSERT IGNORE INTO `products` (`name`, `description`, `price`, `stock`, `image_url`) VALUES +('优质鲜牛奶', '新鲜优质牛奶,富含营养', 5000, 1000, '/uploads/products/milk.jpg'), +('有机牛肉', '无添加有机牛肉', 12000, 500, '/uploads/products/beef.jpg'), +('纯羊毛制品', '100%纯羊毛制品', 8000, 300, '/uploads/products/wool.jpg'); -- ============================================ -- 索引优化建议 diff --git a/design.md b/design.md index cc223a4..cf480b6 100644 --- a/design.md +++ b/design.md @@ -347,31 +347,138 @@ ## 5. 接口设计 -### 5.1 用户认证接口 -- POST /api/auth/login - 用户登录 -- POST /api/auth/logout - 用户登出 -- POST /api/auth/register - 用户注册 +### 5.1 通用API规范 +#### 5.1.1 响应格式 +所有API响应遵循统一格式: +```json +{ + "success": true, + "data": {}, + "message": "操作成功", + "timestamp": "2025-01-18T10:30:00Z" +} +``` -### 5.2 用户管理接口 -- GET /api/users - 获取用户列表 -- GET /api/users/{id} - 获取用户详情 -- POST /api/users - 创建用户 -- PUT /api/users/{id} - 更新用户信息 -- DELETE /api/users/{id} - 删除用户 +#### 5.1.2 错误处理 +- HTTP状态码:4xx客户端错误,5xx服务端错误 +- 错误信息:中英文错误描述 +- 错误日志:记录详细错误信息 -### 5.3 养殖场管理接口 -- GET /api/farms - 获取养殖场列表 -- GET /api/farms/{id} - 获取养殖场详情 -- POST /api/farms - 创建养殖场 -- PUT /api/farms/{id} - 更新养殖场信息 -- DELETE /api/farms/{id} - 删除养殖场 +#### 5.1.3 认证机制 +- Authorization: Bearer +- Token过期:401 Unauthorized +- 权限不足:403 Forbidden -### 5.4 产品管理接口 -- GET /api/products - 获取产品列表 -- GET /api/products/{id} - 获取产品详情 -- POST /api/products - 创建产品 -- PUT /api/products/{id} - 更新产品信息 -- DELETE /api/products/{id} - 删除产品 +### 5.2 用户认证接口 +- **POST /api/auth/login** - 用户登录 + - 请求体:{username, password} + - 响应:JWT令牌和用户信息 +- **POST /api/auth/logout** - 用户登出 + - 请求头:Authorization: Bearer + - 响应:登出成功消息 +- **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. 安全设计