From 2516b8d1dee8c49bd82cb145ac2399393f20e183 Mon Sep 17 00:00:00 2001 From: Du Wenbo Date: Mon, 6 Apr 2026 08:55:15 +0800 Subject: [PATCH] docs: rewrite README with correct URLs, structure, and v1.2.0 - 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) --- README.md | 218 ++++++++++++++++++++++++------------------------------ 1 file changed, 98 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index ca9c28e..2a99de8 100644 --- a/README.md +++ b/README.md @@ -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. --- -## 核心功能 - -- **实时监控大屏** — 3D 园区可视化 + 多维度能源数据实时展示 -- **设备管理** — 园区设备台账、运行状态监控、故障告警 -- **能耗分析** — 多维度能耗统计、同比环比分析、能耗排名 -- **碳排放管理** — 碳排放核算、碳足迹追踪、减排目标管理 -- **告警中心** — 实时告警推送、告警分级处理、历史告警查询 -- **报表中心** — 自动生成日/周/月报表、支持 Excel 导出 -- **系统管理** — 用户权限管理、操作日志、系统配置 - ---- - -## 系统架构 +## System Architecture ``` - ┌────────────────────┐ - │ Backend (Core) │ - │ FastAPI │ - │ :8000 │ - │ /api/v1/* │ - └─────────┬──────────┘ - │ - ┌────────────┼────────────┐ - │ │ -┌──────▼──────┐ ┌───────▼───────┐ -│ TimescaleDB │ │ Redis │ -│ PostgreSQL │ │ 缓存/队列 │ -│ :5432 │ │ :6379 │ -└─────────────┘ └───────────────┘ + +--------------------+ + | Backend (Core) | + | FastAPI | + | :8000 | + | /api/v1/* | + +--------+-----------+ + | + +-----------+-----------+ + | | ++------v------+ +------v-------+ +| TimescaleDB | | Redis | +| PostgreSQL | | Cache/Queue| +| :5432 | | :6379 | ++-------------+ +--------------+ Note: Frontend and Nginx are NOT part of ems-core. 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 -| 层级 | 技术 | -|------|------| -| 后端框架 | FastAPI (Python 3.11) | +| Layer | Technology | +|-------|-----------| +| Backend | FastAPI (Python 3.11) | | ORM | SQLAlchemy 2.0 (async) | -| 数据库 | TimescaleDB (PostgreSQL 16) | -| 缓存 | Redis 7 | -| 任务队列 | Celery + APScheduler | -| 数据库迁移 | Alembic | -| 容器化 | Docker + Docker Compose | +| Database | TimescaleDB (PostgreSQL 16) | +| Cache | Redis 7 | +| Task Queue | Celery + APScheduler | +| Migrations | Alembic | +| Container | Docker + Docker Compose | --- -## 快速开始 +## Quick Start -### 前置要求 +### Prerequisites - Docker 20.10+ - Docker Compose 2.0+ -### 一键启动 +### Start Services ```bash -# 克隆项目 -git clone http://100.108.180.60:3300/tianpu/tianpu-ems.git -cd tianpu-ems +# Clone +git clone http://100.69.143.96:3300/tianpu/ems-core.git +cd ems-core -# 复制环境变量 +# Configure cp .env.example .env -# 启动所有服务 -docker-compose up -d +# Start all services +docker compose up -d -# 初始化数据库 & 写入种子数据 -docker exec tianpu_backend python scripts/init_db.py -docker exec tianpu_backend python scripts/seed_data.py +# Initialize database +docker compose exec backend python scripts/init_db.py ``` -或使用快速启动脚本： +Or use the quick-start script: ```bash bash scripts/quick-start.sh ``` -### 访问地址 +### Access -| 服务 | 地址 | -|------|------| -| 后端 API | http://localhost:8000 | -| API 文档 (Swagger) | http://localhost:8000/docs | -| 健康检查 | http://localhost:8000/health | +| Service | URL | +|---------|-----| +| Backend API | http://localhost:8000 | +| API Docs (Swagger) | http://localhost:8000/docs | +| Health Check | http://localhost:8000/health | -### 默认账号 +### Default Login -| 角色 | 用户名 | 密码 | -|------|--------|------| -| 管理员 | admin | admin123 | +| Role | Username | Password | +|------|----------|----------| +| Admin | admin | admin123 | -> 请在首次登录后立即修改默认密码。 +> Change the default password after first login. --- -## 本地开发 - -### 后端开发 +## Local Development ```bash cd backend -# 创建虚拟环境 +# Create venv python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate -# 安装依赖 +# Install deps 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 ``` -### 仅启动基础设施 +Start only infrastructure: ```bash -# 只启动数据库和 Redis -docker-compose up -d postgres redis +docker compose up -d postgres redis ``` --- -## 生产部署 - -```bash -# 使用生产配置 -docker-compose -f docker-compose.prod.yml up -d -``` - -生产环境后端使用 Gunicorn + Uvicorn workers。Nginx 和前端由各客户项目自行提供。 - ---- - -## 项目结构 +## Project Structure ``` 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 ++-- backend/ # Backend service +| +-- app/ +| | +-- api/v1/ # API routes +| | +-- collectors/ # Data collectors (Sungrow, Modbus, MQTT, HTTP) +| | +-- core/ # Core config +| | +-- hooks/ # Customer plugin system +| | +-- models/ # SQLAlchemy ORM models +| | +-- services/ # Business logic +| | +-- tasks/ # Background tasks (Celery + APScheduler) +| | +-- templates/ # Email templates +| | +-- main.py # App entry point +| +-- alembic/ # Database migrations +| +-- tests/ # Test suite +| +-- Dockerfile +| +-- requirements.txt ++-- scripts/ # Utility scripts +| +-- init_db.py # Database initialization +| +-- backfill_data.py # Historical data backfill +| +-- quick-start.sh # Quick start script ++-- docker-compose.yml # Dev environment ++-- docker-compose.prod.yml # Production environment ++-- VERSION # Version file ++-- 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` — 认证与授权 -- `/api/v1/devices` — 设备管理 -- `/api/v1/energy` — 能耗数据 -- `/api/v1/carbon` — 碳排放 -- `/api/v1/alarms` — 告警管理 -- `/api/v1/reports` — 报表 -- `/api/v1/system` — 系统管理 +Full Swagger docs at [http://localhost:8000/docs](http://localhost:8000/docs) after starting the backend. --- -## 说明 +## 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 -Copyright 2026 天普集团. All rights reserved. +Copyright 2026. All rights reserved.