tianpu-ems/README.md

# 天普零碳园区智慧能源管理平台

> Tianpu Zero-Carbon Park Smart Energy Management System

天普零碳园区智慧能源管理平台是面向工业园区业主的一站式能源管理解决方案。通过实时数据采集、智能分析和可视化大屏，帮助园区实现能源消耗透明化、碳排放精准核算和运营效率全面提升。

---

## 核心功能

- **实时监控大屏** — 3D 园区可视化 + 多维度能源数据实时展示
- **设备管理** — 园区设备台账、运行状态监控、故障告警
- **能耗分析** — 多维度能耗统计、同比环比分析、能耗排名
- **碳排放管理** — 碳排放核算、碳足迹追踪、减排目标管理
- **告警中心** — 实时告警推送、告警分级处理、历史告警查询
- **报表中心** — 自动生成日/周/月报表、支持 Excel 导出
- **系统管理** — 用户权限管理、操作日志、系统配置

---

## 系统架构

```
                          ┌──────────────┐
                          │   Nginx      │
                          │  反向代理     │
                          │  :80 / :443  │
                          └──────┬───────┘
                                 │
                 ┌───────────────┼───────────────┐
                 │                               │
          ┌──────▼──────┐               ┌────────▼────────┐
          │  Frontend   │               │    Backend       │
          │  React 19   │               │   FastAPI        │
          │  Ant Design │               │   :8000          │
          │  ECharts    │               │                  │
          │  Three.js   │               │  /api/v1/*       │
          └─────────────┘               └───────┬──────────┘
                                                │
                                 ┌──────────────┼──────────────┐
                                 │                             │
                          ┌──────▼──────┐             ┌───────▼───────┐
                          │ TimescaleDB │             │    Redis      │
                          │ PostgreSQL  │             │   缓存/队列    │
                          │   :5432     │             │   :6379       │
                          └─────────────┘             └───────────────┘
```

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | React 19 + TypeScript |
| UI 组件库 | Ant Design 5 + ProComponents |
| 数据可视化 | ECharts 6 |
| 3D 渲染 | Three.js + React Three Fiber |
| 后端框架 | FastAPI (Python 3.11) |
| ORM | SQLAlchemy 2.0 (async) |
| 数据库 | TimescaleDB (PostgreSQL 16) |
| 缓存 | Redis 7 |
| 任务队列 | Celery + APScheduler |
| 数据库迁移 | Alembic |
| 容器化 | Docker + Docker Compose |

---

## 快速开始

### 前置要求

- Docker 20.10+
- Docker Compose 2.0+

### 一键启动

```bash
# 克隆项目
git clone http://100.108.180.60:3300/tianpu/tianpu-ems.git
cd tianpu-ems

# 复制环境变量
cp .env.example .env

# 启动所有服务
docker-compose up -d

# 初始化数据库 & 写入种子数据
docker exec tianpu_backend python scripts/init_db.py
docker exec tianpu_backend python scripts/seed_data.py
```

或使用快速启动脚本：

```bash
bash scripts/quick-start.sh
```

### 访问地址

| 服务 | 地址 |
|------|------|
| 前端页面 | http://localhost:3000 |
| 后端 API | http://localhost:8000 |
| API 文档 (Swagger) | http://localhost:8000/docs |
| 健康检查 | http://localhost:8000/health |

### 默认账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 管理员 | admin | admin123 |

> 请在首次登录后立即修改默认密码。

---

## 本地开发

### 后端开发

```bash
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器 (需先启动 PostgreSQL 和 Redis)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 前端开发

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

### 仅启动基础设施

```bash
# 只启动数据库和 Redis
docker-compose up -d postgres redis
```

---

## 生产部署

```bash
# 使用生产配置
docker-compose -f docker-compose.prod.yml up -d
```

生产环境使用 Nginx 反向代理，前端编译为静态文件，后端使用 Gunicorn + Uvicorn workers。

---

## 项目结构

```
tianpu-ems/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/               # API 路由
│   │   │   └── v1/            # v1 版本接口
│   │   ├── collectors/        # 数据采集器
│   │   ├── core/              # 核心配置
│   │   ├── models/            # 数据模型
│   │   ├── services/          # 业务逻辑
│   │   ├── tasks/             # 后台任务
│   │   └── main.py            # 应用入口
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── components/        # 公共组件
│   │   ├── layouts/           # 布局组件
│   │   ├── pages/             # 页面组件
│   │   │   ├── BigScreen/     # 数据大屏
│   │   │   ├── BigScreen3D/   # 3D 大屏
│   │   │   ├── Dashboard/     # 仪表盘
│   │   │   ├── Monitoring/    # 实时监控
│   │   │   ├── Devices/       # 设备管理
│   │   │   ├── Analysis/      # 能耗分析
│   │   │   ├── Carbon/        # 碳排放管理
│   │   │   ├── Alarms/        # 告警中心
│   │   │   ├── Reports/       # 报表中心
│   │   │   ├── System/        # 系统管理
│   │   │   └── Login/         # 登录页
│   │   ├── services/          # API 服务
│   │   └── utils/             # 工具函数
│   ├── Dockerfile
│   └── package.json
├── nginx/                      # Nginx 配置
│   ├── nginx.conf
│   └── Dockerfile
├── scripts/                    # 脚本工具
│   ├── init_db.py             # 数据库初始化
│   ├── seed_data.py           # 种子数据
│   ├── backfill_data.py       # 历史数据回填
│   └── quick-start.sh         # 快速启动脚本
├── docker-compose.yml          # 开发环境编排
├── docker-compose.prod.yml     # 生产环境编排
├── .env.example                # 环境变量模板
└── README.md
```

---

## API 文档

启动后端服务后访问 [http://localhost:8000/docs](http://localhost:8000/docs) 查看完整的 Swagger API 文档。

主要接口模块：

- `/api/v1/auth` — 认证与授权
- `/api/v1/devices` — 设备管理
- `/api/v1/energy` — 能耗数据
- `/api/v1/carbon` — 碳排放
- `/api/v1/alarms` — 告警管理
- `/api/v1/reports` — 报表
- `/api/v1/system` — 系统管理

---

## 截图预览

> 截图待补充

| 页面 | 说明 |
|------|------|
| 数据大屏 | 园区能源全景概览 |
| 3D 园区 | 三维可视化园区模型 |
| 仪表盘 | 关键能耗指标看板 |
| 设备监控 | 设备运行状态实时监控 |

---

## License

Copyright 2026 天普集团. All rights reserved.