# EMS Core Development Guidelines

## Overview
This is the shared core library for all EMS customer projects. Changes here affect ALL customer deployments.

## Golden Rules
- All changes must go through Pull Request with code review
- Follow Conventional Commits: `<type>(<scope>): <description>`
- Types: feat, fix, refactor, docs, test, chore, style, perf
- Scopes: api, models, services, collector, hooks, tasks, config

## Architecture
- `backend/app/api/v1/` — API endpoint modules
- `backend/app/collectors/` — Device data collectors (Sungrow, Modbus, MQTT, HTTP)
- `backend/app/hooks/` — Customer plugin system (base + loader)
- `backend/app/models/` — SQLAlchemy ORM models
- `backend/app/services/` — Business logic layer
- `backend/app/tasks/` — Background tasks (Celery + APScheduler)
- `backend/alembic/` — Database migrations
- **Note:** Frontend is NOT included in ems-core. Each customer repo owns its own frontend.

## Database Migrations
- Every model change requires an Alembic migration
- Test migrations before deploying: `alembic upgrade head`
- Never manually edit `alembic_version` table

## Testing
- Run tests: `cd backend && pytest`
- Minimum test coverage for new features

## Version
- Follow SemVer (MAJOR.MINOR.PATCH)
- Current: see VERSION file