# data-analysis

**Repository Path**: elfbobo_admin_admin/data-analysis

## Basic Information

- **Project Name**: data-analysis
- **Description**: 专注于数据分析领域的开源项目，提供数据处理、分析及可视化工具，助力开发者高效解决数据相关问题。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-13
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Data-Analysis Platform

> 物业保洁设备与员工健康管理的AI分析平台

[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 📋 项目简介

Data-Analysis Platform 是一个基于 FastAPI 的实时数据分析平台，专为物业保洁行业设计。系统通过 WebSocket 提供实时数据分析服务，结合AI技术生成智能化的分析报告。

### 核心功能

- **🔧 设备运行分析**：实时监控清洁设备的运行状况，计算6维评分（可用性、出勤、利用率、一致性、合规、可靠性）
- **💚 员工健康监测**：分析60岁以上保洁员工的健康数据，提供健康建议和用人风险评估
- **🤖 AI智能分析**：集成多个AI模型（GPT-4、DeepSeek等），自动生成专业分析报告
- **📊 数据可视化**：提供区域、项目、设备等多维度的数据展示
- **🔐 权限管理**：基于部门的数据访问控制

---

## 🚀 快速开始

### 前置要求

- Python 3.9 或更高版本
- MongoDB 4.4+
- Elasticsearch 7.17+
- Redis 6.0+

### 安装步骤

#### 1. 克隆项目

```bash
git clone <repository_url>
cd data-analysis
```

#### 2. 创建虚拟环境

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\\Scripts\\activate
# macOS/Linux:
source venv/bin/activate
```

#### 3. 安装依赖

```bash
pip install -r req.txt
```

#### 4. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填写实际配置
# 必须配置的项目：
# - AI API 密钥（LAOZHANG_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY）
# - MongoDB连接URI (MONGODB_URI)
# - Elasticsearch配置 (ELASTICSEARCH_*)
# - Redis配置 (REDIS_*)
```

#### 5. 启动服务

```bash
# 开发模式启动
python main.py

# 或使用 uvicorn 启动
uvicorn main:app --host 0.0.0.0 --port 8990 --reload
```

服务启动后访问：
- API文档：http://localhost:8990/docs
- 健康检查：http://localhost:8990/health

---

## 📁 项目结构

```
data-analysis/
├── client/                 # 外部服务客户端
│   ├── es_client.py        # Elasticsearch客户端
│   ├── openai_client.py    # AI服务客户端（支持多个提供商）
│   └── redis_client.py     # Redis客户端
├── controller/             # API控制器（路由层）
│   ├── ai/                 # AI分析端点
│   │   ├── equipment.py    # 设备分析WebSocket
│   │   └── health.py       # 健康分析WebSocket
│   └── api/                # REST API端点
├── dao/                    # 数据访问对象（DAO层）
│   ├── es_dao/             # Elasticsearch数据访问
│   │   ├── i_iot_run_dao.py       # IoT运行数据
│   │   └── p_health_log_dao.py    # 健康日志数据
│   ├── mongo_dao/          # MongoDB数据访问
│   └── redis_dao/          # Redis数据访问
├── middleware/             # 中间件
│   └── auth_middleware.py  # 认证中间件
├── model/                  # 数据模型
│   └── es/                 # Elasticsearch数据模型
├── utils/                  # 工具函数
│   ├── date_utils.py       # 日期时间工具
│   ├── logger_util.py      # 日志工具
│   └── mongo_util.py       # MongoDB工具
├── docs/                   # 项目文档
│   ├── architecture.md     # 架构设计文档
│   ├── api_reference.md    # API参考文档
│   ├── deployment.md       # 部署指南
│   ├── troubleshooting.md  # 问题排查手册
│   └── onboarding.md       # 新人培训指南
├── test/                   # 测试代码
├── config.py               # 配置文件
├── main.py                 # 应用入口
├── .env.example            # 环境变量模板
└── req.txt                 # 依赖列表
```

---

## 🔌 API 接口

### WebSocket 接口

#### 1. 设备运行分析

**端点**：`ws://localhost:8990/dataAnalysis/ai/equipmentAnalysisWs?token=YOUR_TOKEN`

**请求格式**：
```json
{
  "term": {
    "member.id": 123
  },
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-31T23:59:59Z"
}
```

**响应格式**：
```json
{
  "type": "analysis_data",
  "summary": [...],
  "monthly_scores": [...],
  "weekly_summary": [...],
  "region_scores": [...],
  "project_scores": [...]
}
```

#### 2. 员工健康分析

**端点**：`ws://localhost:8990/test/ai/healthAnalysisWs?token=YOUR_TOKEN`

**请求格式**：
```json
{
  "imei": ["device1", "device2"],
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z",
  "model": "gpt-4o-mini"
}
```

详细API文档请查看 [docs/api_reference.md](docs/api_reference.md)

---

## 🔐 认证机制

系统使用基于Token的认证机制：

1. **Token来源**：从WebSocket查询参数或Authorization头获取
2. **Token验证**：从Redis验证token有效性
3. **权限控制**：基于部门ID列表进行数据访问控制

### 连接示例

```javascript
// 方式1：通过查询参数传递token
const ws = new WebSocket('ws://localhost:8990/dataAnalysis/ai/equipmentAnalysisWs?token=YOUR_TOKEN');

// 方式2：通过请求头传递token（需要客户端支持）
const ws = new WebSocket('ws://localhost:8990/dataAnalysis/ai/equipmentAnalysisWs', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});
```

---

## 📊 核心业务逻辑

### 设备评分算法

系统采用6维度评分体系（0-100分）：

| 维度 | 代码 | 权重 | 说明 |
|-----|------|-----|------|
| 可用性 | A | 10% | 设备可工作天数占比 |
| 出勤覆盖 | C | 25% | 实际工作天数占可工作天数比例 |
| 强度利用 | U | 25% | 实际工作时长与标准工作时长比例 |
| 一致性 | S | 5% | 工作时长的稳定程度 |
| 合规达标 | P | 30% | 达到工作标准的天数占比 |
| 可靠性 | R | 5% | 反映设备故障率 |

**综合分** = 0.1×A + 0.25×C + 0.25×U + 0.05×S + 0.30×P + 0.05×R

详细算法说明请查看 [docs/architecture.md](docs/architecture.md)

---

## 🛠️ 开发指南

### 代码规范

- 使用中文注释，方便团队理解
- 函数和类必须包含docstring（包含参数、返回值、异常说明）
- 使用类型注解（typing）提高代码可读性
- 遵循PEP 8代码风格

### 添加新的数据分析端点

1. 在 `controller/ai/` 创建新文件
2. 导入认证中间件：
   ```python
   from middleware.auth_middleware import authenticate_websocket_token
   ```
3. 在WebSocket端点中添加认证：
   ```python
   @router.websocket("/yourEndpoint")
   async def your_endpoint(ws: WebSocket):
       user_context = await authenticate_websocket_token(ws)
       if not user_context:
           await ws.close(code=1008)
           return
       await ws.accept()
       # 你的业务逻辑...
   ```

### 数据访问最佳实践

```python
# ✅ 推荐：使用DAO层
from dao.es_dao.i_iot_run_dao import get_equipment_list

equipment = await get_equipment_list(query_params)

# ❌ 不推荐：直接使用客户端
from client.es_client import ESClient

client = ESClient()
equipment = await client.search(...)  # 耦合度高，不利于维护
```

---

## 🧪 测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest test/controller/test_equipment.py

# 生成覆盖率报告
pytest --cov=. --cov-report=html
```

---

## 📝 日志

应用使用Python标准logging模块，日志配置在 `utils/logger_util.py`。

日志级别：
- `DEBUG`: 详细的调试信息
- `INFO`: 一般信息（默认级别）
- `WARNING`: 警告信息
- `ERROR`: 错误信息
- `CRITICAL`: 严重错误

日志文件位置：`./logs/app.log`（每日轮转，保留30天）

---

## 🚨 故障排查

常见问题和解决方案请查看 [docs/troubleshooting.md](docs/troubleshooting.md)

### 快速检查清单

- [ ] 环境变量是否正确配置（检查 `.env` 文件）
- [ ] MongoDB/Elasticsearch/Redis 是否正常运行
- [ ] API密钥是否有效（检查日志中的认证错误）
- [ ] 网络连接是否正常（检查防火墙设置）
- [ ] Python版本是否符合要求（>=3.9）

---

## 📚 相关文档

- [系统架构设计](docs/architecture.md) - 了解系统整体架构
- [API参考文档](docs/api_reference.md) - 详细的API接口说明
- [部署运维指南](docs/deployment.md) - 生产环境部署步骤
- [问题排查手册](docs/troubleshooting.md) - 常见问题解决方案
- [新人培训指南](docs/onboarding.md) - 新成员快速上手

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！在提交PR之前，请确保：

1. 代码符合项目规范
2. 添加了必要的测试
3. 更新了相关文档
4. 通过了所有测试

---

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 👥 联系方式

- 项目负责人：Data Analysis Team
- Email: support@example.com
- Issue反馈：[GitHub Issues](https://github.com/your-org/data-analysis/issues)

---

## 🎯 路线图

### v1.0（当前版本）
- ✅ 基础设备分析功能
- ✅ 健康数据分析功能
- ✅ Token认证机制
- ✅ 多AI模型集成

### v2.0（计划中）
- 🔲 灵活查询粒度（区域/项目/设备组合查询）
- 🔲 实时告警系统
- 🔲 数据导出功能（Excel/PDF）
- 🔲 移动端支持

### v3.0（长期规划）
- 🔲 机器学习预测模型
- 🔲 自定义报表系统
- 🔲 多租户支持
- 🔲 API开放平台

---

**祝你使用愉快！** 🎉