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

修改文件结构，统一文档格式

Browse Source
This commit is contained in:
ylweng
2025-09-02 23:22:10 +08:00
parent 02fe7d11da
commit 6b4e0c227f
85 changed files with 5501 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

894
docs/API.md Normal file
View File

@@ -0,0 +1,894 @@
# 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 <your_jwt_token>
```
### 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月*

266
docs/CHANGELOG.md Normal file
View File

@@ -0,0 +1,266 @@
# 更新日志
所有项目的重要变更都将记录在此文件中。
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范。
## [未发布]
### 新增
- 完善项目文档体系
- 创建故障排除指南
- 添加开发指南和API文档
### 变更
- 优化项目目录结构
- 更新README文档
### 修复
- 修复经纬度数据同步问题
- 解决地图组件显示异常
## [1.2.0] - 2025-01-18
### 新增
- **性能监控系统**: 全新的系统性能监控功能
- 实时监控 CPU、内存、磁盘使用情况
- 数据库性能监控和慢查询分析
- API 响应时间统计和错误率监控
- 可配置的警报阈值系统
- **虚拟滚动组件**: 优化大数据量列表显示性能
- **图表性能监控**: 基于 ECharts 的性能指标可视化
- **地图缩放演示**: 多级缩放功能展示
### 变更
- **前端架构升级**:
- Vue 3.4+ 升级，提升响应性能
- Ant Design Vue 4.0+ 组件库更新
- Pinia 2.0+ 状态管理重构
- **后端优化**:
- 数据库连接池优化
- API 响应时间提升 30%
- 新增查询优化器
### 修复
- 修复百度地图 API 密钥配置问题
- 解决设备状态更新延迟问题
- 修复用户权限验证逻辑错误
- 优化内存泄漏问题
### 安全
- 加强 JWT Token 验证机制
- 更新密码加密算法强度
- 添加 API 请求频率限制
## [1.1.0] - 2024-12-15
### 新增
- **农场管理功能**:
- 农场信息 CRUD 操作
- 地理位置管理和地图展示
- 农场状态监控
- **动物健康管理**:
- 动物信息记录和追踪
- 健康状态监控
- 检查记录管理
- **设备监控系统**:
- 设备状态实时监控
- 设备指标数据收集
- 设备维护记录
- **预警管理**:
- 多级别预警系统
- 预警处理流程
- 预警统计分析
### 变更
- 数据库架构优化，支持更复杂的业务关系
- API 接口标准化，统一响应格式
- 前端路由结构重构
### 修复
- 修复数据库外键约束问题
- 解决前端路由跳转异常
- 优化 API 错误处理机制
## [1.0.0] - 2024-11-01
### 新增
- **核心系统架构**:
- Node.js + Express 后端服务
- Vue 3 + Vite 前端框架
- MySQL 数据库支持
- Sequelize ORM 集成
- **用户认证系统**:
- JWT 基础认证
- 角色权限管理
- 用户注册和登录
- **基础 CRUD 功能**:
- 用户管理
- 产品管理
- 订单管理
- **系统基础设施**:
- 日志系统 (Winston)
- API 文档 (Swagger)
- 数据库迁移和种子数据
- 环境配置管理
### 技术栈
- **后端**: Node.js 18+, Express 4.18+, Sequelize 6.30+
- **前端**: Vue 3.4+, Ant Design Vue 4.0+, Vite 5.0+
- **数据库**: MySQL 8.0+
- **工具**: ESLint, Prettier, PM2
## 版本命名规范
我们采用语义化版本控制 (SemVer) 格式：`主版本号.次版本号.修订号`
- **主版本号**: 不兼容的 API 修改
- **次版本号**: 向下兼容的功能性新增
- **修订号**: 向下兼容的问题修正
### 变更类型说明
- `新增` - 新增功能
- `变更` - 对现有功能的变更
- `废弃` - 即将移除的功能
- `移除` - 已移除的功能
- `修复` - 问题修复
- `安全` - 安全相关的修复
## 升级指南
### 从 1.1.0 升级到 1.2.0
#### 数据库更新
```sql
-- 添加性能监控相关表
-- 运行迁移脚本
npm run db:migrate
```
#### 配置更新
```bash
# 添加新的环境变量
ENABLE_PERFORMANCE_MONITORING=true
PERFORMANCE_LOG_LEVEL=info
```
#### 依赖更新
```bash
# 更新前端依赖
cd admin-system/frontend
npm update vue@^3.4.0
npm update ant-design-vue@^4.0.0
# 更新后端依赖
cd ../../backend
npm update
```
### 从 1.0.0 升级到 1.1.0
#### 数据库迁移
```sql
-- 添加农场管理相关表
CREATE TABLE farms (...);
CREATE TABLE animals (...);
CREATE TABLE devices (...);
CREATE TABLE alerts (...);
```
#### 配置变更
```bash
# 添加百度地图 API 配置
BAIDU_MAP_API_KEY=your_api_key_here
```
## 已知问题
### v1.2.0
- 性能监控在高并发情况下可能影响系统性能
- 某些旧版本浏览器可能不支持新的前端特性
### v1.1.0
- 百度地图在某些网络环境下加载较慢
- 大数据量查询时可能出现超时
### v1.0.0
- 初始版本，功能相对基础
- 部分边界情况处理不够完善
## 兼容性支持
### 浏览器支持
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
### Node.js 版本支持
- Node.js 18.x (推荐)
- Node.js 16.x (最低要求)
### 数据库版本支持
- MySQL 8.0+ (推荐)
- MySQL 5.7+ (最低要求)
## 贡献指南
我们欢迎社区贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何参与项目开发。
### 报告问题
如果您发现问题，请在 GitHub Issues 中创建新的问题报告，并包含：
- 问题描述
- 复现步骤
- 预期行为
- 实际行为
- 环境信息
### 提交代码
1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交变更 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request
## 技术路线图
### v1.3.0 (计划中)
- [ ] 微服务架构重构
- [ ] 实时数据推送 (WebSocket)
- [ ] 移动端适配优化
- [ ] 多语言支持
### v1.4.0 (规划中)
- [ ] 人工智能预警系统
- [ ] 大数据分析平台
- [ ] 第三方系统集成
- [ ] 高可用架构升级
### v2.0.0 (远期规划)
- [ ] 云原生架构
- [ ] 容器化部署
- [ ] 多租户支持
- [ ] 国际化部署
## 致谢
感谢所有为项目做出贡献的开发者和用户！
### 主要贡献者
- 项目架构设计团队
- 前端开发团队
- 后端开发团队
- 测试团队
- 文档团队
### 特别感谢
- 宁夏农业部门的需求指导
- 养殖户的实际使用反馈
- 技术社区的开源支持
---
*如需查看完整的提交历史，请访问项目的 Git 日志: `git log --oneline`*
*最后更新: 2025年1月*

594
docs/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,594 @@
# 贡献指南
## 欢迎贡献
我们热烈欢迎社区开发者为宁夏智慧养殖监管平台做出贡献！无论您是想修复bug、添加新功能、改进文档，还是提供反馈建议，我们都非常感谢您的参与。
## 目录
- [开始之前](#开始之前)
- [如何贡献](#如何贡献)
- [开发环境搭建](#开发环境搭建)
- [代码贡献流程](#代码贡献流程)
- [代码规范](#代码规范)
- [提交规范](#提交规范)
- [Pull Request 指南](#pull-request-指南)
- [问题报告](#问题报告)
- [文档贡献](#文档贡献)
- [社区行为准则](#社区行为准则)
## 开始之前
### 阅读项目文档
在开始贡献之前，请确保您已经阅读并理解了以下文档：
- [README.md](README.md) - 项目概述
- [DEVELOPMENT.md](DEVELOPMENT.md) - 开发指南
- [API.md](API.md) - API 文档
- [架构文档](arch.md) - 系统架构
### 了解项目状态
- 查看 [Issues](https://github.com/your-org/nxxmdata/issues) 了解当前需要解决的问题
- 查看 [Projects](https://github.com/your-org/nxxmdata/projects) 了解项目路线图
- 查看 [CHANGELOG.md](CHANGELOG.md) 了解最新变更
## 如何贡献
您可以通过以下方式为项目做出贡献：
### 🐛 报告 Bug
- 发现了系统错误或异常行为
- 遇到了文档中的错误或不清楚的地方
- 发现了安全漏洞（请通过私密渠道报告）
### 💡 提出功能建议
- 提出新的功能想法
- 建议改进现有功能
- 提出用户体验优化建议
### 📝 改进文档
- 修复文档中的错误
- 添加缺失的文档
- 改进文档的清晰度和准确性
- 翻译文档到其他语言
### 💻 贡献代码
- 修复已知的 bug
- 实现新功能
- 优化性能
- 重构代码
- 添加测试用例
### 🎨 设计贡献
- 改进用户界面设计
- 提供图标和图片资源
- 优化用户体验
## 开发环境搭建
### 前置要求
- Node.js 18.0+
- npm 8.0+ 或 yarn 1.22+
- MySQL 8.0+
- Git 2.25+
### 克隆项目
```bash
# 1. Fork 项目到您的 GitHub 账户
# 2. 克隆您的 fork
git clone https://github.com/YOUR_USERNAME/nxxmdata.git
cd nxxmdata
# 3. 添加上游仓库
git remote add upstream https://github.com/original-org/nxxmdata.git
```
### 安装依赖
```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
```
### 配置环境
```bash
# 复制环境配置文件
cd backend
cp .env.example .env
cd ../admin-system/frontend
cp .env.example .env
# 编辑配置文件，设置数据库连接等信息
```
### 初始化数据库
```bash
cd backend
# 创建数据库
mysql -u root -p -e "CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 运行迁移
npm run db:migrate
# 填充种子数据
npm run db:seed
```
### 启动开发服务器
```bash
# 启动后端服务
cd backend
npm run dev
# 启动前端服务（新终端）
cd admin-system/frontend
npm run dev
# 启动官网大屏（新终端）
cd website/data-screen
npm run dev
```
## 代码贡献流程
### 1. 选择或创建 Issue
- 查看现有的 [Issues](https://github.com/your-org/nxxmdata/issues)
- 选择标记为 `good first issue` 的问题（适合新手）
- 如果是新功能，请先创建 Issue 讨论
### 2. 创建分支
```bash
# 更新主分支
git checkout main
git pull upstream main
# 创建功能分支
git checkout -b feature/your-feature-name
# 或者修复分支
git checkout -b fix/bug-description
```
### 3. 开发代码
- 编写代码
- 添加或更新测试
- 更新相关文档
- 确保代码符合项目规范
### 4. 测试代码
```bash
# 运行单元测试
npm test
# 运行集成测试
npm run test:integration
# 运行端到端测试
npm run test:e2e
# 检查代码风格
npm run lint
# 修复代码风格问题
npm run lint:fix
```
### 5. 提交代码
```bash
# 添加变更文件
git add .
# 提交代码（遵循提交信息规范）
git commit -m "feat: add user profile management feature"
# 推送到您的 fork
git push origin feature/your-feature-name
```
### 6. 创建 Pull Request
- 在 GitHub 上创建 Pull Request
- 填写 PR 模板中的所有必要信息
- 等待代码审查
## 代码规范
### JavaScript/TypeScript 规范
#### 命名约定
```javascript
// 变量和函数使用 camelCase
const userName = 'john_doe';
function getUserInfo() {}
// 常量使用 UPPER_SNAKE_CASE
const API_BASE_URL = 'http://localhost:5350';
// 类名使用 PascalCase
class UserService {}
// 文件名使用 kebab-case
// user-service.js, farm-detail.vue
```
#### 代码风格
```javascript
// 使用 const/let，避免 var
const config = {...};
let mutableData = [];
// 使用箭头函数
const processData = (data) => {
return data.map(item => item.value);
};
// 使用模板字符串
const message = `Hello, ${userName}!`;
// 使用对象解构
const { name, email } = user;
// 使用扩展运算符
const newArray = [...oldArray, newItem];
```
#### 错误处理
```javascript
// 使用 try-catch 处理异步错误
try {
const result = await api.fetchData();
return result;
} catch (error) {
logger.error('Failed to fetch data:', error);
throw new Error('Data fetch failed');
}
// 返回 Promise 的函数应该处理所有可能的错误
async function createUser(userData) {
try {
const user = await User.create(userData);
return { success: true, data: user };
} catch (error) {
return { success: false, error: error.message };
}
}
```
### Vue.js 组件规范
```vue
<template>
<div class="component-name">
<!-- 使用语义化的 HTML 标签 -->
<header class="component-header">
<h1>{{ title }}</h1>
</header>
<!-- 事件处理使用 handle 前缀 -->
<button @click="handleSubmit">提交</button>
</div>
</template>
<script>
import { ref, computed, onMounted } from 'vue'
export default {
name: 'ComponentName', // 组件名使用 PascalCase
props: {
title: {
type: String,
required: true,
default: ''
}
},
emits: ['submit'],
setup(props, { emit }) {
// 响应式数据
const isLoading = ref(false)
// 计算属性
const displayTitle = computed(() => {
return props.title.toUpperCase()
})
// 方法
const handleSubmit = () => {
emit('submit')
}
// 生命周期
onMounted(() => {
// 初始化逻辑
})
return {
isLoading,
displayTitle,
handleSubmit
}
}
}
</script>
<style scoped>
.component-name {
/* 使用 BEM 命名法 */
}
.component-header {
/* 样式规则 */
}
</style>
```
### CSS/SCSS 规范
```css
/* 使用 BEM 命名法 */
.block {}
.block__element {}
.block--modifier {}
/* 使用语义化的类名 */
.button--primary {}
.form__input--error {}
/* 避免深层嵌套 */
.component {
.header {} /* 最多 3 层嵌套 */
}
```
## 提交规范
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
### 提交消息格式
```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
### 类型 (type)
- `feat`: 新增功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整（不影响代码逻辑）
- `refactor`: 重构（既不是新增功能也不是修复 bug）
- `perf`: 性能优化
- `test`: 添加或修改测试
- `chore`: 构建过程或辅助工具的变动
- `ci`: CI/CD 相关变更
### 范围 (scope)
- `api`: API 相关
- `ui`: 用户界面
- `auth`: 认证相关
- `db`: 数据库相关
- `config`: 配置相关
### 示例
```bash
feat(api): add user profile update endpoint
fix(ui): resolve map display issue on mobile devices
docs(readme): update installation instructions
style(frontend): format code with prettier
refactor(auth): simplify token validation logic
perf(db): optimize farm data query performance
test(api): add unit tests for user controller
chore(deps): update vue to version 3.4.0
```
### 破坏性变更
```bash
feat(api)!: change user authentication method
BREAKING CHANGE: JWT token format has changed
```
## Pull Request 指南
### PR 标题
PR 标题应该简洁明了地描述变更内容，遵循提交信息规范：
```
feat(user): add profile management feature
fix(map): resolve coordinate display issue
docs: update API documentation
```
### PR 描述模板
```markdown
## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
- [ ] 其他: ____________
## 变更描述
<!-- 简要描述这个 PR 的变更内容 -->
## 相关 Issue
<!-- 如果有相关的 Issue，请在此链接 -->
Closes #123
## 测试
- [ ] 我已经测试了我的代码
- [ ] 我已经添加了测试用例
- [ ] 所有测试都通过了
## 检查清单
- [ ] 我的代码遵循项目的代码规范
- [ ] 我已经进行了自我代码审查
- [ ] 我已经添加了必要的注释
- [ ] 我已经更新了相关文档
- [ ] 我的变更不会产生新的警告
- [ ] 我已经添加了适当的测试
- [ ] 新功能和修复都有对应的测试
## 截图（如果适用）
<!-- 如果是 UI 相关的变更，请添加截图 -->
## 额外说明
<!-- 任何其他需要说明的内容 -->
```
### 代码审查
- 所有 PR 都需要至少一个审查者的批准
- 解决所有审查意见后才能合并
- 保持代码变更的原子性和逻辑性
- 确保 CI/CD 检查通过
## 问题报告
### Bug 报告
使用 Bug 报告模板创建 Issue：
```markdown
**问题描述**
简要描述遇到的问题。
**复现步骤**
1. 进入 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误
**预期行为**
描述您期望发生的行为。
**实际行为**
描述实际发生的行为。
**截图**
如果适用，添加截图来帮助解释您的问题。
**环境信息:**
- 操作系统: [例如 macOS 12.0]
- 浏览器: [例如 Chrome 95.0]
- Node.js 版本: [例如 18.12.0]
- 项目版本: [例如 1.2.0]
**附加信息**
添加任何其他有关问题的信息。
```
### 功能请求
```markdown
**功能描述**
简要描述您想要的功能。
**问题解决**
这个功能解决了什么问题？
**解决方案**
描述您想要的解决方案。
**备选方案**
描述您考虑过的任何备选解决方案或功能。
**附加信息**
添加任何其他关于功能请求的信息或截图。
```
## 文档贡献
### 文档类型
- **用户文档**: README, 安装指南, 使用教程
- **开发者文档**: API 文档, 开发指南, 架构文档
- **运维文档**: 部署指南, 故障排除, 监控指南
### 文档写作规范
- 使用清晰、简洁的语言
- 提供具体的示例和代码片段
- 包含必要的截图和图表
- 保持文档的时效性
- 使用统一的格式和风格
### 文档更新流程
1. 识别需要更新的文档
2. 创建文档分支 `docs/update-api-guide`
3. 更新文档内容
4. 提交并创建 PR
5. 经过审查后合并
## 社区行为准则
### 我们的承诺
为了营造一个开放和受欢迎的环境，我们作为贡献者和维护者承诺：无论年龄、体型、身体健全或残疾、民族、性别特征、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何，参与我们项目和社区的每个人都享有无骚扰的体验。
### 我们的标准
有助于创造积极环境的行为包括：
- 使用受欢迎和包容性的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同情
不可接受的行为包括：
- 使用性化的语言或图像以及不受欢迎的性关注或求爱
- 捣乱、侮辱/贬损评论以及个人或政治攻击
- 公开或私下骚扰
- 未经明确许可发布他人的私人信息
- 在专业环境中可能被合理认为不适当的其他行为
### 报告
如果您遇到不当行为，请联系项目团队：
- 邮箱: conduct@nxxmdata.com
- 我们将认真对待所有报告并进行调查
## 获得帮助
### 联系方式
- **技术问题**: 在 GitHub Issues 中提问
- **功能讨论**: 在 GitHub Discussions 中讨论
- **安全问题**: 发送邮件到 security@nxxmdata.com
- **其他问题**: 发送邮件到 hello@nxxmdata.com
### 社区资源
- [GitHub 仓库](https://github.com/your-org/nxxmdata)
- [项目文档](https://docs.nxxmdata.com)
- [API 文档](https://api.nxxmdata.com/docs)
## 认可贡献者
我们感谢所有为项目做出贡献的人！贡献者将被列在：
- [CONTRIBUTORS.md](CONTRIBUTORS.md) 文件中
- 项目的 README 中
- 每次发布的致谢中
### 贡献类型
我们认可以下类型的贡献：
- 💻 代码贡献
- 📖 文档贡献
- 🎨 设计贡献
- 🐛 Bug 报告
- 💡 想法和建议
- 🤔 答疑解惑
- 📢 推广项目
## 许可证
通过向此项目贡献代码，您同意您的贡献将在与项目相同的许可证下被许可。
---
再次感谢您对宁夏智慧养殖监管平台的关注和贡献！我们期待与您一起构建更好的系统。
*最后更新: 2025年1月*

630
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,630 @@
# 宁夏智慧养殖监管平台部署指南
## 概述
本文档详细说明了宁夏智慧养殖监管平台的部署流程，包括开发环境、测试环境和生产环境的部署方案。
## 系统要求
### 基础要求
- **操作系统**: 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 <repository-url>
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 <repository-url>
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 <commit-hash>
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月*

932
docs/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,932 @@
# 开发指南
## 概述
本文档为开发者提供宁夏智慧养殖监管平台的详细开发指南，包括开发环境搭建、代码规范、开发流程、调试技巧等内容。
## 开发环境搭建
### 系统要求
- **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 <repository-url>
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
<template>
<!-- 1. 模板根元素必须有唯一的根节点 -->
<div class="component-name">
<!-- 2. 使用语义化的HTML标签 -->
<header class="component-header">
<h1>{{ title }}</h1>
</header>
<main class="component-content">
<!-- 3. 事件处理使用 handle 前缀 -->
<button @click="handleSubmit">提交</button>
</main>
</div>
</template>
<script>
import { ref, computed, onMounted } from 'vue'
export default {
name: 'ComponentName', // 4. 组件名使用 PascalCase
props: {
// 5. Props 定义要详细
title: {
type: String,
required: true,
default: ''
}
},
emits: ['submit'], // 6. 声明所有 emit 事件
setup(props, { emit }) {
// 7. 响应式数据使用 ref 或 reactive
const isLoading = ref(false)
// 8. 计算属性使用 computed
const displayTitle = computed(() => {
return props.title.toUpperCase()
})
// 9. 方法使用 handle 前缀
const handleSubmit = () => {
emit('submit')
}
// 10. 生命周期钩子
onMounted(() => {
// 组件挂载后的逻辑
})
return {
isLoading,
displayTitle,
handleSubmit
}
}
}
</script>
<style scoped>
/* 11. 样式使用 scoped 避免污染 */
.component-name {
/* 12. 使用 BEM 命名法 */
}
</style>
```
#### 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
<template>
<!-- 图片懒加载 -->
<img v-lazy="imageUrl" alt="Farm image">
<!-- 响应式图片 -->
<picture>
<source media="(min-width: 800px)" :srcset="largeImage">
<img :src="smallImage" alt="Farm">
</picture>
</template>
```
##### 3. 虚拟滚动
```vue
<template>
<!-- 大列表虚拟滚动 -->
<virtual-scroll
:items="farms"
:item-height="60"
#default="{ item }"
>
<farm-item :farm="item" />
</virtual-scroll>
</template>
```
### 测试指南
#### 单元测试
##### 后端单元测试 (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 <PID>
taskkill /PID <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月*

180
docs/FINAL_STRUCTURE_REPORT.md Normal file
View File

@@ -0,0 +1,180 @@
# 项目文件结构最终调整报告
## 📋 本次调整概述
根据用户最新要求，对项目文件结构进行了最终调整，确保完全符合以下规范：
- **backend** - 后端目录
- **admin-system** - 管理后台
- **website** - 官网
- **mini_program** - 微信小程序矩阵目录
- **docs** - 文档目录
- **test** - 测试文件目录
- **scripts** - 执行脚本目录
## 🔄 本次调整内容
### 1. 文档文件整理
**从根目录迁移到docs目录：**
- `arch.md` → `docs/architecture.md` (系统架构设计文档)
- `design.md` → `docs/design.md` (详细设计文档)
- `dev-plan.md` → `docs/development-plan.md` (开发计划文档)
- `task.md` → `docs/task-list.md` (任务清单文档)
### 2. SQL脚本整理
**从根目录迁移到scripts/database目录：**
- `create_tables.sql` → `scripts/database/create_tables.sql` (完整数据库表结构)
- `schema.sql` → `scripts/database/schema.sql` (基础数据库结构)
**新建目录：**
- 创建 `scripts/database/` 目录用于存放数据库相关脚本
### 3. 示例代码整理
**迁移示例代码：**
- `examples/performance-monitor-integration.js` → `docs/examples/performance-monitor-integration.js`
- 删除空的 `examples/` 目录
**新建目录：**
- 创建 `docs/examples/` 目录用于存放示例代码
### 4. 文档索引更新
**更新 scripts/README.md：**
- 添加了 `database/` 子目录的说明
- 新增数据库脚本文件的索引
- 更新脚本使用说明
**更新 docs/README.md：**
- 新增"项目设计"分类，包含架构、设计、开发计划等文档
- 新增"示例代码"分类，包含各种功能集成示例
- 扩展文档分类说明，提供更好的导航
## ✅ 最终项目结构
```
nxxmdata/
├── backend/ # 后端目录 ✅
│ ├── config/ # 配置文件
│ ├── controllers/ # 控制器
│ ├── middleware/ # 中间件
│ ├── migrations/ # 数据库迁移
│ ├── models/ # 数据模型
│ ├── routes/ # 路由定义
│ ├── seeds/ # 种子数据
│ ├── tools/ # 工具脚本(已分类)
│ ├── utils/ # 工具函数
│ ├── package.json # 依赖配置
│ └── server.js # 服务器入口
│
├── admin-system/ # 管理后台 ✅
│ └── frontend/ # 前端代码
│
├── website/ # 官网 ✅
│ └── data-screen/ # 数据大屏
│
├── mini_program/ # 微信小程序矩阵目录 ✅
│ └── farm-monitor-dashboard/ # 农场监控小程序
│
├── docs/ # 文档目录 ✅
│ ├── examples/ # 🆕 示例代码
│ │ └── performance-monitor-integration.js
│ ├── architecture.md # 🆕 系统架构文档
│ ├── design.md # 🆕 详细设计文档
│ ├── development-plan.md # 🆕 开发计划文档
│ ├── task-list.md # 🆕 任务清单文档
│ ├── baidu-map-license.md # 百度地图授权方案
│ ├── performance-monitoring.md # 性能监控文档
│ ├── data-sync-fix-report.md # 数据同步报告
│ ├── farms-data-import-summary.md # 农场导入总结
│ ├── location-data-validation-report.md # 位置验证报告
│ └── README.md # 📝 文档索引(已更新)
│
├── test/ # 测试文件目录 ✅
│ ├── performance-monitor-test.js # 性能监控测试
│ └── README.md # 测试说明
│
├── scripts/ # 执行脚本目录 ✅
│ ├── database/ # 🆕 数据库脚本
│ │ ├── create_tables.sql # 🆕 完整表结构
│ │ └── schema.sql # 🆕 基础结构
│ ├── init-db.js # 数据库初始化
│ ├── migration-manager.js # 迁移管理
│ ├── seed-manager.js # 种子数据管理
│ ├── test-connection.js # 连接测试
│ ├── test-map-api.js # 地图API测试
│ └── README.md # 📝 脚本说明(已更新)
│
└── 根目录文档 # 项目核心文档
├── README.md # 项目概览
├── API.md # API文档
├── DEPLOYMENT.md # 部署指南
├── DEVELOPMENT.md # 开发指南
├── TROUBLESHOOTING.md # 故障排除
├── CHANGELOG.md # 更新日志
├── CONTRIBUTING.md # 贡献指南
├── SECURITY.md # 安全指南
├── PRD.md # 产品需求文档
└── PROJECT_CLEANUP_REPORT.md # 整理报告
```
## 📊 调整统计
### 文件移动记录
- **文档文件移动**: 4个文件从根目录迁移到docs目录
- **SQL脚本移动**: 2个文件从根目录迁移到scripts/database目录
- **示例代码移动**: 1个文件迁移到docs/examples目录
- **空目录清理**: 删除了空的examples目录
### 新建目录
- `scripts/database/` - 数据库脚本目录
- `docs/examples/` - 示例代码目录
### 文档更新
- 更新 `scripts/README.md` - 添加database子目录说明
- 更新 `docs/README.md` - 新增设计文档和示例代码分类
## ✅ 验证结果
**目录结构符合性检查：**
- ✅ backend (后端目录) - 符合要求
- ✅ admin-system (管理后台) - 符合要求
- ✅ website (官网) - 符合要求
- ✅ mini_program (微信小程序矩阵目录) - 符合要求
- ✅ docs (文档目录) - 符合要求
- ✅ test (测试文件目录) - 符合要求
- ✅ scripts (执行脚本目录) - 符合要求
**根目录清洁度：**
- ✅ 所有散落的技术文档已整理到docs目录
- ✅ 所有SQL脚本已整理到scripts/database目录
- ✅ 保留了必要的核心项目文档
- ✅ 保持了清晰的根目录结构
## 🎯 整理价值
本次最终调整实现了：
1. **🎯 完全合规**: 项目结构100%符合用户指定的目录规范
2. **📁 分类明确**: 所有文件都在正确的功能目录中
3. **📚 文档集中**: 技术文档统一管理，便于维护
4. **🔧 脚本整理**: 数据库脚本独立分类，便于运维
5. **📝 索引完善**: 各目录都有详细的README说明
## 🎉 最终状态
经过本次调整，宁夏智慧养殖监管平台项目现在拥有：
- ✅ **标准化目录结构**: 完全符合既定规范
- ✅ **清晰的文件分类**: 每个文件都在正确位置
- ✅ **完整的文档体系**: 技术文档集中管理
- ✅ **规范的脚本组织**: 数据库脚本独立分类
- ✅ **便于维护的结构**: 清晰的导航和索引
项目文件结构调整工作现已全面完成！🎉
---
*报告生成时间: 2025年1月*
*调整完成状态: ✅ 完成*

340
docs/PRD.md Normal file
View File

@@ -0,0 +1,340 @@
# 宁夏智慧养殖监管平台产品需求文档
## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2025-01-18 | 产品经理 | 初始版本 |
## 1. 项目概述
### 1.1 项目背景
宁夏回族自治区作为中国重要的畜牧业基地，养殖业在区域经济发展中占据重要地位。随着现代信息技术的快速发展，传统养殖业正逐步向智能化、数字化方向转型升级。为提升宁夏地区养殖业的管理水平和监管效率，建设一套完善的智慧养殖监管平台势在必行。
### 1.2 项目目标
宁夏智慧养殖监管平台旨在通过数字化手段实现对养殖全过程的监管，具体目标包括：
- 实现养殖场信息数字化管理
- 提供养殖环境实时监控功能
- 支持养殖过程数据记录与追溯
- 提供数据分析和决策支持
- 构建统一的养殖监管体系
### 1.3 成功标准
- 用户日活跃度提升20%
- 养殖场管理效率提升30%
- 异常预警响应时间缩短至5分钟内
- 系统可用性达到99.9%
### 1.4 范围界定
**本版本包含：**
- 用户权限管理系统
- 养殖场信息管理
- 设备监控管理
- 动物健康管理
- 预警管理系统
- 数据可视化展示
**本版本不包含：**
- 移动端小程序功能（二期规划）
- 人工智能预警功能（三期规划）
- 微服务架构改造（后续版本）
## 2. 用户角色与用例
### 2.1 用户角色
| 角色 | 描述 | 权限范围 |
|------|------|----------|
| 系统管理员 | 负责系统整体管理和维护 | 全系统权限，用户管理，系统配置 |
| 养殖场管理员 | 负责具体养殖场的管理 | 养殖场信息管理，设备监控，动物管理 |
| 监管人员 | 负责区域养殖监管 | 数据查看，预警处理，报表分析 |
| 普通用户 | 基础系统使用者 | 个人信息管理，数据查看 |
### 2.2 核心用例
#### 用例1：用户登录认证
**As a** 系统用户
**I want to** 通过账号密码登录系统
**So that** 我可以访问系统功能
**验收标准：**
- Given 用户打开登录页面
- When 输入正确的用户名和密码
- Then 系统跳转到仪表盘页面
- And 显示欢迎信息
#### 用例2：养殖场信息管理
**As a** 养殖场管理员
**I want to** 管理养殖场基本信息
**So that** 我可以维护养殖场档案
**验收标准：**
- Given 用户有养殖场管理权限
- When 进入养殖场管理页面
- Then 可以查看养殖场列表
- And 可以新增、编辑、删除养殖场信息
#### 用例3：实时设备监控
**As a** 监管人员
**I want to** 实时查看设备状态
**So that** 我可以及时发现设备异常
**验收标准：**
- Given 用户有设备查看权限
- When 进入设备监控页面
- Then 可以查看设备实时状态
- And 设备异常时收到预警通知
## 3. 功能需求
### 3.1 用户管理模块
#### 3.1.1 用户认证
**用户故事：** As a 用户，I want to 通过安全的方式登录系统，so that 我的账户信息得到保护
**验收标准：**
- Given 用户访问登录页面
- When 输入正确的凭证
- Then 系统颁发JWT令牌
- And 令牌有效期24小时
- And 密码使用bcrypt加密存储
#### 3.1.2 权限管理
**用户故事：** As a 系统管理员，I want to 管理用户角色和权限，so that 我可以控制不同用户的访问范围
**验收标准：**
- Given 管理员进入权限管理页面
- When 分配用户角色
- Then 用户获得相应权限
- And 权限变更实时生效
### 3.2 养殖场管理模块
#### 3.2.1 养殖场信息维护
**用户故事：** As a 养殖场管理员，I want to 维护养殖场基本信息，so that 信息准确完整
**验收标准：**
- Given 管理员进入养殖场管理
- When 填写养殖场信息（名称、类型、位置、联系人等）
- Then 信息保存到数据库
- And 地理位置信息格式正确
#### 3.2.2 地图展示
**用户故事：** As a 监管人员，I want to 在地图上查看养殖场分布，so that 我可以直观了解区域养殖情况
**验收标准：**
- Given 用户有地图查看权限
- When 打开地图页面
- Then 显示所有养殖场位置标记
- And 点击标记显示养殖场基本信息
### 3.3 设备监控模块
#### 3.3.1 设备状态监控
**用户故事：** As a 监管人员，I want to 实时监控设备状态，so that 我可以确保设备正常运行
**验收标准：**
- Given 设备数据正常上报
- When 用户查看设备监控页面
- Then 显示设备实时状态（在线、离线、维护）
- And 状态更新间隔不超过30秒
#### 3.3.2 设备预警
**用户故事：** As a 系统用户，I want to 接收设备异常预警，so that 我可以及时处理问题
**验收标准：**
- Given 设备出现异常状态
- When 系统检测到异常
- Then 发送预警通知给相关用户
- And 预警级别根据异常程度划分
### 3.4 动物管理模块
#### 3.4.1 动物信息管理
**用户故事：** As a 养殖场管理员，I want to 管理动物基本信息，so that 我可以跟踪动物健康状况
**验收标准：**
- Given 管理员进入动物管理
- When 录入动物信息（类型、数量、健康状态）
- Then 信息保存到数据库
- And 健康状态可更新
#### 3.4.2 健康监测
**用户故事：** As a 监管人员，I want to 查看动物健康数据，so that 我可以评估养殖场健康状况
**验收标准：**
- Given 有动物健康数据
- When 用户查看健康报表
- Then 显示健康状态统计
- And 可以按时间范围筛选
### 3.5 数据分析模块
#### 3.5.1 数据可视化
**用户故事：** As a 用户，I want to 通过图表查看数据，so that 我可以更直观理解数据趋势
**验收标准：**
- Given 有统计数据
- When 用户打开数据看板
- Then 显示ECharts图表
- And 图表支持交互操作
#### 3.5.2 报表生成
**用户故事：** As a 监管人员，I want to 生成养殖统计报表，so that 我可以进行决策分析
**验收标准：**
- Given 用户有报表权限
- When 选择报表类型和时间范围
- Then 生成PDF格式报表
- And 报表包含关键指标数据
## 4. 非功能需求
### 4.1 性能要求
- 页面加载时间：<3秒
- API响应时间：<500ms
- 并发用户支持：1000+用户
- 数据查询性能：复杂查询<2秒
### 4.2 安全要求
- 数据传输：HTTPS加密
- 身份认证：JWT令牌机制
- 密码存储：bcrypt加密
- SQL注入防护：ORM参数化查询
- XSS防护：输入验证和转义
### 4.3 可靠性要求
- 系统可用性：99.9%
- 数据备份：每日自动备份
- 故障恢复：30分钟内恢复
- 监控告警：关键指标监控
### 4.4 兼容性要求
- 浏览器支持：Chrome、Firefox、Safari最新版本
- 移动端适配：响应式设计
- 分辨率支持：1920x1080及以上
## 5. 原型说明
### 5.1 界面布局
- **顶部导航栏**：系统logo、用户信息、通知中心、退出按钮
- **侧边菜单**：模块导航菜单，支持折叠展开
- **主内容区**：功能页面展示区域
- **底部信息**：版权信息、系统版本
### 5.2 关键页面
#### 5.2.1 登录页面
- 用户名/密码输入框
- 记住密码选项
- 登录按钮
- 忘记密码链接
#### 5.2.2 仪表盘页面
- 数据概览卡片（养殖场数、设备数、动物数、预警数）
- 实时监控图表
- 最新预警列表
- 快捷操作入口
#### 5.2.3 养殖场管理页面
- 养殖场列表表格
- 搜索筛选功能
- 新增/编辑表单
- 地图展示选项卡
#### 5.2.4 设备监控页面
- 设备状态卡片布局
- 实时数据图表
- 状态筛选功能
- 设备详情模态框
#### 5.2.5 数据报表页面
- 时间范围选择器
- 图表展示区域
- 报表类型切换
- 数据导出功能
### 5.3 交互流程
#### 5.3.1 登录流程
1. 用户访问系统 → 跳转到登录页面
2. 输入用户名密码 → 点击登录按钮
3. 验证通过 → 跳转到仪表盘页面
4. 验证失败 → 显示错误提示
#### 5.3.2 预警处理流程
1. 设备异常 → 系统生成预警
2. 预警通知 → 用户收到通知
3. 查看预警详情 → 进入预警处理页面
4. 处理预警 → 更新预警状态
5. 填写处理说明 → 完成预警处理
## 6. API规范
### 6.1 通用响应格式
```json
{
"success": true,
"data": {},
"message": "操作成功",
"timestamp": "2025-01-18T10:30:00Z"
}
```
### 6.2 错误处理
- HTTP状态码：4xx客户端错误，5xx服务端错误
- 错误信息：中英文错误描述
- 错误日志：记录详细错误信息
### 6.3 认证机制
- Authorization: Bearer <token>
- 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日*

210
docs/PROJECT_CLEANUP_REPORT.md Normal file
View File

@@ -0,0 +1,210 @@
# 项目文件整理总结报告
## 📋 整理概述
本次项目文件整理工作已全面完成，按照既定的目录结构规范对整个项目进行了系统性的重新组织和优化。
## 🎯 整理目标
根据项目内存信息和目录结构规范，确保项目文件按以下结构组织：
- `backend/` - 后端目录
- `admin-system/` - 管理后台
- `website/` - 官网
- `mini_program/` - 微信小程序矩阵目录
- `docs/` - 文档目录
- `test/` - 测试文件目录
- `scripts/` - 执行脚本目录
## ✅ 完成的整理工作
### 1. Backend目录重构 🔧
**问题分析**：
- backend目录原有60+个临时脚本和测试文件散乱分布
- 缺乏分类管理，影响代码维护性
- 违反了清晰的目录结构原则
**整理措施**：
```
backend/
├── config/ # 配置文件
├── controllers/ # 业务逻辑控制器
├── middleware/ # 中间件
├── migrations/ # 数据库迁移
├── models/ # 数据模型
├── routes/ # API路由
├── seeds/ # 种子数据
├── utils/ # 工具类
├── tools/ # 🆕 工具脚本目录
│ ├── data-management/ # 数据管理脚本
│ ├── testing/ # 测试脚本
│ ├── verification/ # 验证脚本
│ └── README.md # 工具说明文档
├── server.js # 服务器入口
└── package.json # 依赖配置
```
**移动的文件统计**：
- **数据管理脚本** (25个文件): `create-*.js`, `generate-*.js`, `import-*.js`, `fix-*.js`, 等
- **测试脚本** (15个文件): `test-*.js`, `test_*.js`
- **验证脚本** (18个文件): `check-*.js`, `verify-*.js`, `analyze-*.js`, 等
### 2. 文档体系完善 📚
**新增核心文档**：
- ✅ `API.md` - 完整的RESTful API文档
- ✅ `DEPLOYMENT.md` - 详细部署指南
- ✅ `DEVELOPMENT.md` - 开发指南和规范
- ✅ `TROUBLESHOOTING.md` - 故障排除指南
- ✅ `CHANGELOG.md` - 版本更新日志
- ✅ `CONTRIBUTING.md` - 贡献指南
- ✅ `SECURITY.md` - 安全指南
**优化现有文档**：
- ✅ `README.md` - 全面重写，添加快速开始指南
- ✅ 保持原有的 `arch.md`, `design.md`, `PRD.md`
**目录说明文档**：
- ✅ `docs/README.md` - 文档目录索引
- ✅ `test/README.md` - 测试目录说明
- ✅ `scripts/README.md` - 脚本目录说明
- ✅ `backend/tools/README.md` - 工具目录说明
### 3. 文档和报告迁移 📁
**从backend迁移到docs**：
- `data-sync-fix-report.md` - 数据同步修复报告
- `farms-data-import-summary.md` - 农场数据导入总结
- `location-data-validation-report.md` - 位置数据验证报告
### 4. 版本控制优化 🔒
**完善.gitignore文件**：
- 扩展了忽略规则（从62行扩展到135行）
- 添加了更多项目相关的忽略模式
- 包含了现代开发工具的缓存和临时文件
- 加强了安全文件的保护
**新增忽略类别**：
- 测试相关文件和缓存
- 文档构建工具
- 部署平台文件
- 安全证书和密钥
- 性能监控缓存
- 各种构建工具缓存
### 5. 目录结构标准化 📂
**最终项目结构**：
```
nxxmdata/
├── 📁 backend/ # 后端目录
│ ├── config/ # 配置文件
│ ├── controllers/ # 控制器
│ ├── models/ # 数据模型
│ ├── routes/ # 路由
│ ├── middleware/ # 中间件
│ ├── utils/ # 工具类
│ ├── migrations/ # 数据库迁移
│ ├── seeds/ # 种子数据
│ ├── tools/ # 🆕 工具脚本
│ └── server.js # 服务入口
├── 📁 admin-system/ # 管理后台
├── 📁 website/ # 官网
├── 📁 mini_program/ # 微信小程序矩阵
├── 📁 docs/ # 文档目录
│ ├── baidu-map-license.md # 百度地图许可
│ ├── performance-monitoring.md # 性能监控文档
│ ├── data-sync-fix-report.md # 🆕 数据同步报告
│ ├── farms-data-import-summary.md # 🆕 农场导入总结
│ ├── location-data-validation-report.md # 🆕 位置验证报告
│ └── README.md # 🆕 文档索引
├── 📁 test/ # 测试文件目录
│ ├── performance-monitor-test.js
│ └── README.md # 🆕 测试说明
├── 📁 scripts/ # 执行脚本目录
│ ├── init-db.js
│ ├── migration-manager.js
│ ├── seed-manager.js
│ ├── test-connection.js
│ ├── test-map-api.js
│ └── README.md # 🆕 脚本说明
├── 📁 examples/ # 示例代码
├── 📄 核心文档
│ ├── README.md # ✨ 优化主文档
│ ├── API.md # 🆕 API文档
│ ├── DEPLOYMENT.md # 🆕 部署指南
│ ├── DEVELOPMENT.md # 🆕 开发指南
│ ├── TROUBLESHOOTING.md # 🆕 故障排除
│ ├── CHANGELOG.md # 🆕 更新日志
│ ├── CONTRIBUTING.md # 🆕 贡献指南
│ ├── SECURITY.md # 🆕 安全指南
│ ├── arch.md # 架构文档
│ ├── design.md # 设计文档
│ └── PRD.md # 需求文档
├── 📄 数据库文件
│ ├── schema.sql # 数据库架构
│ └── create_tables.sql # 建表脚本
└── 📄 配置文件
├── .gitignore # ✨ 优化版本控制
├── dev-plan.md # 开发计划
└── task.md # 任务列表
```
## 📊 整理成果统计
### 文件数量统计
- **移动文件**: 58个脚本文件重新分类
- **新增文档**: 11个专业文档
- **优化文档**: 4个现有文档
- **新增目录**: 8个子目录
### 提升效果
- **维护性** ⬆️ 大幅提升：文件分类清晰，易于查找和维护
- **专业性** ⬆️ 显著提升：完整的企业级文档体系
- **开发效率** ⬆️ 明显提升：清晰的目录结构和详细指南
- **代码质量** ⬆️ 持续提升：规范的版本控制和代码组织
## 🎯 后续建议
### 立即执行
1. **团队培训**: 向开发团队介绍新的目录结构
2. **文档维护**: 建立文档更新机制
3. **脚本管理**: 制定工具脚本使用规范
### 中期规划
1. **CI/CD集成**: 将新的目录结构集成到自动化流程
2. **监控接入**: 设置文档和目录结构的持续监控
3. **模板制作**: 基于新结构创建项目模板
### 长期优化
1. **自动化工具**: 开发自动化的文件整理工具
2. **最佳实践**: 总结和推广文件管理最佳实践
3. **标准输出**: 将整理经验标准化为团队规范
## ✨ 整理价值
本次文件整理工作实现了：
1. **🎯 目标达成**: 完全符合项目目录结构规范
2. **📚 文档完善**: 建立了企业级的完整文档体系
3. **🔧 工具优化**: 系统性整理了开发和运维工具
4. **📊 结构清晰**: 实现了模块化、分层化的项目组织
5. **⚡ 效率提升**: 为团队开发和维护提供了坚实基础
## 🎉 总结
经过系统性的文件整理，宁夏智慧养殖监管平台项目现在拥有：
- ✅ **清晰的目录结构**：符合规范，易于导航
- ✅ **完整的文档体系**：涵盖开发、部署、运维各环节
- ✅ **规范的工具管理**：脚本分类清晰，使用便捷
- ✅ **优化的版本控制**：完善的忽略规则，保护敏感信息
- ✅ **专业的项目形象**：展现了企业级项目的专业水准
这为项目的长期发展和团队协作奠定了坚实的基础！
---
*整理完成时间: 2025年1月*
*整理责任人: AI Assistant*
*整理版本: v1.0*

52
docs/README.md Normal file
View File

@@ -0,0 +1,52 @@
# 项目文档目录
本目录包含宁夏智慧养殖监管平台的所有技术文档和报告。
## 📋 文档索引
### 💾 系统报告
- [`data-sync-fix-report.md`](data-sync-fix-report.md) - 经纬度数据同步问题修复报告
- [`farms-data-import-summary.md`](farms-data-import-summary.md) - 农场静态数据导入总结
- [`location-data-validation-report.md`](location-data-validation-report.md) - 经纬度数据传递验证报告
### 🗺️ 第三方服务
- [`baidu-map-license.md`](baidu-map-license.md) - 百度地图商用授权解决方案
### 📊 系统监控
- [`performance-monitoring.md`](performance-monitoring.md) - 性能监控系统完整文档
### 📚 项目设计
- [`architecture.md`](architecture.md) - 系统架构设计文档
- [`design.md`](design.md) - 详细设计文档
- [`development-plan.md`](development-plan.md) - 开发计划文档
- [`task-list.md`](task-list.md) - 任务清单文档
### 💼 示例代码
- [`examples/performance-monitor-integration.js`](examples/performance-monitor-integration.js) - 性能监控集成示例
## 📂 文档分类
### 运维报告
包含系统维护、数据修复、功能验证等相关的技术报告，记录了系统运行过程中的重要问题解决方案。
### 服务集成
包含第三方服务（如百度地图API）的配置、授权、使用说明等文档。
### 系统监控
包含性能监控、系统健康检查、监控指标等相关的配置和使用文档。
### 架构设计
包含系统架构、详细设计、开发计划等技术设计文档。
### 示例代码
包含各种功能集成的示例代码和最佳实践。
## 🔄 文档维护
- 所有技术报告都应记录在此目录下
- 定期更新过时的文档内容
- 新增重要功能或修复时应更新相关文档
---
*最后更新: 2025年1月*

331
docs/SECURITY.md Normal file
View File

@@ -0,0 +1,331 @@
# 安全指南
## 概述
本文档为宁夏智慧养殖监管平台提供全面的安全指导，包括安全漏洞报告、安全最佳实践、以及系统安全配置建议。
## 漏洞报告
### 报告渠道
**如果您发现安全漏洞，请不要在公开渠道（如 GitHub Issues）报告。**
请通过以下私密渠道报告：
- 📧 **安全邮箱**: security@nxxmdata.com
- 🔒 **加密通信**: 支持 PGP 加密
### 报告内容
请在安全报告中包含以下信息：
1. **漏洞类型** (SQL注入、XSS、CSRF等)
2. **影响范围** (影响的组件、用户类型、严重程度)
3. **复现步骤** (详细的复现步骤)
4. **概念验证** (代码示例或截图)
5. **建议修复方案** (如果有修复建议请提供)
### 响应承诺
| 严重程度 | 确认时间 | 修复时间 |
|---------|---------|---------|
| 严重 | 4 小时 | 24-48 小时 |
| 高 | 24 小时 | 3-7 天 |
| 中 | 72 小时 | 1-4 周 |
| 低 | 1 周 | 1-3 个月 |
## 认证与授权
### JWT Token 安全
```javascript
// 安全的 JWT 配置
const jwtConfig = {
secret: process.env.JWT_SECRET, // 至少 64 字符的强密钥
algorithm: 'HS256',
expiresIn: '24h',
issuer: 'nxxmdata-api',
audience: 'nxxmdata-client'
};
```
### 密码安全
- 最低长度 8 位
- 必须包含大小写字母、数字和特殊字符
- 使用 bcrypt 加密存储
- 盐值强度至少为 12
### 权限控制
实施基于角色的访问控制 (RBAC)：
- **admin**: 系统管理员权限
- **manager**: 养殖场管理员权限
- **operator**: 操作员权限
- **viewer**: 只读权限
## 数据安全
### 输入验证
所有用户输入必须经过严格验证：
```javascript
// SQL 注入防护 - 使用参数化查询
const getFarms = async (status) => {
return await Farm.findAll({
where: { status } // Sequelize 自动参数化
});
};
// XSS 防护 - 输入转义
const validator = require('validator');
const sanitizedInput = validator.escape(userInput);
```
### 数据加密
- 敏感数据字段加密存储
- 数据库连接使用 SSL/TLS
- 文件传输使用 HTTPS
## 网络安全
### HTTPS 配置
强制使用 HTTPS：
```nginx
server {
listen 80;
server_name nxxmdata.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
ssl_protocols TLSv1.2 TLSv1.3;
# 其他 SSL 配置...
}
```
### 安全头配置
```nginx
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=63072000";
add_header Content-Security-Policy "default-src 'self'";
```
### 速率限制
```javascript
const rateLimit = require('express-rate-limit');
// API 速率限制
const apiLimiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 分钟
max: 100, // 每 IP 最多 100 请求
message: 'Too many requests, please try again later'
});
// 登录限制更严格
const loginLimiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 5 // 每 IP 最多 5 次登录尝试
});
```
## 部署安全
### Docker 安全
```dockerfile
# 使用非特权用户
FROM node:18-alpine
RUN adduser -S node -u 1001
USER node
# 只读文件系统
# docker run --read-only --tmpfs /tmp myapp
```
### 环境变量
```bash
# 使用强密钥
JWT_SECRET=随机生成的64字符密钥
DB_PASSWORD=强密码
ENCRYPTION_KEY=32字节hex密钥
# 生产环境配置
NODE_ENV=production
LOG_LEVEL=warn
```
### 服务器加固
```bash
# 防火墙配置
ufw default deny incoming
ufw default allow outgoing
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
# SSH 安全
sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
```
## 依赖安全
### 定期审计
```bash
# 检查已知漏洞
npm audit
# 修复漏洞
npm audit fix
# 更新依赖
npm update
```
### 自动化扫描
在 CI/CD 流程中集成安全扫描：
```yaml
# .github/workflows/security.yml
name: Security Scan
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run npm audit
run: npm audit --audit-level high
```
## 监控与日志
### 安全事件监控
```javascript
// 记录安全相关事件
const logSecurityEvent = (event, details) => {
securityLogger.warn({
event,
timestamp: new Date().toISOString(),
ip: details.ip,
userAgent: details.userAgent,
details
});
};
// 监控异常登录
if (failedAttempts > 3) {
logSecurityEvent('MULTIPLE_LOGIN_FAILURES', {
ip: req.ip,
attempts: failedAttempts
});
}
```
### 审计日志
- 记录所有敏感操作
- 包含用户信息、时间戳、操作详情
- 定期备份和分析日志
## 应急响应
### 安全事件处理流程
1. **发现阶段**: 监控系统检测异常
2. **评估阶段**: 确定影响范围和严重程度
3. **隔离阶段**: 隔离受影响的系统
4. **修复阶段**: 修复漏洞或问题
5. **恢复阶段**: 恢复正常服务
6. **总结阶段**: 分析原因和改进措施
### 紧急联系方式
- **安全团队**: security@nxxmdata.com
- **技术支持**: support@nxxmdata.com
- **紧急热线**: 400-xxx-xxxx
## 安全培训
### 开发人员安全意识
- 定期进行安全培训
- 了解 OWASP Top 10
- 掌握安全编码实践
- 参与安全代码审查
### 安全开发生命周期
1. **需求阶段**: 识别安全需求
2. **设计阶段**: 威胁建模分析
3. **开发阶段**: 安全编码实践
4. **测试阶段**: 安全测试和扫描
5. **部署阶段**: 安全配置检查
6. **维护阶段**: 持续监控和更新
## 合规要求
### 数据保护
- 遵循数据保护法规
- 实施数据分类管理
- 提供数据删除机制
- 限制数据访问权限
### 审计要求
- 保留详细的操作日志
- 定期进行安全审计
- 配合第三方安全评估
- 及时报告安全事件
## 安全检查清单
### 开发阶段
- [ ] 输入验证和清理
- [ ] 参数化查询
- [ ] 错误处理不泄露信息
- [ ] 使用安全的加密算法
- [ ] 实施权限检查
### 部署阶段
- [ ] HTTPS 配置正确
- [ ] 安全头配置完整
- [ ] 防火墙规则适当
- [ ] 服务器已加固
- [ ] 监控系统运行
### 运维阶段
- [ ] 定期安全扫描
- [ ] 及时更新补丁
- [ ] 监控异常活动
- [ ] 备份关键数据
- [ ] 测试应急预案
## 联系我们
如有安全相关问题，请联系：
- **安全邮箱**: security@nxxmdata.com
- **技术支持**: support@nxxmdata.com
- **项目地址**: https://github.com/your-org/nxxmdata
---
*最后更新: 2025年1月*
*请定期查看本文档的更新版本*

795
docs/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,795 @@
# 故障排除指南
## 概述
本文档提供宁夏智慧养殖监管平台常见问题的诊断和解决方案，帮助开发人员和运维人员快速定位和解决系统故障。
## 目录
- [环境相关问题](#环境相关问题)
- [数据库问题](#数据库问题)
- [API服务问题](#api服务问题)
- [前端问题](#前端问题)
- [性能问题](#性能问题)
- [部署问题](#部署问题)
- [日志分析](#日志分析)
- [监控和诊断工具](#监控和诊断工具)
## 环境相关问题
### Node.js 版本问题
**问题症状:**
```bash
Error: The engine "node" is incompatible with this module
```
**解决方案:**
```bash
# 检查当前 Node.js 版本
node --version
# 要求版本: Node.js 18.0+
# 升级 Node.js
nvm install 18
nvm use 18
# 或者使用官方安装包
# https://nodejs.org/
```
### npm 依赖安装失败
**问题症状:**
```bash
npm ERR! peer dep missing
npm ERR! network timeout
```
**解决方案:**
```bash
# 1. 清理缓存
npm cache clean --force
# 2. 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json
# 3. 重新安装
npm install
# 4. 如果网络问题，使用国内镜像
npm config set registry https://registry.npmmirror.com/
# 5. 使用 yarn 替代
yarn install
```
### 环境变量配置问题
**问题症状:**
```bash
Error: Missing required environment variable
```
**解决方案:**
```bash
# 1. 检查 .env 文件是否存在
ls -la .env
# 2. 复制示例配置文件
cp .env.example .env
# 3. 编辑配置文件
nano .env
# 4. 验证环境变量
node -e "console.log(process.env.DB_HOST)"
```
## 数据库问题
### 数据库连接失败
**问题症状:**
```
Error: connect ECONNREFUSED 127.0.0.1:3306
SequelizeConnectionError: Access denied for user
```
**诊断步骤:**
```bash
# 1. 检查 MySQL 服务状态
# macOS
brew services list | grep mysql
# Linux
systemctl status mysql
# Windows
net start mysql
# 2. 测试数据库连接
mysql -u root -p -h localhost -P 3306
# 3. 检查端口占用
lsof -i :3306
netstat -an | grep 3306
```
**解决方案:**
```bash
# 1. 启动 MySQL 服务
# macOS
brew services start mysql
# Linux
sudo systemctl start mysql
# Windows
net start mysql
# 2. 重置 MySQL 密码
mysql -u root -p
ALTER USER 'root'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;
# 3. 创建数据库用户
CREATE USER 'nxxmdata_user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON nxxmdata.* TO 'nxxmdata_user'@'localhost';
FLUSH PRIVILEGES;
```
### 数据库迁移失败
**问题症状:**
```
Migration failed: Table already exists
Sequelize migration error
```
**解决方案:**
```bash
# 1. 检查迁移状态
cd backend
npm run db:status
# 2. 回滚迁移
npm run db:rollback
# 3. 强制重置数据库（谨慎使用）
mysql -u root -p
DROP DATABASE nxxmdata;
CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# 4. 重新运行迁移
npm run db:migrate
```
### 数据不一致问题
**问题症状:**
```
Foreign key constraint fails
Data validation errors
```
**诊断脚本:**
```bash
cd backend
# 检查外键约束
node check-orphaned-foreign-keys.js
# 检查数据完整性
node verify-data.js
# 检查表结构
node check-table-structure.js
```
**解决方案:**
```bash
# 修复孤立外键
node fix-orphaned-foreign-keys.js
# 重新排序主键
node reorder-primary-keys.js
# 验证修复结果
node verify-data.js
```
## API服务问题
### 服务启动失败
**问题症状:**
```bash
Error: listen EADDRINUSE :::5350
Cannot find module
```
**解决方案:**
```bash
# 1. 检查端口占用
lsof -i :5350
netstat -tulpn | grep 5350
# 2. 杀死占用进程
kill -9 <PID>
# 3. 更换端口
export PORT=5351
npm run dev
# 4. 检查模块依赖
npm install
npm audit fix
```
### JWT Token 问题
**问题症状:**
```
401 Unauthorized
Token expired
Invalid token
```
**解决方案:**
```bash
# 1. 检查 JWT 密钥配置
echo $JWT_SECRET
# 2. 验证 Token 格式
node -e "console.log(require('jsonwebtoken').verify('YOUR_TOKEN', 'YOUR_SECRET'))"
# 3. 重新生成密钥
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
```
### API 响应慢
**问题症状:**
```
Response time > 5000ms
Timeout errors
```
**诊断工具:**
```bash
# 1. 检查数据库查询性能
cd backend
node utils/query-optimizer.js
# 2. 查看性能监控
curl http://localhost:5350/api/performance/metrics
# 3. 分析慢查询日志
tail -f logs/performance/database-YYYY-MM-DD.log
```
**优化方案:**
```javascript
// 1. 添加数据库索引
CREATE INDEX idx_farms_status ON farms(status);
CREATE INDEX idx_devices_farm_id ON devices(farm_id);
// 2. 优化查询语句
const farms = await Farm.findAll({
attributes: ['id', 'name', 'status'], // 只查询需要的字段
include: [{
model: Device,
attributes: ['id', 'status']
}],
limit: 10,
offset: (page - 1) * 10
});
// 3. 使用缓存
const Redis = require('redis');
const redis = Redis.createClient();
```
## 前端问题
### 构建失败
**问题症状:**
```bash
Build failed with errors
Module not found
Syntax error in code
```
**解决方案:**
```bash
# 1. 清理构建缓存
cd admin-system/frontend
rm -rf node_modules/.vite
rm -rf dist
# 2. 检查依赖版本
npm ls
# 3. 更新依赖
npm update
# 4. 重新构建
npm run build
```
### 路由问题
**问题症状:**
```
404 Page not found
Router navigation errors
```
**解决方案:**
```javascript
// 1. 检查路由配置
// router/routes.js
export const routes = [
{
path: '/',
redirect: '/dashboard'
},
{
path: '/farms',
component: () => import('../views/Farms.vue')
}
];
// 2. 检查 Nginx 配置
// location / {
// try_files $uri $uri/ /index.html;
// }
```
### API 调用失败
**问题症状:**
```
CORS errors
Network errors
401/403 errors
```
**解决方案:**
```javascript
// 1. 检查 API 基础 URL
// config/env.js
export const API_BASE_URL = process.env.VITE_API_BASE_URL || 'http://localhost:5350/api';
// 2. 添加请求拦截器
axios.interceptors.request.use(
config => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
},
error => Promise.reject(error)
);
// 3. 处理响应错误
axios.interceptors.response.use(
response => response,
error => {
if (error.response?.status === 401) {
// 清除 token，跳转到登录页
localStorage.removeItem('token');
router.push('/login');
}
return Promise.reject(error);
}
);
```
### 地图显示问题
**问题症状:**
```
百度地图加载失败
地图空白
坐标偏移
```
**解决方案:**
```javascript
// 1. 检查 API 密钥
console.log('百度地图 API Key:', process.env.VITE_BAIDU_MAP_API_KEY);
// 2. 验证域名白名单
// 登录百度地图开放平台控制台检查 Referer 设置
// 3. 检查坐标系统
// 确保使用 BD09 坐标系
const point = new BMap.Point(106.26667, 38.46667);
// 4. 处理坐标转换
// 如果数据是 WGS84 或 GCJ02，需要转换为 BD09
```
## 性能问题
### 内存泄漏
**问题症状:**
```
Memory usage keeps growing
Process killed by system
```
**诊断工具:**
```bash
# 1. 监控内存使用
node --inspect server.js
# 打开 Chrome DevTools -> Memory 选项卡
# 2. 使用 clinic.js
npm install -g clinic
clinic doctor -- node server.js
# 3. 使用 PM2 监控
pm2 install pm2-server-monit
pm2 monit
```
**解决方案:**
```javascript
// 1. 清理事件监听器
process.removeAllListeners('exit');
// 2. 关闭数据库连接
await sequelize.close();
// 3. 限制并发请求
const pLimit = require('p-limit');
const limit = pLimit(10);
// 4. 使用对象池
const pool = new Pool({
create: () => new ExpensiveObject(),
destroy: (obj) => obj.cleanup()
});
```
### CPU 使用率高
**问题症状:**
```
CPU usage > 80%
Response time degradation
```
**诊断方法:**
```bash
# 1. 查看进程状态
top -p $(pgrep node)
htop
# 2. 分析性能瓶颈
node --prof server.js
node --prof-process isolate-*.log > processed.txt
# 3. 使用火焰图
npm install -g 0x
0x server.js
```
### 数据库查询慢
**问题症状:**
```
Query execution time > 1000ms
Database connection pool exhausted
```
**优化策略:**
```sql
-- 1. 添加索引
EXPLAIN SELECT * FROM farms WHERE status = 'active';
CREATE INDEX idx_farms_status ON farms(status);
-- 2. 优化查询
-- 避免 SELECT *
SELECT id, name, status FROM farms WHERE status = 'active';
-- 3. 使用查询缓存
SET SESSION query_cache_type = ON;
```
## 部署问题
### Docker 构建失败
**问题症状:**
```
Docker build failed
Image size too large
Container startup errors
```
**解决方案:**
```dockerfile
# 1. 优化 Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
# 2. 使用多阶段构建
FROM node:18-alpine AS runner
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 5350
CMD ["npm", "start"]
# 3. 添加 .dockerignore
node_modules
.git
.env
logs/*
```
### Nginx 配置问题
**问题症状:**
```
502 Bad Gateway
404 for static files
CORS errors
```
**解决方案:**
```nginx
server {
listen 80;
server_name localhost;
# 解决 CORS 问题
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
add_header Access-Control-Allow-Headers "Content-Type, Authorization";
# 前端路由
location / {
root /usr/share/nginx/html;
try_files $uri $uri/ /index.html;
}
# API 代理
location /api {
proxy_pass http://backend: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;
}
}
```
### SSL 证书问题
**问题症状:**
```
Certificate expired
SSL handshake failed
Mixed content warnings
```
**解决方案:**
```bash
# 1. 使用 Let's Encrypt
certbot --nginx -d yourdomain.com
# 2. 检查证书状态
openssl x509 -in /path/to/cert.pem -text -noout
# 3. 自动续期
echo "0 12 * * * /usr/bin/certbot renew --quiet" | crontab -
# 4. 强制 HTTPS
return 301 https://$server_name$request_uri;
```
## 日志分析
### 后端日志
**日志位置:**
```bash
backend/logs/
├── app.log # 应用日志
├── error.log # 错误日志
├── access.log # 访问日志
└── performance/ # 性能监控日志
├── system-YYYY-MM-DD.log
└── database-YYYY-MM-DD.log
```
**常用命令:**
```bash
# 实时查看日志
tail -f backend/logs/app.log
# 搜索错误
grep -i error backend/logs/*.log
# 分析访问模式
awk '{print $1}' backend/logs/access.log | sort | uniq -c | sort -nr
# 查看特定时间段日志
sed -n '/2025-01-18 10:00/,/2025-01-18 11:00/p' backend/logs/app.log
```
### 前端日志
**浏览器控制台:**
```javascript
// 1. 查看网络请求
// Network 标签页 -> 筛选 XHR/Fetch
// 2. 查看 JavaScript 错误
// Console 标签页 -> 筛选 Errors
// 3. 查看性能
// Performance 标签页 -> 录制并分析
// 4. 查看内存使用
// Memory 标签页 -> Heap snapshot
```
## 监控和诊断工具
### 系统监控
```bash
# 1. 系统资源监控
htop
iostat -x 1
vmstat 1
# 2. 磁盘使用
df -h
du -sh /path/to/project
# 3. 网络连接
netstat -tulpn
ss -tulpn
```
### 应用监控
```bash
# 1. PM2 监控
pm2 monit
pm2 logs
pm2 show app-name
# 2. Node.js 性能分析
node --inspect server.js
# 访问 chrome://inspect
# 3. 数据库监控
SHOW PROCESSLIST;
SHOW STATUS LIKE 'Slow_queries';
```
### 自定义监控脚本
```bash
#!/bin/bash
# health-check.sh
# 检查服务状态
curl -f http://localhost:5350/api/health || echo "API 服务异常"
# 检查数据库连接
mysql -u root -p -e "SELECT 1" > /dev/null 2>&1 || echo "数据库连接失败"
# 检查磁盘空间
df -h | awk '$5 > 80 {print "磁盘使用率过高: " $0}'
# 检查内存使用
free | awk 'NR==2{printf "内存使用率: %.2f%%\n", $3*100/$2}'
```
## 紧急响应流程
### 服务不可用
**立即响应 (5分钟内):**
```bash
# 1. 检查服务状态
pm2 status
systemctl status nginx
# 2. 重启服务
pm2 restart all
systemctl restart nginx
# 3. 检查日志
tail -f logs/error.log
```
**深入分析 (30分钟内):**
```bash
# 1. 检查系统资源
top
df -h
free -h
# 2. 分析错误日志
grep -i error logs/*.log | tail -20
# 3. 数据库健康检查
mysql -e "SHOW PROCESSLIST;"
```
### 数据库异常
**紧急处理:**
```bash
# 1. 检查数据库状态
systemctl status mysql
# 2. 查看错误日志
tail -f /var/log/mysql/error.log
# 3. 重启数据库服务
systemctl restart mysql
# 4. 检查数据完整性
mysqlcheck -u root -p --all-databases
```
### 安全事件
**响应步骤:**
```bash
# 1. 隔离受影响的服务
pm2 stop suspicious-process
# 2. 检查访问日志
grep -E "(404|500)" logs/access.log | tail -50
# 3. 更新密码和密钥
# 重新生成 JWT 密钥
# 强制所有用户重新登录
# 4. 通知相关人员
echo "安全事件发生，请立即检查系统" | mail -s "紧急: 安全告警" admin@company.com
```
## 联系支持
### 获取帮助的渠道
1. **技术支持邮箱**: support@nxxmdata.com
2. **紧急联系电话**: 400-xxx-xxxx
3. **在线文档**: https://docs.nxxmdata.com
4. **GitHub Issues**: https://github.com/your-org/nxxmdata/issues
### 报告问题时请提供
1. **错误描述**: 详细的错误信息和复现步骤
2. **环境信息**: 操作系统、Node.js版本、浏览器版本
3. **日志文件**: 相关的错误日志
4. **配置信息**: 去敏感化的配置文件
5. **系统状态**: CPU、内存、磁盘使用情况
---
*最后更新: 2025年1月*
**注意**: 本文档会根据系统更新持续完善，请定期查看最新版本。

423
docs/architecture.md Normal file
View File

@@ -0,0 +1,423 @@
# 项目架构文档
## 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*
*分析基于实际代码结构*

122
docs/data-sync-fix-report.md Normal file
View File

@@ -0,0 +1,122 @@
# 经纬度数据同步问题修复报告
## 问题描述
用户反馈经纬度输入框的值与数据库存储的值不一致，存在数据不同步的问题。
## 问题分析
通过深入调查，发现问题的根本原因是：
### 1. 数据库存储格式问题
- **问题**: 数据库中的 `location` 字段被存储为 JSON 字符串而不是 JSON 对象
- **表现**: `location` 字段值为 `"{\"lat\":38.47,\"lng\":106.28}"` (字符串格式)
- **期望**: `location` 字段值应为 `{"lat":38.47,"lng":106.28}` (对象格式)
### 2. 前端解析问题
- 当 `location` 字段为字符串时，前端无法正确解析 `lng` 和 `lat` 属性
- 导致编辑表单中经纬度输入框显示为空
## 解决方案
### 1. 数据库格式修复
创建并运行了 `fix-location-data.js` 脚本：
```javascript
// 将JSON字符串转换为JSON对象
if (typeof farm.location === 'string') {
newLocation = JSON.parse(farm.location);
await farm.update({ location: newLocation });
}
```
**修复结果**:
- 总记录数: 12
- 修复成功: 11
- 修复失败: 0
- 无需修复: 1
### 2. 代码验证
#### 后端代码检查
- ✅ `Farm` 模型定义正确 (`DataTypes.JSON`)
- ✅ `createFarm` 函数正确处理经纬度数据
- ✅ `updateFarm` 函数正确构建 location 对象
#### 前端代码检查
- ✅ `editFarm` 函数正确解析 `record.location?.lng` 和 `record.location?.lat`
- ✅ 表单验证规则完整
- ✅ `handleSubmit` 函数正确提交数据
## 测试验证
### 1. 数据格式验证
修复前:
```
Location对象: "{\"lat\":38.4872,\"lng\":106.2309}"
❌ Location字段为空或格式错误
```
修复后:
```
Location对象: {"lat":38.4872,"lng":106.2309}
经度 (lng): 106.2309 (类型: number)
纬度 (lat): 38.4872 (类型: number)
✅ 有经纬度数据
```
### 2. 数据同步测试
运行 `test-data-sync.js` 验证完整流程：
```
=== 测试结果 ===
✅ 创建记录成功
✅ 查询验证通过
✅ API响应格式正确
✅ 前端数据解析正确
✅ 更新操作成功
✅ 数据一致性检查通过
结果: 数据同步正常
```
## 修复效果
### 修复前
- 数据库中 location 字段为 JSON 字符串
- 前端无法正确解析经纬度数据
- 编辑表单中经纬度输入框显示为空
- 用户输入的值与数据库存储值不一致
### 修复后
- 数据库中 location 字段为 JSON 对象
- 前端正确解析并显示经纬度数据
- 编辑表单正确回显经纬度值
- 用户输入值与数据库存储值完全一致
## 预防措施
### 1. 数据验证
- 在 `createFarm` 和 `updateFarm` 函数中确保 location 对象格式正确
- 添加数据类型检查，确保经纬度为数值类型
### 2. 前端处理
- 在 `editFarm` 函数中添加容错处理
- 确保 location 对象解析的健壮性
### 3. 测试覆盖
- 定期运行数据一致性检查
- 在部署前验证经纬度数据的完整流程
## 总结
经纬度数据同步问题已完全解决：
1. **根本原因**: 数据库中 location 字段存储格式错误（JSON字符串 vs JSON对象）
2. **解决方案**: 运行数据修复脚本，将所有记录的 location 字段转换为正确的 JSON 对象格式
3. **验证结果**: 所有测试通过，数据同步正常
4. **预防措施**: 建立了完整的测试和验证机制
现在用户在前端编辑养殖场时，经纬度输入框会正确显示数据库中存储的值，实现了完全的数据同步。

551
docs/design.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. 集成人工智能技术，实现智能预警和决策支持

44
docs/development-plan.md Normal file
View File

@@ -0,0 +1,44 @@
# 项目开发计划
## 1. 项目目标
开发一个现代化的农场管理系统，实现以下核心功能：
- 实时监控农场设备和动物状态
- 数据可视化分析仪表盘
- 多角色权限管理系统
- 移动端适配（二期规划）
## 2. 里程碑计划
| 阶段 | 时间节点 | 交付物 |
|------|----------|--------|
| 需求确认 | 2025/8/20 | 需求规格说明书 |
| 原型设计 | 2025/8/25 | Figma设计稿 |
| 核心功能开发 | 2025/9/10 | 设备监控模块、动物管理模块 |
| 数据分析模块 | 2025/9/20 | 可视化报表系统 |
| 系统联调 | 2025/9/25 | 集成测试报告 |
| 上线部署 | 2025/9/30 | 生产环境部署包 |
## 3. 任务分解
### 3.1 后端开发
- [ ] 设备状态API开发（3人日）
- [ ] 动物健康数据模型设计（2人日）
- [ ] 用户权限管理系统（5人日）
### 3.2 前端开发
- [ ] 实时监控看板（4人日）
- [ ] 地图可视化组件（3人日）
- [ ] 响应式布局适配（2人日）
## 4. 资源需求
- 开发团队：3名后端 + 2名前端
- 测试资源：专职QA 1名
- 服务器：腾讯云CVM 2台（4核8G）
## 5. 风险预案
| 风险项 | 应对方案 |
|--------|----------|
| 第三方地图API延迟 | 备用百度地图/高德地图双方案 |
| 数据量激增 | 提前规划数据库分表方案 |
| 人员流动 | 核心模块双人负责制 |
---
*最后更新：2025/8/18*

108
docs/examples/performance-monitor-integration.js Normal file
View File

@@ -0,0 +1,108 @@
/**
* 性能监控系统集成示例
* @file performance-monitor-integration.js
* @description 演示如何在Express应用中集成性能监控系统
*/
const express = require('express');
const { initPerformanceMonitoring, getPerformanceRoutes } = require('../backend/config/performance-config');
const logger = require('../backend/utils/logger');
// 创建Express应用
const app = express();
// 配置中间件
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// 初始化性能监控系统
const performanceMonitor = initPerformanceMonitoring(app, {
autoStart: true,
interval: 30000, // 30秒监控间隔
logToConsole: true,
thresholds: {
system: {
cpuUsage: 75, // CPU使用率阈值（百分比）
memoryUsage: 80, // 内存使用率阈值（百分比）
diskUsage: 85 // 磁盘使用率阈值（百分比）
},
database: {
connectionPoolUtilization: 70, // 连接池利用率阈值（百分比）
slowQueryCount: 3, // 慢查询数量阈值
errorRate: 2 // 错误率阈值（百分比）
},
api: {
responseTime: 300, // API响应时间阈值（毫秒）
errorRate: 1, // API错误率阈值（百分比）
requestRate: 500 // 每分钟请求数阈值
}
}
});
// 注册性能监控路由
app.use('/api/performance', getPerformanceRoutes());
// 示例API路由
app.get('/api/users', (req, res) => {
// 模拟数据库操作延迟
setTimeout(() => {
res.json({ users: [{ id: 1, name: '张三' }, { id: 2, name: '李四' }] });
}, 50);
});
app.get('/api/products', (req, res) => {
// 模拟数据库操作延迟
setTimeout(() => {
res.json({ products: [{ id: 1, name: '产品A' }, { id: 2, name: '产品B' }] });
}, 30);
});
// 模拟慢响应API
app.get('/api/reports', (req, res) => {
// 模拟耗时操作
setTimeout(() => {
res.json({ report: { id: 1, data: '报表数据...' } });
}, 600); // 超过阈值的响应时间
});
// 模拟错误API
app.get('/api/error', (req, res) => {
res.status(500).json({ error: '服务器内部错误' });
});
// 错误处理中间件
app.use((err, req, res, next) => {
logger.error('应用错误:', err);
res.status(500).json({ error: '服务器内部错误', message: err.message });
});
// 启动服务器
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
logger.info(`服务器已启动，监听端口 ${PORT}`);
logger.info('性能监控系统已集成');
// 输出性能监控访问信息
logger.info('性能监控API:');
logger.info('- 获取所有指标: GET /api/performance/metrics');
logger.info('- 获取系统指标: GET /api/performance/system');
logger.info('- 获取数据库指标: GET /api/performance/database');
logger.info('- 获取API指标: GET /api/performance/api');
logger.info('- 获取监控状态: GET /api/performance/status');
});
// 优雅关闭
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);
function shutdown() {
logger.info('正在关闭应用...');
// 停止性能监控
performanceMonitor.stopMonitoring();
// 关闭服务器
server.close(() => {
logger.info('HTTP服务器已关闭');
process.exit(0);
});
}

116
docs/farms-data-import-summary.md Normal file
View File

@@ -0,0 +1,116 @@
# Farms静态数据导入总结
## 概述
成功将后端API中的farms静态数据导入到数据库的farms表中。
## 数据来源
### 1. API静态数据
来源：`routes/farms.js` 中的 `/public` 路由
- 宁夏农场1 (银川市)
- 宁夏农场2 (石嘴山市)
- 宁夏农场3 (吴忠市)
### 2. 种子数据
来源：`seeds/20230102000000_farm_data.js` 和 `seeds/20230103000000_extended_data.js`
- 阳光农场 (养猪场)
- 绿野牧场 (养牛场)
- 山谷羊场 (养羊场)
- 蓝天养鸡场 (养鸡场)
- 金山养鸭场 (养鸭场)
- 银河渔场 (渔场)
- 星空牧场 (综合养殖场)
- 彩虹农庄 (有机农场)
## 导入过程
### 1. 创建导入脚本
文件：`import-farms-static-data.js`
- 合并API静态数据和种子数据
- 使用事务确保数据一致性
- 清空现有数据并重置自增ID
- 批量插入新数据
### 2. 执行导入
```bash
node import-farms-static-data.js
```
### 3. 验证导入结果
文件：`verify-farms-import.js`
- 数据完整性检查
- ID序列连续性验证
- 地理位置数据验证
- 农场类型统计
## 导入结果
### 数据统计
- **总计**：11个农场
- **ID范围**：1-11（连续）
- **数据完整性**：✅ 所有字段完整
- **地理位置**：✅ 所有位置数据有效
### 农场类型分布
| 类型 | 数量 |
|------|------|
| 综合农场 | 3个 |
| 养猪场 | 1个 |
| 养牛场 | 1个 |
| 养羊场 | 1个 |
| 养鸡场 | 1个 |
| 养鸭场 | 1个 |
| 渔场 | 1个 |
| 综合养殖场 | 1个 |
| 有机农场 | 1个 |
### API验证
- `/api/farms/public` ✅ 返回正确的静态数据
- `/api/farms` ✅ 返回完整的数据库数据
## 数据结构
每个农场记录包含以下字段：
- `id`: 主键，自增
- `name`: 农场名称
- `type`: 农场类型
- `location`: 地理位置（JSON格式，包含lat和lng）
- `address`: 详细地址
- `contact`: 联系人
- `phone`: 联系电话
- `status`: 状态（active/inactive/maintenance）
- `created_at`: 创建时间
- `updated_at`: 更新时间
## 相关文件
### 创建的文件
- `import-farms-static-data.js` - 数据导入脚本
- `verify-farms-import.js` - 数据验证脚本
- `farms-data-import-summary.md` - 本总结文档
### 涉及的现有文件
- `routes/farms.js` - API路由定义
- `models/Farm.js` - 数据模型定义
- `controllers/farmController.js` - 控制器逻辑
- `seeds/20230102000000_farm_data.js` - 种子数据
- `seeds/20230103000000_extended_data.js` - 扩展种子数据
## 注意事项
1. **数据库连接警告**：执行过程中出现循环依赖警告，但不影响功能
2. **事务安全**：使用数据库事务确保数据导入的原子性
3. **ID重置**：导入前重置了自增ID，确保从1开始
4. **数据覆盖**：导入过程会清空现有farms数据
## 后续建议
1. 定期备份farms数据
2. 考虑添加数据迁移脚本
3. 优化循环依赖问题
4. 添加更多数据验证规则
---
**导入完成时间**：2025-08-21
**状态**：✅ 成功完成

256
docs/location-data-validation-report.md Normal file
View File

@@ -0,0 +1,256 @@
# 经纬度数据传递验证报告
## 概述
本报告详细验证了经纬度输入值从前端表单到数据库操作层的完整传递流程，确保location字段的更新逻辑被正确执行，并验证查询绑定的值与数据库中的实际值一致。
## 验证范围
### 1. 前端数据处理
- ✅ 经纬度输入框配置正确
- ✅ 表单验证规则完善
- ✅ 数据提交格式正确
### 2. 后端API处理
- ✅ 创建养殖场时经纬度处理
- ✅ 更新养殖场时经纬度处理（已修复）
- ✅ 空值和边界值处理
### 3. 数据库存储
- ✅ JSON字段存储格式正确
- ✅ 数据类型保持一致
- ✅ 精度保持完整
## 详细验证结果
### 前端组件配置
**经度输入框配置：**
```vue
<a-input-number
v-model:value="formData.longitude"
:min="-180"
:max="180"
:precision="6"
:step="0.000001"
:string-mode="false"
:controls="false"
placeholder="请输入经度 (-180 ~ 180)"
:parser="(value) => {
if (typeof value === 'string') {
const num = parseFloat(value.replace(/[^\d.-]/g, ''));
return isNaN(num) ? undefined : num;
}
return value;
}"
:formatter="(value) => value ? value.toString() : ''"
/>
```
**纬度输入框配置：**
```vue
<a-input-number
v-model:value="formData.latitude"
:min="-90"
:max="90"
:precision="6"
:step="0.000001"
:string-mode="false"
:controls="false"
placeholder="请输入纬度 (-90 ~ 90)"
:parser="(value) => {
if (typeof value === 'string') {
const num = parseFloat(value.replace(/[^\d.-]/g, ''));
return isNaN(num) ? undefined : num;
}
return value;
}"
:formatter="(value) => value ? value.toString() : ''"
/>
```
### 表单验证规则
**经度验证：**
- ✅ 允许为空值
- ✅ 数值有效性检查
- ✅ 范围验证（-180 到 180）
- ✅ 精度限制（最多6位小数）
**纬度验证：**
- ✅ 允许为空值
- ✅ 数值有效性检查
- ✅ 范围验证（-90 到 90）
- ✅ 精度限制（最多6位小数）
### 后端API处理
**创建养殖场（createFarm）：**
```javascript
// 构建location对象
const location = {};
if (longitude !== undefined && longitude !== null) {
location.lng = parseFloat(longitude);
}
if (latitude !== undefined && latitude !== null) {
location.lat = parseFloat(latitude);
}
const farm = await Farm.create({
name,
type: 'farm',
location,
address,
contact: owner,
phone,
status: status || 'active'
});
```
**更新养殖场（updateFarm）：**
```javascript
// 构建location对象 - 创建新对象以确保Sequelize检测到变化
const location = { ...(farm.location || {}) };
if (longitude !== undefined && longitude !== null) {
location.lng = parseFloat(longitude);
}
if (latitude !== undefined && latitude !== null) {
location.lat = parseFloat(latitude);
}
await farm.update({
name,
type: farm.type || 'farm',
location,
address,
contact: owner,
phone,
status: status || 'active'
});
```
### 数据库模型定义
```javascript
location: {
type: DataTypes.JSON,
allowNull: false,
defaultValue: {}
}
```
## 测试结果
### 基础功能测试
| 测试项目 | 输入值 | 期望结果 | 实际结果 | 状态 |
|---------|--------|----------|----------|------|
| 创建记录 | lng: 106.123456, lat: 38.654321 | 正确存储 | ✅ 正确存储 | 通过 |
| 更新记录 | lng: 107.987654, lat: 39.123456 | 正确更新 | ✅ 正确更新 | 通过 |
| 部分更新 | 仅更新经度 | 经度更新，纬度保持 | ✅ 符合期望 | 通过 |
| 清空坐标 | 空对象 | location为空对象 | ✅ 符合期望 | 通过 |
### 边界值测试
| 测试项目 | 输入值 | 存储值 | 精度保持 | 状态 |
|---------|--------|--------|----------|------|
| 最小边界值 | lng: -180, lat: -90 | lng: -180, lat: -90 | ✅ | 通过 |
| 最大边界值 | lng: 180, lat: 90 | lng: 180, lat: 90 | ✅ | 通过 |
| 零值 | lng: 0, lat: 0 | lng: 0, lat: 0 | ✅ | 通过 |
| 高精度值 | lng: 106.123456789, lat: 38.987654321 | lng: 106.123456789, lat: 38.987654321 | ✅ | 通过 |
### 空值处理测试
| 测试项目 | 输入值 | 处理结果 | 状态 |
|---------|--------|----------|------|
| undefined值 | longitude: undefined, latitude: undefined | location: {} | ✅ 通过 |
| null值 | longitude: null, latitude: null | location: {} | ✅ 通过 |
| 空字符串 | longitude: '', latitude: '' | location: {} | ✅ 通过 |
| 仅经度有值 | longitude: 106.123, latitude: undefined | location: {lng: 106.123} | ✅ 通过 |
| 仅纬度有值 | longitude: undefined, latitude: 38.456 | location: {lat: 38.456} | ✅ 通过 |
### API流程测试
| 操作 | 输入经纬度 | 存储结果 | 状态 |
|------|------------|----------|------|
| 创建 | lng: 106.789123, lat: 38.456789 | ✅ 正确存储 | 通过 |
| 更新 | lng: 107.111222, lat: 39.333444 | ✅ 正确更新 | 通过 |
## 发现的问题及修复
### 问题1：更新操作中经纬度值未正确保存
**问题描述：**
在更新养殖场时，新的经纬度值没有被正确保存到数据库中。
**原因分析：**
原代码直接修改了原有的location对象引用：
```javascript
const location = farm.location || {};
```
Sequelize可能没有检测到这个对象的变化，因为它是同一个引用。
**修复方案：**
创建一个新的location对象来确保Sequelize检测到变化：
```javascript
const location = { ...(farm.location || {}) };
```
**修复验证：**
- ✅ 更新操作现在能正确保存新的经纬度值
- ✅ 部分更新功能正常工作
- ✅ 不影响其他字段的更新
## 数据流验证
### 完整数据流路径
1. **前端输入** → 用户在经纬度输入框中输入数值
2. **前端验证** → 表单验证规则检查数值有效性和范围
3. **前端提交** → 通过API发送JSON数据到后端
4. **后端接收** → 控制器从req.body中提取longitude和latitude
5. **后端处理** → 使用parseFloat转换并构建location对象
6. **数据库存储** → Sequelize将location对象存储为JSON格式
7. **数据库查询** → 查询时返回完整的location对象
8. **前端显示** → 编辑时正确解析location.lng和location.lat
### 数据类型转换验证
| 阶段 | 数据类型 | 示例值 |
|------|----------|--------|
| 前端输入 | number | 106.123456 |
| API传输 | number | 106.123456 |
| 后端处理 | number (parseFloat) | 106.123456 |
| 数据库存储 | JSON | {"lng":106.123456,"lat":38.654321} |
| 数据库查询 | number | 106.123456 |
| 前端显示 | number | 106.123456 |
## 结论
### 验证结果总结
✅ **经纬度数据传递流程完全正确**
- 前端输入框配置合理，支持高精度数值输入
- 表单验证规则完善，确保数据有效性
- 后端API正确处理经纬度数据的创建和更新
- 数据库存储格式正确，支持JSON格式的location字段
- 数据类型在整个流程中保持一致
✅ **修复的问题**
- 更新操作中的对象引用问题已解决
- 经纬度值现在能正确保存和更新
✅ **边界情况处理**
- 空值处理正确
- 边界值验证通过
- 高精度数值保持完整
### 建议
1. **监控建议**：建议在生产环境中添加日志记录，监控经纬度数据的更新操作
2. **性能建议**：对于大量的位置更新操作，可以考虑批量更新优化
3. **扩展建议**：未来可以考虑添加地理位置验证（如检查坐标是否在合理的地理范围内）
### 最终确认
经过全面测试验证，经纬度输入值能够正确传递到数据库操作层，location字段的更新逻辑被正确执行，查询绑定的值与数据库中的实际值完全一致。系统现在能够可靠地处理经纬度数据的存储和更新操作。

40
docs/task-list.md Normal file
View File

@@ -0,0 +1,40 @@
# 项目任务列表
本文档列出了基于项目架构的任务拆解，包括前端和后端的各项开发任务。每个任务都有优先级和状态标记，方便跟踪进度。
## 前端任务
### 高优先级
- [x] **前端用户界面组件开发**：基于Vue 3的组件化开发
- [x] **集成Ant Design Vue组件库**：引入并配置UI组件库
- [x] **配置Pinia状态管理**：实现应用状态管理
- [x] **设置Vue Router路由管理**：配置前端路由系统
### 中优先级
- [x] **实现百度地图API服务集成**：集成地图服务功能
- [x] **集成ECharts图表库**：实现数据可视化功能
## 后端任务
### 高优先级
- [x] **开发后端RESTful API服务**：实现API接口
- [x] **实现JWT认证与授权系统**：开发用户认证功能
- [x] **配置ORM数据库访问层**：实现数据库交互
### 中优先级
- [x] **优化性能监控系统**：实现系统性能监控
## 任务状态说明
- [ ] 待处理
- [x] 已完成
- [-] 进行中
## 后续计划
- 引入微服务架构
- 进一步优化性能监控系统