ems-core/README.md

# 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.

---

## Version Management

We use **Semantic Versioning** (MAJOR.MINOR.PATCH) and **git tags** to manage releases.

### Where Version Is Tracked

Version must be consistent across **three places**:

| Location | Example | How to update |
|----------|---------|---------------|
| `VERSIONS.json` | `"project_version": "1.2.0"` | Edit the file |
| Git tag | `v1.2.0` | `git tag -a v1.2.0 -m "description"` |
| Gitea repo description | `[v1.2.0] EMS Core...` | Gitea Settings or API |

### Releasing a New Version

```bash
# 1. Update VERSIONS.json (set project_version, last_updated, notes)
#    For customer repos, also update core_version if core was updated

# 2. Commit the version bump
git add VERSIONS.json
git commit -m "chore: bump version to vX.Y.Z"

# 3. Create annotated tag (MUST be after VERSIONS.json is updated)
git tag -a vX.Y.Z -m "vX.Y.Z: brief description of this release"

# 4. Push commit AND tag together
git push origin main
git push origin vX.Y.Z

# 5. Update Gitea repo description
curl -X PATCH "http://<GITEA_HOST>/api/v1/repos/tianpu/<REPO>" \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"description": "[vX.Y.Z] Updated description"}'
```

### Downloading a Specific Version

```bash
# Clone and checkout a specific version
git clone http://100.69.143.96:3300/tianpu/ems-core.git
cd ems-core
git checkout v1.1.0       # switch to v1.1.0 (detached HEAD)

# Or download as zip without cloning
curl -o ems-core-v1.1.0.zip \
  "http://100.69.143.96:3300/tianpu/ems-core/archive/v1.1.0.zip"
```

### Viewing / Comparing Versions

```bash
# List all available versions
git tag -l

# See what changed between two versions
git diff v1.1.0 v1.2.0

# View a specific file at an old version
git show v1.1.0:VERSIONS.json

# View commit log between versions
git log v1.1.0..v1.2.0 --oneline
```

### Switching Back to Latest

```bash
git checkout main          # go back to latest
```

---

## 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.