实现数据接入层功能（REST API + WebSocket + 批量导入）
- 实现REST API服务器，支持IoT数据、手动录入和批量导入接口 - 实现WebSocket服务器，支持实时数据推送和连接管理 - 实现批量导入模块，支持CSV、Excel、JSON多种格式 - 实现数据处理工具，包含字段映射和单位转换功能 - 实现数据模型定义和数据验证机制 - 创建主程序入口和配置文件 - 添加详细的使用文档和API说明
This commit is contained in:
@@ -0,0 +1,299 @@
|
||||
# 水务管理系统 - 数据接入层
|
||||
|
||||
## 项目概述
|
||||
|
||||
本项目是水务管理系统中的数据接入层，实现了多源数据接入、实时WebSocket推送和批量数据导入功能。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. REST API 数据接入
|
||||
- **IoT设备数据接入**：支持实时接收传感器数据
|
||||
- **手动数据录入**：支持人工录入数据
|
||||
- **批量API导入**：支持通过API批量导入数据
|
||||
- **数据查询接口**：提供按数据类型、时间范围等条件的数据查询
|
||||
- **统计分析接口**：提供数据统计和分析功能
|
||||
|
||||
### 2. WebSocket 实时推送
|
||||
- **实时数据推送**：传感器数据实时推送到客户端
|
||||
- **连接管理**：支持多客户端连接和订阅管理
|
||||
- **数据历史**：新连接客户端可以获取历史数据
|
||||
- **警报推送**：支持实时警报推送
|
||||
- **心跳检测**：支持连接状态监控
|
||||
|
||||
### 3. 批量数据导入
|
||||
- **多格式支持**：支持CSV、Excel、JSON格式导入
|
||||
- **数据验证**：内置数据验证和错误处理
|
||||
- **字段映射**：支持水利行业标准字段映射
|
||||
- **单位转换**：自动进行单位转换和标准化
|
||||
- **批量处理**：支持大批量数据处理
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **后端框架**：FastAPI
|
||||
- **WebSocket**：websockets
|
||||
- **数据处理**：pandas, numpy
|
||||
- **异步处理**：asyncio
|
||||
- **数据验证**：pydantic
|
||||
- **文件处理**：aiofiles
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
water-management-system/
|
||||
├── src/
|
||||
│ ├── api/ # REST API模块
|
||||
│ │ └── rest_api.py # 主API服务器
|
||||
│ ├── websocket/ # WebSocket模块
|
||||
│ │ └── websocket_server.py # WebSocket服务器
|
||||
│ ├── batch/ # 批量导入模块
|
||||
│ │ └── batch_import.py # 批量导入功能
|
||||
│ ├── utils/ # 工具模块
|
||||
│ │ └── data_utils.py # 数据处理工具
|
||||
│ └── models/ # 数据模型
|
||||
│ └── models.py # 数据模型定义
|
||||
├── main.py # 主程序入口
|
||||
├── requirements.txt # 依赖文件
|
||||
├── config.json # 配置文件
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## API 接口文档
|
||||
|
||||
### REST API 端点
|
||||
|
||||
#### 1. IoT 数据接收
|
||||
```
|
||||
POST /api/iot/data
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"device_id": "device_001",
|
||||
"data_type": "LL",
|
||||
"value": 25.5,
|
||||
"timestamp": "2024-01-01T12:00:00",
|
||||
"location": "A区"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 手动数据录入
|
||||
```
|
||||
POST /api/manual/data
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"source": "manual",
|
||||
"data_type": "YL",
|
||||
"value": 0.8,
|
||||
"timestamp": "2024-01-01T12:00:00",
|
||||
"operator": "张三",
|
||||
"notes": "定期数据录入"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 批量导入
|
||||
```
|
||||
POST /api/batch/import
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"batch_id": "batch_001",
|
||||
"data_source": "system_import",
|
||||
"records": [
|
||||
{
|
||||
"device_id": "device_002",
|
||||
"data_type": "SW",
|
||||
"value": 5.2,
|
||||
"timestamp": "2024-01-01T12:00:00",
|
||||
"location": "B区"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 数据查询
|
||||
```
|
||||
GET /api/data/{data_type}?limit=100&offset=0
|
||||
GET /api/data/recent?hours=24&limit=100
|
||||
GET /api/stats
|
||||
```
|
||||
|
||||
### WebSocket 连接
|
||||
|
||||
#### 连接端点
|
||||
```
|
||||
ws://localhost:8765
|
||||
```
|
||||
|
||||
#### 消息格式
|
||||
|
||||
**发送消息**：
|
||||
```json
|
||||
{
|
||||
"type": "subscribe",
|
||||
"subscription": "LL" // 订阅特定类型数据，"all"订阅所有
|
||||
}
|
||||
```
|
||||
|
||||
**接收消息**：
|
||||
```json
|
||||
{
|
||||
"type": "sensor_data",
|
||||
"data_type": "LL",
|
||||
"device_id": "device_001",
|
||||
"value": 25.5,
|
||||
"location": "A区",
|
||||
"timestamp": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 安装和运行
|
||||
|
||||
### 1. 安装依赖
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 启动系统
|
||||
```bash
|
||||
# 普通模式
|
||||
python main.py
|
||||
|
||||
# 演示模式（自动生成数据）
|
||||
python main.py --demo
|
||||
|
||||
# 指定配置文件
|
||||
python main.py --config custom_config.json
|
||||
```
|
||||
|
||||
### 3. 初始化项目
|
||||
```bash
|
||||
python main.py --init
|
||||
```
|
||||
|
||||
## 配置文件
|
||||
|
||||
创建 `config.json` 文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 8000
|
||||
},
|
||||
"websocket": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 8765
|
||||
},
|
||||
"batch": {
|
||||
"max_file_size_mb": 100,
|
||||
"supported_formats": ["csv", "excel", "json"]
|
||||
},
|
||||
"demo_mode": true,
|
||||
"logging": {
|
||||
"level": "INFO",
|
||||
"file": "water_management.log"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 数据类型说明
|
||||
|
||||
支持的水利行业标准数据类型：
|
||||
|
||||
| 数据类型 | 描述 | 单位 |
|
||||
|---------|------|------|
|
||||
| LL | 流量 | m³/h |
|
||||
| YL | 压力 | MPa |
|
||||
| SW | 水位 | m |
|
||||
| ZD | 浊度 | NTU |
|
||||
| PH | pH值 | - |
|
||||
| WD | 温度 | °C |
|
||||
| DD | 电导率 | μS/cm |
|
||||
| YD | 硬度 | mg/L |
|
||||
|
||||
## 开发规范
|
||||
|
||||
### 代码结构
|
||||
- 遵循模块化设计，功能解耦
|
||||
- 使用异步编程提高性能
|
||||
- 统一的错误处理机制
|
||||
- 完整的日志记录
|
||||
|
||||
### 数据处理
|
||||
- 数据验证和清洗
|
||||
- 标准化字段映射
|
||||
- 单位自动转换
|
||||
- 质量评分机制
|
||||
|
||||
### 安全考虑
|
||||
- 输入数据验证
|
||||
- 文件大小限制
|
||||
- 连接状态监控
|
||||
- 错误信息脱敏
|
||||
|
||||
## 测试和验证
|
||||
|
||||
### 数据验证
|
||||
```python
|
||||
from src.utils.data_utils import data_converter
|
||||
|
||||
# 验证传感器数据
|
||||
validation_result = data_converter.validate_sensor_data({
|
||||
"device_id": "device_001",
|
||||
"data_type": "LL",
|
||||
"value": 25.5,
|
||||
"location": "A区"
|
||||
})
|
||||
|
||||
print(validation_result)
|
||||
```
|
||||
|
||||
### 批量导入测试
|
||||
```python
|
||||
import asyncio
|
||||
from src.batch.batch_import import batch_manager
|
||||
|
||||
async def test_import():
|
||||
result = await batch_manager.import_file(
|
||||
file_path="data.csv",
|
||||
batch_id="test_batch",
|
||||
data_source="test"
|
||||
)
|
||||
print(result)
|
||||
|
||||
asyncio.run(test_import())
|
||||
```
|
||||
|
||||
## 部署建议
|
||||
|
||||
### 1. 生产环境配置
|
||||
- 使用反向代理（Nginx）
|
||||
- 配置SSL证书
|
||||
- 设置防火墙规则
|
||||
- 监控系统资源使用
|
||||
|
||||
### 2. 性能优化
|
||||
- 数据库连接池
|
||||
- 缓存机制
|
||||
- 异步处理优化
|
||||
- 连接数限制
|
||||
|
||||
### 3. 监控和日志
|
||||
- 应用性能监控
|
||||
- 错误日志收集
|
||||
- 性能指标统计
|
||||
- 告警机制
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目遵循 MIT 许可证。
|
||||
|
||||
## 贡献指南
|
||||
|
||||
欢迎提交 Issue 和 Pull Request来贡献代码。
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题，请通过以下方式联系：
|
||||
- 邮箱：bot_dev1@xayunmei.com
|
||||
- 项目地址：http://git.xayunmei.com/bot_ym/water-management-system
|
||||
Reference in New Issue
Block a user