2516b8d1de
- 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>
180 lines
4.3 KiB
Markdown
180 lines
4.3 KiB
Markdown
# EMS Core Platform (ems-core)
|
|
|
|
> 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
|
|
|
|
```
|
|
+--------------------+
|
|
| 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.
|
|
```
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| Backend | FastAPI (Python 3.11) |
|
|
| ORM | SQLAlchemy 2.0 (async) |
|
|
| 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
|
|
# Clone
|
|
git clone http://100.69.143.96:3300/tianpu/ems-core.git
|
|
cd ems-core
|
|
|
|
# Configure
|
|
cp .env.example .env
|
|
|
|
# Start all services
|
|
docker compose up -d
|
|
|
|
# Initialize database
|
|
docker compose exec backend python scripts/init_db.py
|
|
```
|
|
|
|
Or use the quick-start script:
|
|
|
|
```bash
|
|
bash scripts/quick-start.sh
|
|
```
|
|
|
|
### Access
|
|
|
|
| Service | URL |
|
|
|---------|-----|
|
|
| Backend API | http://localhost:8000 |
|
|
| API Docs (Swagger) | http://localhost:8000/docs |
|
|
| Health Check | http://localhost:8000/health |
|
|
|
|
### Default Login
|
|
|
|
| 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
|
|
|
|
# Start dev server (requires PostgreSQL and Redis running)
|
|
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
Start only infrastructure:
|
|
|
|
```bash
|
|
docker compose up -d postgres redis
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ems-core/
|
|
+-- 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 Endpoints
|
|
|
|
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
|
|
|
|
Full Swagger docs at [http://localhost:8000/docs](http://localhost:8000/docs) after starting the backend.
|
|
|
|
---
|
|
|
|
## Note
|
|
|
|
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.
|