aiotagro/nxxmdata
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

删除废弃的API和架构文档

Browse Source
This commit is contained in:
ylweng
2025-09-19 23:46:15 +08:00
parent 35db747d4f
commit 3143c3ad0b
46 changed files with 11804 additions and 3235 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
docs/architecture/开发计划.md Normal file
View File

@@ -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 迭代计划
- 根据用户反馈持续优化功能
- 定期发布新版本
- 扩展新的业务模块
---
**文档维护**: 本文档将根据项目进展情况定期更新
**联系方式**: 如有疑问，请联系项目经理或系统架构师

592
docs/architecture/数据库设计文档.md Normal file
View File

@@ -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';
```
---
**文档维护说明：**
本文档应随着系统功能的增加和数据库结构的变化及时更新。所有数据库结构变更都应该通过版本控制进行管理，确保开发、测试、生产环境的一致性。

1555
docs/architecture/系统架构文档.md Normal file
View File

File diff suppressed because it is too large Load Diff

551
docs/architecture/系统详细设计文档.md Normal file
View File

@@ -0,0 +1,551 @@
# 宁夏智慧养殖监管平台详细设计文档
## 1. 项目概述
### 1.1 项目背景
宁夏回族自治区作为中国重要的畜牧业基地，养殖业在区域经济发展中占据重要地位。随着现代信息技术的快速发展，传统养殖业正逐步向智能化、数字化方向转型升级。为提升宁夏地区养殖业的管理水平和监管效率，建设一套完善的智慧养殖监管平台势在必行。
### 1.2 项目目标
宁夏智慧养殖监管平台旨在通过数字化手段实现对养殖全过程的监管，具体目标包括：
- 实现养殖场信息数字化管理
- 提供养殖环境实时监控功能
- 支持养殖过程数据记录与追溯
- 提供数据分析和决策支持
- 构建统一的养殖监管体系
### 1.3 项目范围
本项目主要涵盖以下功能模块：
- 用户权限管理
- 养殖场信息管理
- 养殖环境监控
- 养殖过程管理
- 产品信息管理
- 数据分析与报表
- 地理信息系统展示
## 2. 技术架构设计
### 2.1 整体架构
本项目采用前后端分离的架构设计模式，包含以下主要模块：
- **后端服务** (`backend/`): Node.js + Express + Sequelize ORM
- **管理后台** (`admin-system/`): Vue.js 3.x + Ant Design Vue
- **官网** (`website/`): Vue.js 3.x + 数据大屏展示
- **微信小程序** (`mini_program/`): React + TypeScript + Tailwind CSS
- **脚本工具** (`scripts/`): 数据库管理和维护脚本
- **文档** (`docs/`): 项目技术文档，包含API文档、部署指南、开发指南、故障排除、更新日志、贡献指南、安全指南、产品需求文档等
- **测试** (`test/`): 测试脚本和用例
### 2.2 前端技术栈
- **核心框架**: Vue.js 3.x
- **UI组件库**: Ant Design Vue
- **构建工具**: Vite
- **状态管理**: Pinia
- **路由管理**: Vue Router
- **地图服务**: 百度地图API
- **图表库**: ECharts
### 2.3 后端技术栈
- **运行环境**: Node.js
- **Web框架**: Express.js 4.18+
- **API风格**: RESTful API
- **认证授权**: JWT (jsonwebtoken 9.0+)
- **数据库访问**: Sequelize ORM 6.30+
- **数据库**: MySQL (mysql2 3.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
### 2.4 部署架构
- **开发环境**: 本地运行
- **生产环境**: Docker容器化部署
## 3. 数据库设计
### 3.1 数据库连接信息
- 数据库地址：http://192.168.0.240:3306
- 数据库用户名：root
- 数据库密码：aiot$Aiot123
- 数据库名称：nxxmdata
### 3.2 数据库连接失败解决方案
在开发过程中，可能会遇到数据库连接失败的问题，此时应采取以下措施：
1. **确认MySQL服务状态**:
- 确保MySQL服务已经安装并正在运行
- 检查MySQL是否在默认端口3306上运行和监听
2. **创建数据库**:
- 可以执行项目中的SQL文件来创建数据库和表
- 根据项目中的 schema.sql 文件，手动执行创建数据库和表的SQL语句
3. **提供正确的连接参数**:
- 需要提供正确的数据库连接信息，包括主机地址（host）、端口号（port）、用户名（user）、密码（password）、数据库名（database）
- 验证主机地址、端口号、用户名、密码等连接参数的正确性
- 确保提供完整的数据库配置参数，检查参数格式是否符合MCP工具的要求
4. **连接验证参数**:
- 主机: `localhost` 或 `127.0.0.1`
- 端口: `3306` (MySQL默认端口)
- 用户名: MySQL用户名 (例如: `root`)
- 密码: MySQL密码
- 数据库: `nxxmdata`
5. **处理未知数据库问题**:
- 如果遇到"Unknown database"错误，应手动创建相应的数据库
- 使用schema.sql文件创建数据库结构
- 确保在连接数据库前完成数据库的初始化工作
6. **验证数据库连接**:
- 在完成数据库创建和配置后，再次尝试连接数据库
- 通过执行简单的数据库操作验证连接的有效性
当无法直接连接数据库时，可以通过创建完整的数据库设计文档和SQL脚本文件来提供替代方案。这种方法可以确保设计工作继续进行，并为后续的数据库部署提供可执行的起点。
### 3.3 数据表结构设计
#### 3.3.1 用户表 (users)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| email | VARCHAR(100) | UNIQUE, NOT NULL | 邮箱地址 |
| password | VARCHAR(255) | NOT NULL | 密码（加密后） |
| phone | VARCHAR(20) | NULL | 手机号 |
| avatar | VARCHAR(255) | NULL | 头像URL |
| status | ENUM('active','inactive','banned') | DEFAULT 'active' | 用户状态 |
| last_login | DATETIME | NULL | 最后登录时间 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
#### 3.3.2 角色表 (roles)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 角色ID |
| name | VARCHAR(50) | UNIQUE, NOT NULL | 角色名称 |
| description | TEXT | NULL | 角色描述 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
#### 3.3.3 用户角色关联表 (user_roles)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| user_id | INT | FOREIGN KEY (users.id), NOT NULL | 用户ID |
| role_id | INT | FOREIGN KEY (roles.id), NOT NULL | 角色ID |
| assigned_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 分配时间 |
#### 3.3.4 产品表 (products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 产品ID |
| name | VARCHAR(100) | NOT NULL | 产品名称 |
| description | TEXT | NULL | 产品描述 |
| price | INT | NOT NULL | 产品价格（单位：分） |
| stock | INT | DEFAULT 0 | 库存数量 |
| image_url | VARCHAR(255) | NULL | 产品图片URL |
| is_active | TINYINT(1) | DEFAULT 1 | 是否激活 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
#### 3.3.5 订单表 (orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | INT | FOREIGN KEY (users.id), NOT NULL | 用户ID |
| total_amount | INT | DEFAULT 0 | 订单总金额（单位：分） |
| status | ENUM('pending','processing','shipped','delivered','cancelled') | DEFAULT 'pending' | 订单状态 |
| payment_status | ENUM('unpaid','paid','refunded') | DEFAULT 'unpaid' | 支付状态 |
| shipping_address | TEXT | NULL | 收货地址 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
#### 3.3.6 订单项表 (order_items)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单项ID |
| order_id | INT | FOREIGN KEY (orders.id), NOT NULL | 订单ID |
| product_id | INT | FOREIGN KEY (products.id), NOT NULL | 产品ID |
| quantity | INT | DEFAULT 1 | 数量 |
| price | INT | NOT NULL | 单价（单位：分） |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
#### 3.3.7 养殖场表 (farms)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 养殖场ID |
| name | VARCHAR(100) | NOT NULL | 养殖场名称 |
| type | VARCHAR(50) | NOT NULL | 养殖场类型 |
| location | JSON | NOT NULL | 地理位置信息 |
| address | VARCHAR(255) | NULL | 详细地址 |
| contact | VARCHAR(50) | NULL | 联系人 |
| phone | VARCHAR(20) | NULL | 联系电话 |
| status | ENUM('active','inactive','maintenance') | DEFAULT 'active' | 养殖场状态 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
#### 3.3.8 动物表 (animals)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 动物ID |
| type | VARCHAR(50) | NOT NULL | 动物类型 |
| count | INT | DEFAULT 0 | 数量 |
| farm_id | INT | FOREIGN KEY (farms.id), NOT NULL | 所属养殖场ID |
| health_status | ENUM('healthy','sick','quarantine') | DEFAULT 'healthy' | 健康状态 |
| last_inspection | DATETIME | NULL | 最后检查时间 |
| notes | TEXT | NULL | 备注信息 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
#### 3.3.9 设备表 (devices)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 设备ID |
| name | VARCHAR(100) | NOT NULL | 设备名称 |
| type | VARCHAR(50) | NOT NULL | 设备类型 |
| status | ENUM('online','offline','maintenance') | DEFAULT 'offline' | 设备状态 |
| farm_id | INT | FOREIGN KEY (farms.id), NOT NULL | 所属养殖场ID |
| last_maintenance | DATETIME | NULL | 最后维护时间 |
| installation_date | DATETIME | NULL | 安装日期 |
| metrics | JSON | NULL | 设备指标数据 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
#### 3.3.10 预警表 (alerts)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 预警ID |
| type | VARCHAR(50) | NOT NULL | 预警类型 |
| level | ENUM('low','medium','high','critical') | DEFAULT 'medium' | 预警级别 |
| message | TEXT | NOT NULL | 预警消息 |
| status | ENUM('active','acknowledged','resolved') | DEFAULT 'active' | 预警状态 |
| farm_id | INT | FOREIGN KEY (farms.id), NOT NULL | 所属养殖场ID |
| device_id | INT | FOREIGN KEY (devices.id), NULL | 关联设备ID |
| resolved_at | DATETIME | NULL | 解决时间 |
| resolved_by | INT | FOREIGN KEY (users.id), NULL | 解决人ID |
| resolution_notes | TEXT | NULL | 解决说明 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 3.4 初始数据
#### 3.4.1 角色数据
系统初始化时会创建以下基础角色数据：
- admin: 系统管理员
- user: 普通用户
- guest: 访客
#### 3.4.2 用户数据
系统初始化时会创建以下示例用户数据：
- admin用户: admin@example.com
- 普通用户: john@example.com
#### 3.4.3 产品数据
系统初始化时会创建以下示例产品数据：
- 示例产品1: 价格99.99，库存100
- 示例产品2: 价格149.99，库存50
## 4. 功能模块详细设计
### 4.1 用户管理模块
#### 4.1.1 用户认证
- 用户登录/登出功能
- 密码加密存储
- JWT令牌管理
- 会话超时处理
#### 4.1.2 用户权限管理
- 基于角色的访问控制(RBAC)
- 权限分配与验证
- 用户角色管理
- 访问日志记录
### 4.2 养殖场信息管理模块
#### 4.2.1 养殖场基本信息
- 养殖场名称、地址、联系人等基本信息维护
- 养殖场资质证书管理
- 养殖场规模信息记录
- 养殖场照片上传与展示
#### 4.2.2 养殖场地理信息
- 基于百度地图API的养殖场位置标注
- 养殖场地理围栏设置
- 区域养殖密度可视化展示
### 4.3 养殖环境监控模块
#### 4.3.1 实时数据监控
- 温度、湿度等环境参数实时展示
- 异常数据预警功能
- 历史数据趋势分析
#### 4.3.2 设备管理
- 传感器设备信息管理
- 设备状态监控
- 设备故障报警
### 4.4 养殖过程管理模块
#### 4.4.1 饲料管理
- 饲料种类信息维护
- 饲料投喂记录管理
- 饲料库存管理
#### 4.4.2 疫苗管理
- 疫苗信息维护
- 疫苗接种记录管理
- 疫苗批次追踪
#### 4.4.3 养殖档案
- 养殖动物个体信息管理
- 生长过程记录
- 出栏信息管理
### 4.5 产品管理模块
#### 4.5.1 产品信息管理
- 产品基本信息维护
- 产品质量标准设定
- 产品批次管理
#### 4.5.2 库存管理
- 产品入库管理
- 产品出库管理
- 库存预警功能
### 4.6 数据分析与报表模块
#### 4.6.1 数据可视化
- 基于ECharts的数据图表展示
- 实时监控大屏
- 历史数据趋势分析
#### 4.6.2 报表生成
- 养殖统计报表
- 销售分析报表
- 监管合规报表
- 自定义报表功能
### 4.7 系统管理模块
#### 4.7.1 系统配置
- 系统参数配置
- 字典数据管理
- 系统日志管理
#### 4.7.2 权限管理
- 角色权限配置
- 菜单权限管理
- 数据权限控制
## 5. 接口设计
### 5.1 通用API规范
#### 5.1.1 响应格式
所有API响应遵循统一格式：
```json
{
"success": true,
"data": {},
"message": "操作成功",
"timestamp": "2025-01-18T10:30:00Z"
}
```
#### 5.1.2 错误处理
- HTTP状态码：4xx客户端错误，5xx服务端错误
- 错误信息：中英文错误描述
- 错误日志：记录详细错误信息
#### 5.1.3 认证机制
- Authorization: Bearer <token>
- Token过期：401 Unauthorized
- 权限不足：403 Forbidden
### 5.2 用户认证接口
- **POST /api/auth/login** - 用户登录
- 请求体：{username, password}
- 响应：JWT令牌和用户信息
- **POST /api/auth/logout** - 用户登出
- 请求头：Authorization: Bearer <token>
- 响应：登出成功消息
- **POST /api/auth/register** - 用户注册
- 请求体：{username, email, password}
- 响应：注册成功消息
### 5.3 用户管理接口
- **GET /api/users** - 获取用户列表（需要admin权限）
- 查询参数：page, limit, search
- 响应：用户列表分页数据
- **GET /api/users/{id}** - 获取用户详情（需要认证）
- 路径参数：用户ID
- 响应：用户详细信息
- **POST /api/users** - 创建用户（需要admin权限）
- 请求体：用户信息
- 响应：创建的用户信息
- **PUT /api/users/{id}** - 更新用户信息（需要认证）
- 路径参数：用户ID
- 请求体：更新字段
- 响应：更新后的用户信息
- **DELETE /api/users/{id}** - 删除用户（需要admin权限）
- 路径参数：用户ID
- 响应：删除成功消息
### 5.4 养殖场管理接口
- **GET /api/farms** - 获取养殖场列表（需要认证）
- 查询参数：page, limit, type, status
- 响应：养殖场列表分页数据
- **GET /api/farms/{id}** - 获取养殖场详情（需要认证）
- 路径参数：养殖场ID
- 响应：养殖场详细信息
- **POST /api/farms** - 创建养殖场（需要manager权限）
- 请求体：养殖场信息（包含地理位置JSON）
- 响应：创建的养殖场信息
- **PUT /api/farms/{id}** - 更新养殖场信息（需要manager权限）
- 路径参数：养殖场ID
- 请求体：更新字段
- 响应：更新后的养殖场信息
- **DELETE /api/farms/{id}** - 删除养殖场（需要admin权限）
- 路径参数：养殖场ID
- 响应：删除成功消息
### 5.5 设备管理接口
- **GET /api/devices** - 获取设备列表（需要认证）
- 查询参数：page, limit, farm_id, type, status
- 响应：设备列表分页数据
- **GET /api/devices/{id}** - 获取设备详情（需要认证）
- 路径参数：设备ID
- 响应：设备详细信息（包含实时指标数据）
- **POST /api/devices** - 创建设备（需要manager权限）
- 请求体：设备信息
- 响应：创建设备信息
- **PUT /api/devices/{id}** - 更新设备信息（需要manager权限）
- 路径参数：设备ID
- 请求体：更新字段
- 响应：更新后的设备信息
- **DELETE /api/devices/{id}** - 删除设备（需要admin权限）
- 路径参数：设备ID
- 响应：删除成功消息
### 5.6 预警管理接口
- **GET /api/alerts** - 获取预警列表（需要认证）
- 查询参数：page, limit, farm_id, level, status
- 响应：预警列表分页数据
- **GET /api/alerts/{id}** - 获取预警详情（需要认证）
- 路径参数：预警ID
- 响应：预警详细信息
- **PUT /api/alerts/{id}/acknowledge** - 确认预警（需要manager权限）
- 路径参数：预警ID
- 响应：确认成功消息
- **PUT /api/alerts/{id}/resolve** - 解决预警（需要manager权限）
- 路径参数：预警ID
- 请求体：解决说明
- 响应：解决成功消息
### 5.7 产品管理接口
- **GET /api/products** - 获取产品列表（需要认证）
- 查询参数：page, limit, search
- 响应：产品列表分页数据
- **GET /api/products/{id}** - 获取产品详情（需要认证）
- 路径参数：产品ID
- 响应：产品详细信息
- **POST /api/products** - 创建产品（需要manager权限）
- 请求体：产品信息
- 响应：创建的产品信息
- **PUT /api/products/{id}** - 更新产品信息（需要manager权限）
- 路径参数：产品ID
- 请求体：更新字段
- 响应：更新后的产品信息
- **DELETE /api/products/{id}** - 删除产品（需要admin权限）
- 路径参数：产品ID
- 响应：删除成功消息
### 5.8 统计分析接口
- **GET /api/stats/overview** - 获取系统概览统计（需要认证）
- 响应：养殖场数、设备数、动物数、预警数等
- **GET /api/stats/farms/{id}** - 获取养殖场统计（需要认证）
- 路径参数：养殖场ID
- 响应：养殖场详细统计数据
- **GET /api/stats/alerts** - 获取预警统计（需要认证）
- 查询参数：timeRange（今日、本周、本月）
- 响应：预警级别分布统计
- **GET /api/stats/animals** - 获取动物健康统计（需要认证）
- 查询参数：farm_id
- 响应：动物健康状态分布
## 6. 安全设计
### 6.1 认证安全
- 用户密码加密存储（BCrypt等）
- JWT令牌机制
- 登录失败次数限制
- 会话超时管理
### 6.2 接口安全
- HTTPS协议支持
- 接口访问权限控制
- 请求参数校验
- SQL注入防护
### 6.3 数据安全
- 敏感数据加密存储
- 数据备份策略
- 数据访问日志记录
## 7. 性能优化
### 7.1 前端优化
- 组件懒加载
- 图片压缩与懒加载
- 数据缓存机制
- 防抖节流处理
### 7.2 后端优化
- 数据库索引优化
- 接口缓存机制
- 数据库连接池
- 异步任务处理
### 7.3 数据库优化
- 查询语句优化
- 表结构设计优化
- 分表分库策略
## 8. 部署方案
### 8.1 开发环境
- 本地开发环境搭建
- 开发调试工具配置
- 代码版本管理
### 8.2 生产环境
- Docker容器化部署
- Nginx反向代理配置
- 负载均衡方案
- 监控告警机制
## 9. 扩展性设计
### 9.1 模块化扩展
- 支持功能模块的独立开发和部署
- 微服务架构兼容性设计
### 9.2 第三方服务集成
- 易于集成物联网设备数据
- 支持与其他监管系统对接
- 开放API接口设计
## 10. 后续发展规划
1. 引入微服务架构，提升系统可扩展性
2. 优化性能监控，提升系统稳定性
3. 增强数据分析能力，提供更深入的业务洞察
4. 完善移动端支持，提供更便捷的操作体验
5. 集成人工智能技术，实现智能预警和决策支持