tianpu/ems-core
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README with correct URLs, structure, and v1.2.0

Browse Source 
- Fix clone URL from old Mac Studio to labmac3 Gitea
- Fix repo name from tianpu-ems to ems-core
- Remove nonexistent seed_data.py reference
- Add missing dirs: tests/, templates/, VERSION, VERSIONS.json
- Add version badge referencing VERSIONS.json

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Du Wenbo
2026-04-06 08:55:15 +08:00
parent 4095ba0b56
commit 2516b8d1de
1 changed files with 98 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
README.md
View File

@@ -1,40 +1,30 @@
# 天普零碳园区智慧能源管理平台 # EMS Core Platform (ems-core)
> Tianpu Zero-Carbon Park Smart Energy Management System > Backend + shared libraries for all EMS customer projects
天普零碳园区智慧能源管理平台是面向工业园区业主的一站式能源管理解决方案。通过实时数据采集、智能分析和可视化大屏，帮助园区实现能源消耗透明化、碳排放精准核算和运营效率全面提升。 **Current Version: 1.2.0** (see `VERSIONS.json`)
ems-core is the shared backend core for all EMS deployments. It provides the FastAPI backend, database models, data collectors, and customer hooks system. **Frontend and Nginx are NOT included** -- each customer repo provides its own frontend.
--- ---
## 核心功能 ## System Architecture
- **实时监控大屏** — 3D 园区可视化 + 多维度能源数据实时展示
- **设备管理** — 园区设备台账、运行状态监控、故障告警
- **能耗分析** — 多维度能耗统计、同比环比分析、能耗排名
- **碳排放管理** — 碳排放核算、碳足迹追踪、减排目标管理
- **告警中心** — 实时告警推送、告警分级处理、历史告警查询
- **报表中心** — 自动生成日/周/月报表、支持 Excel 导出
- **系统管理** — 用户权限管理、操作日志、系统配置
---
## 系统架构
``` ```
┌────────────────────┐ +--------------------+
│ Backend (Core) │ | Backend (Core) |
│ FastAPI │ | FastAPI |
│ :8000 │ | :8000 |
│ /api/v1/* │ | /api/v1/* |
└─────────┬──────────┘ +--------+-----------+
│ |
┌────────────┼────────────┐ +-----------+-----------+
│ │ | |
┌──────▼──────┐ ┌───────▼───────┐ +------v------+ +------v-------+
│ TimescaleDB │ │ Redis │ | TimescaleDB | | Redis |
│ PostgreSQL │ │ 缓存/队列 │ | PostgreSQL | | Cache/Queue|
│ :5432 │ │ :6379 │ | :5432 | | :6379 |
└─────────────┘ └───────────────┘ +-------------+ +--------------+
Note: Frontend and Nginx are NOT part of ems-core. Note: Frontend and Nginx are NOT part of ems-core.
Each customer repo provides its own frontend and reverse proxy. Each customer repo provides its own frontend and reverse proxy.
@@ -42,160 +32,148 @@ Each customer repo provides its own frontend and reverse proxy.
--- ---
## 技术栈 ## Tech Stack
| 层级 | 技术 | | Layer | Technology |
|------|------| |-------|-----------|
| 后端框架 | FastAPI (Python 3.11) | | Backend | FastAPI (Python 3.11) |
| ORM | SQLAlchemy 2.0 (async) | | ORM | SQLAlchemy 2.0 (async) |
| 数据库 | TimescaleDB (PostgreSQL 16) | | Database | TimescaleDB (PostgreSQL 16) |
| 缓存 | Redis 7 | | Cache | Redis 7 |
| 任务队列 | Celery + APScheduler | | Task Queue | Celery + APScheduler |
| 数据库迁移 | Alembic | | Migrations | Alembic |
| 容器化 | Docker + Docker Compose | | Container | Docker + Docker Compose |
--- ---
## 快速开始 ## Quick Start
### 前置要求 ### Prerequisites
- Docker 20.10+ - Docker 20.10+
- Docker Compose 2.0+ - Docker Compose 2.0+
### 一键启动 ### Start Services
```bash ```bash
# 克隆项目 # Clone
git clone http://100.108.180.60:3300/tianpu/tianpu-ems.git git clone http://100.69.143.96:3300/tianpu/ems-core.git
cd tianpu-ems cd ems-core
# 复制环境变量 # Configure
cp .env.example .env cp .env.example .env
# 启动所有服务 # Start all services
docker-compose up -d docker compose up -d
# 初始化数据库 & 写入种子数据 # Initialize database
docker exec tianpu_backend python scripts/init_db.py docker compose exec backend python scripts/init_db.py
docker exec tianpu_backend python scripts/seed_data.py
``` ```
或使用快速启动脚本： Or use the quick-start script:
```bash ```bash
bash scripts/quick-start.sh bash scripts/quick-start.sh
``` ```
### 访问地址 ### Access
| 服务 | 地址 | | Service | URL |
|------|------| |---------|-----|
| 后端 API | http://localhost:8000 | | Backend API | http://localhost:8000 |
| API 文档 (Swagger) | http://localhost:8000/docs | | API Docs (Swagger) | http://localhost:8000/docs |
| 健康检查 | http://localhost:8000/health | | Health Check | http://localhost:8000/health |
### 默认账号 ### Default Login
| 角色 | 用户名 | 密码 | | Role | Username | Password |
|------|--------|------| |------|----------|----------|
| 管理员 | admin | admin123 | | Admin | admin | admin123 |
> 请在首次登录后立即修改默认密码。 > Change the default password after first login.
--- ---
## 本地开发 ## Local Development
### 后端开发
```bash ```bash
cd backend cd backend
# 创建虚拟环境 # Create venv
python -m venv venv python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖 # Install deps
pip install -r requirements.txt pip install -r requirements.txt
# 启动开发服务器 (需先启动 PostgreSQL 和 Redis) # Start dev server (requires PostgreSQL and Redis running)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
``` ```
### 仅启动基础设施 Start only infrastructure:
```bash ```bash
# 只启动数据库和 Redis docker compose up -d postgres redis
docker-compose up -d postgres redis
``` ```
--- ---
## 生产部署 ## Project Structure
```bash
# 使用生产配置
docker-compose -f docker-compose.prod.yml up -d
```
生产环境后端使用 Gunicorn + Uvicorn workers。Nginx 和前端由各客户项目自行提供。
---
## 项目结构
``` ```
ems-core/ ems-core/
├── backend/ # 后端服务 (Backend-only core) +-- backend/ # Backend service
│ ├── app/ | +-- app/
│ │ ├── api/ # API 路由 | | +-- api/v1/ # API routes
│ │ │ └── v1/ # v1 版本接口 | | +-- collectors/ # Data collectors (Sungrow, Modbus, MQTT, HTTP)
│ │ ├── collectors/ # 数据采集器 | | +-- core/ # Core config
│ │ ├── core/ # 核心配置 | | +-- hooks/ # Customer plugin system
│ │ ├── hooks/ # 客户插件系统 | | +-- models/ # SQLAlchemy ORM models
│ │ ├── models/ # 数据模型 | | +-- services/ # Business logic
│ │ ├── services/ # 业务逻辑 | | +-- tasks/ # Background tasks (Celery + APScheduler)
│ │ ├── tasks/ # 后台任务 | | +-- templates/ # Email templates
│ │ └── main.py # 应用入口 | | +-- main.py # App entry point
│ ├── alembic/ # 数据库迁移 | +-- alembic/ # Database migrations
│ ├── Dockerfile | +-- tests/ # Test suite
│ └── requirements.txt | +-- Dockerfile
├── scripts/ # 脚本工具 | +-- requirements.txt
│ ├── init_db.py # 数据库初始化 +-- scripts/ # Utility scripts
│ ├── seed_data.py # 种子数据 | +-- init_db.py # Database initialization
│ ├── backfill_data.py # 历史数据回填 | +-- backfill_data.py # Historical data backfill
│ └── quick-start.sh # 快速启动脚本 | +-- quick-start.sh # Quick start script
├── docker-compose.yml # 开发环境编排 +-- docker-compose.yml # Dev environment
├── docker-compose.prod.yml # 生产环境编排 +-- docker-compose.prod.yml # Production environment
├── .env.example # 环境变量模板 +-- VERSION # Version file
└── README.md +-- VERSIONS.json # Version metadata
+-- .env.example # Environment variables template
+-- CLAUDE.md # AI assistant guidelines
+-- README.md
``` ```
--- ---
## API 文档 ## API Endpoints
启动后端服务后访问 [http://localhost:8000/docs](http://localhost:8000/docs) 查看完整的 Swagger API 文档。 Main modules:
主要接口模块： - `/api/v1/auth` -- Authentication
- `/api/v1/devices` -- Device management
- `/api/v1/energy` -- Energy data
- `/api/v1/carbon` -- Carbon emissions
- `/api/v1/alarms` -- Alarm management
- `/api/v1/reports` -- Reports
- `/api/v1/system` -- System management
- `/api/v1/auth` — 认证与授权 Full Swagger docs at [http://localhost:8000/docs](http://localhost:8000/docs) after starting the backend.
- `/api/v1/devices` — 设备管理
- `/api/v1/energy` — 能耗数据
- `/api/v1/carbon` — 碳排放
- `/api/v1/alarms` — 告警管理
- `/api/v1/reports` — 报表
- `/api/v1/system` — 系统管理
--- ---
## 说明 ## Note
ems-core 是后端核心库，不包含前端代码。每个客户项目（如 tianpu-ems）拥有自己的前端仓库，独立部署和定制 UI。 ems-core is the backend-only shared library. Each customer project (tp-ems, zpark-ems) owns its own frontend, deployed independently.
--- ---
## License ## License
Copyright 2026 天普集团. All rights reserved. Copyright 2026. All rights reserved.