81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# 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
|
|
```
|