# EMS Frontend Template Development Guidelines

## Overview
EMS Frontend Template is the shared base UI framework for all EMS customer projects. Customer repos (tianpu-ems, zpark-ems, etc.) fork or copy from this template and customize for their specific deployment.

## Golden Rules
- This is a TEMPLATE repo -- changes here must be propagated to customer repos manually
- Use i18n for ALL user-visible strings (`src/i18n/zh.json` + `en.json`), never hardcode Chinese or English text
- Theme customization goes through ThemeContext (`src/contexts/ThemeContext.tsx`)
- All API calls go through `src/services/api.ts` -- never use raw axios/fetch in page components
- Feature flags control page visibility via `/api/v1/branding` endpoint
- Follow Conventional Commits: `<type>(<scope>): <description>`
- Types: feat, fix, refactor, docs, test, chore, style, perf

## Tech Stack
- React 19 + TypeScript
- Ant Design 5 + ProComponents
- ECharts 6 (charts and dashboards)
- Three.js + React Three Fiber (optional 3D visualization)
- i18next (zh + en localization)
- Vite 8 (build tool)
- Axios (HTTP client)

## Architecture
```
src/
  pages/           # Page components (one folder per feature)
  layouts/         # Layout components (MainLayout with sidebar)
  contexts/        # React contexts (ThemeContext for branding)
  hooks/           # Custom hooks (useRealtimeWebSocket, etc.)
  services/        # API service layer (api.ts is the single entry point)
  i18n/            # Internationalization files (zh.json, en.json)
  utils/           # Utility functions
  assets/          # Static assets (images, fonts)
  App.tsx          # Root component with route definitions
  main.tsx         # Entry point
```

## Page Structure
- `Dashboard/` -- Main overview dashboard
- `Monitoring/` -- Real-time device monitoring
- `Devices/` + `DeviceDetail/` -- Device management and detail views
- `Analysis/` -- Energy analysis (cost, loss, YoY, MoM)
- `Alarms/` -- Alarm center
- `Carbon/` -- Carbon emissions tracking
- `Reports/` -- Report center
- `BigScreen/` + `BigScreen3D/` -- 2D and 3D visualization screens
- `Charging/` -- EV charging management
- `Prediction/` -- Energy prediction
- `EnergyStrategy/` -- Energy strategy optimization
- `AIOperations/` -- AI-assisted operations
- `Maintenance/` -- Maintenance management
- `DataQuery/` -- Data query interface
- `Management/` -- General management
- `Quota/` -- Energy quota
- `System/` -- System settings and audit log
- `Login/` -- Login page

## How to Customize for a New Customer
1. Copy this template into the new customer repo's `frontend/` directory
2. Update `src/contexts/ThemeContext.tsx` -- branding colors, customer name
3. Update `src/layouts/MainLayout.tsx` -- logo, sidebar menu items
4. Edit `src/App.tsx` -- add/remove routes per customer needs
5. Update `vite.config.ts` -- adjust proxy target if backend port differs
6. Remove unused dependencies from `package.json` (e.g., Three.js if no 3D)
7. Update `VERSIONS.json` with new project name and version

## Version Management
- `VERSIONS.json` and `VERSION` file must stay in sync
- `package.json` version should also match
- Follow SemVer (MAJOR.MINOR.PATCH)
- When releasing: update all three version references, then tag and push
- Current: see `VERSION` file

## Commands
```bash
npm run dev        # Start dev server (port 3000, proxies /api to backend)
npm run build      # Production build (tsc + vite build)
npm run preview    # Preview production build
```