ems-frontend-template/CLAUDE.md

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

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