From 3143c3ad0b611b2717cfd2342974e1f06401074b Mon Sep 17 00:00:00 2001 From: ylweng Date: Fri, 19 Sep 2025 23:46:15 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=E5=BA=9F=E5=BC=83=E7=9A=84AP?= =?UTF-8?q?I=E5=92=8C=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 226 +++ ...250118000012_fix_iot_cattle_foreign_key.js | 84 + .../20250118000013_create_iot_cattle_table.js | 278 +++ ...50118000014_add_iot_cattle_foreign_keys.js | 56 + ...0250118000015_add_missing_animal_fields.js | 137 ++ docs/API.md | 894 --------- docs/DEPLOYMENT.md | 630 ------ docs/DEVELOPMENT.md | 932 --------- docs/README.md | 115 +- docs/architecture/开发计划.md | 287 +++ docs/architecture/数据库设计文档.md | 592 ++++++ docs/architecture/系统架构文档.md | 1555 ++++++++++++++ .../系统详细设计文档.md} | 0 docs/config/PRD.md | 340 ---- docs/config/arch.md | 423 ---- docs/development/API接口文档.md | 1779 +++++++++++++++++ docs/{ => development}/CONTRIBUTING.md | 0 .../performance-monitor-integration.js | 0 docs/development/代码规范.md | 599 ++++++ docs/development/开发指南.md | 1322 ++++++++++++ docs/development/测试文档.md | 570 ++++++ docs/development/环境配置文档.md | 680 +++++++ docs/{ => operations}/SECURITY.md | 0 docs/{ => operations}/TROUBLESHOOTING.md | 0 .../data-sync-fix-report.md | 0 .../farms-data-import-summary.md | 0 .../location-data-validation-report.md | 0 .../performance-monitoring.md | 0 docs/operations/监控运维文档.md | 597 ++++++ docs/operations/部署文档.md | 841 ++++++++ docs/{ => project}/FINAL_STRUCTURE_REPORT.md | 0 docs/{ => project}/PROJECT_CLEANUP_REPORT.md | 0 docs/{ => project}/baidu-map-license.md | 0 docs/{config/task.md => project/任务文档.md} | 0 docs/{CHANGELOG.md => project/变更日志.md} | 0 .../dev-plan.md => project/开发计划文档.md} | 0 docs/project/项目管理文档.md | 474 +++++ docs/requirements/PRD.md | 741 +++++++ .../official-website-prd.md | 2 +- docs/{ => requirements}/保险端产品需求文档.md | 0 docs/{ => requirements}/政府端产品需求文档.md | 0 .../银行端小程序产品需求文档.md | 0 docs/文档维护规范.md | 439 ++++ .../20250118000013_create_iot_cattle_table.js | 278 +++ ...50118000014_add_iot_cattle_foreign_keys.js | 31 + ...0250118000015_add_missing_animal_fields.js | 137 ++ 46 files changed, 11804 insertions(+), 3235 deletions(-) create mode 100644 README.md create mode 100644 backend/migrations/20250118000012_fix_iot_cattle_foreign_key.js create mode 100644 backend/migrations/20250118000013_create_iot_cattle_table.js create mode 100644 backend/migrations/20250118000014_add_iot_cattle_foreign_keys.js create mode 100644 backend/migrations/20250118000015_add_missing_animal_fields.js delete mode 100644 docs/API.md delete mode 100644 docs/DEPLOYMENT.md delete mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/architecture/开发计划.md create mode 100644 docs/architecture/数据库设计文档.md create mode 100644 docs/architecture/系统架构文档.md rename docs/{config/design.md => architecture/系统详细设计文档.md} (100%) delete mode 100644 docs/config/PRD.md delete mode 100644 docs/config/arch.md create mode 100644 docs/development/API接口文档.md rename docs/{ => development}/CONTRIBUTING.md (100%) rename docs/{ => development}/examples/performance-monitor-integration.js (100%) create mode 100644 docs/development/代码规范.md create mode 100644 docs/development/开发指南.md create mode 100644 docs/development/测试文档.md create mode 100644 docs/development/环境配置文档.md rename docs/{ => operations}/SECURITY.md (100%) rename docs/{ => operations}/TROUBLESHOOTING.md (100%) rename docs/{config => operations}/data-sync-fix-report.md (100%) rename docs/{config => operations}/farms-data-import-summary.md (100%) rename docs/{config => operations}/location-data-validation-report.md (100%) rename docs/{ => operations}/performance-monitoring.md (100%) create mode 100644 docs/operations/监控运维文档.md create mode 100644 docs/operations/部署文档.md rename docs/{ => project}/FINAL_STRUCTURE_REPORT.md (100%) rename docs/{ => project}/PROJECT_CLEANUP_REPORT.md (100%) rename docs/{ => project}/baidu-map-license.md (100%) rename docs/{config/task.md => project/任务文档.md} (100%) rename docs/{CHANGELOG.md => project/变更日志.md} (100%) rename docs/{config/dev-plan.md => project/开发计划文档.md} (100%) create mode 100644 docs/project/项目管理文档.md create mode 100644 docs/requirements/PRD.md rename docs/{ => requirements}/official-website-prd.md (99%) rename docs/{ => requirements}/保险端产品需求文档.md (100%) rename docs/{ => requirements}/政府端产品需求文档.md (100%) rename docs/{ => requirements}/银行端小程序产品需求文档.md (100%) create mode 100644 docs/文档维护规范.md create mode 100644 migrations/20250118000013_create_iot_cattle_table.js create mode 100644 migrations/20250118000014_add_iot_cattle_foreign_keys.js create mode 100644 migrations/20250118000015_add_missing_animal_fields.js diff --git a/README.md b/README.md new file mode 100644 index 0000000..dd56a50 --- /dev/null +++ b/README.md @@ -0,0 +1,226 @@ +# 宁夏智慧养殖监管平台 + +
+ +![项目版本](https://img.shields.io/badge/版本-v2.2.0-blue.svg) +![Node.js版本](https://img.shields.io/badge/Node.js-16.20.2-green.svg) +![Vue版本](https://img.shields.io/badge/Vue-3.4.15-brightgreen.svg) +![许可证](https://img.shields.io/badge/许可证-MIT-yellow.svg) + +**现代化的智慧养殖监管平台，集成IoT设备监控、动物健康管理、数据可视化分析等功能** + +[功能特性](#功能特性) • [快速开始](#快速开始) • [项目架构](#项目架构) • [文档](#文档) • [贡献指南](#贡献指南) + +
+ +## 📋 项目概述 + +宁夏智慧养殖监管平台是一个现代化的农场管理系统，旨在通过数字化手段提升养殖业的管理效率和监管水平。系统采用前后端分离架构，支持多端访问，为养殖场管理者、监管部门和相关机构提供全方位的智慧养殖解决方案。 + +### 🎯 核心价值 + +- **智能监控**：实时监控养殖环境和设备状态 +- **数据驱动**：基于大数据分析的决策支持 +- **全程追溯**：完整的养殖过程记录和追溯 +- **多端协同**：支持Web端、小程序等多平台访问 +- **安全可靠**：企业级安全防护和数据保护 + +## ✨ 功能特性 + +### 🏭 核心业务模块 + +- **🏢 养殖场管理**：养殖场信息、圈舍管理、电子围栏 +- **🐄 动物健康管理**：牲畜档案、健康监测、批次管理 +- **📱 IoT设备监控**：传感器数据、设备状态、实时告警 +- **📊 数据可视化**：统计分析、图表展示、决策支持 +- **👥 用户权限管理**：多角色权限、操作审计、安全控制 +- **🛒 产品订单管理**：产品销售、订单处理、库存管理 +- **⚠️ 预警管理**：智能告警、异常处理、风险预防 + +### 🌐 多端支持 + +- **管理后台**：基于Vue 3的现代化管理界面 +- **数据大屏**：实时数据展示和监控大屏 +- **官方网站**：产品展示和信息发布 +- **小程序矩阵**： + - 银行端小程序：金融服务支持 + - 政府端小程序：监管和政策发布 + - 保险端小程序：保险服务管理 + +### 🛠️ 技术特性 + +- **现代化技术栈**：Vue 3 + Node.js + MySQL +- **响应式设计**：适配多种设备和屏幕尺寸 +- **实时通信**：WebSocket支持实时数据推送 +- **地图集成**：百度地图API地理信息展示 +- **性能监控**：完整的系统性能监控体系 +- **API文档**：Swagger自动生成API文档 + +## 🚀 快速开始 + +### 环境要求 + +- **Node.js**: 16.20.2+ +- **MySQL**: 8.0+ +- **npm**: 8.0.0+ + +### 安装步骤 + +1. **克隆项目** +```bash +git clone +cd nxxmdata +``` + +2. **安装依赖** +```bash +# 安装后端依赖 +cd backend +npm install + +# 安装前端依赖 +cd ../admin-system +npm install + +# 安装数据大屏依赖 +cd ../datav +npm install +``` + +3. **配置环境** +```bash +# 复制环境配置文件 +cp backend/.env.example backend/.env +cp admin-system/.env.example admin-system/.env + +# 编辑配置文件，设置数据库连接等信息 +``` + +4. **初始化数据库** +```bash +cd backend +npm run init-db +``` + +5. **启动服务** +```bash +# 启动后端服务 (端口: 5000) +cd backend +npm run dev + +# 启动管理后台 (端口: 5173) +cd admin-system +npm run dev + +# 启动数据大屏 (端口: 5174) +cd datav +npm run dev +``` + +### 访问地址 + +- **管理后台**: http://localhost:5173 +- **数据大屏**: http://localhost:5174 +- **API文档**: http://localhost:5000/api-docs +- **官方网站**: 直接打开 `website/index.html` + +## 🏗️ 项目架构 + +``` +nxxmdata/ +├── 📁 backend/ # 后端API服务 +│ ├── config/ # 配置文件 +│ ├── controllers/ # 控制器 +│ ├── models/ # 数据模型 +│ ├── routes/ # 路由定义 +│ ├── middleware/ # 中间件 +│ └── utils/ # 工具类 +├── 📁 admin-system/ # 管理后台前端 +│ ├── src/ # 源代码 +│ ├── components/ # 组件库 +│ └── views/ # 页面视图 +├── 📁 datav/ # 数据可视化大屏 +├── 📁 website/ # 官方网站 +├── 📁 bank_mini_program/ # 银行端小程序 +├── 📁 government-mini-program/ # 政府端小程序 +├── 📁 insurance_mini_program/ # 保险端小程序 +├── 📁 docs/ # 项目文档 +└── 📁 scripts/ # 脚本工具 +``` + +### 技术栈 + +**后端技术栈** +- Node.js 16.20.2 + Express.js +- Sequelize ORM + MySQL 8.0 +- JWT认证 + bcryptjs加密 +- Swagger API文档 +- Winston日志系统 + +**前端技术栈** +- Vue 3.4.15 + Vite +- Ant Design Vue 4.0 +- ECharts 5.4 数据可视化 +- Pinia 状态管理 +- Axios HTTP客户端 + +## 📚 文档 + +### 核心文档 + +- [📋 产品需求文档](docs/config/PRD.md) - 详细的业务需求和功能规格 +- [🏗️ 系统架构文档](docs/config/arch.md) - 技术架构和系统设计 +- [🔧 开发指南](docs/DEVELOPMENT.md) - 开发环境搭建和开发规范 +- [🚀 部署指南](docs/DEPLOYMENT.md) - 生产环境部署说明 +- [📖 API文档](docs/API.md) - 接口设计和使用说明 + +### 专项文档 + +- [🏦 银行端小程序文档](docs/银行端小程序产品需求文档.md) +- [🏛️ 政府端小程序文档](docs/政府端产品需求文档.md) +- [🛡️ 保险端小程序文档](docs/保险端产品需求文档.md) +- [🔒 安全说明](docs/SECURITY.md) +- [❓ 故障排除](docs/TROUBLESHOOTING.md) + +## 🤝 贡献指南 + +我们欢迎所有形式的贡献！请阅读 [贡献指南](docs/CONTRIBUTING.md) 了解如何参与项目开发。 + +### 开发流程 + +1. Fork 项目 +2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 创建 Pull Request + +### 代码规范 + +- 遵循 ESLint 配置 +- 使用语义化提交信息 +- 编写单元测试 +- 更新相关文档 + +## 📄 许可证 + +本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 + +## 📞 联系我们 + +- **项目维护者**: NXXM Development Team +- **技术支持**: [创建Issue](../../issues) +- **文档反馈**: [文档仓库](docs/) + +## 🙏 致谢 + +感谢所有为项目做出贡献的开发者和用户！ + +--- + +
+ +**⭐ 如果这个项目对你有帮助，请给我们一个星标！** + +Made with ❤️ by NXXM Development Team + +
\ No newline at end of file diff --git a/backend/migrations/20250118000012_fix_iot_cattle_foreign_key.js b/backend/migrations/20250118000012_fix_iot_cattle_foreign_key.js new file mode 100644 index 0000000..48f0434 --- /dev/null +++ b/backend/migrations/20250118000012_fix_iot_cattle_foreign_key.js @@ -0,0 +1,84 @@ +/** + * 修复iot_cattle表外键约束问题 + * + * 问题描述： + * - iot_cattle表的strain字段与cattle_user表的id字段类型不匹配 + * - 导致外键约束创建失败 + * + * 解决方案： + * - 检查两个字段的类型并确保它们匹配 + * - 重新创建外键约束 + */ + +module.exports = { + up: async (queryInterface, Sequelize) => { + // 开始事务 + const transaction = await queryInterface.sequelize.transaction(); + + try { + // 1. 检查并修改cattle_user表的id字段类型为TINYINT以匹配iot_cattle表的strain字段 + await queryInterface.changeColumn('cattle_user', 'id', { + type: Sequelize.TINYINT, + allowNull: false, + comment: '用途ID' + }, { transaction }); + + // 2. 删除现有的不兼容外键约束（如果存在） + await queryInterface.sequelize.query( + 'ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS iot_cattle_ibfk_2', + { transaction } + ); + + // 3. 确保iot_cattle表的strain字段类型为TINYINT + await queryInterface.changeColumn('iot_cattle', 'strain', { + type: Sequelize.TINYINT, + allowNull: false, + comment: '品系' + }, { transaction }); + + // 4. 重新创建外键约束 + await queryInterface.sequelize.query( + 'ALTER TABLE iot_cattle ADD CONSTRAINT iot_cattle_ibfk_2 FOREIGN KEY (strain) REFERENCES cattle_user (id) ON DELETE RESTRICT ON UPDATE CASCADE', + { transaction } + ); + + // 提交事务 + await transaction.commit(); + console.log('✅ 成功修复iot_cattle表外键约束问题'); + } catch (error) { + // 回滚事务 + await transaction.rollback(); + console.error('❌ 修复iot_cattle表外键约束失败:', error.message); + throw error; + } + }, + + down: async (queryInterface, Sequelize) => { + // 回滚操作 + const transaction = await queryInterface.sequelize.transaction(); + + try { + // 1. 删除外键约束 + await queryInterface.sequelize.query( + 'ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS iot_cattle_ibfk_2', + { transaction } + ); + + // 2. 恢复cattle_user表的id字段类型（可根据需要调整） + await queryInterface.changeColumn('cattle_user', 'id', { + type: Sequelize.INTEGER, + allowNull: false, + comment: '用途ID' + }, { transaction }); + + // 提交事务 + await transaction.commit(); + console.log('✅ 成功回滚外键约束修复'); + } catch (error) { + // 回滚事务 + await transaction.rollback(); + console.error('❌ 回滚外键约束修复失败:', error.message); + throw error; + } + } +}; \ No newline at end of file diff --git a/backend/migrations/20250118000013_create_iot_cattle_table.js b/backend/migrations/20250118000013_create_iot_cattle_table.js new file mode 100644 index 0000000..9465b58 --- /dev/null +++ b/backend/migrations/20250118000013_create_iot_cattle_table.js @@ -0,0 +1,278 @@ +/** + * 创建iot_cattle表 + * + * 问题描述： + * - 数据库中缺少iot_cattle表 + * - 需要创建该表并正确设置外键约束 + */ + +module.exports = { + up: async (queryInterface, Sequelize) => { + await queryInterface.createTable('iot_cattle', { + id: { + type: Sequelize.INTEGER, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '牛只ID' + }, + org_id: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '组织ID' + }, + ear_number: { + type: Sequelize.BIGINT, + allowNull: false, + comment: '耳标号' + }, + sex: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '性别' + }, + strain: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '品系' + }, + varieties: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '品种' + }, + cate: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '类别' + }, + birth_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '出生体重' + }, + birthday: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '出生日期' + }, + pen_id: { + type: Sequelize.INTEGER, + allowNull: true, + comment: '栏舍ID' + }, + into_time: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '入栏时间' + }, + parity: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '胎次' + }, + source: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '来源' + }, + source_day: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '来源天数' + }, + source_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '来源体重' + }, + weight: { + type: Sequelize.DOUBLE(11, 2), + allowNull: false, + comment: '当前体重' + }, + event: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '事件' + }, + event_time: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '事件时间' + }, + lactation_day: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '泌乳天数' + }, + semen_num: { + type: Sequelize.STRING(30), + allowNull: false, + comment: '精液编号' + }, + is_wear: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否佩戴设备' + }, + batch_id: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '批次ID' + }, + imgs: { + type: Sequelize.STRING(800), + allowNull: false, + comment: '图片' + }, + is_ele_auth: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否电子认证' + }, + is_qua_auth: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否质量认证' + }, + is_delete: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '是否删除' + }, + is_out: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '是否出栏' + }, + create_uid: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '创建人ID' + }, + create_time: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '创建时间' + }, + algebra: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '代数' + }, + colour: { + type: Sequelize.TEXT, + allowNull: false, + comment: '毛色' + }, + info_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '信息体重' + }, + descent: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '血统' + }, + is_vaccin: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否接种疫苗' + }, + is_insemination: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否人工授精' + }, + is_insure: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否投保' + }, + is_mortgage: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '是否抵押' + }, + update_time: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '更新时间' + }, + breed_bull_time: { + type: Sequelize.INTEGER, + allowNull: false, + comment: '配种时间' + }, + level: { + type: Sequelize.TINYINT, + allowNull: false, + comment: '等级' + }, + six_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '6月龄体重' + }, + eighteen_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '18月龄体重' + }, + twelve_day_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '12日龄体重' + }, + eighteen_day_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '18日龄体重' + }, + xxiv_day_weight: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false, + comment: '24日龄体重' + }, + semen_breed_imgs: { + type: Sequelize.STRING(800), + allowNull: false, + comment: '精液配种图片' + }, + sell_status: { + type: Sequelize.SMALLINT, + allowNull: false, + comment: '销售状态' + }, + weight_calculate_time: { + type: Sequelize.DATE, + allowNull: true, + comment: '体重计算时间' + }, + day_of_birthday: { + type: Sequelize.INTEGER, + allowNull: true, + comment: '出生天数' + } + }, { + charset: 'utf8mb4', + comment: '物联网牛只表' + }); + + // 添加索引 + await queryInterface.addIndex('iot_cattle', ['org_id']); + await queryInterface.addIndex('iot_cattle', ['strain']); + await queryInterface.addIndex('iot_cattle', ['varieties']); + await queryInterface.addIndex('iot_cattle', ['pen_id']); + await queryInterface.addIndex('iot_cattle', ['batch_id']); + + console.log('✅ 成功创建iot_cattle表'); + }, + + down: async (queryInterface, Sequelize) => { + await queryInterface.dropTable('iot_cattle'); + console.log('✅ 成功删除iot_cattle表'); + } +}; \ No newline at end of file diff --git a/backend/migrations/20250118000014_add_iot_cattle_foreign_keys.js b/backend/migrations/20250118000014_add_iot_cattle_foreign_keys.js new file mode 100644 index 0000000..bbd3fff --- /dev/null +++ b/backend/migrations/20250118000014_add_iot_cattle_foreign_keys.js @@ -0,0 +1,56 @@ +/** + * 为iot_cattle表添加外键约束 + */ + +module.exports = { + up: async (queryInterface, Sequelize) => { + // 添加外键约束 + await queryInterface.sequelize.query(` + ALTER TABLE iot_cattle + ADD CONSTRAINT fk_iot_cattle_org_id + FOREIGN KEY (org_id) REFERENCES farms (id) + ON DELETE CASCADE ON UPDATE CASCADE + `); + + await queryInterface.sequelize.query(` + ALTER TABLE iot_cattle + ADD CONSTRAINT fk_iot_cattle_strain + FOREIGN KEY (strain) REFERENCES cattle_user (id) + ON DELETE RESTRICT ON UPDATE CASCADE + `); + + await queryInterface.sequelize.query(` + ALTER TABLE iot_cattle + ADD CONSTRAINT fk_iot_cattle_varieties + FOREIGN KEY (varieties) REFERENCES cattle_type (id) + ON DELETE RESTRICT ON UPDATE CASCADE + `); + + await queryInterface.sequelize.query(` + ALTER TABLE iot_cattle + ADD CONSTRAINT fk_iot_cattle_pen_id + FOREIGN KEY (pen_id) REFERENCES cattle_pens (id) + ON DELETE SET NULL ON UPDATE CASCADE + `); + + await queryInterface.sequelize.query(` + ALTER TABLE iot_cattle + ADD CONSTRAINT fk_iot_cattle_batch_id + FOREIGN KEY (batch_id) REFERENCES cattle_batches (id) + ON DELETE SET NULL ON UPDATE CASCADE + `); + + console.log('✅ 成功为iot_cattle表添加外键约束'); + }, + + down: async (queryInterface, Sequelize) => { + // 删除外键约束 + await queryInterface.sequelize.query('ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS fk_iot_cattle_org_id'); + await queryInterface.sequelize.query('ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS fk_iot_cattle_strain'); + await queryInterface.sequelize.query('ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS fk_iot_cattle_varieties'); + await queryInterface.sequelize.query('ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS fk_iot_cattle_pen_id'); + await queryInterface.sequelize.query('ALTER TABLE iot_cattle DROP FOREIGN KEY IF EXISTS fk_iot_cattle_batch_id'); + + console.log('✅ 成功删除iot_cattle表的外键约束'); + } +}; \ No newline at end of file diff --git a/backend/migrations/20250118000015_add_missing_animal_fields.js b/backend/migrations/20250118000015_add_missing_animal_fields.js new file mode 100644 index 0000000..7e11853 --- /dev/null +++ b/backend/migrations/20250118000015_add_missing_animal_fields.js @@ -0,0 +1,137 @@ +/** + * 为animals表添加缺失的字段 + */ + +module.exports = { + up: async (queryInterface, Sequelize) => { + const { DataTypes } = require('sequelize'); + + // 添加项圈编号字段 + await queryInterface.addColumn('animals', 'collar_number', { + type: DataTypes.STRING(50), + allowNull: false, + comment: '项圈编号' + }); + + // 添加动物耳号字段 + await queryInterface.addColumn('animals', 'ear_tag', { + type: DataTypes.STRING(50), + allowNull: true, + comment: '动物耳号' + }); + + // 添加动物类型字段 + await queryInterface.addColumn('animals', 'animal_type', { + type: DataTypes.INTEGER, + allowNull: false, + defaultValue: 1, + comment: '动物类型：1-牛，2-羊，3-猪，4-马' + }); + + // 添加品种字段 + await queryInterface.addColumn('animals', 'breed', { + type: DataTypes.INTEGER, + allowNull: false, + defaultValue: 1, + comment: '品种：1-西藏高山牦牛，2-荷斯坦奶牛，3-西门塔尔牛，4-安格斯牛，5-小尾寒羊，6-波尔山羊' + }); + + // 添加品类字段 + await queryInterface.addColumn('animals', 'category', { + type: DataTypes.INTEGER, + allowNull: false, + defaultValue: 1, + comment: '品类：1-乳肉兼用，2-肉用，3-乳用，4-种用' + }); + + // 添加来源类型字段 + await queryInterface.addColumn('animals', 'source_type', { + type: DataTypes.INTEGER, + allowNull: false, + defaultValue: 1, + comment: '来源类型：1-合作社，2-农户，3-养殖场，4-进口' + }); + + // 添加出生日期字段 + await queryInterface.addColumn('animals', 'birth_date', { + type: DataTypes.DATE, + allowNull: true, + comment: '出生日期' + }); + + // 添加出生体重字段 + await queryInterface.addColumn('animals', 'birth_weight', { + type: DataTypes.DECIMAL(10, 2), + allowNull: true, + defaultValue: 0.00, + comment: '出生体重' + }); + + // 添加断奶体重字段 + await queryInterface.addColumn('animals', 'weaning_weight', { + type: DataTypes.DECIMAL(10, 2), + allowNull: true, + defaultValue: 0.00, + comment: '断奶体重' + }); + + // 添加断奶日龄字段 + await queryInterface.addColumn('animals', 'weaning_age', { + type: DataTypes.INTEGER, + allowNull: true, + defaultValue: 0, + comment: '断奶日龄' + }); + + // 添加入场日期字段 + await queryInterface.addColumn('animals', 'entry_date', { + type: DataTypes.DATE, + allowNull: true, + comment: '入场日期' + }); + + // 添加历史已产胎次字段 + await queryInterface.addColumn('animals', 'calving_count', { + type: DataTypes.INTEGER, + allowNull: true, + defaultValue: 0, + comment: '历史已产胎次' + }); + + // 添加乳头数(左)字段 + await queryInterface.addColumn('animals', 'left_teat_count', { + type: DataTypes.INTEGER, + allowNull: true, + comment: '乳头数(左)' + }); + + // 添加乳头数(右)字段 + await queryInterface.addColumn('animals', 'right_teat_count', { + type: DataTypes.INTEGER, + allowNull: true, + comment: '乳头数(右)' + }); + + console.log('✅ 成功为animals表添加缺失的字段'); + }, + + down: async (queryInterface, Sequelize) => { + // 删除添加的字段 + await queryInterface.removeColumn('animals', 'collar_number'); + await queryInterface.removeColumn('animals', 'ear_tag'); + await queryInterface.removeColumn('animals', 'animal_type'); + await queryInterface.removeColumn('animals', 'breed'); + await queryInterface.removeColumn('animals', 'category'); + await queryInterface.removeColumn('animals', 'source_type'); + await queryInterface.removeColumn('animals', 'birth_date'); + await queryInterface.removeColumn('animals', 'birth_weight'); + await queryInterface.removeColumn('animals', 'weaning_weight'); + await queryInterface.removeColumn('animals', 'weaning_age'); + await queryInterface.removeColumn('animals', 'entry_date'); + await queryInterface.removeColumn('animals', 'calving_count'); + await queryInterface.removeColumn('animals', 'left_teat_count'); + await queryInterface.removeColumn('animals', 'right_teat_count'); + + console.log('✅ 成功回滚animals表字段添加操作'); + } +}; \ No newline at end of file diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 5a50996..0000000 --- a/docs/API.md +++ /dev/null @@ -1,894 +0,0 @@ -# API 文档 - -## 概述 - -宁夏智慧养殖监管平台提供全面的RESTful API，支持农场管理、设备监控、动物健康管理、用户管理、订单管理等核心功能。 - -## 基础信息 - -- **Base URL**: `http://localhost:5350/api` (开发环境) -- **Authentication**: JWT Bearer Token -- **Content-Type**: `application/json` -- **API Version**: v1.0 - -## 认证机制 - -### JWT Token认证 -所有需要认证的API都需要在请求头中包含JWT Token： - -```http -Authorization: Bearer -``` - -### Token获取 -通过登录接口获取Token： -```http -POST /api/auth/login -Content-Type: application/json - -{ - "username": "your_username", - "password": "your_password" -} -``` - -## 通用响应格式 - -### 成功响应 -```json -{ - "success": true, - "data": {}, - "message": "操作成功", - "timestamp": "2025-01-18T10:30:00Z" -} -``` - -### 错误响应 -```json -{ - "success": false, - "error": { - "code": "ERROR_CODE", - "message": "错误描述", - "details": "详细错误信息" - }, - "timestamp": "2025-01-18T10:30:00Z" -} -``` - -### HTTP状态码 -- `200` - 请求成功 -- `201` - 创建成功 -- `400` - 请求参数错误 -- `401` - 未认证或Token过期 -- `403` - 权限不足 -- `404` - 资源不存在 -- `409` - 资源冲突 -- `500` - 服务器内部错误 - -## 认证相关API - -### 用户登录 -```http -POST /api/auth/login -``` - -**请求体:** -```json -{ - "username": "admin", - "password": "password123" -} -``` - -**响应:** -```json -{ - "success": true, - "data": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "user": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "roles": ["admin"] - } - } -} -``` - -### 用户注册 -```http -POST /api/auth/register -``` - -**请求体:** -```json -{ - "username": "newuser", - "email": "newuser@example.com", - "password": "password123", - "phone": "13800138000" -} -``` - -### 用户登出 -```http -POST /api/auth/logout -``` -**需要认证**: 是 - -### 验证Token -```http -GET /api/auth/verify -``` -**需要认证**: 是 - -## 用户管理API - -### 获取用户列表 -```http -GET /api/users -``` -**需要认证**: 是 -**权限要求**: admin - -**查询参数:** -- `page` (int): 页码，默认1 -- `limit` (int): 每页数量，默认10 -- `search` (string): 搜索关键词 -- `status` (string): 用户状态 (`active`, `inactive`, `banned`) - -**响应:** -```json -{ - "success": true, - "data": { - "users": [ - { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "phone": "13800138000", - "status": "active", - "created_at": "2025-01-01T00:00:00Z", - "roles": ["admin"] - } - ], - "pagination": { - "page": 1, - "limit": 10, - "total": 1, - "pages": 1 - } - } -} -``` - -### 获取用户详情 -```http -GET /api/users/{id} -``` -**需要认证**: 是 - -### 创建用户 -```http -POST /api/users -``` -**需要认证**: 是 -**权限要求**: admin - -**请求体:** -```json -{ - "username": "newuser", - "email": "newuser@example.com", - "password": "password123", - "phone": "13800138000", - "status": "active", - "roles": ["user"] -} -``` - -### 更新用户 -```http -PUT /api/users/{id} -``` -**需要认证**: 是 - -### 删除用户 -```http -DELETE /api/users/{id} -``` -**需要认证**: 是 -**权限要求**: admin - -## 养殖场管理API - -### 获取养殖场列表 -```http -GET /api/farms -``` -**需要认证**: 是 - -**查询参数:** -- `page` (int): 页码，默认1 -- `limit` (int): 每页数量，默认10 -- `type` (string): 养殖场类型 -- `status` (string): 状态 (`active`, `inactive`, `maintenance`) - -**响应:** -```json -{ - "success": true, - "data": { - "farms": [ - { - "id": 1, - "name": "宁夏示范养殖场", - "type": "奶牛养殖", - "location": { - "lat": 38.46667, - "lng": 106.26667 - }, - "address": "宁夏回族自治区银川市金凤区", - "contact": "张经理", - "phone": "13800138000", - "status": "active", - "created_at": "2025-01-01T00:00:00Z" - } - ], - "pagination": { - "page": 1, - "limit": 10, - "total": 1, - "pages": 1 - } - } -} -``` - -### 获取公开养殖场数据 -```http -GET /api/farms/public -``` -**需要认证**: 否 - -### 获取养殖场详情 -```http -GET /api/farms/{id} -``` -**需要认证**: 是 - -### 创建养殖场 -```http -POST /api/farms -``` -**需要认证**: 是 -**权限要求**: manager - -**请求体:** -```json -{ - "name": "新养殖场", - "type": "养猪场", - "longitude": 106.26667, - "latitude": 38.46667, - "address": "详细地址", - "owner": "联系人姓名", - "phone": "13800138000", - "status": "active" -} -``` - -### 更新养殖场 -```http -PUT /api/farms/{id} -``` -**需要认证**: 是 -**权限要求**: manager - -### 删除养殖场 -```http -DELETE /api/farms/{id} -``` -**需要认证**: 是 -**权限要求**: admin - -## 设备管理API - -### 获取设备列表 -```http -GET /api/devices -``` -**需要认证**: 是 - -**查询参数:** -- `page` (int): 页码 -- `limit` (int): 每页数量 -- `farm_id` (int): 养殖场ID -- `type` (string): 设备类型 -- `status` (string): 设备状态 (`online`, `offline`, `maintenance`) - -### 获取设备详情 -```http -GET /api/devices/{id} -``` -**需要认证**: 是 - -**响应:** -```json -{ - "success": true, - "data": { - "id": 1, - "name": "温度传感器001", - "type": "温度传感器", - "status": "online", - "farm_id": 1, - "metrics": { - "temperature": 25.5, - "humidity": 60 - }, - "last_maintenance": "2025-01-01T00:00:00Z", - "installation_date": "2024-01-01T00:00:00Z", - "farm": { - "id": 1, - "name": "宁夏示范养殖场" - } - } -} -``` - -### 创建设备 -```http -POST /api/devices -``` -**需要认证**: 是 -**权限要求**: manager - -**请求体:** -```json -{ - "name": "新设备", - "type": "传感器", - "farm_id": 1, - "installation_date": "2025-01-18", - "metrics": { - "temperature": 25.0 - } -} -``` - -### 更新设备 -```http -PUT /api/devices/{id} -``` -**需要认证**: 是 -**权限要求**: manager - -### 删除设备 -```http -DELETE /api/devices/{id} -``` -**需要认证**: 是 -**权限要求**: admin - -## 动物管理API - -### 获取动物列表 -```http -GET /api/animals -``` -**需要认证**: 是 - -**查询参数:** -- `page` (int): 页码 -- `limit` (int): 每页数量 -- `farm_id` (int): 养殖场ID -- `type` (string): 动物类型 -- `health_status` (string): 健康状态 (`healthy`, `sick`, `quarantine`) - -### 获取动物详情 -```http -GET /api/animals/{id} -``` -**需要认证**: 是 - -### 创建动物记录 -```http -POST /api/animals -``` -**需要认证**: 是 -**权限要求**: manager - -**请求体:** -```json -{ - "type": "奶牛", - "count": 100, - "farm_id": 1, - "health_status": "healthy", - "notes": "备注信息" -} -``` - -### 更新动物记录 -```http -PUT /api/animals/{id} -``` -**需要认证**: 是 -**权限要求**: manager - -### 删除动物记录 -```http -DELETE /api/animals/{id} -``` -**需要认证**: 是 -**权限要求**: admin - -## 预警管理API - -### 获取预警列表 -```http -GET /api/alerts -``` -**需要认证**: 是 - -**查询参数:** -- `page` (int): 页码 -- `limit` (int): 每页数量 -- `farm_id` (int): 养殖场ID -- `level` (string): 预警级别 (`low`, `medium`, `high`, `critical`) -- `status` (string): 预警状态 (`active`, `acknowledged`, `resolved`) - -**响应:** -```json -{ - "success": true, - "data": { - "alerts": [ - { - "id": 1, - "type": "temperature_high", - "level": "high", - "message": "温度过高警报", - "status": "active", - "farm_id": 1, - "device_id": 1, - "created_at": "2025-01-18T10:00:00Z", - "farm": { - "name": "宁夏示范养殖场" - }, - "device": { - "name": "温度传感器001" - } - } - ], - "pagination": { - "page": 1, - "limit": 10, - "total": 1, - "pages": 1 - } - } -} -``` - -### 确认预警 -```http -PUT /api/alerts/{id}/acknowledge -``` -**需要认证**: 是 -**权限要求**: manager - -### 解决预警 -```http -PUT /api/alerts/{id}/resolve -``` -**需要认证**: 是 -**权限要求**: manager - -**请求体:** -```json -{ - "resolution_notes": "问题已解决，温度已恢复正常" -} -``` - -## 产品管理API - -### 获取产品列表 -```http -GET /api/products -``` -**需要认证**: 是 - -**查询参数:** -- `page` (int): 页码 -- `limit` (int): 每页数量 -- `search` (string): 搜索关键词 -- `is_active` (boolean): 是否激活 - -### 获取产品详情 -```http -GET /api/products/{id} -``` -**需要认证**: 是 - -### 创建产品 -```http -POST /api/products -``` -**需要认证**: 是 -**权限要求**: manager - -**请求体:** -```json -{ - "name": "优质鲜牛奶", - "description": "新鲜优质牛奶，富含营养", - "price": 5000, - "stock": 1000, - "image_url": "/uploads/products/milk.jpg", - "is_active": true -} -``` - -### 更新产品 -```http -PUT /api/products/{id} -``` -**需要认证**: 是 -**权限要求**: manager - -### 删除产品 -```http -DELETE /api/products/{id} -``` -**需要认证**: 是 -**权限要求**: admin - -## 订单管理API - -### 获取订单列表 -```http -GET /api/orders -``` -**需要认证**: 是 - -**查询参数:** -- `page` (int): 页码 -- `limit` (int): 每页数量 -- `user_id` (int): 用户ID -- `status` (string): 订单状态 (`pending`, `processing`, `shipped`, `delivered`, `cancelled`) -- `payment_status` (string): 支付状态 (`unpaid`, `paid`, `refunded`) - -### 获取订单详情 -```http -GET /api/orders/{id} -``` -**需要认证**: 是 - -**响应:** -```json -{ - "success": true, - "data": { - "id": 1, - "user_id": 1, - "total_amount": 10000, - "status": "pending", - "payment_status": "unpaid", - "shipping_address": "收货地址", - "created_at": "2025-01-18T10:00:00Z", - "user": { - "username": "用户名", - "email": "user@example.com" - }, - "items": [ - { - "id": 1, - "product_id": 1, - "quantity": 2, - "price": 5000, - "product": { - "name": "优质鲜牛奶", - "image_url": "/uploads/products/milk.jpg" - } - } - ] - } -} -``` - -### 创建订单 -```http -POST /api/orders -``` -**需要认证**: 是 - -**请求体:** -```json -{ - "items": [ - { - "product_id": 1, - "quantity": 2 - } - ], - "shipping_address": "收货地址" -} -``` - -### 更新订单状态 -```http -PUT /api/orders/{id}/status -``` -**需要认证**: 是 -**权限要求**: manager - -**请求体:** -```json -{ - "status": "processing" -} -``` - -## 统计分析API - -### 系统概览统计 -```http -GET /api/stats/overview -``` -**需要认证**: 是 - -**响应:** -```json -{ - "success": true, - "data": { - "farms": { - "total": 10, - "active": 8, - "inactive": 2 - }, - "devices": { - "total": 50, - "online": 45, - "offline": 3, - "maintenance": 2 - }, - "animals": { - "total": 5000, - "healthy": 4800, - "sick": 150, - "quarantine": 50 - }, - "alerts": { - "active": 5, - "resolved_today": 12 - } - } -} -``` - -### 养殖场统计 -```http -GET /api/stats/farms/{id} -``` -**需要认证**: 是 - -### 预警统计 -```http -GET /api/stats/alerts -``` -**需要认证**: 是 - -**查询参数:** -- `timeRange` (string): 时间范围 (`today`, `week`, `month`) - -### 动物健康统计 -```http -GET /api/stats/animals -``` -**需要认证**: 是 - -**查询参数:** -- `farm_id` (int): 养殖场ID - -## 地图服务API - -### 获取地图数据 -```http -GET /api/map/data -``` -**需要认证**: 是 - -**响应:** -```json -{ - "success": true, - "data": { - "farms": [ - { - "id": 1, - "name": "宁夏示范养殖场", - "location": { - "lat": 38.46667, - "lng": 106.26667 - }, - "type": "奶牛养殖", - "status": "active", - "devices_count": 5, - "animals_count": 500 - } - ] - } -} -``` - -## 性能监控API - -### 获取性能指标 -```http -GET /api/performance/metrics -``` -**需要认证**: 是 -**权限要求**: admin - -### 获取系统资源信息 -```http -GET /api/performance/system -``` -**需要认证**: 是 -**权限要求**: admin - -### 获取数据库性能信息 -```http -GET /api/performance/database -``` -**需要认证**: 是 -**权限要求**: admin - -### 获取API性能统计 -```http -GET /api/performance/api -``` -**需要认证**: 是 -**权限要求**: admin - -## 文件上传API - -### 上传头像 -```http -POST /api/upload/avatar -``` -**需要认证**: 是 -**Content-Type**: `multipart/form-data` - -**请求:** -``` -Content-Type: multipart/form-data - -avatar: [文件] -``` - -### 上传产品图片 -```http -POST /api/upload/product -``` -**需要认证**: 是 -**权限要求**: manager -**Content-Type**: `multipart/form-data` - -## 错误代码参考 - -| 错误代码 | 描述 | HTTP状态码 | -|---------|------|------------| -| `INVALID_CREDENTIALS` | 用户名或密码错误 | 401 | -| `TOKEN_EXPIRED` | Token已过期 | 401 | -| `TOKEN_INVALID` | Token无效 | 401 | -| `INSUFFICIENT_PERMISSIONS` | 权限不足 | 403 | -| `RESOURCE_NOT_FOUND` | 资源不存在 | 404 | -| `VALIDATION_ERROR` | 参数验证失败 | 400 | -| `DUPLICATE_RESOURCE` | 资源重复 | 409 | -| `DATABASE_ERROR` | 数据库错误 | 500 | -| `INTERNAL_SERVER_ERROR` | 服务器内部错误 | 500 | - -## API限制 - -### 频率限制 -- 登录接口：每分钟最多5次尝试 -- 普通API：每分钟最多1000次请求 -- 上传接口：每分钟最多10次请求 - -### 文件上传限制 -- 头像：最大2MB，支持jpg、png格式 -- 产品图片：最大5MB，支持jpg、png、webp格式 - -## SDK示例 - -### JavaScript/Node.js -```javascript -// 安装: npm install axios - -const axios = require('axios'); - -class NxxmdataAPI { - constructor(baseURL, token) { - this.client = axios.create({ - baseURL: baseURL, - headers: { - 'Authorization': `Bearer ${token}`, - 'Content-Type': 'application/json' - } - }); - } - - async getFarms(params = {}) { - const response = await this.client.get('/farms', { params }); - return response.data; - } - - async createFarm(farmData) { - const response = await this.client.post('/farms', farmData); - return response.data; - } -} - -// 使用示例 -const api = new NxxmdataAPI('http://localhost:5350/api', 'your_token'); -const farms = await api.getFarms({ page: 1, limit: 10 }); -``` - -### Python -```python -import requests - -class NxxmdataAPI: - def __init__(self, base_url, token): - self.base_url = base_url - self.headers = { - 'Authorization': f'Bearer {token}', - 'Content-Type': 'application/json' - } - - def get_farms(self, params=None): - response = requests.get(f'{self.base_url}/farms', - headers=self.headers, params=params) - return response.json() - - def create_farm(self, farm_data): - response = requests.post(f'{self.base_url}/farms', - headers=self.headers, json=farm_data) - return response.json() - -# 使用示例 -api = NxxmdataAPI('http://localhost:5350/api', 'your_token') -farms = api.get_farms({'page': 1, 'limit': 10}) -``` - -## 测试环境 - -### Swagger文档 -访问 `http://localhost:5350/api-docs` 查看交互式API文档。 - -### Postman集合 -提供完整的Postman集合文件，包含所有API的示例请求。 - ---- - -## 更新记录 - -- **v1.0** (2025-01-18): 初始版本，包含所有核心API -- 定期更新，请关注CHANGELOG.md - -## 联系方式 - -如有API相关问题，请联系： -- 技术支持: api-support@nxxmdata.com -- 文档反馈: docs@nxxmdata.com - -*最后更新: 2025年1月* \ No newline at end of file diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md deleted file mode 100644 index d1f3516..0000000 --- a/docs/DEPLOYMENT.md +++ /dev/null @@ -1,630 +0,0 @@ -# 宁夏智慧养殖监管平台部署指南 - -## 概述 - -本文档详细说明了宁夏智慧养殖监管平台的部署流程，包括开发环境、测试环境和生产环境的部署方案。 - -## 系统要求 - -### 基础要求 -- **操作系统**: Linux (推荐 Ubuntu 18.04+), macOS 10.14+, Windows 10+ -- **Node.js**: 18.0 或更高版本 -- **MySQL**: 8.0 或更高版本 -- **内存**: 最少 4GB RAM（推荐 8GB+） -- **存储**: 最少 20GB 可用空间 - -### 推荐配置（生产环境） -- **CPU**: 4核 或更高 -- **内存**: 16GB RAM -- **存储**: 100GB SSD -- **网络**: 100Mbps 带宽 - -## 前期准备 - -### 1. 环境检查 -```bash -# 检查 Node.js 版本 -node --version # 应显示 v18.0.0 或更高 - -# 检查 npm 版本 -npm --version - -# 检查 MySQL 版本 -mysql --version # 应显示 8.0 或更高 -``` - -### 2. 数据库准备 -```sql --- 创建数据库 -CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - --- 创建数据库用户（可选） -CREATE USER 'nxxmdata_user'@'localhost' IDENTIFIED BY 'your_secure_password'; -GRANT ALL PRIVILEGES ON nxxmdata.* TO 'nxxmdata_user'@'localhost'; -FLUSH PRIVILEGES; -``` - -### 3. 获取源代码 -```bash -# 克隆项目（如果使用Git） -git clone -cd nxxmdata - -# 或者解压源码包 -unzip nxxmdata.zip -cd nxxmdata -``` - -## 开发环境部署 - -### 1. 安装依赖 - -#### 后端依赖安装 -```bash -cd backend -npm install -``` - -#### 前端依赖安装 -```bash -# 管理后台 -cd admin-system/frontend -npm install - -# 官网大屏 -cd ../../website/data-screen -npm install - -# 微信小程序（可选） -cd ../../mini_program/farm-monitor-dashboard -npm install -``` - -### 2. 环境配置 - -#### 后端环境配置 -在 `backend` 目录下创建 `.env` 文件： -```bash -# 数据库配置 -DB_HOST=localhost -DB_PORT=3306 -DB_NAME=nxxmdata -DB_USER=root -DB_PASSWORD=your_mysql_password - -# JWT配置 -JWT_SECRET=your_jwt_secret_key_here -JWT_EXPIRES_IN=24h - -# 服务器配置 -PORT=5350 -NODE_ENV=development - -# 百度地图API配置 -BAIDU_MAP_API_KEY=your_baidu_map_api_key - -# 日志配置 -LOG_LEVEL=debug -LOG_FILE_PATH=./logs/ -``` - -#### 前端环境配置 -在 `admin-system/frontend` 目录下创建 `.env` 文件： -```bash -# API配置 -VITE_API_BASE_URL=http://localhost:5350/api -VITE_BAIDU_MAP_API_KEY=your_baidu_map_api_key - -# 开发服务器配置 -VITE_PORT=5301 -``` - -### 3. 数据库初始化 -```bash -cd backend - -# 运行数据库迁移 -npm run init-db - -# 或者手动执行SQL脚本 -mysql -u root -p nxxmdata < create_tables.sql -``` - -### 4. 启动开发服务器 - -#### 启动后端服务 -```bash -cd backend -npm run dev -# 服务将在 http://localhost:5350 启动 -``` - -#### 启动前端服务 -```bash -# 启动管理后台 -cd admin-system/frontend -npm run dev -# 服务将在 http://localhost:5301 启动 - -# 启动官网大屏 -cd ../../website/data-screen -npm run dev -# 服务将在 http://localhost:5302 启动 -``` - -### 5. 验证部署 -访问以下URL验证部署是否成功： -- 后端API: http://localhost:5350/api/health -- 管理后台: http://localhost:5301 -- 官网大屏: http://localhost:5302 -- API文档: http://localhost:5350/api-docs - -## 测试环境部署 - -### 1. 使用PM2管理进程 -```bash -# 安装PM2 -npm install -g pm2 - -# 构建项目 -cd admin-system/frontend -npm run build - -cd ../../website/data-screen -npm run build - -# 启动后端服务 -cd ../../backend -pm2 start ecosystem.config.js --env test -``` - -### 2. Nginx配置 -创建 `/etc/nginx/sites-available/nxxmdata-test` 文件： -```nginx -server { - listen 80; - server_name test.nxxmdata.com; - - # 前端静态文件 - location / { - root /path/to/nxxmdata/admin-system/frontend/dist; - try_files $uri $uri/ /index.html; - } - - # 官网大屏 - location /screen { - root /path/to/nxxmdata/website/data-screen/dist; - try_files $uri $uri/ /index.html; - } - - # API代理 - location /api { - proxy_pass http://localhost:5350; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } -} -``` - -## 生产环境部署 - -### 1. Docker部署（推荐） - -#### 创建Dockerfile -```dockerfile -# 多阶段构建 - 前端构建阶段 -FROM node:18-alpine AS frontend-builder - -# 构建管理后台 -WORKDIR /app/admin-system/frontend -COPY admin-system/frontend/package*.json ./ -RUN npm ci --only=production -COPY admin-system/frontend/ ./ -RUN npm run build - -# 构建官网大屏 -WORKDIR /app/website/data-screen -COPY website/data-screen/package*.json ./ -RUN npm ci --only=production -COPY website/data-screen/ ./ -RUN npm run build - -# 后端运行阶段 -FROM node:18-alpine AS backend - -WORKDIR /app - -# 安装后端依赖 -COPY backend/package*.json ./ -RUN npm ci --only=production - -# 复制后端代码 -COPY backend/ ./ - -# 复制前端构建产物 -COPY --from=frontend-builder /app/admin-system/frontend/dist ./public/admin -COPY --from=frontend-builder /app/website/data-screen/dist ./public/screen - -# 创建非root用户 -RUN addgroup -g 1001 -S nodejs -RUN adduser -S node -u 1001 -USER node - -EXPOSE 5350 - -CMD ["npm", "start"] -``` - -#### 创建docker-compose.yml -```yaml -version: '3.8' -services: - nxxmdata-app: - build: . - ports: - - "5350:5350" - environment: - - NODE_ENV=production - - DB_HOST=mysql - - DB_PORT=3306 - - DB_NAME=nxxmdata - - DB_USER=nxxmdata_user - - DB_PASSWORD=${DB_PASSWORD} - - JWT_SECRET=${JWT_SECRET} - depends_on: - - mysql - restart: unless-stopped - volumes: - - ./logs:/app/logs - - mysql: - image: mysql:8.0 - environment: - - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD} - - MYSQL_DATABASE=nxxmdata - - MYSQL_USER=nxxmdata_user - - MYSQL_PASSWORD=${DB_PASSWORD} - ports: - - "3306:3306" - volumes: - - mysql_data:/var/lib/mysql - - ./create_tables.sql:/docker-entrypoint-initdb.d/init.sql - restart: unless-stopped - - nginx: - image: nginx:alpine - ports: - - "80:80" - - "443:443" - volumes: - - ./nginx.conf:/etc/nginx/nginx.conf - - ./ssl:/etc/nginx/ssl - depends_on: - - nxxmdata-app - restart: unless-stopped - -volumes: - mysql_data: -``` - -#### 创建环境变量文件 -创建 `.env` 文件： -```bash -# 数据库密码 -DB_PASSWORD=your_secure_db_password -MYSQL_ROOT_PASSWORD=your_secure_root_password - -# JWT密钥 -JWT_SECRET=your_very_secure_jwt_secret_key - -# 百度地图API -BAIDU_MAP_API_KEY=your_baidu_map_api_key -``` - -#### 部署命令 -```bash -# 构建并启动服务 -docker-compose up -d - -# 查看服务状态 -docker-compose ps - -# 查看日志 -docker-compose logs -f nxxmdata-app -``` - -### 2. 传统部署方式 - -#### 安装和配置 -```bash -# 1. 克隆项目 -git clone -cd nxxmdata - -# 2. 安装依赖 -cd backend && npm install --production -cd ../admin-system/frontend && npm install && npm run build -cd ../../website/data-screen && npm install && npm run build - -# 3. 配置环境变量 -cp backend/.env.example backend/.env -# 编辑 .env 文件，设置生产环境配置 - -# 4. 初始化数据库 -cd backend && npm run init-db - -# 5. 使用PM2启动服务 -npm install -g pm2 -pm2 start ecosystem.config.js --env production -``` - -#### PM2配置文件 (ecosystem.config.js) -```javascript -module.exports = { - apps: [{ - name: 'nxxmdata-backend', - script: './server.js', - cwd: './backend', - instances: 'max', - exec_mode: 'cluster', - env: { - NODE_ENV: 'production', - PORT: 5350 - }, - error_file: './logs/pm2-error.log', - out_file: './logs/pm2-out.log', - log_file: './logs/pm2-combined.log', - time: true - }] -} -``` - -### 3. Nginx配置（生产环境） -```nginx -server { - listen 80; - server_name nxxmdata.com www.nxxmdata.com; - return 301 https://$server_name$request_uri; -} - -server { - listen 443 ssl http2; - server_name nxxmdata.com www.nxxmdata.com; - - ssl_certificate /etc/nginx/ssl/nxxmdata.com.crt; - ssl_certificate_key /etc/nginx/ssl/nxxmdata.com.key; - - # SSL配置 - ssl_protocols TLSv1.2 TLSv1.3; - ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; - ssl_prefer_server_ciphers off; - - # Gzip压缩 - gzip on; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml; - - # 管理后台 - location / { - root /path/to/nxxmdata/admin-system/frontend/dist; - try_files $uri $uri/ /index.html; - expires 1y; - add_header Cache-Control "public, immutable"; - } - - # 官网大屏 - location /screen { - alias /path/to/nxxmdata/website/data-screen/dist; - try_files $uri $uri/ /index.html; - expires 1y; - add_header Cache-Control "public, immutable"; - } - - # API代理 - location /api { - proxy_pass http://localhost:5350; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_connect_timeout 30s; - proxy_send_timeout 30s; - proxy_read_timeout 30s; - } - - # API文档 - location /api-docs { - proxy_pass http://localhost:5350; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } -} -``` - -## 监控和维护 - -### 1. 日志管理 -```bash -# PM2日志管理 -pm2 logs -pm2 logs nxxmdata-backend -pm2 flush # 清空日志 - -# 应用日志位置 -tail -f backend/logs/app.log -tail -f backend/logs/error.log -``` - -### 2. 性能监控 -```bash -# PM2监控 -pm2 monit - -# 系统资源监控 -htop -iostat -x 1 -``` - -### 3. 数据库备份 -```bash -# 创建备份脚本 backup.sh -#!/bin/bash -DATE=$(date +%Y%m%d_%H%M%S) -mysqldump -u root -p nxxmdata > /backup/nxxmdata_$DATE.sql -find /backup -name "nxxmdata_*.sql" -mtime +7 -delete - -# 设置定时任务 -crontab -e -# 添加: 0 2 * * * /path/to/backup.sh -``` - -### 4. 自动更新脚本 -```bash -#!/bin/bash -# update.sh -cd /path/to/nxxmdata -git pull origin main - -# 构建前端 -cd admin-system/frontend && npm run build -cd ../../website/data-screen && npm run build - -# 重启服务 -pm2 restart nxxmdata-backend -``` - -## 故障排除 - -### 常见问题 - -1. **端口占用** -```bash -# 查看端口占用 -lsof -i :5350 -netstat -tulpn | grep :5350 - -# 解决方法：杀死占用进程或更改端口 -``` - -2. **数据库连接失败** -```bash -# 检查MySQL服务状态 -systemctl status mysql - -# 检查连接配置 -mysql -u root -p -h localhost -``` - -3. **内存不足** -```bash -# 查看内存使用 -free -h -top - -# 优化PM2配置，减少实例数量 -``` - -4. **磁盘空间不足** -```bash -# 查看磁盘使用 -df -h - -# 清理日志文件 -pm2 flush -find /path/to/logs -name "*.log" -mtime +30 -delete -``` - -## 安全加固 - -### 1. 防火墙配置 -```bash -# 使用ufw -ufw allow 22 # SSH -ufw allow 80 # HTTP -ufw allow 443 # HTTPS -ufw enable -``` - -### 2. SSL证书配置 -```bash -# 使用Let's Encrypt -certbot --nginx -d nxxmdata.com -d www.nxxmdata.com - -# 自动续期 -echo "0 12 * * * /usr/bin/certbot renew --quiet" | crontab - -``` - -### 3. 定期安全更新 -```bash -# 系统更新 -apt update && apt upgrade -y - -# Node.js依赖安全检查 -npm audit -npm audit fix -``` - -## 性能优化 - -### 1. 数据库优化 -```sql --- 添加必要的索引 -CREATE INDEX idx_farms_location ON farms(location); -CREATE INDEX idx_devices_status ON devices(status); -CREATE INDEX idx_alerts_created_at ON alerts(created_at); - --- 定期优化表 -OPTIMIZE TABLE farms, devices, alerts, users; -``` - -### 2. 缓存配置 -```bash -# 安装Redis（可选） -apt install redis-server - -# 在应用中配置Redis缓存 -``` - -### 3. CDN配置 -- 静态资源使用CDN加速 -- 图片和视频文件外部存储 - -## 回滚策略 - -### 1. 代码回滚 -```bash -# Git回滚 -git revert -git push origin main - -# 重新部署 -./update.sh -``` - -### 2. 数据库回滚 -```bash -# 恢复数据库备份 -mysql -u root -p nxxmdata < /backup/nxxmdata_20231201_020000.sql -``` - -### 3. 服务回滚 -```bash -# 停止当前版本 -pm2 stop nxxmdata-backend - -# 恢复上一版本 -pm2 start ecosystem.config.js.backup -``` - ---- - -## 联系信息 - -如有部署问题，请联系技术支持团队： -- 邮箱: tech-support@nxxmdata.com -- 电话: 400-xxx-xxxx - -*最后更新: 2025年1月* \ No newline at end of file diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md deleted file mode 100644 index f5337ad..0000000 --- a/docs/DEVELOPMENT.md +++ /dev/null @@ -1,932 +0,0 @@ -# 开发指南 - -## 概述 - -本文档为开发者提供宁夏智慧养殖监管平台的详细开发指南，包括开发环境搭建、代码规范、开发流程、调试技巧等内容。 - -## 开发环境搭建 - -### 系统要求 -- **Node.js**: 18.0+ (推荐使用 LTS 版本) -- **npm**: 8.0+ 或 **yarn**: 1.22+ -- **MySQL**: 8.0+ -- **Git**: 2.25+ -- **编辑器**: VSCode (推荐) - -### 工具推荐 -- **API测试**: Postman 或 Insomnia -- **数据库管理**: MySQL Workbench 或 phpMyAdmin -- **版本控制**: Git + GitHub/GitLab -- **终端**: iTerm2 (macOS) 或 Windows Terminal - -### 环境搭建步骤 - -#### 1. 克隆项目 -```bash -git clone -cd nxxmdata -``` - -#### 2. 安装依赖 -```bash -# 后端依赖 -cd backend -npm install - -# 前端依赖 - 管理后台 -cd ../admin-system/frontend -npm install - -# 前端依赖 - 官网大屏 -cd ../../website/data-screen -npm install - -# 微信小程序（可选） -cd ../../mini_program/farm-monitor-dashboard -npm install -``` - -#### 3. 数据库配置 -```bash -# 创建数据库 -mysql -u root -p -CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - -# 导入数据结构 -cd backend -mysql -u root -p nxxmdata < ../create_tables.sql -``` - -#### 4. 环境变量配置 -```bash -# 后端环境变量 -cp backend/.env.example backend/.env -# 编辑 .env 文件，配置数据库连接等信息 - -# 前端环境变量 -cp admin-system/frontend/.env.example admin-system/frontend/.env -# 配置API基础URL等 -``` - -#### 5. 启动开发服务器 -```bash -# 启动后端 (Terminal 1) -cd backend -npm run dev - -# 启动管理后台前端 (Terminal 2) -cd admin-system/frontend -npm run dev - -# 启动官网大屏 (Terminal 3) -cd website/data-screen -npm run dev -``` - -## 项目结构详解 - -### 后端架构 (`backend/`) -``` -backend/ -├── config/ # 配置文件 -│ ├── database.js # 数据库配置 -│ ├── swagger.js # API文档配置 -│ └── performance-config.js # 性能监控配置 -├── controllers/ # 控制器层 -│ ├── farmController.js # 农场业务逻辑 -│ ├── deviceController.js # 设备业务逻辑 -│ └── userController.js # 用户业务逻辑 -├── models/ # 数据模型层 -│ ├── Farm.js # 农场模型 -│ ├── Device.js # 设备模型 -│ └── User.js # 用户模型 -├── routes/ # 路由层 -│ ├── farms.js # 农场相关路由 -│ ├── devices.js # 设备相关路由 -│ └── auth.js # 认证相关路由 -├── middleware/ # 中间件 -│ ├── auth.js # 认证中间件 -│ └── performance-middleware.js # 性能监控中间件 -├── utils/ # 工具类 -│ ├── logger.js # 日志工具 -│ └── performance-monitor.js # 性能监控工具 -├── migrations/ # 数据库迁移 -├── seeds/ # 种子数据 -├── logs/ # 日志文件 -└── server.js # 服务器入口 -``` - -### 前端架构 (`admin-system/frontend/`) -``` -frontend/ -├── src/ -│ ├── components/ # 可复用组件 -│ │ ├── BaiduMap.vue # 百度地图组件 -│ │ ├── EChart.vue # 图表组件 -│ │ └── Dashboard.vue # 仪表盘组件 -│ ├── views/ # 页面组件 -│ │ ├── Home.vue # 首页 -│ │ ├── MapView.vue # 地图视图 -│ │ └── Analytics.vue # 数据分析 -│ ├── stores/ # 状态管理 (Pinia) -│ │ ├── user.js # 用户状态 -│ │ └── data.js # 数据状态 -│ ├── router/ # 路由配置 -│ │ ├── index.js # 路由实例 -│ │ └── routes.js # 路由定义 -│ ├── utils/ # 工具函数 -│ │ └── api.js # API调用封装 -│ ├── styles/ # 样式文件 -│ └── config/ # 配置文件 -├── public/ # 静态资源 -└── vite.config.js # Vite配置 -``` - -## 开发规范 - -### 代码风格规范 - -#### JavaScript/Vue.js 规范 -```javascript -// 1. 使用 ES6+ 语法 -const apiUrl = process.env.VITE_API_BASE_URL; - -// 2. 函数命名使用驼峰命名 -function getUserInfo() {} - -// 3. 常量使用大写字母和下划线 -const API_BASE_URL = 'http://localhost:5350/api'; - -// 4. 类名使用 PascalCase -class UserService {} - -// 5. 文件名使用 kebab-case -// user-service.js, farm-detail.vue -``` - -#### Vue.js 组件规范 -```vue - - - - - -``` - -#### Node.js 后端规范 -```javascript -// 1. 使用严格模式 -'use strict'; - -// 2. 模块导入顺序：内置模块 -> 第三方模块 -> 本地模块 -const path = require('path'); -const express = require('express'); -const { Farm } = require('../models'); - -// 3. 异步函数使用 async/await -const getFarms = async (req, res) => { - try { - // 4. 输入验证 - const { page = 1, limit = 10 } = req.query; - - // 5. 业务逻辑 - const farms = await Farm.findAll({ - limit: parseInt(limit), - offset: (parseInt(page) - 1) * parseInt(limit) - }); - - // 6. 统一响应格式 - res.json({ - success: true, - data: farms, - message: '获取成功' - }); - } catch (error) { - // 7. 错误处理 - res.status(500).json({ - success: false, - error: { - message: error.message - } - }); - } -}; - -module.exports = { - getFarms -}; -``` - -### Git 工作流规范 - -#### 分支命名规范 -```bash -# 功能分支 -feature/user-management -feature/device-monitoring - -# 修复分支 -fix/login-error -fix/map-display-issue - -# 发布分支 -release/v1.0.0 - -# 热修复分支 -hotfix/security-patch -``` - -#### 提交信息规范 -```bash -# 格式: type(scope): description - -# 类型 (type): -# feat: 新功能 -# fix: 修复bug -# docs: 文档更新 -# style: 代码格式调整 -# refactor: 重构 -# test: 测试相关 -# chore: 构建过程或辅助工具的变动 - -# 示例: -git commit -m "feat(user): add user registration functionality" -git commit -m "fix(map): resolve baidu map display issue" -git commit -m "docs(api): update API documentation" -``` - -### 数据库设计规范 - -#### 表命名规范 -```sql --- 表名使用小写字母和下划线 -CREATE TABLE users (...); -CREATE TABLE user_roles (...); -CREATE TABLE device_sensors (...); - --- 字段名使用小写字母和下划线 -ALTER TABLE users ADD COLUMN created_at DATETIME; -ALTER TABLE users ADD COLUMN updated_at DATETIME; - --- 索引命名 -CREATE INDEX idx_users_email ON users(email); -CREATE INDEX idx_farms_location ON farms(location); -``` - -#### 模型定义规范 -```javascript -// models/User.js -const { DataTypes } = require('sequelize'); - -module.exports = (sequelize) => { - const User = sequelize.define('User', { - id: { - type: DataTypes.INTEGER, - primaryKey: true, - autoIncrement: true, - comment: '用户唯一标识' - }, - username: { - type: DataTypes.STRING(50), - allowNull: false, - unique: true, - comment: '用户名' - }, - email: { - type: DataTypes.STRING(100), - allowNull: false, - unique: true, - validate: { - isEmail: true - }, - comment: '邮箱地址' - } - }, { - tableName: 'users', - timestamps: true, - underscored: true, - comment: '用户表' - }); - - // 定义关联关系 - User.associate = (models) => { - User.belongsToMany(models.Role, { - through: models.UserRole, - foreignKey: 'user_id', - otherKey: 'role_id' - }); - }; - - return User; -}; -``` - -## 开发流程 - -### 功能开发流程 - -#### 1. 需求分析 -- 理解业务需求 -- 确认技术方案 -- 评估开发时间 - -#### 2. 设计阶段 -```bash -# 数据库设计 -# 1. 创建或修改表结构 -# 2. 更新模型定义 -# 3. 编写迁移脚本 - -# API设计 -# 1. 定义路由 -# 2. 设计请求/响应格式 -# 3. 更新API文档 - -# 前端设计 -# 1. UI组件设计 -# 2. 状态管理设计 -# 3. 路由规划 -``` - -#### 3. 开发阶段 -```bash -# 创建功能分支 -git checkout -b feature/new-feature - -# 后端开发 -# 1. 创建/修改模型 -# 2. 编写控制器逻辑 -# 3. 添加路由 -# 4. 编写单元测试 - -# 前端开发 -# 1. 创建Vue组件 -# 2. 实现业务逻辑 -# 3. 添加样式 -# 4. 集成API - -# 提交代码 -git add . -git commit -m "feat: implement new feature" -git push origin feature/new-feature -``` - -#### 4. 测试阶段 -```bash -# 单元测试 -npm test - -# 集成测试 -npm run test:integration - -# 端到端测试 -npm run test:e2e - -# 手动测试 -# 1. 功能测试 -# 2. 兼容性测试 -# 3. 性能测试 -``` - -#### 5. 代码审查 -- 创建 Pull Request -- 代码审查 -- 修改反馈问题 -- 合并到主分支 - -### 调试技巧 - -#### 后端调试 - -##### 1. 使用 console.log 调试 -```javascript -// 在关键位置添加日志 -console.log('User data:', userData); -console.log('Database query result:', result); - -// 使用 JSON.stringify 查看对象 -console.log('Request body:', JSON.stringify(req.body, null, 2)); -``` - -##### 2. 使用 Winston 日志 -```javascript -const logger = require('../utils/logger'); - -// 不同级别的日志 -logger.info('User logged in', { userId: user.id }); -logger.warn('Invalid input', { input: req.body }); -logger.error('Database error', { error: error.message }); -``` - -##### 3. 使用 Node.js 调试器 -```bash -# 启动调试模式 -node --inspect-brk server.js - -# 在 Chrome 中打开 chrome://inspect -# 连接到 Node.js 进程进行调试 -``` - -##### 4. 数据库查询调试 -```javascript -// 启用 Sequelize 日志 -const sequelize = new Sequelize(config, { - logging: console.log, // 显示 SQL 查询 - benchmark: true // 显示查询时间 -}); - -// 手动执行 SQL 查询 -const [results, metadata] = await sequelize.query( - 'SELECT * FROM users WHERE id = ?', - { replacements: [userId] } -); -``` - -#### 前端调试 - -##### 1. 使用 Vue DevTools -```bash -# 安装 Vue DevTools 浏览器扩展 -# 查看组件状态、props、events -# 检查 Pinia store 状态 -``` - -##### 2. 使用 console.log -```javascript -// 在组件中添加调试信息 -export default { - setup() { - const userData = ref(null); - - const fetchUser = async () => { - console.log('Fetching user data...'); - const response = await api.getUser(); - console.log('User response:', response); - userData.value = response.data; - }; - - return { userData, fetchUser }; - } -} -``` - -##### 3. 使用浏览器开发者工具 -```javascript -// 在代码中设置断点 -debugger; - -// 查看网络请求 -// Network 标签页 -> 检查 API 请求和响应 - -// 查看控制台错误 -// Console 标签页 -> 查看 JavaScript 错误 -``` - -##### 4. API 调试 -```javascript -// 创建 API 调试工具 -const apiDebug = { - log: (method, url, data, response) => { - console.group(`API ${method.toUpperCase()} ${url}`); - console.log('Request data:', data); - console.log('Response:', response); - console.groupEnd(); - } -}; - -// 在 API 调用中使用 -const response = await axios.post('/api/farms', farmData); -apiDebug.log('POST', '/api/farms', farmData, response.data); -``` - -### 性能优化 - -#### 后端性能优化 - -##### 1. 数据库查询优化 -```javascript -// 使用索引 -// 在经常查询的字段上添加索引 -CREATE INDEX idx_farms_status ON farms(status); - -// 避免 N+1 查询 -const farms = await Farm.findAll({ - include: [{ - model: Device, - as: 'devices' - }] -}); - -// 使用分页 -const farms = await Farm.findAndCountAll({ - limit: 10, - offset: (page - 1) * 10 -}); - -// 只查询需要的字段 -const farms = await Farm.findAll({ - attributes: ['id', 'name', 'status'] -}); -``` - -##### 2. 缓存策略 -```javascript -// 使用内存缓存 -const cache = new Map(); - -const getCachedData = (key) => { - if (cache.has(key)) { - return cache.get(key); - } - return null; -}; - -const setCachedData = (key, data, ttl = 300000) => { - cache.set(key, data); - setTimeout(() => cache.delete(key), ttl); -}; -``` - -##### 3. 异步处理 -```javascript -// 使用 Promise.all 并行处理 -const [farms, devices, users] = await Promise.all([ - Farm.findAll(), - Device.findAll(), - User.findAll() -]); - -// 使用 stream 处理大量数据 -const stream = Farm.findAll({ stream: true }); -stream.on('data', (farm) => { - // 处理单个农场数据 -}); -``` - -#### 前端性能优化 - -##### 1. 组件懒加载 -```javascript -// router/routes.js -const routes = [ - { - path: '/farms', - component: () => import('../views/Farms.vue') // 懒加载 - } -]; -``` - -##### 2. 图片优化 -```vue - -``` - -##### 3. 虚拟滚动 -```vue - -``` - -### 测试指南 - -#### 单元测试 - -##### 后端单元测试 (Jest) -```javascript -// tests/controllers/farmController.test.js -const { getFarms } = require('../../controllers/farmController'); -const { Farm } = require('../../models'); - -jest.mock('../../models'); - -describe('Farm Controller', () => { - describe('getFarms', () => { - it('should return farms list', async () => { - const mockFarms = [ - { id: 1, name: 'Farm 1' }, - { id: 2, name: 'Farm 2' } - ]; - - Farm.findAll.mockResolvedValue(mockFarms); - - const req = { query: {} }; - const res = { - json: jest.fn(), - status: jest.fn().mockReturnThis() - }; - - await getFarms(req, res); - - expect(res.json).toHaveBeenCalledWith({ - success: true, - data: mockFarms, - message: '获取成功' - }); - }); - }); -}); -``` - -##### 前端单元测试 (Vitest) -```javascript -// tests/components/FarmList.test.js -import { mount } from '@vue/test-utils'; -import FarmList from '@/components/FarmList.vue'; - -describe('FarmList', () => { - it('renders farm list correctly', () => { - const farms = [ - { id: 1, name: 'Farm 1', status: 'active' }, - { id: 2, name: 'Farm 2', status: 'inactive' } - ]; - - const wrapper = mount(FarmList, { - props: { farms } - }); - - expect(wrapper.findAll('.farm-item')).toHaveLength(2); - expect(wrapper.text()).toContain('Farm 1'); - expect(wrapper.text()).toContain('Farm 2'); - }); - - it('emits select event when farm is clicked', async () => { - const farms = [{ id: 1, name: 'Farm 1', status: 'active' }]; - - const wrapper = mount(FarmList, { - props: { farms } - }); - - await wrapper.find('.farm-item').trigger('click'); - - expect(wrapper.emitted('select')).toBeTruthy(); - expect(wrapper.emitted('select')[0]).toEqual([farms[0]]); - }); -}); -``` - -#### 集成测试 -```javascript -// tests/integration/farms.test.js -const request = require('supertest'); -const app = require('../../server'); - -describe('Farms API', () => { - it('GET /api/farms should return farms list', async () => { - const response = await request(app) - .get('/api/farms') - .set('Authorization', 'Bearer valid_token') - .expect(200); - - expect(response.body.success).toBe(true); - expect(Array.isArray(response.body.data)).toBe(true); - }); - - it('POST /api/farms should create new farm', async () => { - const farmData = { - name: 'Test Farm', - type: 'cattle', - longitude: 106.26667, - latitude: 38.46667 - }; - - const response = await request(app) - .post('/api/farms') - .set('Authorization', 'Bearer admin_token') - .send(farmData) - .expect(201); - - expect(response.body.success).toBe(true); - expect(response.body.data.name).toBe(farmData.name); - }); -}); -``` - -### 部署和运维 - -#### 本地开发部署 -```bash -# 1. 启动所有服务 -npm run dev:all - -# 2. 查看日志 -tail -f backend/logs/app.log - -# 3. 数据库管理 -npm run db:migrate -npm run db:seed -``` - -#### 生产环境部署 -```bash -# 1. 构建项目 -npm run build - -# 2. 使用 PM2 部署 -pm2 start ecosystem.config.js --env production - -# 3. 监控服务 -pm2 monit -pm2 logs -``` - -## 常见问题解决 - -### 开发环境问题 - -#### 1. 端口占用 -```bash -# 查找占用端口的进程 -lsof -i :5350 -netstat -ano | findstr :5350 # Windows - -# 杀死进程 -kill -9 -taskkill /PID /F # Windows -``` - -#### 2. 依赖安装失败 -```bash -# 清除 npm 缓存 -npm cache clean --force - -# 删除 node_modules 重新安装 -rm -rf node_modules package-lock.json -npm install - -# 使用 yarn 代替 npm -yarn install -``` - -#### 3. 数据库连接失败 -```bash -# 检查 MySQL 服务状态 -brew services list | grep mysql # macOS -systemctl status mysql # Linux -net start mysql # Windows - -# 测试数据库连接 -mysql -u root -p -h localhost -P 3306 -``` - -### 运行时问题 - -#### 1. API 请求失败 -```javascript -// 检查网络请求 -// 1. 打开浏览器开发者工具 -// 2. 查看 Network 标签页 -// 3. 检查请求状态码和响应内容 - -// 添加请求拦截器 -axios.interceptors.request.use( - config => { - console.log('Request:', config); - return config; - }, - error => { - console.error('Request Error:', error); - return Promise.reject(error); - } -); -``` - -#### 2. 组件渲染问题 -```javascript -// 检查 Vue 组件状态 -// 1. 安装 Vue DevTools -// 2. 检查组件 props 和 data -// 3. 查看 computed 属性 -// 4. 检查事件监听器 -``` - -## 最佳实践 - -### 代码组织 -1. **模块化开发**: 将功能拆分成独立的模块 -2. **组件复用**: 创建可复用的组件库 -3. **状态管理**: 合理使用 Pinia 管理应用状态 -4. **错误处理**: 统一的错误处理机制 -5. **日志记录**: 详细的日志记录便于调试 - -### 性能优化 -1. **懒加载**: 组件和路由懒加载 -2. **缓存策略**: 合理使用缓存提升性能 -3. **数据库优化**: 优化查询语句和索引 -4. **图片优化**: 压缩图片和使用适当格式 -5. **打包优化**: 优化 Webpack/Vite 配置 - -### 安全考虑 -1. **输入验证**: 严格验证用户输入 -2. **权限控制**: 实现细粒度的权限控制 -3. **SQL注入防护**: 使用参数化查询 -4. **XSS防护**: 过滤和转义用户输入 -5. **CSRF防护**: 实现 CSRF Token 机制 - -## 工具和资源 - -### 开发工具 -- **IDE**: VSCode -- **API测试**: Postman -- **数据库**: MySQL Workbench -- **版本控制**: Git -- **包管理**: npm/yarn - -### 有用的 VSCode 插件 -- **Vue Language Features (Volar)**: Vue 3 支持 -- **ESLint**: 代码质量检查 -- **Prettier**: 代码格式化 -- **Auto Rename Tag**: 自动重命名标签 -- **Bracket Pair Colorizer**: 括号高亮 -- **GitLens**: Git 增强 - -### 学习资源 -- **Vue.js 官方文档**: https://vuejs.org/ -- **Node.js 官方文档**: https://nodejs.org/ -- **Sequelize 文档**: https://sequelize.org/ -- **Ant Design Vue**: https://antdv.com/ -- **ECharts 文档**: https://echarts.apache.org/ - ---- - -## 联系支持 - -如有开发相关问题，请联系： -- **技术支持**: dev-support@nxxmdata.com -- **文档反馈**: docs@nxxmdata.com -- **Bug 报告**: bugs@nxxmdata.com - -*最后更新: 2025年1月* \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 22244cb..1bacbea 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,19 +1,104 @@ -# 项目文档目录说明 +# 宁夏智慧养殖监管平台文档中心 -本文档说明了项目中docs目录的结构和内容。 +## 文档概述 -## 目录结构 +本文档中心包含了宁夏智慧养殖监管平台的完整技术文档，涵盖产品需求、系统架构、开发指南、部署运维等各个方面。 -- `config/` - 存放项目的所有配置文档，包括： - - 产品需求文档 (PRD.md) - - 系统架构文档 (arch.md) - - 系统设计文档 (design.md) - - 开发计划文档 (dev-plan.md) - - 任务文档 (task.md) - - 数据同步修复报告 (data-sync-fix-report.md) - - 农场数据导入摘要 (farms-data-import-summary.md) - - 位置数据验证报告 (location-data-validation-report.md) +## 2. 文档结构 -- 其他技术文档 - - 百度地图许可说明 (baidu-map-license.md) - - 性能监控说明 (performance-monitoring.md) \ No newline at end of file +### 2.1 需求文档 (requirements/) +- **PRD.md** - 核心产品需求文档 +- **政府端产品需求文档.md** - 政府监管端功能需求 +- **保险端产品需求文档.md** - 保险理赔端功能需求 +- **银行端小程序产品需求文档.md** - 银行贷款端小程序需求 +- **official-website-prd.md** - 官方网站产品需求 + +### 2.2 系统架构 (architecture/) +- **系统架构文档.md** - 整体架构设计、技术选型、部署方案 +- **系统详细设计文档.md** - 详细的系统设计和技术实现方案 +- **数据库设计文档.md** - 数据模型、表结构、关系设计 +- **开发计划.md** - 项目开发计划、里程碑、资源配置 +- **设计文档.md** - UI/UX设计规范、交互设计 + +### 2.3 开发文档 (development/) +- **开发指南.md** - 环境搭建、开发规范、调试技巧 +- **API接口文档.md** - 接口定义、参数说明、示例代码 +- **代码规范.md** - 编码标准、命名规范、最佳实践 +- **测试文档.md** - 测试策略、工具配置、用例设计 +- **环境配置文档.md** - 开发、测试、生产环境配置指南 +- **CONTRIBUTING.md** - 项目贡献指南、开发流程 +- **examples/** - 配置文件示例、代码模板 + +### 2.4 运维文档 (operations/) +- **部署文档.md** - 环境部署、配置管理、容器化部署 +- **监控运维文档.md** - 系统监控、性能优化、故障处理 +- **SECURITY.md** - 安全指南、漏洞报告、安全配置 +- **TROUBLESHOOTING.md** - 常见问题、故障排除、解决方案 +- **performance-monitoring.md** - 性能监控配置和分析 +- **data-sync-fix-report.md** - 数据同步问题修复报告 +- **farms-data-import-summary.md** - 养殖场数据导入总结 +- **location-data-validation-report.md** - 位置数据验证报告 + +### 2.5 项目管理 (project/) +- **项目管理文档.md** - 项目组织架构、计划管理、风险控制 +- **开发计划文档.md** - 项目规划、里程碑、时间安排 +- **任务文档.md** - 任务分解、进度跟踪、问题记录 +- **变更日志.md** - 版本更新、功能变更、问题修复 +- **baidu-map-license.md** - 百度地图许可证信息 +- **FINAL_STRUCTURE_REPORT.md** - 项目结构最终报告 +- **PROJECT_CLEANUP_REPORT.md** - 项目清理报告 + +## 文档维护 + +### 版本管理 +- 所有文档都有版本历史记录 +- 重要变更会在CHANGELOG.md中记录 +- 文档与代码版本保持同步 + +### 更新规范 +1. **文档更新**: 功能变更时同步更新相关文档 +2. **版本标记**: 每次更新都要更新版本号和修改日期 +3. **审核流程**: 重要文档变更需要团队审核 +4. **格式统一**: 遵循Markdown格式规范 + +### 贡献指南 +- 参考 [贡献指南](./CONTRIBUTING.md) 了解如何参与文档维护 +- 提交文档变更前请先阅读相关规范 +- 鼓励团队成员积极完善文档内容 + +## 快速导航 + +### 新手入门 +1. 阅读 [产品需求文档](./requirements/PRD.md) 了解项目背景 +2. 查看 [系统架构文档](./architecture/系统架构文档.md) 理解技术架构 +3. 按照 [开发指南](./development/开发指南.md) 配置开发环境 +4. 参考 [API接口文档](./development/API接口文档.md) 进行接口开发 + +### 部署上线 +1. 阅读 [部署文档](./operations/部署文档.md) 了解部署流程 +2. 参考 [安全配置](./operations/SECURITY.md) 进行安全设置 +3. 遇到问题查看 [故障排除](./operations/TROUBLESHOOTING.md) + +### 多端开发 +1. 根据目标端选择对应的需求文档 +2. 查看 [代码规范](./development/代码规范.md) +3. 参考 [贡献指南](./development/CONTRIBUTING.md) 了解开发流程 + +## 联系我们 + +### 技术支持 +- **邮箱**: tech-support@nxxmdata.com +- **电话**: 400-xxx-xxxx +- **工作时间**: 周一至周五 9:00-18:00 + +### 文档反馈 +如果您发现文档中的错误或有改进建议，请通过以下方式联系我们： +- 提交 Issue 到项目仓库 +- 发送邮件到 docs@nxxmdata.com +- 直接提交 Pull Request + +--- + +**最后更新**: 2024年1月20日 +**文档版本**: v2.0 +**维护团队**: 宁夏智慧养殖平台开发团队 \ No newline at end of file diff --git a/docs/architecture/开发计划.md b/docs/architecture/开发计划.md new file mode 100644 index 0000000..132ec1d --- /dev/null +++ b/docs/architecture/开发计划.md @@ -0,0 +1,287 @@ +# 宁夏智慧养殖监管平台开发计划 + +## 版本历史 + +| 版本 | 日期 | 修改内容 | 修改人 | +|------|------|----------|--------| +| v1.0 | 2025-01-19 | 初始版本 | 系统架构师 | + +## 1. 项目概述 + +### 1.1 项目背景 +宁夏智慧养殖监管平台是一个综合性的数字化养殖监管系统，旨在通过现代信息技术提升养殖业的管理水平和监管效率。 + +### 1.2 开发目标 +- 构建完整的智慧养殖监管平台 +- 实现多端应用协同工作 +- 确保系统稳定性和可扩展性 +- 提供优质的用户体验 + +## 2. 项目范围 + +### 2.1 核心模块 +- **后端服务** (backend/) +- **管理后台** (admin-system/) +- **官方网站** (website/) +- **小程序矩阵** (mini-app/) + +### 2.2 支撑模块 +- 数据库设计与实现 +- API接口开发 +- 用户权限管理 +- 数据分析与报表 + +## 3. 开发阶段规划 + +### 3.1 第一阶段：基础架构搭建 (4周) + +#### 3.1.1 后端基础服务 (2周) +**任务分解：** +- [ ] 项目初始化和环境配置 (2人日) +- [ ] 数据库设计和建表 (3人日) +- [ ] 基础框架搭建 (Express + Sequelize) (2人日) +- [ ] 用户认证和权限管理 (3人日) +- [ ] 基础API接口开发 (4人日) + +**工时估算：** 14人日 +**负责人员：** 后端开发工程师 2人 +**里程碑：** 基础API服务可用 + +#### 3.1.2 前端基础框架 (2周) +**任务分解：** +- [ ] 管理后台项目初始化 (1人日) +- [ ] 官网项目初始化 (1人日) +- [ ] UI组件库集成和配置 (2人日) +- [ ] 路由和状态管理配置 (2人日) +- [ ] 基础页面布局开发 (4人日) +- [ ] 登录和权限验证 (4人日) + +**工时估算：** 14人日 +**负责人员：** 前端开发工程师 2人 +**里程碑：** 前端基础框架完成 + +### 3.2 第二阶段：核心功能开发 (8周) + +#### 3.2.1 用户管理模块 (2周) +**任务分解：** +- [ ] 用户注册和登录API (2人日) +- [ ] 用户信息管理API (2人日) +- [ ] 角色权限管理API (3人日) +- [ ] 前端用户管理界面 (4人日) +- [ ] 权限控制组件开发 (3人日) + +**工时估算：** 14人日 +**负责人员：** 全栈开发工程师 2人 + +#### 3.2.2 养殖场管理模块 (3周) +**任务分解：** +- [ ] 养殖场信息管理API (3人日) +- [ ] 养殖场地理位置服务 (2人日) +- [ ] 养殖场档案管理 (3人日) +- [ ] 前端养殖场管理界面 (5人日) +- [ ] 地图展示和交互功能 (4人日) +- [ ] 数据导入导出功能 (4人日) + +**工时估算：** 21人日 +**负责人员：** 全栈开发工程师 2人 + +#### 3.2.3 监控数据模块 (3周) +**任务分解：** +- [ ] 环境监控数据API (3人日) +- [ ] 实时数据处理服务 (4人日) +- [ ] 数据存储和查询优化 (3人日) +- [ ] 前端数据展示界面 (4人日) +- [ ] 图表和可视化组件 (4人日) +- [ ] 报警和通知功能 (3人日) + +**工时估算：** 21人日 +**负责人员：** 全栈开发工程师 2人 + +### 3.3 第三阶段：小程序开发 (4周) + +#### 3.3.1 政府端小程序 (1.5周) +**任务分解：** +- [ ] 小程序项目初始化 (1人日) +- [ ] 监管数据查看功能 (3人日) +- [ ] 养殖场信息查询 (2人日) +- [ ] 数据统计和报表 (3人日) +- [ ] 消息通知功能 (1人日) + +**工时估算：** 10人日 +**负责人员：** 小程序开发工程师 1人 + +#### 3.3.2 保险端小程序 (1.5周) +**任务分解：** +- [ ] 小程序项目初始化 (1人日) +- [ ] 保险业务管理 (3人日) +- [ ] 理赔数据查看 (2人日) +- [ ] 风险评估功能 (3人日) +- [ ] 业务流程管理 (1人日) + +**工时估算：** 10人日 +**负责人员：** 小程序开发工程师 1人 + +#### 3.3.3 银行端小程序 (1周) +**任务分解：** +- [ ] 小程序项目初始化 (1人日) +- [ ] 贷款业务管理 (2人日) +- [ ] 客户信息查看 (2人日) +- [ ] 风险控制功能 (2人日) +- [ ] 业务审批流程 (1人日) + +**工时估算：** 8人日 +**负责人员：** 小程序开发工程师 1人 + +### 3.4 第四阶段：系统集成和测试 (3周) + +#### 3.4.1 系统集成 (1周) +**任务分解：** +- [ ] 各模块接口联调 (2人日) +- [ ] 数据一致性验证 (2人日) +- [ ] 性能优化 (3人日) + +**工时估算：** 7人日 +**负责人员：** 全栈开发工程师 2人 + +#### 3.4.2 测试阶段 (2周) +**任务分解：** +- [ ] 单元测试编写 (3人日) +- [ ] 集成测试执行 (3人日) +- [ ] 用户验收测试 (4人日) +- [ ] 性能测试 (2人日) +- [ ] 安全测试 (2人日) + +**工时估算：** 14人日 +**负责人员：** 测试工程师 2人 + +### 3.5 第五阶段：部署上线 (2周) + +#### 3.5.1 生产环境部署 (1周) +**任务分解：** +- [ ] 生产环境配置 (2人日) +- [ ] 数据库迁移 (1人日) +- [ ] 应用部署和配置 (2人日) +- [ ] 域名和SSL证书配置 (1人日) +- [ ] 监控和日志配置 (1人日) + +**工时估算：** 7人日 +**负责人员：** 运维工程师 1人 + +#### 3.5.2 上线验证 (1周) +**任务分解：** +- [ ] 生产环境功能验证 (2人日) +- [ ] 性能监控和调优 (2人日) +- [ ] 用户培训和文档 (2人日) +- [ ] 问题修复和优化 (1人日) + +**工时估算：** 7人日 +**负责人员：** 全栈开发工程师 2人 + +## 4. 资源配置 + +### 4.1 人员配置 +- **项目经理**: 1人，负责项目整体协调和进度管理 +- **系统架构师**: 1人，负责技术架构设计和技术决策 +- **后端开发工程师**: 2人，负责后端服务开发 +- **前端开发工程师**: 2人，负责管理后台和官网开发 +- **小程序开发工程师**: 1人，负责小程序矩阵开发 +- **测试工程师**: 2人，负责测试用例设计和执行 +- **运维工程师**: 1人，负责部署和运维工作 + +### 4.2 技术资源 +- **开发环境**: 本地开发环境 + 测试服务器 +- **生产环境**: 云服务器 + 数据库 + CDN +- **第三方服务**: 百度地图API、短信服务、支付服务 + +## 5. 风险管理 + +### 5.1 技术风险 +- **风险**: 第三方API服务不稳定 +- **应对**: 准备备用方案，实现服务降级 +- **风险**: 数据库性能瓶颈 +- **应对**: 提前进行性能测试，优化查询和索引 + +### 5.2 进度风险 +- **风险**: 需求变更导致延期 +- **应对**: 严格控制需求变更，建立变更评估流程 +- **风险**: 人员流动影响进度 +- **应对**: 做好知识传承，建立备用人员计划 + +### 5.3 质量风险 +- **风险**: 测试不充分导致线上问题 +- **应对**: 建立完善的测试体系，增加自动化测试 +- **风险**: 安全漏洞 +- **应对**: 进行安全评估，建立安全开发规范 + +## 6. 质量保证 + +### 6.1 代码质量 +- 建立代码审查机制 +- 使用ESLint和Prettier统一代码风格 +- 编写单元测试，确保代码覆盖率 + +### 6.2 文档质量 +- 维护完整的API文档 +- 编写用户使用手册 +- 建立技术文档更新机制 + +### 6.3 测试质量 +- 制定详细的测试计划 +- 执行多层次测试（单元、集成、系统、验收） +- 建立缺陷跟踪和修复流程 + +## 7. 项目里程碑 + +| 里程碑 | 计划完成时间 | 交付物 | +|--------|--------------|--------| +| 基础架构完成 | 第4周 | 后端API框架、前端基础框架 | +| 核心功能完成 | 第12周 | 用户管理、养殖场管理、监控数据模块 | +| 小程序开发完成 | 第16周 | 三端小程序应用 | +| 系统测试完成 | 第19周 | 测试报告、缺陷修复 | +| 生产上线 | 第21周 | 生产环境部署、用户培训 | + +## 8. 沟通计划 + +### 8.1 定期会议 +- **日常站会**: 每日上午9:00，15分钟 +- **周例会**: 每周五下午，1小时 +- **月度评审**: 每月最后一周，2小时 + +### 8.2 报告机制 +- **日报**: 开发人员每日提交工作进展 +- **周报**: 项目经理每周汇总项目状态 +- **月报**: 向管理层汇报项目整体进展 + +## 9. 成功标准 + +### 9.1 功能标准 +- 所有核心功能按需求实现 +- 系统性能满足预期指标 +- 用户体验良好 + +### 9.2 质量标准 +- 代码覆盖率达到80%以上 +- 系统可用性达到99.5%以上 +- 安全测试通过 + +### 9.3 交付标准 +- 按时完成项目交付 +- 预算控制在计划范围内 +- 用户满意度达到85%以上 + +## 10. 后续维护 + +### 10.1 维护计划 +- 建立7x24小时监控体系 +- 制定应急响应预案 +- 定期进行系统优化和升级 + +### 10.2 迭代计划 +- 根据用户反馈持续优化功能 +- 定期发布新版本 +- 扩展新的业务模块 + +--- + +**文档维护**: 本文档将根据项目进展情况定期更新 +**联系方式**: 如有疑问，请联系项目经理或系统架构师 \ No newline at end of file diff --git a/docs/architecture/数据库设计文档.md b/docs/architecture/数据库设计文档.md new file mode 100644 index 0000000..eff29a5 --- /dev/null +++ b/docs/architecture/数据库设计文档.md @@ -0,0 +1,592 @@ +# 宁夏智慧养殖监管平台 数据库设计文档 + +## 版本历史 + +| 版本 | 日期 | 作者 | 描述 | +|------|------|------|------| +| v1.0 | 2025-01-19 | 开发团队 | 初始版本，完整数据库设计 | + +## 1. 数据库概述 + +### 1.1 设计原则 + +**数据完整性原则：** +- 实体完整性：每个表都有主键 +- 参照完整性：外键约束确保数据一致性 +- 域完整性：字段类型和约束确保数据有效性 + +**性能优化原则：** +- 合理的索引设计 +- 分区表设计（大数据量表） +- 查询优化友好的表结构 + +**扩展性原则：** +- 预留扩展字段 +- 模块化表设计 +- 支持水平和垂直扩展 + +### 1.2 技术规范 + +**数据库引擎：** MySQL 8.0+ +**字符集：** utf8mb4 +**排序规则：** utf8mb4_unicode_ci +**存储引擎：** InnoDB +**事务支持：** ACID 完整性 + +## 2. 数据库架构设计 + +### 2.1 逻辑架构 + +``` +宁夏智慧养殖监管平台数据库 +├── 用户权限模块 +│ ├── users (用户表) +│ ├── roles (角色表) +│ ├── permissions (权限表) +│ ├── role_permissions (角色权限关联表) +│ └── menu_permissions (菜单权限表) +├── 养殖场管理模块 +│ ├── farms (养殖场表) +│ ├── animals (动物信息表) +│ ├── iot_cattle (物联网牛只表) +│ ├── cattle_types (牛只品种表) +│ └── cattle_users (牛只用户表) +├── 设备管理模块 +│ ├── devices (设备表) +│ ├── sensor_data (传感器数据表) +│ ├── iot_xq_clients (物联网客户端表) +│ ├── iot_jbq_servers (物联网服务器表) +│ └── iot_jbq_clients (物联网客户端表) +├── 圈舍管理模块 +│ ├── pens (圈舍表) +│ ├── cattle_pens (牛只圈舍表) +│ ├── cattle_batches (牛只批次表) +│ └── cattle_batch_animals (批次动物关联表) +├── 电子围栏模块 +│ ├── electronic_fences (电子围栏表) +│ └── electronic_fence_points (围栏点表) +├── 业务记录模块 +│ ├── cattle_transfer_records (牛只转移记录表) +│ ├── cattle_exit_records (牛只出场记录表) +│ ├── alerts (预警表) +│ └── operation_logs (操作日志表) +├── 商城模块 +│ ├── products (产品表) +│ ├── orders (订单表) +│ └── order_items (订单项表) +└── 系统配置模块 + ├── system_configs (系统配置表) + └── form_logs (表单日志表) +``` + +### 2.2 物理架构 + +**主从复制架构：** +- 主库：负责写操作和实时查询 +- 从库：负责读操作和数据备份 +- 读写分离：提高系统并发能力 + +**分库分表策略：** +- 按业务模块分库 +- 大数据量表按时间分表（如传感器数据表） +- 按养殖场ID分表（如动物信息表） + +## 3. 核心数据表设计 + +### 3.1 用户权限模块 + +#### 3.1.1 用户表 (users) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 用户ID（主键）| +| username | VARCHAR | 50 | NO | - | 用户名（唯一）| +| email | VARCHAR | 100 | NO | - | 邮箱（唯一）| +| password | VARCHAR | 255 | NO | - | 密码（加密存储）| +| phone | VARCHAR | 20 | YES | NULL | 手机号 | +| avatar | VARCHAR | 255 | YES | NULL | 头像URL | +| roles | INT | - | YES | 2 | 角色ID（外键）| +| status | ENUM | - | NO | 'active' | 状态：active/inactive/suspended | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +**索引设计：** +```sql +PRIMARY KEY (id) +UNIQUE KEY uk_username (username) +UNIQUE KEY uk_email (email) +INDEX idx_roles (roles) +INDEX idx_status (status) +``` + +#### 3.1.2 角色表 (roles) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 角色ID（主键）| +| name | VARCHAR | 50 | NO | - | 角色名称（唯一）| +| description | TEXT | - | YES | NULL | 角色描述 | +| status | ENUM | - | NO | 'active' | 状态：active/inactive | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +### 3.2 养殖场管理模块 + +#### 3.2.1 养殖场表 (farms) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 养殖场ID（主键）| +| name | VARCHAR | 100 | NO | - | 养殖场名称 | +| type | VARCHAR | 50 | NO | - | 养殖场类型 | +| location | JSON | - | NO | {} | 地理位置（经纬度）| +| address | VARCHAR | 255 | YES | NULL | 详细地址 | +| contact | VARCHAR | 50 | YES | NULL | 联系人 | +| phone | VARCHAR | 20 | YES | NULL | 联系电话 | +| status | ENUM | - | NO | 'active' | 状态：active/inactive/maintenance | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +**索引设计：** +```sql +PRIMARY KEY (id) +INDEX idx_name (name) +INDEX idx_type (type) +INDEX idx_status (status) +``` + +#### 3.2.2 动物信息表 (animals) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | BIGINT | - | NO | AUTO_INCREMENT | 动物ID（主键）| +| collar_number | VARCHAR | 50 | NO | - | 项圈编号 | +| ear_tag | VARCHAR | 50 | YES | NULL | 动物耳号 | +| animal_type | INT | - | NO | 1 | 动物类型：1-牛，2-羊，3-猪，4-马 | +| breed | INT | - | NO | 1 | 品种ID | +| category | INT | - | NO | 1 | 品类：1-乳肉兼用，2-肉用，3-乳用，4-种用 | +| source_type | INT | - | NO | 1 | 来源类型：1-合作社，2-农户，3-养殖场，4-进口 | +| birth_date | DATE | - | YES | NULL | 出生日期 | +| birth_weight | DECIMAL | 10,2 | YES | 0.00 | 出生体重 | +| weaning_weight | DECIMAL | 10,2 | YES | 0.00 | 断奶体重 | +| weaning_age | INT | - | YES | 0 | 断奶日龄 | +| entry_date | DATE | - | YES | NULL | 入场日期 | +| calving_count | INT | - | YES | 0 | 历史已产胎次 | +| left_teat_count | INT | - | YES | NULL | 乳头数(左) | +| right_teat_count | INT | - | YES | NULL | 乳头数(右) | +| farm_id | INT | - | YES | NULL | 农场ID（外键）| +| pen_id | INT | - | YES | NULL | 圈舍ID（外键）| +| status | INT | - | NO | 1 | 状态：1-正常，2-生病，3-死亡 | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +**索引设计：** +```sql +PRIMARY KEY (id) +INDEX idx_collar_number (collar_number) +INDEX idx_ear_tag (ear_tag) +INDEX idx_farm_id (farm_id) +INDEX idx_pen_id (pen_id) +INDEX idx_animal_type (animal_type) +INDEX idx_status (status) +``` + +#### 3.2.3 物联网牛只表 (iot_cattle) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | BIGINT | - | NO | AUTO_INCREMENT | 牛只ID（主键）| +| orgId | INT | - | YES | NULL | 组织ID（外键到farms）| +| penId | INT | - | YES | NULL | 圈舍ID（外键）| +| batchId | INT | - | YES | NULL | 批次ID（外键）| +| varieties | INT | - | YES | NULL | 品种ID（外键）| +| strain | INT | - | YES | NULL | 品系ID（外键）| +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +### 3.3 设备管理模块 + +#### 3.3.1 设备表 (devices) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 设备ID（主键）| +| name | VARCHAR | 100 | NO | - | 设备名称 | +| type | VARCHAR | 50 | NO | - | 设备类型 | +| model | VARCHAR | 100 | YES | NULL | 设备型号 | +| serial_number | VARCHAR | 100 | YES | NULL | 设备序列号 | +| farm_id | INT | - | YES | NULL | 农场ID（外键）| +| location | JSON | - | YES | NULL | 设备位置 | +| status | ENUM | - | NO | 'active' | 状态：active/inactive/maintenance | +| last_heartbeat | TIMESTAMP | - | YES | NULL | 最后心跳时间 | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +#### 3.3.2 传感器数据表 (sensor_data) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | BIGINT | - | NO | AUTO_INCREMENT | 数据ID（主键）| +| device_id | INT | - | NO | - | 设备ID（外键）| +| farm_id | INT | - | YES | NULL | 农场ID（外键）| +| sensor_type | VARCHAR | 50 | NO | - | 传感器类型 | +| value | DECIMAL | 10,4 | NO | - | 传感器数值 | +| unit | VARCHAR | 20 | YES | NULL | 数值单位 | +| timestamp | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 数据时间戳 | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | + +**分表策略：** +- 按月分表：sensor_data_YYYYMM +- 保留最近12个月数据，历史数据归档 + +### 3.4 圈舍管理模块 + +#### 3.4.1 牛只圈舍表 (cattle_pens) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 圈舍ID（主键）| +| name | VARCHAR | 100 | NO | - | 圈舍名称 | +| farm_id | INT | - | NO | - | 农场ID（外键）| +| capacity | INT | - | NO | 0 | 容量 | +| current_count | INT | - | NO | 0 | 当前数量 | +| pen_type | VARCHAR | 50 | YES | NULL | 圈舍类型 | +| area | DECIMAL | 10,2 | YES | NULL | 面积（平方米）| +| status | ENUM | - | NO | 'active' | 状态：active/inactive/maintenance | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +#### 3.4.2 牛只批次表 (cattle_batches) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 批次ID（主键）| +| batch_name | VARCHAR | 100 | NO | - | 批次名称 | +| farm_id | INT | - | NO | - | 农场ID（外键）| +| batch_date | DATE | - | NO | - | 批次日期 | +| total_count | INT | - | NO | 0 | 总数量 | +| current_count | INT | - | NO | 0 | 当前数量 | +| status | ENUM | - | NO | 'active' | 状态：active/completed/cancelled | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +### 3.5 电子围栏模块 + +#### 3.5.1 电子围栏表 (electronic_fences) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 围栏ID（主键）| +| name | VARCHAR | 100 | NO | - | 围栏名称 | +| farm_id | INT | - | NO | - | 农场ID（外键）| +| fence_type | VARCHAR | 50 | NO | - | 围栏类型 | +| status | ENUM | - | NO | 'active' | 状态：active/inactive | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +#### 3.5.2 围栏点表 (electronic_fence_points) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 点ID（主键）| +| fence_id | INT | - | NO | - | 围栏ID（外键）| +| latitude | DECIMAL | 10,8 | NO | - | 纬度 | +| longitude | DECIMAL | 11,8 | NO | - | 经度 | +| point_order | INT | - | NO | - | 点序号 | +| created_by | INT | - | YES | NULL | 创建人（外键）| +| updated_by | INT | - | YES | NULL | 更新人（外键）| +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +### 3.6 业务记录模块 + +#### 3.6.1 预警表 (alerts) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | INT | - | NO | AUTO_INCREMENT | 预警ID（主键）| +| farm_id | INT | - | YES | NULL | 农场ID（外键）| +| device_id | INT | - | YES | NULL | 设备ID（外键）| +| alert_type | VARCHAR | 50 | NO | - | 预警类型 | +| level | ENUM | - | NO | 'low' | 预警级别：low/medium/high/critical | +| title | VARCHAR | 200 | NO | - | 预警标题 | +| message | TEXT | - | YES | NULL | 预警消息 | +| status | ENUM | - | NO | 'pending' | 状态：pending/acknowledged/resolved | +| acknowledged_at | TIMESTAMP | - | YES | NULL | 确认时间 | +| resolved_at | TIMESTAMP | - | YES | NULL | 解决时间 | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | +| updated_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 更新时间 | + +#### 3.6.2 操作日志表 (operation_logs) + +| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 | +|--------|------|------|----------|--------|------| +| id | BIGINT | - | NO | AUTO_INCREMENT | 日志ID（主键）| +| user_id | INT | - | YES | NULL | 用户ID（外键）| +| action | VARCHAR | 100 | NO | - | 操作动作 | +| resource | VARCHAR | 100 | NO | - | 操作资源 | +| resource_id | INT | - | YES | NULL | 资源ID | +| details | JSON | - | YES | NULL | 操作详情 | +| ip_address | VARCHAR | 45 | YES | NULL | IP地址 | +| user_agent | TEXT | - | YES | NULL | 用户代理 | +| created_at | TIMESTAMP | - | NO | CURRENT_TIMESTAMP | 创建时间 | + +## 4. 数据库优化策略 + +### 4.1 索引优化 + +**主键索引：** +- 所有表都使用自增整型主键 +- 确保主键的唯一性和非空性 + +**唯一索引：** +- 用户名、邮箱等唯一字段 +- 设备序列号等业务唯一标识 + +**复合索引：** +```sql +-- 传感器数据查询优化 +CREATE INDEX idx_sensor_data_query ON sensor_data (device_id, sensor_type, timestamp); + +-- 动物信息查询优化 +CREATE INDEX idx_animal_farm_status ON animals (farm_id, status, created_at); + +-- 预警查询优化 +CREATE INDEX idx_alert_farm_status ON alerts (farm_id, status, level, created_at); +``` + +### 4.2 分区策略 + +**时间分区：** +```sql +-- 传感器数据按月分区 +CREATE TABLE sensor_data ( + -- 字段定义... +) PARTITION BY RANGE (YEAR(created_at) * 100 + MONTH(created_at)) ( + PARTITION p202501 VALUES LESS THAN (202502), + PARTITION p202502 VALUES LESS THAN (202503), + -- 更多分区... +); +``` + +**哈希分区：** +```sql +-- 操作日志按用户ID哈希分区 +CREATE TABLE operation_logs ( + -- 字段定义... +) PARTITION BY HASH(user_id) PARTITIONS 8; +``` + +### 4.3 查询优化 + +**慢查询优化：** +- 启用慢查询日志 +- 定期分析慢查询 +- 优化查询语句和索引 + +**缓存策略：** +- Redis缓存热点数据 +- 查询结果缓存 +- 分布式缓存架构 + +## 5. 数据安全与备份 + +### 5.1 数据安全 + +**访问控制：** +- 数据库用户权限最小化 +- 应用层数据访问控制 +- 敏感数据加密存储 + +**数据加密：** +```sql +-- 密码字段加密 +password VARCHAR(255) NOT NULL COMMENT '密码（bcrypt加密）' + +-- 敏感信息加密存储 +phone VARCHAR(255) COMMENT '手机号（AES加密）' +``` + +### 5.2 备份策略 + +**全量备份：** +- 每日凌晨全量备份 +- 备份文件异地存储 +- 备份文件加密压缩 + +**增量备份：** +- 每小时增量备份 +- binlog备份和恢复 +- 实时数据同步 + +**备份验证：** +- 定期备份恢复测试 +- 备份文件完整性校验 +- 灾难恢复演练 + +## 6. 监控与维护 + +### 6.1 性能监控 + +**关键指标：** +- QPS（每秒查询数） +- 连接数和活跃连接 +- 慢查询统计 +- 表空间使用率 + +**监控工具：** +- MySQL Performance Schema +- Prometheus + Grafana +- 自定义监控脚本 + +### 6.2 维护策略 + +**定期维护：** +- 表结构优化 +- 索引重建和优化 +- 数据清理和归档 +- 统计信息更新 + +**容量规划：** +- 存储容量预测 +- 性能瓶颈分析 +- 扩容方案制定 + +## 7. 数据字典 + +### 7.1 枚举值定义 + +**用户状态 (user_status)：** +- active：激活 +- inactive：未激活 +- suspended：已暂停 + +**设备状态 (device_status)：** +- active：正常运行 +- inactive：离线 +- maintenance：维护中 + +**预警级别 (alert_level)：** +- low：低级 +- medium：中级 +- high：高级 +- critical：严重 + +**动物类型 (animal_type)：** +- 1：牛 +- 2：羊 +- 3：猪 +- 4：马 + +### 7.2 业务规则 + +**数据完整性规则：** +1. 动物必须关联到养殖场 +2. 设备必须关联到养殖场 +3. 传感器数据必须关联到设备 +4. 预警可以关联到设备或养殖场 + +**业务逻辑规则：** +1. 圈舍当前数量不能超过容量 +2. 动物转移需要记录转移记录 +3. 批次完成后不能再添加动物 +4. 电子围栏至少需要3个点 + +## 8. 版本升级与迁移 + +### 8.1 版本控制 + +**数据库版本管理：** +- 使用数据库迁移工具 +- 版本号管理和追踪 +- 回滚方案制定 + +**升级策略：** +- 灰度升级 +- 数据迁移验证 +- 业务连续性保障 + +### 8.2 数据迁移 + +**迁移工具：** +- 自定义迁移脚本 +- 数据同步工具 +- 数据验证工具 + +**迁移流程：** +1. 数据备份 +2. 结构升级 +3. 数据迁移 +4. 数据验证 +5. 业务切换 + +## 9. 附录 + +### 9.1 建表语句示例 + +```sql +-- 用户表 +CREATE TABLE users ( + id INT AUTO_INCREMENT PRIMARY KEY, + username VARCHAR(50) NOT NULL UNIQUE, + email VARCHAR(100) NOT NULL UNIQUE, + password VARCHAR(255) NOT NULL, + phone VARCHAR(20), + avatar VARCHAR(255), + roles INT DEFAULT 2, + status ENUM('active', 'inactive', 'suspended') DEFAULT 'active', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_roles (roles), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; + +-- 养殖场表 +CREATE TABLE farms ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(100) NOT NULL, + type VARCHAR(50) NOT NULL, + location JSON NOT NULL DEFAULT (JSON_OBJECT()), + address VARCHAR(255), + contact VARCHAR(50), + phone VARCHAR(20), + status ENUM('active', 'inactive', 'maintenance') DEFAULT 'active', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_name (name), + INDEX idx_type (type), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; +``` + +### 9.2 常用查询示例 + +```sql +-- 查询养殖场及其动物数量 +SELECT f.id, f.name, COUNT(a.id) as animal_count +FROM farms f +LEFT JOIN animals a ON f.id = a.farm_id AND a.status = 1 +WHERE f.status = 'active' +GROUP BY f.id, f.name; + +-- 查询最近24小时的预警统计 +SELECT alert_type, level, COUNT(*) as count +FROM alerts +WHERE created_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR) +GROUP BY alert_type, level +ORDER BY count DESC; + +-- 查询设备在线状态 +SELECT d.id, d.name, d.status, + CASE + WHEN d.last_heartbeat >= DATE_SUB(NOW(), INTERVAL 5 MINUTE) THEN 'online' + ELSE 'offline' + END as online_status +FROM devices d +WHERE d.status = 'active'; +``` + +--- + +**文档维护说明：** +本文档应随着系统功能的增加和数据库结构的变化及时更新。所有数据库结构变更都应该通过版本控制进行管理，确保开发、测试、生产环境的一致性。 \ No newline at end of file diff --git a/docs/architecture/系统架构文档.md b/docs/architecture/系统架构文档.md new file mode 100644 index 0000000..bfb0b4d --- /dev/null +++ b/docs/architecture/系统架构文档.md @@ -0,0 +1,1555 @@ +# 宁夏智慧养殖监管平台系统架构文档 + +## 版本历史 + +| 版本 | 日期 | 作者 | 描述 | +|------|------|------|------| +| v1.0 | 2025-01-18 | 架构师 | 初始版本 | +| v2.0 | 2025-01-19 | 架构师 | 全面重构，增加多端支持和微服务架构 | + +## 1. 架构概述 + +### 1.1 系统定位 + +宁夏智慧养殖监管平台是一个面向现代化养殖业的综合性数字化监管平台，采用分布式架构设计，支持多端应用，提供全方位的养殖监管、数据分析和业务服务功能。 + +### 1.2 设计原则 + +**可扩展性原则：** +- 采用模块化设计，支持功能模块独立扩展 +- 支持水平扩展，可根据业务需求增加服务器节点 +- 预留接口，支持第三方系统集成 + +**高可用性原则：** +- 采用负载均衡和故障转移机制 +- 数据库主从架构，确保数据安全 +- 服务降级和熔断机制，保证系统稳定性 + +**安全性原则：** +- 多层安全防护，包括网络、应用、数据层面 +- 身份认证和权限控制机制 +- 数据加密传输和存储 + +**性能优化原则：** +- 缓存机制提升响应速度 +- 数据库优化和索引设计 +- CDN加速静态资源访问 + +### 1.3 技术选型理由 + +**后端技术栈选择：** +- **Node.js**: 高并发处理能力，适合IoT数据处理 +- **Express.js**: 轻量级Web框架，开发效率高 +- **Sequelize**: 成熟的ORM框架，支持多种数据库 +- **MySQL**: 稳定可靠的关系型数据库，适合业务数据存储 +- **Redis**: 高性能缓存，提升系统响应速度 + +**前端技术栈选择：** +- **Vue 3**: 现代化前端框架，组件化开发 +- **Vite**: 快速构建工具，开发体验好 +- **Ant Design Vue**: 企业级UI组件库，界面美观 +- **ECharts**: 强大的数据可视化库 +- **Pinia**: 轻量级状态管理 + +## 2. 系统架构设计 + +### 2.1 整体架构图 + +```mermaid +graph TB + subgraph "用户层" + A[Web管理后台] + B[数据可视化大屏] + C[银行端小程序] + D[政府端小程序] + E[保险端小程序] + F[官方网站] + end + + subgraph "网关层" + G[Nginx负载均衡器] + H[API网关] + end + + subgraph "应用层" + I[认证服务] + J[养殖场管理服务] + K[设备监控服务] + L[数据分析服务] + M[消息通知服务] + N[文件管理服务] + end + + subgraph "数据层" + O[MySQL主库] + P[MySQL从库] + Q[Redis缓存] + R[文件存储OSS] + end + + subgraph "外部服务" + S[百度地图API] + T[短信服务] + U[邮件服务] + V[微信服务] + end + + A --> G + B --> G + C --> G + D --> G + E --> G + F --> G + + G --> H + H --> I + H --> J + H --> K + H --> L + H --> M + H --> N + + I --> O + J --> O + K --> O + L --> O + M --> Q + N --> R + + O --> P + + M --> S + M --> T + M --> U + M --> V +``` + +### 2.2 分层架构设计 + +#### 2.2.1 表现层 (Presentation Layer) + +**Web管理后台：** +- 基于Vue 3 + Ant Design Vue构建 +- 响应式设计，支持多种屏幕尺寸 +- 模块化组件设计，便于维护和扩展 +- 支持权限控制和角色管理 + +**数据可视化大屏：** +- 全屏展示模式，适配大屏显示设备 +- 实时数据更新，支持WebSocket连接 +- 丰富的图表展示，基于ECharts实现 +- 自适应布局，支持不同分辨率 + +**小程序矩阵：** +- 基于uni-app框架，一套代码多端运行 +- 针对不同业务场景定制化界面 +- 支持微信小程序生态集成 +- 离线数据缓存和同步机制 + +#### 2.2.2 网关层 (Gateway Layer) + +**负载均衡器 (Nginx)：** +- HTTP/HTTPS请求分发 +- 静态资源服务和缓存 +- SSL证书管理 +- 请求限流和防护 + +**API网关：** +- 统一API入口管理 +- 请求路由和转发 +- 身份认证和授权 +- API版本控制 +- 请求日志记录 + +#### 2.2.3 业务逻辑层 (Business Logic Layer) + +**认证服务 (Auth Service)：** +- JWT Token管理 +- 用户身份验证 +- 权限控制和角色管理 +- 单点登录(SSO)支持 +- 多因子认证(MFA) + +**养殖场管理服务 (Farm Service)：** +- 养殖场信息CRUD操作 +- 地理位置管理 +- 证件和资质管理 +- 审核流程管理 +- 统计数据计算 + +**设备监控服务 (Device Service)：** +- IoT设备连接管理 +- 实时数据采集和处理 +- 告警规则引擎 +- 设备状态监控 +- 历史数据存储 + +**数据分析服务 (Analytics Service)：** +- 数据统计和分析 +- 报表生成 +- 趋势分析 +- 数据导出 +- 自定义查询 + +**消息通知服务 (Notification Service)：** +- 多渠道消息推送 +- 消息模板管理 +- 消息队列处理 +- 推送状态跟踪 +- 消息历史记录 + +**文件管理服务 (File Service)：** +- 文件上传和下载 +- 图片处理和压缩 +- 文件权限控制 +- 云存储集成 +- 文件备份管理 + +#### 2.2.4 数据访问层 (Data Access Layer) + +**数据库访问：** +- Sequelize ORM框架 +- 数据库连接池管理 +- 事务处理 +- 数据验证和约束 +- 数据库迁移管理 + +**缓存访问：** +- Redis客户端封装 +- 缓存策略管理 +- 分布式锁实现 +- 会话存储 +- 热点数据缓存 + +#### 2.2.5 数据存储层 (Data Storage Layer) + +**关系型数据库 (MySQL)：** +- 主从复制架构 +- 读写分离 +- 数据备份和恢复 +- 性能监控和优化 +- 数据安全和加密 + +**缓存数据库 (Redis)：** +- 内存数据存储 +- 数据持久化 +- 集群模式支持 +- 高可用配置 +- 性能监控 + +**文件存储 (OSS)：** +- 云存储服务 +- CDN加速 +- 文件备份 +- 访问控制 +- 成本优化 + +## 3. 核心模块设计 + +### 3.1 用户认证与权限模块 + +#### 3.1.1 认证机制 + +**JWT Token认证：** +```javascript +// Token结构 +{ + "header": { + "alg": "HS256", + "typ": "JWT" + }, + "payload": { + "userId": 123, + "username": "admin", + "roles": ["admin", "farm_manager"], + "permissions": ["farm:read", "farm:write"], + "exp": 1642694400, + "iat": 1642608000 + } +} +``` + +**认证流程：** +1. 用户提交登录凭证 +2. 服务器验证用户身份 +3. 生成JWT Token并返回 +4. 客户端存储Token +5. 后续请求携带Token +6. 服务器验证Token有效性 + +#### 3.1.2 权限控制 + +**RBAC权限模型：** +- 用户(User) - 角色(Role) - 权限(Permission) +- 支持角色继承和权限组合 +- 细粒度权限控制 +- 动态权限分配 + +**权限验证中间件：** +```javascript +const authMiddleware = (requiredPermission) => { + return (req, res, next) => { + const token = req.headers.authorization; + const decoded = jwt.verify(token, secret); + + if (hasPermission(decoded.permissions, requiredPermission)) { + req.user = decoded; + next(); + } else { + res.status(403).json({ error: 'Insufficient permissions' }); + } + }; +}; +``` + +### 3.2 数据采集与处理模块 + +#### 3.2.1 IoT数据采集 + +**数据采集架构：** +```mermaid +graph LR + A[IoT设备] --> B[数据网关] + B --> C[消息队列] + C --> D[数据处理服务] + D --> E[数据存储] + D --> F[实时告警] +``` + +**数据格式规范：** +```json +{ + "deviceId": "DEVICE_001", + "farmId": "FARM_001", + "timestamp": "2025-01-19T10:00:00Z", + "data": { + "temperature": 25.5, + "humidity": 60.2, + "ammonia": 15.8, + "co2": 800 + }, + "location": { + "latitude": 38.4872, + "longitude": 106.2309 + } +} +``` + +#### 3.2.2 实时数据处理 + +**流处理架构：** +- 数据接收和验证 +- 数据清洗和转换 +- 实时计算和分析 +- 告警规则匹配 +- 数据存储和分发 + +**告警规则引擎：** +```javascript +const alertRules = [ + { + id: 'TEMP_HIGH', + condition: 'temperature > 30', + level: 'warning', + message: '温度过高告警' + }, + { + id: 'AMMONIA_CRITICAL', + condition: 'ammonia > 50', + level: 'critical', + message: '氨气浓度严重超标' + } +]; +``` + +### 3.3 数据可视化模块 + +#### 3.3.1 图表组件设计 + +**图表类型支持：** +- 折线图：趋势数据展示 +- 柱状图：对比数据展示 +- 饼图：占比数据展示 +- 散点图：相关性分析 +- 地图：地理分布展示 +- 仪表盘：实时指标展示 + +**图表配置示例：** +```javascript +const chartConfig = { + type: 'line', + title: '温度趋势图', + xAxis: { + type: 'time', + data: timestamps + }, + yAxis: { + type: 'value', + name: '温度(°C)' + }, + series: [{ + name: '温度', + type: 'line', + data: temperatureData, + smooth: true + }] +}; +``` + +#### 3.3.2 大屏展示设计 + +**布局设计：** +- 响应式网格布局 +- 组件拖拽和调整 +- 主题切换支持 +- 全屏展示模式 + +**数据更新机制：** +- WebSocket实时推送 +- 定时轮询更新 +- 增量数据更新 +- 异常处理和重连 + +## 4. 数据库设计 + +### 4.1 数据库架构 + +#### 4.1.1 主从架构 + +**主库配置：** +- 处理所有写操作 +- 实时数据同步到从库 +- 自动故障转移 +- 性能监控和优化 + +**从库配置：** +- 处理读操作 +- 负载均衡分发 +- 数据一致性保证 +- 备份和恢复 + +#### 4.1.2 分库分表策略 + +**垂直分库：** +- 用户管理库 +- 养殖业务库 +- 设备数据库 +- 日志分析库 + +**水平分表：** +- 按时间分表：传感器数据表 +- 按地区分表：养殖场数据表 +- 按用户分表：操作日志表 + +### 4.2 核心数据表设计 + +#### 4.2.1 用户相关表 + +**用户表 (users)：** +```sql +CREATE TABLE users ( + id INT PRIMARY KEY AUTO_INCREMENT, + username VARCHAR(50) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + email VARCHAR(100), + phone VARCHAR(20), + real_name VARCHAR(50), + avatar_url VARCHAR(255), + status ENUM('active', 'inactive', 'banned') DEFAULT 'active', + last_login_at TIMESTAMP, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_username (username), + INDEX idx_email (email), + INDEX idx_phone (phone) +); +``` + +**角色表 (roles)：** +```sql +CREATE TABLE roles ( + id INT PRIMARY KEY AUTO_INCREMENT, + name VARCHAR(50) UNIQUE NOT NULL, + display_name VARCHAR(100), + description TEXT, + permissions JSON, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP +); +``` + +#### 4.2.2 业务相关表 + +**养殖场表 (farms)：** +```sql +CREATE TABLE farms ( + id INT PRIMARY KEY AUTO_INCREMENT, + name VARCHAR(100) NOT NULL, + code VARCHAR(50) UNIQUE, + type VARCHAR(50), + scale ENUM('small', 'medium', 'large'), + address VARCHAR(200), + latitude DECIMAL(10,8), + longitude DECIMAL(11,8), + contact_person VARCHAR(50), + contact_phone VARCHAR(20), + license_number VARCHAR(100), + status ENUM('active', 'inactive', 'pending') DEFAULT 'pending', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_code (code), + INDEX idx_location (latitude, longitude), + INDEX idx_status (status) +); +``` + +**设备表 (devices)：** +```sql +CREATE TABLE devices ( + id INT PRIMARY KEY AUTO_INCREMENT, + farm_id INT NOT NULL, + device_id VARCHAR(100) UNIQUE NOT NULL, + device_name VARCHAR(100), + device_type VARCHAR(50), + model VARCHAR(50), + manufacturer VARCHAR(100), + location VARCHAR(100), + install_date DATE, + status ENUM('online', 'offline', 'maintenance') DEFAULT 'offline', + last_online_at TIMESTAMP, + config JSON, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + FOREIGN KEY (farm_id) REFERENCES farms(id), + INDEX idx_farm_id (farm_id), + INDEX idx_device_id (device_id), + INDEX idx_status (status) +); +``` + +#### 4.2.3 数据相关表 + +**传感器数据表 (sensor_data)：** +```sql +CREATE TABLE sensor_data ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + device_id VARCHAR(100) NOT NULL, + farm_id INT NOT NULL, + data_type VARCHAR(50), + value DECIMAL(10,4), + unit VARCHAR(20), + timestamp TIMESTAMP NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + INDEX idx_device_timestamp (device_id, timestamp), + INDEX idx_farm_timestamp (farm_id, timestamp), + INDEX idx_type_timestamp (data_type, timestamp) +) PARTITION BY RANGE (UNIX_TIMESTAMP(timestamp)) ( + PARTITION p202501 VALUES LESS THAN (UNIX_TIMESTAMP('2025-02-01')), + PARTITION p202502 VALUES LESS THAN (UNIX_TIMESTAMP('2025-03-01')), + PARTITION p202503 VALUES LESS THAN (UNIX_TIMESTAMP('2025-04-01')) +); +``` + +### 4.3 数据库优化策略 + +#### 4.3.1 索引优化 + +**索引设计原则：** +- 为查询频繁的字段创建索引 +- 复合索引遵循最左前缀原则 +- 避免过多索引影响写性能 +- 定期分析索引使用情况 + +**索引监控：** +```sql +-- 查看索引使用情况 +SELECT + table_name, + index_name, + cardinality, + non_unique +FROM information_schema.statistics +WHERE table_schema = 'nxxmdata'; + +-- 查看慢查询 +SELECT + query_time, + lock_time, + rows_sent, + rows_examined, + sql_text +FROM mysql.slow_log +ORDER BY query_time DESC +LIMIT 10; +``` + +#### 4.3.2 查询优化 + +**查询优化技巧：** +- 使用EXPLAIN分析查询计划 +- 避免SELECT *，只查询需要的字段 +- 合理使用JOIN和子查询 +- 利用缓存减少数据库访问 + +**分页查询优化：** +```sql +-- 传统分页（性能差） +SELECT * FROM sensor_data +ORDER BY timestamp DESC +LIMIT 1000, 20; + +-- 优化后分页（性能好） +SELECT * FROM sensor_data +WHERE id < last_id +ORDER BY id DESC +LIMIT 20; +``` + +## 5. 缓存架构设计 + +### 5.1 缓存策略 + +#### 5.1.1 多级缓存架构 + +```mermaid +graph TB + A[客户端] --> B[CDN缓存] + B --> C[Nginx缓存] + C --> D[应用缓存] + D --> E[Redis缓存] + E --> F[数据库] +``` + +**缓存层级说明：** +- **CDN缓存**: 静态资源缓存，就近访问 +- **Nginx缓存**: 反向代理缓存，减少后端压力 +- **应用缓存**: 内存缓存，提升响应速度 +- **Redis缓存**: 分布式缓存，数据共享 + +#### 5.1.2 缓存模式 + +**Cache-Aside模式：** +```javascript +async function getFarmData(farmId) { + // 1. 先查缓存 + let data = await redis.get(`farm:${farmId}`); + + if (data) { + return JSON.parse(data); + } + + // 2. 缓存未命中，查数据库 + data = await Farm.findById(farmId); + + // 3. 写入缓存 + await redis.setex(`farm:${farmId}`, 3600, JSON.stringify(data)); + + return data; +} +``` + +**Write-Through模式：** +```javascript +async function updateFarmData(farmId, updateData) { + // 1. 更新数据库 + const data = await Farm.update(updateData, { where: { id: farmId } }); + + // 2. 同时更新缓存 + await redis.setex(`farm:${farmId}`, 3600, JSON.stringify(data)); + + return data; +} +``` + +### 5.2 缓存设计 + +#### 5.2.1 缓存键设计 + +**命名规范：** +``` +业务模块:实体类型:标识符[:附加信息] + +示例： +- user:profile:123 +- farm:info:456 +- device:status:789 +- stats:daily:2025-01-19 +``` + +**过期策略：** +- 用户会话：24小时 +- 基础数据：1小时 +- 统计数据：30分钟 +- 实时数据：5分钟 + +#### 5.2.2 缓存更新策略 + +**主动更新：** +- 数据变更时立即更新缓存 +- 定时任务批量更新 +- 版本号控制缓存一致性 + +**被动更新：** +- 缓存过期自动失效 +- LRU算法淘汰冷数据 +- 内存不足时清理缓存 + +## 6. 消息队列设计 + +### 6.1 消息队列架构 + +#### 6.1.1 队列类型 + +**实时数据队列：** +- 处理IoT设备数据 +- 高吞吐量，低延迟 +- 数据持久化保证 + +**告警通知队列：** +- 处理系统告警 +- 优先级队列 +- 失败重试机制 + +**异步任务队列：** +- 处理耗时任务 +- 任务调度和监控 +- 结果回调通知 + +#### 6.1.2 消息格式 + +**标准消息格式：** +```json +{ + "messageId": "msg_123456", + "type": "sensor_data", + "priority": "normal", + "timestamp": "2025-01-19T10:00:00Z", + "source": "device_001", + "target": "data_processor", + "payload": { + "deviceId": "device_001", + "data": { + "temperature": 25.5, + "humidity": 60.2 + } + }, + "metadata": { + "retryCount": 0, + "maxRetries": 3, + "ttl": 3600 + } +} +``` + +### 6.2 消息处理 + +#### 6.2.1 生产者设计 + +```javascript +class MessageProducer { + constructor(queueName) { + this.queueName = queueName; + this.connection = createConnection(); + } + + async sendMessage(message) { + const messageWithId = { + ...message, + messageId: generateId(), + timestamp: new Date().toISOString() + }; + + await this.connection.publish( + this.queueName, + JSON.stringify(messageWithId) + ); + } +} +``` + +#### 6.2.2 消费者设计 + +```javascript +class MessageConsumer { + constructor(queueName, handler) { + this.queueName = queueName; + this.handler = handler; + this.connection = createConnection(); + } + + async startConsuming() { + await this.connection.consume(this.queueName, async (message) => { + try { + const data = JSON.parse(message.content); + await this.handler(data); + this.connection.ack(message); + } catch (error) { + console.error('Message processing failed:', error); + this.connection.nack(message, false, true); + } + }); + } +} +``` + +## 7. 安全架构设计 + +### 7.1 安全防护体系 + +#### 7.1.1 网络安全 + +**防火墙配置：** +- 端口访问控制 +- IP白名单机制 +- DDoS攻击防护 +- 流量监控和分析 + +**SSL/TLS加密：** +- HTTPS强制跳转 +- 证书自动更新 +- 加密算法升级 +- 安全头配置 + +#### 7.1.2 应用安全 + +**输入验证：** +```javascript +const validateInput = (schema) => { + return (req, res, next) => { + const { error } = schema.validate(req.body); + if (error) { + return res.status(400).json({ + error: 'Validation failed', + details: error.details + }); + } + next(); + }; +}; +``` + +**SQL注入防护：** +```javascript +// 使用参数化查询 +const getUserById = async (userId) => { + return await User.findOne({ + where: { id: userId } // Sequelize自动转义 + }); +}; +``` + +**XSS防护：** +```javascript +const helmet = require('helmet'); +app.use(helmet({ + contentSecurityPolicy: { + directives: { + defaultSrc: ["'self'"], + scriptSrc: ["'self'", "'unsafe-inline'"], + styleSrc: ["'self'", "'unsafe-inline'"] + } + } +})); +``` + +### 7.2 数据安全 + +#### 7.2.1 数据加密 + +**敏感数据加密：** +```javascript +const crypto = require('crypto'); + +class DataEncryption { + constructor(key) { + this.key = key; + this.algorithm = 'aes-256-gcm'; + } + + encrypt(text) { + const iv = crypto.randomBytes(16); + const cipher = crypto.createCipher(this.algorithm, this.key, iv); + + let encrypted = cipher.update(text, 'utf8', 'hex'); + encrypted += cipher.final('hex'); + + const authTag = cipher.getAuthTag(); + + return { + encrypted, + iv: iv.toString('hex'), + authTag: authTag.toString('hex') + }; + } + + decrypt(encryptedData) { + const decipher = crypto.createDecipher( + this.algorithm, + this.key, + Buffer.from(encryptedData.iv, 'hex') + ); + + decipher.setAuthTag(Buffer.from(encryptedData.authTag, 'hex')); + + let decrypted = decipher.update(encryptedData.encrypted, 'hex', 'utf8'); + decrypted += decipher.final('utf8'); + + return decrypted; + } +} +``` + +#### 7.2.2 访问控制 + +**权限矩阵：** +| 角色 | 养殖场管理 | 设备监控 | 数据分析 | 用户管理 | +|------|------------|----------|----------|----------| +| 系统管理员 | ✓ | ✓ | ✓ | ✓ | +| 监管人员 | ✓ | ✓ | ✓ | ✗ | +| 养殖场管理员 | ✓ | ✓ | ✓ | ✗ | +| 养殖场员工 | ✓ | ✓ | ✗ | ✗ | + +**数据脱敏：** +```javascript +const maskSensitiveData = (data, userRole) => { + if (userRole !== 'admin') { + // 脱敏处理 + data.phone = data.phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'); + data.idCard = data.idCard.replace(/(\d{6})\d{8}(\d{4})/, '$1********$2'); + } + return data; +}; +``` + +## 8. 监控与运维 + +### 8.1 系统监控 + +#### 8.1.1 监控指标 + +**系统指标：** +- CPU使用率 +- 内存使用率 +- 磁盘I/O +- 网络流量 +- 进程状态 + +**应用指标：** +- 请求响应时间 +- 错误率 +- 吞吐量 +- 并发用户数 +- 队列长度 + +**业务指标：** +- 用户活跃度 +- 功能使用率 +- 数据准确性 +- 告警处理时间 + +#### 8.1.2 监控实现 + +**Prometheus配置：** +```yaml +global: + scrape_interval: 15s + evaluation_interval: 15s + +scrape_configs: + - job_name: 'node-exporter' + static_configs: + - targets: ['localhost:9100'] + + - job_name: 'mysql-exporter' + static_configs: + - targets: ['localhost:9104'] + + - job_name: 'redis-exporter' + static_configs: + - targets: ['localhost:9121'] +``` + +**Grafana仪表盘：** +- 系统资源监控 +- 应用性能监控 +- 业务数据监控 +- 告警状态监控 + +### 8.2 日志管理 + +#### 8.2.1 日志分类 + +**应用日志：** +- 访问日志 +- 错误日志 +- 业务日志 +- 调试日志 + +**系统日志：** +- 系统事件日志 +- 安全日志 +- 性能日志 +- 审计日志 + +#### 8.2.2 日志格式 + +**结构化日志格式：** +```json +{ + "timestamp": "2025-01-19T10:00:00Z", + "level": "INFO", + "service": "farm-service", + "traceId": "trace_123456", + "userId": "user_789", + "action": "create_farm", + "message": "Farm created successfully", + "data": { + "farmId": "farm_001", + "farmName": "示例养殖场" + }, + "duration": 150, + "ip": "192.168.1.100", + "userAgent": "Mozilla/5.0..." +} +``` + +### 8.3 备份与恢复 + +#### 8.3.1 备份策略 + +**数据库备份：** +- 全量备份：每日凌晨执行 +- 增量备份：每小时执行 +- 二进制日志备份：实时备份 +- 异地备份：每周同步 + +**文件备份：** +- 应用代码备份 +- 配置文件备份 +- 日志文件备份 +- 用户上传文件备份 + +#### 8.3.2 恢复流程 + +**数据恢复步骤：** +1. 评估故障范围和影响 +2. 选择合适的备份点 +3. 停止相关服务 +4. 执行数据恢复 +5. 验证数据完整性 +6. 重启服务并测试 +7. 通知相关人员 + +## 9. 性能优化 + +### 9.1 前端性能优化 + +#### 9.1.1 资源优化 + +**代码分割：** +```javascript +// 路由懒加载 +const routes = [ + { + path: '/farm', + component: () => import('@/views/Farm.vue') + }, + { + path: '/device', + component: () => import('@/views/Device.vue') + } +]; +``` + +**资源压缩：** +```javascript +// Vite配置 +export default defineConfig({ + build: { + rollupOptions: { + output: { + manualChunks: { + vendor: ['vue', 'vue-router', 'pinia'], + antd: ['ant-design-vue'], + charts: ['echarts'] + } + } + }, + minify: 'terser', + terserOptions: { + compress: { + drop_console: true, + drop_debugger: true + } + } + } +}); +``` + +#### 9.1.2 渲染优化 + +**虚拟滚动：** +```vue + +``` + +**图片懒加载：** +```vue + +``` + +### 9.2 后端性能优化 + +#### 9.2.1 数据库优化 + +**连接池配置：** +```javascript +const sequelize = new Sequelize(database, username, password, { + host: 'localhost', + dialect: 'mysql', + pool: { + max: 20, // 最大连接数 + min: 5, // 最小连接数 + acquire: 30000, // 获取连接超时时间 + idle: 10000 // 连接空闲时间 + } +}); +``` + +**查询优化：** +```javascript +// 使用索引优化查询 +const farms = await Farm.findAll({ + where: { + status: 'active', + createdAt: { + [Op.gte]: startDate, + [Op.lte]: endDate + } + }, + include: [{ + model: Device, + where: { status: 'online' }, + required: false + }], + order: [['createdAt', 'DESC']], + limit: 20, + offset: page * 20 +}); +``` + +#### 9.2.2 缓存优化 + +**多级缓存：** +```javascript +class CacheManager { + constructor() { + this.l1Cache = new Map(); // 内存缓存 + this.l2Cache = redis; // Redis缓存 + } + + async get(key) { + // L1缓存查找 + if (this.l1Cache.has(key)) { + return this.l1Cache.get(key); + } + + // L2缓存查找 + const value = await this.l2Cache.get(key); + if (value) { + this.l1Cache.set(key, value); + return value; + } + + return null; + } + + async set(key, value, ttl = 3600) { + this.l1Cache.set(key, value); + await this.l2Cache.setex(key, ttl, value); + } +} +``` + +## 10. 扩展性设计 + +### 10.1 微服务架构演进 + +#### 10.1.1 服务拆分策略 + +**按业务领域拆分：** +- 用户服务 (User Service) +- 养殖场服务 (Farm Service) +- 设备服务 (Device Service) +- 数据分析服务 (Analytics Service) +- 通知服务 (Notification Service) + +**服务边界定义：** +```mermaid +graph TB + subgraph "用户域" + A[用户服务] + B[认证服务] + end + + subgraph "业务域" + C[养殖场服务] + D[动物管理服务] + end + + subgraph "设备域" + E[设备管理服务] + F[数据采集服务] + end + + subgraph "分析域" + G[数据分析服务] + H[报表服务] + end +``` + +#### 10.1.2 服务通信 + +**同步通信 (HTTP/REST)：** +```javascript +// 服务间调用 +class FarmService { + async getFarmDevices(farmId) { + const response = await axios.get( + `${DEVICE_SERVICE_URL}/devices?farmId=${farmId}` + ); + return response.data; + } +} +``` + +**异步通信 (消息队列)：** +```javascript +// 事件发布 +class FarmService { + async createFarm(farmData) { + const farm = await Farm.create(farmData); + + // 发布农场创建事件 + await eventBus.publish('farm.created', { + farmId: farm.id, + farmName: farm.name, + timestamp: new Date() + }); + + return farm; + } +} + +// 事件订阅 +class NotificationService { + constructor() { + eventBus.subscribe('farm.created', this.handleFarmCreated.bind(this)); + } + + async handleFarmCreated(event) { + // 发送欢迎通知 + await this.sendWelcomeNotification(event.farmId); + } +} +``` + +### 10.2 容器化部署 + +#### 10.2.1 Docker配置 + +**应用Dockerfile：** +```dockerfile +FROM node:16-alpine + +WORKDIR /app + +# 复制依赖文件 +COPY package*.json ./ +RUN npm ci --only=production + +# 复制应用代码 +COPY . . + +# 创建非root用户 +RUN addgroup -g 1001 -S nodejs +RUN adduser -S nodejs -u 1001 + +USER nodejs + +EXPOSE 3000 + +CMD ["npm", "start"] +``` + +**Docker Compose配置：** +```yaml +version: '3.8' + +services: + app: + build: . + ports: + - "3000:3000" + environment: + - NODE_ENV=production + - DB_HOST=mysql + - REDIS_HOST=redis + depends_on: + - mysql + - redis + restart: unless-stopped + + mysql: + image: mysql:8.0 + environment: + - MYSQL_ROOT_PASSWORD=rootpassword + - MYSQL_DATABASE=nxxmdata + volumes: + - mysql_data:/var/lib/mysql + restart: unless-stopped + + redis: + image: redis:6-alpine + volumes: + - redis_data:/data + restart: unless-stopped + + nginx: + image: nginx:alpine + ports: + - "80:80" + - "443:443" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf + - ./ssl:/etc/nginx/ssl + depends_on: + - app + restart: unless-stopped + +volumes: + mysql_data: + redis_data: +``` + +#### 10.2.2 Kubernetes部署 + +**应用部署配置：** +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nxxmdata-app +spec: + replicas: 3 + selector: + matchLabels: + app: nxxmdata-app + template: + metadata: + labels: + app: nxxmdata-app + spec: + containers: + - name: app + image: nxxmdata:latest + ports: + - containerPort: 3000 + env: + - name: NODE_ENV + value: "production" + - name: DB_HOST + value: "mysql-service" + resources: + requests: + memory: "256Mi" + cpu: "250m" + limits: + memory: "512Mi" + cpu: "500m" + livenessProbe: + httpGet: + path: /health + port: 3000 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /ready + port: 3000 + initialDelaySeconds: 5 + periodSeconds: 5 +``` + +## 11. 技术债务管理 + +### 11.1 代码质量 + +#### 11.1.1 代码规范 + +**ESLint配置：** +```json +{ + "extends": [ + "eslint:recommended", + "@vue/typescript/recommended" + ], + "rules": { + "no-console": "warn", + "no-debugger": "error", + "prefer-const": "error", + "no-var": "error" + } +} +``` + +**代码审查流程：** +1. 开发人员提交PR +2. 自动化测试执行 +3. 代码质量检查 +4. 同行代码审查 +5. 技术负责人审批 +6. 合并到主分支 + +#### 11.1.2 技术债务识别 + +**债务类型：** +- 代码重复 +- 复杂度过高 +- 测试覆盖率不足 +- 文档缺失 +- 性能问题 + +**债务评估：** +```javascript +// 使用SonarQube进行代码质量分析 +const qualityGate = { + coverage: '>= 80%', + duplicatedLines: '<= 3%', + maintainabilityRating: 'A', + reliabilityRating: 'A', + securityRating: 'A' +}; +``` + +### 11.2 重构策略 + +#### 11.2.1 渐进式重构 + +**重构原则：** +- 小步快跑，频繁重构 +- 保持功能不变 +- 增加测试覆盖 +- 文档同步更新 + +**重构计划：** +1. 识别重构目标 +2. 编写测试用例 +3. 小范围重构 +4. 验证功能正确性 +5. 部署到测试环境 +6. 生产环境发布 + +## 12. 未来规划 + +### 12.1 技术演进路线 + +#### 12.1.1 短期规划 (6个月内) + +**技术优化：** +- 完善监控体系 +- 优化数据库性能 +- 增强安全防护 +- 提升系统稳定性 + +**功能扩展：** +- 移动端APP开发 +- 数据分析增强 +- 第三方系统集成 +- 用户体验优化 + +#### 12.1.2 中期规划 (1年内) + +**架构升级：** +- 微服务架构改造 +- 容器化部署 +- 云原生架构 +- DevOps流程完善 + +**技术创新：** +- 人工智能集成 +- 物联网平台扩展 +- 区块链溯源 +- 边缘计算应用 + +#### 12.1.3 长期规划 (2-3年) + +**平台化发展：** +- 开放API平台 +- 生态系统建设 +- 行业标准制定 +- 国际化扩展 + +**技术前沿：** +- 5G网络应用 +- 数字孪生技术 +- 量子计算探索 +- 绿色计算实践 + +### 12.2 风险评估 + +#### 12.2.1 技术风险 + +**风险识别：** +- 技术栈过时风险 +- 第三方依赖风险 +- 安全漏洞风险 +- 性能瓶颈风险 + +**应对措施：** +- 定期技术评估 +- 依赖版本管理 +- 安全扫描机制 +- 性能监控预警 + +#### 12.2.2 业务风险 + +**风险识别：** +- 需求变更风险 +- 竞争对手风险 +- 政策法规风险 +- 市场环境风险 + +**应对措施：** +- 敏捷开发模式 +- 差异化竞争 +- 合规性保证 +- 市场调研分析 + +--- + +**文档维护说明：** +- 本文档将根据技术发展和业务需求定期更新 +- 架构变更需经过技术委员会评审 +- 重大架构调整需要影响评估和风险分析 +- 相关技术人员需及时同步架构变更 + +*最后更新时间：2025-01-19* +*文档版本：v2.0* +*维护人员：架构师* \ No newline at end of file diff --git a/docs/config/design.md b/docs/architecture/系统详细设计文档.md similarity index 100% rename from docs/config/design.md rename to docs/architecture/系统详细设计文档.md diff --git a/docs/config/PRD.md b/docs/config/PRD.md deleted file mode 100644 index aa2e61b..0000000 --- a/docs/config/PRD.md +++ /dev/null @@ -1,340 +0,0 @@ -# 宁夏智慧养殖监管平台产品需求文档 - -## 版本历史 -| 版本 | 日期 | 作者 | 描述 | -|------|------|------|------| -| 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/docs/config/arch.md b/docs/config/arch.md deleted file mode 100644 index 72e3490..0000000 --- a/docs/config/arch.md +++ /dev/null @@ -1,423 +0,0 @@ -# 项目架构文档 - -## 1. 项目概述 -本项目是**宁夏智慧养殖监管平台**，一个现代化的农场管理系统，包含以下核心功能： -- **农场设备监控**: 实时监控农场设备状态和运行数据 -- **动物健康管理**: 跟踪和管理动物健康状况 -- **地图可视化**: 基于百度地图的农场地理信息展示 -- **数据分析与可视化**: 提供丰富的图表和统计分析 -- **用户权限管理**: 基于角色的用户认证和授权系统 -- **订单管理**: 产品销售和订单处理功能 -- **预警管理**: 实时告警监控和预警处理 -- **性能监控**: 实时系统性能监控和分析 - -## 2. 目录结构 -### 2.1 后端 (`backend/`) -- `config/`: 配置文件 - - `database.js`: MySQL数据库连接配置 - - `database-pool.js`: 数据库连接池管理 - - `performance-config.js`: 性能监控配置 - - `swagger.js`: API文档配置 -- `controllers/`: 业务逻辑控制器 - - `farmController.js`: 农场管理 - - `animalController.js`: 动物管理 - - `deviceController.js`: 设备管理 - - `alertController.js`: 告警管理 - - `statsController.js`: 统计分析 - - `mapController.js`: 地图服务 - - `userController.js`: 用户管理 - - `productController.js`: 产品管理 - - `orderController.js`: 订单管理 -- `models/`: 数据模型定义（Sequelize ORM） - - `Farm.js`: 农场模型 - - `Animal.js`: 动物模型 - - `Device.js`: 设备模型 - - `Alert.js`: 告警模型 - - `User.js`: 用户模型 - - `Role.js`: 角色模型 - - `Product.js`: 产品模型 - - `Order.js`: 订单模型 - - `OrderItem.js`: 订单项模型 - - `UserRole.js`: 用户角色关联模型 - - `SensorData.js`: 传感器数据模型 - - `BaseModel.js`: 基础模型 - - `index.js`: 模型入口文件 -- `routes/`: API路由定义 - - `auth.js`: 认证路由 - - `users.js`: 用户管理路由 - - `products.js`: 产品管理路由 - - `orders.js`: 订单管理路由 - - `farms.js`: 农场管理路由 - - `animals.js`: 动物管理路由 - - `devices.js`: 设备管理路由 - - `alerts.js`: 告警管理路由 - - `stats.js`: 统计分析路由 - - `map.js`: 地图服务路由 - - `performance-routes.js`: 性能监控路由 -- `middleware/`: 中间件 - - `auth.js`: 认证中间件 - - `performance-middleware.js`: 性能监控中间件 -- `utils/`: 工具类 - - `logger.js`: 日志工具 - - `performance-monitor.js`: 性能监控 - - `db-monitor.js`: 数据库监控 - - `query-optimizer.js`: 查询优化器 -- `migrations/`: 数据库迁移文件 -- `seeds/`: 种子数据文件 -- `logs/`: 日志文件目录 - -### 2.2 管理后台 (`admin-system/`) -- `frontend/`: 管理后台前端项目 - - `src/components/`: 可复用的UI组件 - - `BaiduMap.vue`: 百度地图组件 - - `EChart.vue`: 图表组件 - - `Menu.vue`: 导航菜单 - - `Dashboard.vue`: 仪表盘组件 - - `AlertStats.vue`: 告警统计组件 - - `AnimalStats.vue`: 动物统计组件 - - `DeviceStats.vue`: 设备统计组件 - - `FarmDetail.vue`: 农场详情组件 - - `MonitorChart.vue`: 监控图表组件 - - `ChartPerformanceMonitor.vue`: 性能监控图表 - - `VirtualScrollChart.vue`: 虚拟滚动图表 - - `src/views/`: 页面级组件 - - `Home.vue`: 首页 - - `Dashboard.vue`: 系统概览 - - `MapView.vue`: 地图监控 - - `Analytics.vue`: 数据分析 - - `Monitor.vue`: 实时监控 - - `Login.vue`: 登录页面 - - `Users.vue`: 用户管理 - - `Products.vue`: 产品管理 - - `Orders.vue`: 订单管理 - - `Devices.vue`: 设备管理 - - `Animals.vue`: 动物管理 - - `Alerts.vue`: 预警管理 - - `TestAnalytics.vue`: 测试分析页面 - - `MapZoomDemo.vue`: 地图缩放演示 - - `NotFound.vue`: 404页面 - - `src/stores/`: 状态管理（Pinia） - - `user.js`: 用户状态管理 - - `data.js`: 数据状态管理 - - `settings.js`: 设置状态管理 - - `index.js`: 状态管理入口 - - `src/router/`: 路由配置 - - `index.js`: 路由实例和守卫 - - `routes.js`: 路由定义 - - `src/utils/`: 工具类（API调用、图表服务等） - - `api.js`: API请求封装 - - `src/config/`: 配置文件 - - `public/`: 静态资源和测试页面 - - `debug-devices.html`: 设备调试页面 - - `debug-users.html`: 用户调试页面 - - `map-test.html`: 地图测试页面 - - `test-auto-login.html`: 自动登录测试 - - `test-users-display.html`: 用户显示测试 - -### 2.3 官网 (`website/`) -- `data-screen/`: 官网前端项目 - - 包含官网展示页面和数据大屏功能 - -### 2.4 微信小程序 (`mini_program/`) -- `farm-monitor-dashboard/`: 微信小程序项目 - - 包含移动端监控仪表盘功能 - -### 2.5 脚本目录 (`scripts/`) -- `init-db.js`: 数据库初始化 -- `migration-manager.js`: 迁移管理 -- `seed-manager.js`: 种子数据管理 -- `test-connection.js`: 连接测试 -- `test-map-api.js`: 地图API测试 - -### 2.6 文档目录 (`docs/`) -- `API.md`: API 文档 -- `DEPLOYMENT.md`: 部署指南 -- `DEVELOPMENT.md`: 开发指南 -- `TROUBLESHOOTING.md`: 故障排除 -- `CHANGELOG.md`: 更新日志 -- `CONTRIBUTING.md`: 贡献指南 -- `SECURITY.md`: 安全指南 -- `PRD.md`: 产品需求文档 -- `baidu-map-license.md`: 百度地图许可文档 -- `performance-monitoring.md`: 性能监控文档 -- `FINAL_STRUCTURE_REPORT.md`: 项目结构报告 -- `PROJECT_CLEANUP_REPORT.md`: 项目清理报告 -- `arch.md`: 架构文档 -- `design.md`: 详细设计 -- `schema.sql`: 数据库架构脚本 -- `create_tables.sql`: 数据库表创建脚本 - -### 2.7 测试目录 (`test/`) -- `performance-monitor-test.js`: 性能监控测试 - -### 2.8 其他文件 -- `examples/`: 示例代码 - - `performance-monitor-integration.js`: 性能监控集成示例 -- `create_tables.sql`: 数据库表创建脚本 -- `schema.sql`: 数据库架构脚本 -- `design.md`: 详细设计文档 -- `dev-plan.md`: 开发计划文档 -- `task.md`: 任务列表文档 - -## 3. 模块划分 -### 3.1 后端模块 -- **农场管理模块**: 农场信息管理、地理位置管理 -- **设备管理模块**: 监控农场设备状态、设备数据采集 -- **动物管理模块**: 跟踪动物健康数据、动物档案管理 -- **告警管理模块**: 系统告警处理、告警规则配置 -- **用户管理模块**: 用户认证、角色权限管理 -- **订单管理模块**: 产品销售、订单处理流程 -- **统计分析模块**: 数据统计、报表生成 -- **地图服务模块**: 地理信息服务、位置数据处理 -- **性能监控模块**: 系统性能监控、API性能分析 - -### 3.2 前端模块 -- **首页模块**: 系统入口、快速导航 -- **仪表盘模块**: 关键指标展示、数据概览 -- **地图模块**: 基于百度地图的可视化展示、地图缩放演示 -- **数据分析模块**: 图表展示、数据分析工具、测试分析功能 -- **实时监控模块**: 实时数据监控、告警展示、性能监控图表 -- **用户管理模块**: 用户信息管理、权限配置 -- **产品管理模块**: 产品信息维护、库存管理 -- **订单管理模块**: 订单处理、订单状态跟踪 -- **设备管理模块**: 设备状态监控、设备信息管理 -- **动物管理模块**: 动物健康档案、动物信息管理 -- **预警管理模块**: 告警规则配置、预警信息处理 -- **认证模块**: 用户登录、权限验证、自动登录 - -## 4. 核心架构 -### 4.1 技术栈 -**后端技术栈:** -- **运行环境**: Node.js 18.0+ -- **Web框架**: Express.js 4.18+ -- **API风格**: RESTful API -- **ORM框架**: Sequelize 6.30+ -- **数据库**: MySQL 8.0+ (mysql2 3.0+) -- **认证授权**: JWT (jsonwebtoken 9.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 - -**前端技术栈:** -- **框架**: Vue.js 3.4+ -- **构建工具**: Vite 5.0+ -- **路由管理**: Vue Router 4.0+ -- **状态管理**: Pinia 2.0+ -- **UI组件库**: Ant Design Vue 4.0+ -- **图表库**: 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代理到后端服务器 - -**数据库设计:** -- **主数据库**: MySQL (生产环境) -- **连接池**: 数据库连接池管理 -- **字符集**: UTF8MB4 -- **时区**: +08:00 (北京时间) - -### 4.2 数据流架构 -1. **前端请求流程**: - - 用户操作 → Vue组件 → Pinia状态管理 → API调用 -2. **后端处理流程**: - - API路由 → 中间件验证 → 控制器处理 → 模型操作 → 数据库 -3. **响应返回流程**: - - 数据库结果 → 模型封装 → 控制器响应 → 前端状态更新 → UI渲染 -4. **实时数据流**: - - 设备数据采集 → 后端处理 → 数据库存储 → 前端轮询/推送更新 - -## 5. 数据模型关系 -### 5.1 核心实体关系 -- **Farm (农场)** ← 一对多 → **Animal (动物)** -- **Farm (农场)** ← 一对多 → **Device (设备)** -- **Farm (农场)** ← 一对多 → **Alert (告警)** -- **Device (设备)** ← 一对多 → **Alert (告警)** -- **User (用户)** ← 多对多 → **Role (角色)** (通过UserRole中间表) -- **User (用户)** ← 一对多 → **Order (订单)** -- **Order (订单)** ← 一对多 → **OrderItem (订单项)** -- **Product (产品)** ← 一对多 → **OrderItem (订单项)** - -### 5.2 数据库约束 -- **外键约束**: 确保数据完整性 -- **级联删除**: Farm删除时级联删除相关Animal、Device、Alert -- **级联更新**: 主键更新时自动更新外键 -- **限制删除**: Product被OrderItem引用时限制删除 - -## 6. API设计规范 -### 6.1 RESTful API结构 -``` -/api/farms - 农场管理 -/api/animals - 动物管理 -/api/devices - 设备管理 -/api/alerts - 告警管理 -/api/users - 用户管理 -/api/products - 产品管理 -/api/orders - 订单管理 -/api/stats - 统计数据 -/api/map - 地图服务 -/api/auth - 认证服务 -``` - -### 6.2 响应格式标准 -```json -{ - "success": true, - "data": {}, - "message": "操作成功", - "timestamp": "2025-01-18T10:30:00Z" -} -``` - -## 7. 安全架构 -### 7.1 认证与授权 -- **JWT Token**: 无状态身份验证 -- **角色权限**: 基于RBAC的权限控制 -- **路由守卫**: 前端路由级别的权限验证 -- **API中间件**: 后端接口级别的权限验证 - -### 7.2 数据安全 -- **密码加密**: bcrypt哈希加密 -- **SQL注入防护**: Sequelize ORM参数化查询 -- **XSS防护**: 前端输入验证和转义 -- **CORS配置**: 跨域请求安全控制 - -## 8. 性能优化 -### 8.1 后端性能 -- **数据库连接池**: 优化数据库连接管理 -- **查询优化**: 数据库查询性能监控 -- **API性能监控**: 接口响应时间监控 -- **内存监控**: 系统资源使用监控 - -### 8.2 前端性能 -- **组件懒加载**: 路由级别的代码分割 -- **图表优化**: ECharts按需加载 -- **状态管理**: Pinia轻量级状态管理 -- **构建优化**: Vite快速构建和热更新 - -## 9. 部署架构 -### 9.1 开发环境 -- **前端**: Vite开发服务器 (http://localhost:5300) -- **后端**: Node.js开发服务器 (http://localhost:5350) -- **数据库**: MySQL本地实例 - -### 9.2 生产环境建议 -- **前端**: 静态文件部署 (Nginx) -- **后端**: PM2进程管理 -- **数据库**: MySQL主从复制 -- **负载均衡**: Nginx反向代理 -- **容器化**: Docker部署支持 - -## 10. 依赖关系 -### 10.1 后端主要依赖 -```json -{ - "express": "^4.18.0", - "sequelize": "^6.30.0", - "mysql2": "^3.0.0", - "jsonwebtoken": "^9.0.0", - "bcrypt": "^5.1.0", - "swagger-ui-express": "^5.0.0", - "swagger-jsdoc": "^6.2.8", - "winston": "^3.17.0", - "cors": "^2.8.5", - "express-validator": "^7.2.1", - "dotenv": "^16.0.0", - "axios": "^1.4.0", - "nodemon": "^3.0.0" -} -``` - -### 10.2 前端主要依赖 -```json -{ - "vue": "^3.4.0", - "vue-router": "^4.0.0", - "pinia": "^2.0.0", - "ant-design-vue": "^4.0.0", - "echarts": "^5.4.0", - "axios": "^1.11.0", - "@vitejs/plugin-vue": "^5.0.0", - "vite": "^5.0.0" -} -``` - -### 10.3 外部服务 -- **百度地图API**: 地理信息可视化服务 -- **MySQL数据库**: 数据持久化存储 - -## 11. 扩展性设计 -### 11.1 模块化架构 -- **前端组件化**: 可复用的Vue组件 -- **后端模块化**: 控制器、模型、路由分离 -- **配置外部化**: 环境变量配置管理 - -### 11.2 未来扩展方向 -- **微服务架构**: 服务拆分和独立部署 -- **消息队列**: 异步任务处理 -- **缓存系统**: Redis缓存优化 -- **实时通信**: WebSocket实时数据推送 -- **移动端支持**: 响应式设计和PWA - -## 12. 项目特色功能 - -### 12.1 性能监控系统 -- **实时性能监控**: 监控API响应时间、系统资源使用情况 -- **性能分析图表**: 基于ECharts的性能数据可视化 -- **虚拟滚动优化**: 大数据量图表的性能优化 -- **数据库查询优化**: 查询性能监控和优化建议 - -### 12.2 地图可视化系统 -- **百度地图集成**: 农场地理位置可视化展示 -- **地图缩放演示**: 多级缩放功能演示 -- **地理信息服务**: 位置数据处理和展示 - -### 12.3 数据分析系统 -- **多维度统计**: 设备、动物、告警等多维度数据统计 -- **实时图表**: 基于ECharts的实时数据图表 -- **测试分析功能**: 专门的测试分析页面 - -### 12.4 认证与权限系统 -- **JWT无状态认证**: 基于Token的身份验证 -- **自动登录功能**: 智能的自动登录和Token验证 -- **路由权限守卫**: 前端路由级别的权限控制 -- **角色权限管理**: 基于RBAC的权限控制 - -### 12.5 开发与调试工具 -- **API调试页面**: 专门的API测试和调试页面 -- **性能测试工具**: 内置的性能测试和监控工具 -- **数据库管理脚本**: 完整的数据库管理和维护脚本 - ---- -*最后更新: 2025-01-18* -*版本: v2.1* -*分析基于实际代码结构* \ No newline at end of file diff --git a/docs/development/API接口文档.md b/docs/development/API接口文档.md new file mode 100644 index 0000000..348c3b0 --- /dev/null +++ b/docs/development/API接口文档.md @@ -0,0 +1,1779 @@ +# 宁夏智慧养殖监管平台 API 设计文档 + +## 版本历史 + +| 版本 | 日期 | 作者 | 描述 | +|------|------|------|------| +| v1.0 | 2025-01-18 | 开发团队 | 初始版本 | +| v2.0 | 2025-01-19 | 开发团队 | 全面重构，增加多端支持和标准化规范 | + +## 1. API 概述 + +### 1.1 设计原则 + +**RESTful 设计原则：** +- 使用标准HTTP方法（GET、POST、PUT、DELETE） +- 资源导向的URL设计 +- 无状态通信 +- 统一的响应格式 +- 合理的HTTP状态码使用 + +**安全性原则：** +- JWT Token认证 +- HTTPS加密传输 +- 输入参数验证 +- SQL注入防护 +- 访问频率限制 + +**性能原则：** +- 分页查询支持 +- 数据缓存机制 +- 响应数据压缩 +- 异步处理支持 + +### 1.2 基础信息 + +**基础URL：** +``` +开发环境: http://localhost:5350/api +测试环境: https://test-api.nxxmdata.com/api +生产环境: https://api.nxxmdata.com/api +``` + +**API版本控制：** +- 当前版本：v1 +- 版本控制方式：URL路径版本控制 +- 示例：`/api/v1/farms` + +**内容类型：** +- 请求：`application/json` +- 响应：`application/json` +- 字符编码：`UTF-8` + +### 1.3 认证机制 + +**JWT Token认证：** +```http +Authorization: Bearer +``` + +**Token获取：** +```http +POST /api/v1/auth/login +Content-Type: application/json + +{ + "username": "admin", + "password": "password123" +} +``` + +**Token刷新：** +```http +POST /api/v1/auth/refresh +Authorization: Bearer +``` + +## 2. 通用规范 + +### 2.1 请求格式 + +**请求头规范：** +```http +Content-Type: application/json +Authorization: Bearer +Accept: application/json +User-Agent: +X-Request-ID: +``` + +**分页参数：** +```json +{ + "page": 1, + "limit": 20, + "sort": "created_at", + "order": "desc" +} +``` + +**查询参数：** +```json +{ + "filter": { + "status": "active", + "created_at": { + "gte": "2025-01-01", + "lte": "2025-01-31" + } + }, + "search": "关键词", + "fields": ["id", "name", "status"] +} +``` + +### 2.2 响应格式 + +**成功响应：** +```json +{ + "success": true, + "code": 200, + "message": "操作成功", + "data": { + // 具体数据 + }, + "timestamp": "2025-01-19T10:00:00Z", + "request_id": "req_123456789" +} +``` + +**分页响应：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "items": [ + // 数据列表 + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 100, + "pages": 5, + "has_next": true, + "has_prev": false + } + }, + "timestamp": "2025-01-19T10:00:00Z", + "request_id": "req_123456789" +} +``` + +**错误响应：** +```json +{ + "success": false, + "code": 400, + "message": "请求参数错误", + "error": { + "type": "ValidationError", + "details": [ + { + "field": "email", + "message": "邮箱格式不正确" + } + ] + }, + "timestamp": "2025-01-19T10:00:00Z", + "request_id": "req_123456789" +} +``` + +### 2.3 状态码规范 + +**成功状态码：** +- `200 OK` - 请求成功 +- `201 Created` - 资源创建成功 +- `204 No Content` - 请求成功，无返回内容 + +**客户端错误：** +- `400 Bad Request` - 请求参数错误 +- `401 Unauthorized` - 未认证 +- `403 Forbidden` - 权限不足 +- `404 Not Found` - 资源不存在 +- `409 Conflict` - 资源冲突 +- `422 Unprocessable Entity` - 数据验证失败 +- `429 Too Many Requests` - 请求频率超限 + +**服务器错误：** +- `500 Internal Server Error` - 服务器内部错误 +- `502 Bad Gateway` - 网关错误 +- `503 Service Unavailable` - 服务不可用 +- `504 Gateway Timeout` - 网关超时 + +## 3. 认证与授权 API + +### 3.1 用户认证 + +#### 3.1.1 用户登录 + +**接口信息：** +- **URL**: `/api/v1/auth/login` +- **方法**: `POST` +- **描述**: 用户登录获取访问令牌 + +**请求参数：** +```json +{ + "username": "admin", + "password": "password123", + "remember_me": false, + "captcha": "ABCD", + "captcha_key": "captcha_123456" +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "登录成功", + "data": { + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "token_type": "Bearer", + "expires_in": 3600, + "user": { + "id": 1, + "username": "admin", + "real_name": "管理员", + "email": "admin@example.com", + "roles": ["admin"], + "permissions": ["farm:read", "farm:write"] + } + } +} +``` + +#### 3.1.2 用户登出 + +**接口信息：** +- **URL**: `/api/v1/auth/logout` +- **方法**: `POST` +- **描述**: 用户登出，使令牌失效 + +**请求头：** +```http +Authorization: Bearer +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "登出成功" +} +``` + +#### 3.1.3 令牌刷新 + +**接口信息：** +- **URL**: `/api/v1/auth/refresh` +- **方法**: `POST` +- **描述**: 使用刷新令牌获取新的访问令牌 + +**请求参数：** +```json +{ + "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "令牌刷新成功", + "data": { + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "token_type": "Bearer", + "expires_in": 3600 + } +} +``` + +### 3.2 用户信息 + +#### 3.2.1 获取当前用户信息 + +**接口信息：** +- **URL**: `/api/v1/auth/me` +- **方法**: `GET` +- **描述**: 获取当前登录用户的详细信息 + +**请求头：** +```http +Authorization: Bearer +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "获取成功", + "data": { + "id": 1, + "username": "admin", + "real_name": "管理员", + "email": "admin@example.com", + "phone": "13800138000", + "avatar_url": "https://example.com/avatar.jpg", + "status": "active", + "roles": [ + { + "id": 1, + "name": "admin", + "display_name": "系统管理员" + } + ], + "permissions": [ + "farm:read", + "farm:write", + "user:read", + "user:write" + ], + "last_login_at": "2025-01-19T09:00:00Z", + "created_at": "2025-01-01T00:00:00Z" + } +} +``` + +## 4. 用户管理 API + +### 4.1 用户列表 + +**接口信息：** +- **URL**: `/api/v1/users` +- **方法**: `GET` +- **描述**: 获取用户列表（支持分页和筛选） + +**查询参数：** +``` +page=1&limit=20&status=active&search=admin&sort=created_at&order=desc +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "items": [ + { + "id": 1, + "username": "admin", + "real_name": "管理员", + "email": "admin@example.com", + "phone": "13800138000", + "status": "active", + "roles": ["admin"], + "last_login_at": "2025-01-19T09:00:00Z", + "created_at": "2025-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 1, + "pages": 1, + "has_next": false, + "has_prev": false + } + } +} +``` + +### 4.2 创建用户 + +**接口信息：** +- **URL**: `/api/v1/users` +- **方法**: `POST` +- **描述**: 创建新用户 + +**请求参数：** +```json +{ + "username": "newuser", + "password": "password123", + "real_name": "新用户", + "email": "newuser@example.com", + "phone": "13800138001", + "role_ids": [2, 3], + "status": "active" +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 201, + "message": "用户创建成功", + "data": { + "id": 2, + "username": "newuser", + "real_name": "新用户", + "email": "newuser@example.com", + "phone": "13800138001", + "status": "active", + "created_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 4.3 更新用户 + +**接口信息：** +- **URL**: `/api/v1/users/{id}` +- **方法**: `PUT` +- **描述**: 更新用户信息 + +**请求参数：** +```json +{ + "real_name": "更新后的姓名", + "email": "updated@example.com", + "phone": "13800138002", + "status": "inactive" +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "用户更新成功", + "data": { + "id": 2, + "username": "newuser", + "real_name": "更新后的姓名", + "email": "updated@example.com", + "phone": "13800138002", + "status": "inactive", + "updated_at": "2025-01-19T10:30:00Z" + } +} +``` + +### 4.4 删除用户 + +**接口信息：** +- **URL**: `/api/v1/users/{id}` +- **方法**: `DELETE` +- **描述**: 删除用户（软删除） + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "用户删除成功" +} +``` + +## 5. 养殖场管理 API + +### 5.1 养殖场列表 + +**接口信息：** +- **URL**: `/api/v1/farms` +- **方法**: `GET` +- **描述**: 获取养殖场列表 + +**查询参数：** +``` +page=1&limit=20&status=active&type=pig&scale=large&search=示例养殖场 +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "items": [ + { + "id": 1, + "name": "示例养殖场", + "code": "FARM001", + "type": "pig", + "scale": "large", + "address": "宁夏银川市兴庆区示例路123号", + "latitude": 38.4872, + "longitude": 106.2309, + "contact_person": "张三", + "contact_phone": "13800138000", + "license_number": "NX001234567890", + "status": "active", + "device_count": 15, + "animal_count": 500, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 1, + "pages": 1, + "has_next": false, + "has_prev": false + } + } +} +``` + +### 5.2 获取养殖场详情 + +**接口信息：** +- **URL**: `/api/v1/farms/{id}` +- **方法**: `GET` +- **描述**: 获取指定养殖场的详细信息 + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "id": 1, + "name": "示例养殖场", + "code": "FARM001", + "type": "pig", + "scale": "large", + "address": "宁夏银川市兴庆区示例路123号", + "latitude": 38.4872, + "longitude": 106.2309, + "contact_person": "张三", + "contact_phone": "13800138000", + "license_number": "NX001234567890", + "status": "active", + "description": "这是一个示例养殖场", + "established_date": "2020-01-01", + "area": 10000, + "capacity": 1000, + "devices": [ + { + "id": 1, + "device_id": "DEV001", + "device_name": "温度传感器1", + "device_type": "temperature", + "status": "online" + } + ], + "animals": [ + { + "id": 1, + "tag_id": "PIG001", + "breed": "大白猪", + "status": "healthy" + } + ], + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 5.3 创建养殖场 + +**接口信息：** +- **URL**: `/api/v1/farms` +- **方法**: `POST` +- **描述**: 创建新的养殖场 + +**请求参数：** +```json +{ + "name": "新养殖场", + "code": "FARM002", + "type": "cattle", + "scale": "medium", + "address": "宁夏银川市金凤区新建路456号", + "latitude": 38.5000, + "longitude": 106.2500, + "contact_person": "李四", + "contact_phone": "13800138001", + "license_number": "NX001234567891", + "description": "新建的牛养殖场", + "established_date": "2025-01-01", + "area": 8000, + "capacity": 800 +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 201, + "message": "养殖场创建成功", + "data": { + "id": 2, + "name": "新养殖场", + "code": "FARM002", + "type": "cattle", + "scale": "medium", + "status": "pending", + "created_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 5.4 更新养殖场 + +**接口信息：** +- **URL**: `/api/v1/farms/{id}` +- **方法**: `PUT` +- **描述**: 更新养殖场信息 + +**请求参数：** +```json +{ + "name": "更新后的养殖场名称", + "contact_person": "王五", + "contact_phone": "13800138002", + "status": "active" +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "养殖场更新成功", + "data": { + "id": 1, + "name": "更新后的养殖场名称", + "contact_person": "王五", + "contact_phone": "13800138002", + "status": "active", + "updated_at": "2025-01-19T10:30:00Z" + } +} +``` + +### 5.5 删除养殖场 + +**接口信息：** +- **URL**: `/api/v1/farms/{id}` +- **方法**: `DELETE` +- **描述**: 删除养殖场（软删除） + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "养殖场删除成功" +} +``` + +## 6. 设备管理 API + +### 6.1 设备列表 + +**接口信息：** +- **URL**: `/api/v1/devices` +- **方法**: `GET` +- **描述**: 获取设备列表 + +**查询参数：** +``` +page=1&limit=20&farm_id=1&status=online&device_type=temperature +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "items": [ + { + "id": 1, + "farm_id": 1, + "device_id": "DEV001", + "device_name": "温度传感器1", + "device_type": "temperature", + "model": "TH-100", + "manufacturer": "传感器公司", + "location": "猪舍A区", + "install_date": "2025-01-01", + "status": "online", + "last_online_at": "2025-01-19T10:00:00Z", + "farm": { + "id": 1, + "name": "示例养殖场", + "code": "FARM001" + }, + "latest_data": { + "temperature": 25.5, + "humidity": 60.2, + "timestamp": "2025-01-19T10:00:00Z" + }, + "created_at": "2025-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 1, + "pages": 1, + "has_next": false, + "has_prev": false + } + } +} +``` + +### 6.2 获取设备详情 + +**接口信息：** +- **URL**: `/api/v1/devices/{id}` +- **方法**: `GET` +- **描述**: 获取指定设备的详细信息 + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "id": 1, + "farm_id": 1, + "device_id": "DEV001", + "device_name": "温度传感器1", + "device_type": "temperature", + "model": "TH-100", + "manufacturer": "传感器公司", + "location": "猪舍A区", + "install_date": "2025-01-01", + "status": "online", + "last_online_at": "2025-01-19T10:00:00Z", + "config": { + "sampling_interval": 60, + "alert_threshold": { + "temperature_max": 30, + "temperature_min": 10, + "humidity_max": 80, + "humidity_min": 40 + } + }, + "farm": { + "id": 1, + "name": "示例养殖场", + "code": "FARM001" + }, + "recent_data": [ + { + "temperature": 25.5, + "humidity": 60.2, + "timestamp": "2025-01-19T10:00:00Z" + } + ], + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 6.3 创建设备 + +**接口信息：** +- **URL**: `/api/v1/devices` +- **方法**: `POST` +- **描述**: 添加新设备 + +**请求参数：** +```json +{ + "farm_id": 1, + "device_id": "DEV002", + "device_name": "湿度传感器1", + "device_type": "humidity", + "model": "HU-200", + "manufacturer": "传感器公司", + "location": "猪舍B区", + "install_date": "2025-01-19", + "config": { + "sampling_interval": 30, + "alert_threshold": { + "humidity_max": 85, + "humidity_min": 35 + } + } +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 201, + "message": "设备创建成功", + "data": { + "id": 2, + "device_id": "DEV002", + "device_name": "湿度传感器1", + "device_type": "humidity", + "status": "offline", + "created_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 6.4 获取设备数据 + +**接口信息：** +- **URL**: `/api/v1/devices/{id}/data` +- **方法**: `GET` +- **描述**: 获取设备历史数据 + +**查询参数：** +``` +start_time=2025-01-19T00:00:00Z&end_time=2025-01-19T23:59:59Z&data_type=temperature&limit=100 +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "device_id": "DEV001", + "device_name": "温度传感器1", + "data_points": [ + { + "timestamp": "2025-01-19T10:00:00Z", + "temperature": 25.5, + "humidity": 60.2, + "ammonia": 15.8, + "co2": 800 + }, + { + "timestamp": "2025-01-19T10:01:00Z", + "temperature": 25.6, + "humidity": 60.1, + "ammonia": 15.9, + "co2": 805 + } + ], + "statistics": { + "count": 2, + "avg_temperature": 25.55, + "max_temperature": 25.6, + "min_temperature": 25.5 + } + } +} +``` + +## 7. 动物管理 API + +### 7.1 动物列表 + +**接口信息：** +- **URL**: `/api/v1/animals` +- **方法**: `GET` +- **描述**: 获取动物列表 + +**查询参数：** +``` +page=1&limit=20&farm_id=1&breed=大白猪&status=healthy&gender=male +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "items": [ + { + "id": 1, + "farm_id": 1, + "tag_id": "PIG001", + "breed": "大白猪", + "gender": "male", + "birth_date": "2024-06-01", + "weight": 85.5, + "status": "healthy", + "location": "猪舍A区-栏位001", + "farm": { + "id": 1, + "name": "示例养殖场", + "code": "FARM001" + }, + "health_records": [ + { + "id": 1, + "check_date": "2025-01-15", + "health_status": "healthy", + "notes": "健康状况良好" + } + ], + "created_at": "2024-06-01T00:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 1, + "pages": 1, + "has_next": false, + "has_prev": false + } + } +} +``` + +### 7.2 获取动物详情 + +**接口信息：** +- **URL**: `/api/v1/animals/{id}` +- **方法**: `GET` +- **描述**: 获取指定动物的详细信息 + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "id": 1, + "farm_id": 1, + "tag_id": "PIG001", + "breed": "大白猪", + "gender": "male", + "birth_date": "2024-06-01", + "weight": 85.5, + "status": "healthy", + "location": "猪舍A区-栏位001", + "parent_info": { + "father_tag": "PIG_FATHER_001", + "mother_tag": "PIG_MOTHER_001" + }, + "farm": { + "id": 1, + "name": "示例养殖场", + "code": "FARM001" + }, + "health_records": [ + { + "id": 1, + "check_date": "2025-01-15", + "health_status": "healthy", + "temperature": 38.5, + "weight": 85.5, + "notes": "健康状况良好", + "veterinarian": "兽医张三", + "created_at": "2025-01-15T10:00:00Z" + } + ], + "vaccination_records": [ + { + "id": 1, + "vaccine_name": "猪瘟疫苗", + "vaccination_date": "2024-07-01", + "next_due_date": "2025-07-01", + "veterinarian": "兽医李四", + "created_at": "2024-07-01T10:00:00Z" + } + ], + "created_at": "2024-06-01T00:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 7.3 创建动物档案 + +**接口信息：** +- **URL**: `/api/v1/animals` +- **方法**: `POST` +- **描述**: 创建新的动物档案 + +**请求参数：** +```json +{ + "farm_id": 1, + "tag_id": "PIG002", + "breed": "长白猪", + "gender": "female", + "birth_date": "2024-08-01", + "weight": 75.0, + "location": "猪舍A区-栏位002", + "parent_info": { + "father_tag": "PIG_FATHER_002", + "mother_tag": "PIG_MOTHER_002" + }, + "notes": "新引进的种猪" +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 201, + "message": "动物档案创建成功", + "data": { + "id": 2, + "tag_id": "PIG002", + "breed": "长白猪", + "gender": "female", + "status": "healthy", + "created_at": "2025-01-19T10:00:00Z" + } +} +``` + +## 8. 告警管理 API + +### 8.1 告警列表 + +**接口信息：** +- **URL**: `/api/v1/alerts` +- **方法**: `GET` +- **描述**: 获取告警列表 + +**查询参数：** +``` +page=1&limit=20&farm_id=1&level=warning&status=pending&alert_type=temperature +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "items": [ + { + "id": 1, + "farm_id": 1, + "device_id": 1, + "alert_type": "temperature", + "level": "warning", + "title": "温度过高告警", + "message": "猪舍A区温度达到32°C，超过预设阈值30°C", + "status": "pending", + "trigger_value": 32.0, + "threshold_value": 30.0, + "trigger_time": "2025-01-19T10:00:00Z", + "farm": { + "id": 1, + "name": "示例养殖场", + "code": "FARM001" + }, + "device": { + "id": 1, + "device_id": "DEV001", + "device_name": "温度传感器1", + "location": "猪舍A区" + }, + "created_at": "2025-01-19T10:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 1, + "pages": 1, + "has_next": false, + "has_prev": false + } + } +} +``` + +### 8.2 处理告警 + +**接口信息：** +- **URL**: `/api/v1/alerts/{id}/handle` +- **方法**: `POST` +- **描述**: 处理告警 + +**请求参数：** +```json +{ + "action": "resolved", + "handler_notes": "已调整通风系统，温度恢复正常", + "solution": "增加通风量，调整温控设备参数" +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "告警处理成功", + "data": { + "id": 1, + "status": "resolved", + "handled_at": "2025-01-19T10:30:00Z", + "handler_id": 1, + "handler_name": "管理员", + "handler_notes": "已调整通风系统，温度恢复正常" + } +} +``` + +## 9. 数据统计 API + +### 9.1 概览统计 + +**接口信息：** +- **URL**: `/api/v1/stats/overview` +- **方法**: `GET` +- **描述**: 获取系统概览统计数据 + +**查询参数：** +``` +date_range=7d&farm_id=1 +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "farms": { + "total": 10, + "active": 8, + "inactive": 2 + }, + "devices": { + "total": 150, + "online": 145, + "offline": 5, + "maintenance": 0 + }, + "animals": { + "total": 5000, + "healthy": 4950, + "sick": 30, + "quarantine": 20 + }, + "alerts": { + "total": 25, + "pending": 5, + "resolved": 20, + "critical": 2, + "warning": 15, + "info": 8 + }, + "trends": { + "farms_growth": 5.2, + "devices_growth": 8.1, + "animals_growth": 12.5, + "alerts_reduction": -15.3 + } + } +} +``` + +### 9.2 设备数据统计 + +**接口信息：** +- **URL**: `/api/v1/stats/devices` +- **方法**: `GET` +- **描述**: 获取设备数据统计 + +**查询参数：** +``` +farm_id=1&device_type=temperature&start_time=2025-01-19T00:00:00Z&end_time=2025-01-19T23:59:59Z&interval=hour +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "device_type": "temperature", + "time_range": { + "start": "2025-01-19T00:00:00Z", + "end": "2025-01-19T23:59:59Z" + }, + "statistics": { + "avg_value": 25.5, + "max_value": 32.0, + "min_value": 18.5, + "data_points": 1440 + }, + "time_series": [ + { + "timestamp": "2025-01-19T00:00:00Z", + "avg_value": 20.5, + "max_value": 22.0, + "min_value": 19.0, + "count": 60 + }, + { + "timestamp": "2025-01-19T01:00:00Z", + "avg_value": 21.2, + "max_value": 23.5, + "min_value": 19.8, + "count": 60 + } + ] + } +} +``` + +### 9.3 告警统计 + +**接口信息：** +- **URL**: `/api/v1/stats/alerts` +- **方法**: `GET` +- **描述**: 获取告警统计数据 + +**查询参数：** +``` +farm_id=1&date_range=30d&group_by=level +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "total_alerts": 150, + "resolved_alerts": 135, + "pending_alerts": 15, + "resolution_rate": 90.0, + "avg_resolution_time": 45, + "by_level": [ + { + "level": "critical", + "count": 10, + "percentage": 6.7 + }, + { + "level": "warning", + "count": 80, + "percentage": 53.3 + }, + { + "level": "info", + "count": 60, + "percentage": 40.0 + } + ], + "by_type": [ + { + "type": "temperature", + "count": 60, + "percentage": 40.0 + }, + { + "type": "humidity", + "count": 45, + "percentage": 30.0 + }, + { + "type": "ammonia", + "count": 30, + "percentage": 20.0 + }, + { + "type": "system", + "count": 15, + "percentage": 10.0 + } + ], + "trend": [ + { + "date": "2025-01-13", + "count": 8 + }, + { + "date": "2025-01-14", + "count": 12 + } + ] + } +} +``` + +## 10. 文件管理 API + +### 10.1 文件上传 + +**接口信息：** +- **URL**: `/api/v1/files/upload` +- **方法**: `POST` +- **描述**: 上传文件 + +**请求格式：** +```http +Content-Type: multipart/form-data + +file: +type: image|document|video +category: avatar|farm_image|device_manual|report +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "文件上传成功", + "data": { + "id": 1, + "filename": "farm_image_001.jpg", + "original_name": "养殖场照片.jpg", + "file_path": "/uploads/images/2025/01/19/farm_image_001.jpg", + "file_url": "https://cdn.nxxmdata.com/uploads/images/2025/01/19/farm_image_001.jpg", + "file_size": 1024000, + "mime_type": "image/jpeg", + "type": "image", + "category": "farm_image", + "created_at": "2025-01-19T10:00:00Z" + } +} +``` + +### 10.2 文件下载 + +**接口信息：** +- **URL**: `/api/v1/files/{id}/download` +- **方法**: `GET` +- **描述**: 下载文件 + +**响应：** +```http +Content-Type: application/octet-stream +Content-Disposition: attachment; filename="farm_image_001.jpg" + + +``` + +### 10.3 文件删除 + +**接口信息：** +- **URL**: `/api/v1/files/{id}` +- **方法**: `DELETE` +- **描述**: 删除文件 + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "文件删除成功" +} +``` + +## 11. 地图服务 API + +### 11.1 获取地图数据 + +**接口信息：** +- **URL**: `/api/v1/map/farms` +- **方法**: `GET` +- **描述**: 获取养殖场地图标注数据 + +**查询参数：** +``` +bounds=38.4000,106.2000,38.5000,106.3000&zoom=10&status=active +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "farms": [ + { + "id": 1, + "name": "示例养殖场", + "code": "FARM001", + "latitude": 38.4872, + "longitude": 106.2309, + "status": "active", + "type": "pig", + "scale": "large", + "device_count": 15, + "animal_count": 500, + "alert_count": 2, + "marker_icon": "farm_pig_large", + "popup_info": { + "title": "示例养殖场", + "description": "大型生猪养殖场", + "contact": "张三 - 13800138000", + "status_text": "正常运营" + } + } + ], + "bounds": { + "north": 38.5000, + "south": 38.4000, + "east": 106.3000, + "west": 106.2000 + }, + "center": { + "latitude": 38.4500, + "longitude": 106.2500 + } + } +} +``` + +### 11.2 地理编码 + +**接口信息：** +- **URL**: `/api/v1/map/geocode` +- **方法**: `GET` +- **描述**: 地址转换为经纬度坐标 + +**查询参数：** +``` +address=宁夏银川市兴庆区示例路123号 +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "地理编码成功", + "data": { + "address": "宁夏银川市兴庆区示例路123号", + "location": { + "latitude": 38.4872, + "longitude": 106.2309 + }, + "formatted_address": "宁夏回族自治区银川市兴庆区示例路123号", + "address_components": { + "province": "宁夏回族自治区", + "city": "银川市", + "district": "兴庆区", + "street": "示例路", + "street_number": "123号" + }, + "confidence": 95 + } +} +``` + +## 12. 系统配置 API + +### 12.1 获取系统配置 + +**接口信息：** +- **URL**: `/api/v1/config` +- **方法**: `GET` +- **描述**: 获取系统配置信息 + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "查询成功", + "data": { + "system": { + "name": "宁夏智慧养殖监管平台", + "version": "2.0.0", + "build": "20250119", + "environment": "production" + }, + "features": { + "multi_tenant": true, + "real_time_monitoring": true, + "mobile_app": true, + "data_export": true + }, + "limits": { + "max_farms_per_user": 10, + "max_devices_per_farm": 100, + "max_file_size": 10485760, + "api_rate_limit": 1000 + }, + "integrations": { + "baidu_map": { + "enabled": true, + "api_key": "ak_***" + }, + "sms_service": { + "enabled": true, + "provider": "aliyun" + }, + "email_service": { + "enabled": true, + "smtp_host": "smtp.example.com" + } + } + } +} +``` + +### 12.2 更新系统配置 + +**接口信息：** +- **URL**: `/api/v1/config` +- **方法**: `PUT` +- **描述**: 更新系统配置（需要管理员权限） + +**请求参数：** +```json +{ + "limits": { + "max_farms_per_user": 15, + "api_rate_limit": 1500 + }, + "integrations": { + "sms_service": { + "enabled": false + } + } +} +``` + +**响应示例：** +```json +{ + "success": true, + "code": 200, + "message": "配置更新成功", + "data": { + "updated_fields": [ + "limits.max_farms_per_user", + "limits.api_rate_limit", + "integrations.sms_service.enabled" + ], + "updated_at": "2025-01-19T10:30:00Z" + } +} +``` + +## 13. 错误处理 + +### 13.1 错误码定义 + +**通用错误码：** +- `10000` - 系统内部错误 +- `10001` - 参数验证失败 +- `10002` - 资源不存在 +- `10003` - 权限不足 +- `10004` - 请求频率超限 +- `10005` - 服务暂不可用 + +**认证相关错误码：** +- `20001` - 用户名或密码错误 +- `20002` - Token无效或已过期 +- `20003` - 账户被禁用 +- `20004` - 登录失败次数过多 + +**业务相关错误码：** +- `30001` - 养殖场代码已存在 +- `30002` - 设备ID已存在 +- `30003` - 动物标签ID已存在 +- `30004` - 文件格式不支持 +- `30005` - 文件大小超限 + +### 13.2 错误响应示例 + +**参数验证错误：** +```json +{ + "success": false, + "code": 10001, + "message": "参数验证失败", + "error": { + "type": "ValidationError", + "details": [ + { + "field": "email", + "message": "邮箱格式不正确", + "value": "invalid-email" + }, + { + "field": "phone", + "message": "手机号码格式不正确", + "value": "123" + } + ] + }, + "timestamp": "2025-01-19T10:00:00Z", + "request_id": "req_123456789" +} +``` + +**权限不足错误：** +```json +{ + "success": false, + "code": 10003, + "message": "权限不足", + "error": { + "type": "PermissionError", + "required_permission": "farm:write", + "user_permissions": ["farm:read"] + }, + "timestamp": "2025-01-19T10:00:00Z", + "request_id": "req_123456789" +} +``` + +## 14. API 测试 + +### 14.1 测试环境 + +**测试服务器：** +- 地址：`https://test-api.nxxmdata.com` +- 测试账号：`test_user` +- 测试密码：`test_password_123` + +**Postman集合：** +- 下载地址：`https://api.nxxmdata.com/docs/postman-collection.json` +- 包含所有API接口的测试用例 +- 自动化测试脚本 + +### 14.2 测试用例 + +**用户登录测试：** +```bash +curl -X POST https://test-api.nxxmdata.com/api/v1/auth/login \ + -H "Content-Type: application/json" \ + -d '{ + "username": "test_user", + "password": "test_password_123" + }' +``` + +**获取养殖场列表测试：** +```bash +curl -X GET https://test-api.nxxmdata.com/api/v1/farms \ + -H "Authorization: Bearer " \ + -H "Accept: application/json" +``` + +## 15. SDK 和工具 + +### 15.1 JavaScript SDK + +**安装：** +```bash +npm install @nxxmdata/api-sdk +``` + +**使用示例：** +```javascript +import { NxxmDataAPI } from '@nxxmdata/api-sdk'; + +const api = new NxxmDataAPI({ + baseURL: 'https://api.nxxmdata.com', + apiKey: 'your-api-key' +}); + +// 登录 +const loginResult = await api.auth.login({ + username: 'admin', + password: 'password123' +}); + +// 获取养殖场列表 +const farms = await api.farms.list({ + page: 1, + limit: 20, + status: 'active' +}); +``` + +### 15.2 Python SDK + +**安装：** +```bash +pip install nxxmdata-api-sdk +``` + +**使用示例：** +```python +from nxxmdata_api import NxxmDataAPI + +api = NxxmDataAPI( + base_url='https://api.nxxmdata.com', + api_key='your-api-key' +) + +# 登录 +login_result = api.auth.login( + username='admin', + password='password123' +) + +# 获取养殖场列表 +farms = api.farms.list( + page=1, + limit=20, + status='active' +) +``` + +## 16. 版本更新 + +### 16.1 版本兼容性 + +**向后兼容性：** +- 主版本号变更可能包含破坏性更改 +- 次版本号变更保持向后兼容 +- 修订版本号仅包含bug修复 + +**废弃策略：** +- 废弃功能将在下一个主版本中移除 +- 提前6个月通知废弃计划 +- 提供迁移指南和工具 + +### 16.2 更新日志 + +**v2.0.0 (2025-01-19)：** +- 全面重构API架构 +- 增加多端支持 +- 优化响应格式 +- 增强安全性 +- 添加更多统计接口 + +**v1.0.0 (2025-01-18)：** +- 初始版本发布 +- 基础CRUD功能 +- JWT认证 +- 基本统计功能 + +--- + +**文档维护说明：** +- 本文档将随API版本更新而更新 +- 所有接口变更都会在此文档中体现 +- 如有疑问请联系开发团队 + +**联系方式：** +- 技术支持：tech-support@nxxmdata.com +- API问题：api-support@nxxmdata.com +- 文档反馈：docs@nxxmdata.com + +*最后更新时间：2025-01-19* +*文档版本：v2.0* +*维护人员：开发团队* \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/development/CONTRIBUTING.md similarity index 100% rename from docs/CONTRIBUTING.md rename to docs/development/CONTRIBUTING.md diff --git a/docs/examples/performance-monitor-integration.js b/docs/development/examples/performance-monitor-integration.js similarity index 100% rename from docs/examples/performance-monitor-integration.js rename to docs/development/examples/performance-monitor-integration.js diff --git a/docs/development/代码规范.md b/docs/development/代码规范.md new file mode 100644 index 0000000..606c170 --- /dev/null +++ b/docs/development/代码规范.md @@ -0,0 +1,599 @@ +# 宁夏智慧养殖监管平台代码规范 + +## 版本历史 + +| 版本 | 日期 | 修改内容 | 修改人 | +|------|------|----------|--------| +| v1.0 | 2024-01-20 | 初始版本，制定基础代码规范 | 开发团队 | + +## 1. 概述 + +本文档规定了宁夏智慧养殖监管平台项目的代码编写规范，旨在提高代码质量、可读性和可维护性。 + +## 2. 通用规范 + +### 2.1 文件命名 +- **文件名**: 使用小写字母和连字符，如 `user-service.js` +- **目录名**: 使用小写字母和连字符，如 `user-management` +- **组件文件**: 使用 PascalCase，如 `UserProfile.vue` + +### 2.2 编码格式 +- **字符编码**: UTF-8 +- **换行符**: LF (Unix) +- **缩进**: 2个空格 +- **行尾**: 不允许有多余空格 + +### 2.3 注释规范 +```javascript +/** + * 函数功能描述 + * @param {string} param1 - 参数1描述 + * @param {number} param2 - 参数2描述 + * @returns {boolean} 返回值描述 + * @author 作者名 + * @since 版本号 + */ +function exampleFunction(param1, param2) { + // 单行注释说明 + return true; +} +``` + +## 3. JavaScript/Node.js 规范 + +### 3.1 变量命名 +```javascript +// 使用 camelCase +const userName = 'admin'; +const userAge = 25; + +// 常量使用 UPPER_SNAKE_CASE +const MAX_RETRY_COUNT = 3; +const API_BASE_URL = 'https://api.example.com'; + +// 私有变量使用下划线前缀 +const _privateVariable = 'private'; +``` + +### 3.2 函数定义 +```javascript +// 优先使用箭头函数 +const getUserInfo = (userId) => { + return userService.findById(userId); +}; + +// 异步函数 +const fetchUserData = async (userId) => { + try { + const user = await userService.findById(userId); + return user; + } catch (error) { + logger.error('获取用户数据失败', error); + throw error; + } +}; +``` + +### 3.3 对象和数组 +```javascript +// 对象属性换行 +const userConfig = { + name: 'admin', + role: 'administrator', + permissions: ['read', 'write', 'delete'], + settings: { + theme: 'dark', + language: 'zh-CN' + } +}; + +// 数组解构 +const [first, second, ...rest] = items; + +// 对象解构 +const { name, age, ...otherProps } = user; +``` + +### 3.4 错误处理 +```javascript +// 统一错误处理 +const handleApiError = (error) => { + if (error.response) { + // 服务器响应错误 + logger.error('API响应错误', { + status: error.response.status, + data: error.response.data + }); + } else if (error.request) { + // 请求发送失败 + logger.error('请求发送失败', error.request); + } else { + // 其他错误 + logger.error('未知错误', error.message); + } + throw error; +}; +``` + +## 4. Vue.js 规范 + +### 4.1 组件命名 +```javascript +// 组件名使用 PascalCase +export default { + name: 'UserProfile', + // ... +} + +// 文件名: UserProfile.vue +``` + +### 4.2 组件结构 +```vue + + + + + +``` + +### 4.3 Props 定义 +```javascript +props: { + // 基础类型检查 + title: String, + count: Number, + isActive: Boolean, + + // 复杂类型检查 + user: { + type: Object, + required: true, + validator: (value) => { + return value && typeof value.id === 'string' + } + }, + + // 带默认值 + size: { + type: String, + default: 'medium', + validator: (value) => { + return ['small', 'medium', 'large'].includes(value) + } + } +} +``` + +### 4.4 事件命名 +```javascript +// 使用 kebab-case +this.$emit('user-updated', userData) +this.$emit('form-submitted', formData) + +// 在模板中 + +``` + +## 5. CSS/SCSS 规范 + +### 5.1 类名命名 +```css +/* 使用 BEM 命名法 */ +.user-profile { + /* 块 */ +} + +.user-profile__header { + /* 元素 */ +} + +.user-profile__header--large { + /* 修饰符 */ +} + +.user-profile__avatar { + /* 元素 */ +} + +.user-profile__avatar--round { + /* 修饰符 */ +} +``` + +### 5.2 样式组织 +```scss +// 变量定义 +$primary-color: #1890ff; +$success-color: #52c41a; +$warning-color: #faad14; +$error-color: #f5222d; + +// 混入定义 +@mixin flex-center { + display: flex; + justify-content: center; + align-items: center; +} + +// 组件样式 +.user-profile { + padding: 16px; + border-radius: 4px; + background-color: #fff; + + &__header { + @include flex-center; + margin-bottom: 16px; + font-size: 18px; + font-weight: 600; + } + + &__content { + line-height: 1.6; + } +} +``` + +## 6. API 接口规范 + +### 6.1 接口命名 +```javascript +// RESTful API 命名 +GET /api/users // 获取用户列表 +GET /api/users/:id // 获取单个用户 +POST /api/users // 创建用户 +PUT /api/users/:id // 更新用户 +DELETE /api/users/:id // 删除用户 + +// 复杂操作使用动词 +POST /api/users/:id/reset-password // 重置密码 +POST /api/users/:id/change-status // 更改状态 +``` + +### 6.2 请求响应格式 +```javascript +// 统一响应格式 +{ + "code": 200, + "message": "操作成功", + "data": { + // 具体数据 + }, + "timestamp": "2024-01-20T10:30:00Z" +} + +// 分页响应格式 +{ + "code": 200, + "message": "获取成功", + "data": { + "list": [...], + "pagination": { + "current": 1, + "pageSize": 10, + "total": 100, + "totalPages": 10 + } + } +} + +// 错误响应格式 +{ + "code": 400, + "message": "参数错误", + "error": { + "field": "email", + "reason": "邮箱格式不正确" + }, + "timestamp": "2024-01-20T10:30:00Z" +} +``` + +## 7. 数据库规范 + +### 7.1 表命名 +```sql +-- 表名使用复数形式，下划线分隔 +users +farm_devices +alert_records +user_roles + +-- 关联表使用两个表名组合 +user_farm_bindings +device_alert_configs +``` + +### 7.2 字段命名 +```sql +-- 字段名使用下划线分隔 +CREATE TABLE users ( + id VARCHAR(36) PRIMARY KEY, + user_name VARCHAR(50) NOT NULL, + email VARCHAR(100) UNIQUE, + phone_number VARCHAR(20), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + is_active BOOLEAN DEFAULT TRUE +); +``` + +## 8. Git 提交规范 + +### 8.1 提交信息格式 +``` +(): + + + +