ems-core/README.md

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

> Tianpu Zero-Carbon Park Smart Energy Management System

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

---

## 核心功能

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

---

## 系统架构

```
          ┌────────────────────┐
          │    Backend (Core)  │
          │    FastAPI         │
          │    :8000           │
          │    /api/v1/*       │
          └─────────┬──────────┘
                    │
       ┌────────────┼────────────┐
       │                         │
┌──────▼──────┐          ┌───────▼───────┐
│ TimescaleDB │          │    Redis      │
│ PostgreSQL  │          │   缓存/队列    │
│   :5432     │          │   :6379       │
└─────────────┘          └───────────────┘

Note: Frontend and Nginx are NOT part of ems-core.
Each customer repo provides its own frontend and reverse proxy.
```

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | 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
```

### 访问地址

| 服务 | 地址 |
|------|------|
| 后端 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
# 只启动数据库和 Redis
docker-compose up -d postgres redis
```

---

## 生产部署

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

生产环境后端使用 Gunicorn + Uvicorn workers。Nginx 和前端由各客户项目自行提供。

---

## 项目结构

```
ems-core/
├── backend/                    # 后端服务 (Backend-only core)
│   ├── app/
│   │   ├── api/               # API 路由
│   │   │   └── v1/            # v1 版本接口
│   │   ├── collectors/        # 数据采集器
│   │   ├── core/              # 核心配置
│   │   ├── hooks/             # 客户插件系统
│   │   ├── models/            # 数据模型
│   │   ├── services/          # 业务逻辑
│   │   ├── tasks/             # 后台任务
│   │   └── main.py            # 应用入口
│   ├── alembic/               # 数据库迁移
│   ├── Dockerfile
│   └── requirements.txt
├── 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` — 系统管理

---

## 说明

ems-core 是后端核心库，不包含前端代码。每个客户项目（如 tianpu-ems）拥有自己的前端仓库，独立部署和定制 UI。

---

## License

Copyright 2026 天普集团. All rights reserved.