chore: add CLAUDE.md, fix VERSION file and README version label

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,80 @@
+# 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
+```

README.md

@@ -1,24 +1,87 @@
 # EMS Frontend Template
 
-Base React frontend template for EMS customer projects.
+> Base React/TypeScript UI template for EMS customer projects
 
-## Usage
+**Current Version: 1.4.0** | See `VERSIONS.json`
 
-When creating a new customer project, copy this template:
+This is the shared frontend template used to bootstrap new EMS customer frontends. Copy it into a new customer repo and customize.
+
+---
+
+## Usage — New Customer Setup
 
 ```bash
+# Copy template into customer repo
 cp -r ems-frontend-template/ <customer-repo>/frontend/
 cd <customer-repo>/frontend
+
+# Install dependencies
 npm install
+
+# Start dev server
+npm run dev
+# Opens at http://localhost:3000, proxies /api to localhost:8000
 ```
 
-Then customize:
-1. Edit `src/App.tsx` — add/remove routes per customer needs
-2. Edit `src/layouts/MainLayout.tsx` — customer branding (logo, colors, sidebar)
-3. Edit `package.json` — remove unused deps (e.g., Three.js if no 3D)
-4. Edit `vite.config.ts` — update proxy target if backend port differs
+### Customize for your customer:
+
+1. `src/contexts/ThemeContext.tsx` -- Branding colors, customer name
+2. `src/layouts/MainLayout.tsx` -- Logo, sidebar menu items
+3. `src/App.tsx` -- Add/remove routes per customer needs
+4. `vite.config.ts` -- Update proxy target if backend port differs
+5. `package.json` -- Remove unused deps (e.g., Three.js if no 3D)
+6. Update `VERSIONS.json` -- Set new project name and version
+
+---
+
+## Project Structure
+
+```
+ems-frontend-template/
++-- src/
+|   +-- pages/                 # Page components
+|   |   +-- Dashboard/         # Main dashboard
+|   |   +-- Monitoring/        # Real-time monitoring
+|   |   +-- Devices/           # Device management
+|   |   +-- DeviceDetail/      # Device detail view
+|   |   +-- Analysis/          # Energy analysis (cost, loss, YoY, MoM)
+|   |   +-- Alarms/            # Alarm center
+|   |   +-- Carbon/            # Carbon emissions
+|   |   +-- Reports/           # Report center
+|   |   +-- BigScreen/         # 2D visualization screen
+|   |   +-- BigScreen3D/       # 3D visualization screen
+|   |   +-- Charging/          # EV charging management
+|   |   +-- Prediction/        # Energy prediction
+|   |   +-- EnergyStrategy/    # Energy strategy
+|   |   +-- AIOperations/      # AI-assisted operations
+|   |   +-- Maintenance/       # Maintenance management
+|   |   +-- DataQuery/         # Data query
+|   |   +-- Management/        # General management
+|   |   +-- Quota/             # Energy quota
+|   |   +-- System/            # System settings & audit log
+|   |   +-- Login/             # Login page
+|   +-- layouts/               # Layout components (MainLayout)
+|   +-- contexts/              # React contexts (ThemeContext)
+|   +-- hooks/                 # Custom hooks (useRealtimeWebSocket)
+|   +-- services/              # API service layer
+|   +-- i18n/                  # Internationalization (zh + en)
+|   +-- utils/                 # Utility functions
+|   +-- assets/                # Static assets
+|   +-- App.tsx                # Root component with routes
+|   +-- main.tsx               # Entry point
++-- public/
+|   +-- devices/               # SVG device icons
++-- Dockerfile                 # Dev container
++-- Dockerfile.prod            # Production container
++-- vite.config.ts             # Vite config (proxy, port)
++-- package.json
++-- VERSIONS.json              # Version tracking
+```
+
+---
 
 ## Tech Stack
+
 - React 19 + TypeScript
 - Ant Design 5 + ProComponents
 - ECharts 6
@@ -26,18 +89,62 @@ Then customize:
 - i18next (zh + en)
 - Vite 8
 
-## Available Pages
-- Dashboard, Monitoring, Devices, DeviceDetail
-- Analysis (cost, loss, YoY, MoM, subitem)
-- Alarms, Carbon, Reports
-- BigScreen (2D), BigScreen3D (3D)
-- Charging (stations, piles, orders, pricing)
-- Prediction, EnergyStrategy, AIOperations
-- Maintenance, DataQuery, Management, Quota
-- System (settings, audit log)
-- Login
+---
+
+## Available Commands
+
+```bash
+npm run dev        # Start dev server (port 3000)
+npm run build      # Production build
+npm run preview    # Preview production build
+```
+
+---
+
+## Docker
+
+```bash
+# Development
+docker build -t ems-frontend .
+docker run -p 3000:3000 ems-frontend
+
+# Production
+docker build -f Dockerfile.prod -t ems-frontend-prod .
+docker run -p 80:80 ems-frontend-prod
+```
+
+---
+
+## Version Management
+
+```bash
+# List all versions
+git tag -l
+
+# Download a specific version
+git checkout v1.1.0
+
+# Download as zip
+curl -o template-v1.1.0.zip \
+  "http://100.69.143.96:3300/tianpu/ems-frontend-template/archive/v1.1.0.zip"
+
+# Go back to latest
+git checkout master
+```
+
+When releasing: update `VERSIONS.json` + `package.json` version, then tag and push.
+See [ems-core README](http://100.69.143.96:3300/tianpu/ems-core) for the full version management guide.
+
+---
 
 ## Notes
-- Not all pages are needed for every customer
-- Remove unused page imports from App.tsx
-- Remove corresponding dependencies from package.json
+
+- Not all pages are needed for every customer -- remove unused page imports from `App.tsx`
+- Remove corresponding dependencies from `package.json` (e.g., Three.js if no 3D)
+- The template is designed to work with ems-core backend at `/api`
+
+---
+
+## License
+
+Copyright 2026. All rights reserved.

VERSION

@@ -1 +1 @@
-1.1.0
+1.4.0

VERSIONS.json

@@ -1,7 +1,7 @@
 {
   "project": "ems-frontend-template",
-  "project_version": "1.1.0",
-  "core_version": "1.1.0",
-  "last_updated": "2026-04-05",
-  "notes": "Initial frontend template from ems-core v1.1.0"
+  "project_version": "1.4.0",
+  "core_version": "1.4.0",
+  "last_updated": "2026-04-06",
+  "notes": "Version display on login + sidebar for field engineers"
 }

index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>天普智慧能源管理平台</title>
+    <title>智慧能源管理平台</title>
   </head>
   <body>
     <div id="root"></div>

package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "1.0.0",
+  "version": "1.4.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

src/contexts/ThemeContext.tsx

@@ -12,12 +12,12 @@ const ThemeContext = createContext<ThemeContextType>({
 
 export function ThemeProvider({ children }: { children: ReactNode }) {
   const [darkMode, setDarkMode] = useState(() => {
-    const saved = localStorage.getItem('tianpu-dark-mode');
+    const saved = localStorage.getItem('ems-dark-mode');
     return saved === 'true';
   });
 
   useEffect(() => {
-    localStorage.setItem('tianpu-dark-mode', String(darkMode));
+    localStorage.setItem('ems-dark-mode', String(darkMode));
     document.documentElement.setAttribute('data-theme', darkMode ? 'dark' : 'light');
   }, [darkMode]);
 

src/i18n/index.ts

@@ -8,7 +8,7 @@ i18n.use(initReactI18next).init({
     zh: { translation: zh },
     en: { translation: en },
   },
-  lng: localStorage.getItem('tianpu-lang') || 'zh',
+  lng: localStorage.getItem('ems-lang') || 'zh',
   fallbackLng: 'zh',
   interpolation: {
     escapeValue: false,

src/i18n/locales/en.json

@@ -29,7 +29,7 @@
     "viewAllAlarms": "View all alarms",
     "profile": "Profile",
     "logout": "Sign Out",
-    "brandName": "Tianpu EMS"
+    "brandName": "EMS Platform"
   },
   "common": {
     "save": "Save",

src/i18n/locales/zh.json

@@ -29,7 +29,7 @@
     "viewAllAlarms": "查看全部告警",
     "profile": "个人信息",
     "logout": "退出登录",
-    "brandName": "天普EMS"
+    "brandName": "EMS Platform"
   },
   "common": {
     "save": "保存",

src/layouts/MainLayout.tsx

@@ -12,7 +12,7 @@ import {
 import { Outlet, useNavigate, useLocation } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { getUser, removeToken } from '../utils/auth';
-import { getAlarmStats, getAlarmEvents } from '../services/api';
+import { getAlarmStats, getAlarmEvents, getVersion } from '../services/api';
 import { useTheme } from '../contexts/ThemeContext';
 
 const { Header, Sider, Content } = Layout;
@@ -28,6 +28,7 @@ export default function MainLayout() {
   const [collapsed, setCollapsed] = useState(false);
   const [alarmCount, setAlarmCount] = useState(0);
   const [recentAlarms, setRecentAlarms] = useState<any[]>([]);
+  const [versionInfo, setVersionInfo] = useState<any>(null);
   const navigate = useNavigate();
   const location = useLocation();
   const user = getUser();
@@ -93,6 +94,10 @@ export default function MainLayout() {
     return () => clearInterval(timer);
   }, [fetchAlarms]);
 
+  useEffect(() => {
+    getVersion().then(setVersionInfo).catch(() => {});
+  }, []);
+
   const handleLogout = () => {
     removeToken();
     localStorage.removeItem('user');
@@ -101,7 +106,7 @@ export default function MainLayout() {
 
   const handleLanguageChange = (lang: string) => {
     i18n.changeLanguage(lang);
-    localStorage.setItem('tianpu-lang', lang);
+    localStorage.setItem('ems-lang', lang);
   };
 
   const userMenu = {
@@ -136,6 +141,14 @@ export default function MainLayout() {
             }
           }}
         />
+        {!collapsed && versionInfo && (
+          <div style={{
+            padding: '8px 16px', fontSize: 11, color: 'rgba(255,255,255,0.3)',
+            borderTop: '1px solid rgba(255,255,255,0.06)', textAlign: 'center',
+          }}>
+            v{versionInfo.project_version}
+          </div>
+        )}
       </Sider>
       <Layout>
         <Header style={{

src/pages/BigScreen/index.tsx

@@ -131,7 +131,7 @@ export default function BigScreen() {
       {/* Header */}
       <div className={styles.header}>
         <span className={styles.headerDate}>{formatDate(clock)}</span>
-        <h1 className={styles.headerTitle}>天普零碳园区智慧能源管理平台</h1>
+        <h1 className={styles.headerTitle}>智慧能源管理平台</h1>
         <span className={styles.headerTime}>{formatTime(clock)}</span>
       </div>
 

src/pages/BigScreen3D/components/HUDOverlay.tsx

@@ -47,7 +47,7 @@ export default function HUDOverlay({ overview, realtimeData }: HUDOverlayProps)
     <div className={styles.hudOverlay}>
       <div className={styles.header}>
         <span className={styles.headerDate}>{formatDate(now)}</span>
-        <span className={styles.headerTitle}>天普零碳园区 3D智慧能源管理平台</span>
+        <span className={styles.headerTitle}>3D智慧能源管理平台</span>
         <span className={styles.headerClock}>{formatTime(now)}</span>
       </div>
 

src/pages/BigScreen3D/index.tsx

@@ -71,7 +71,7 @@ export default function BigScreen3D() {
     return (
       <div className={styles.container}>
         <div className={styles.placeholder}>
-          <h2 className={styles.placeholderTitle}>天普零碳园区 3D智慧能源管理平台</h2>
+          <h2 className={styles.placeholderTitle}>3D智慧能源管理平台</h2>
           <p style={{ color: '#8899aa' }}>正在加载设备数据...</p>
         </div>
       </div>

src/pages/Login/index.tsx

@@ -1,8 +1,8 @@
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import { Form, Input, Button, Card, message, Typography } from 'antd';
 import { UserOutlined, LockOutlined, ThunderboltOutlined } from '@ant-design/icons';
 import { useNavigate } from 'react-router-dom';
-import { login } from '../../services/api';
+import { login, getVersion } from '../../services/api';
 import { setToken, setUser } from '../../utils/auth';
 
 const { Title, Text } = Typography;
@@ -10,8 +10,13 @@ const { Title, Text } = Typography;
 export default function LoginPage() {
   const [loading, setLoading] = useState(false);
   const [guestLoading, setGuestLoading] = useState(false);
+  const [versionInfo, setVersionInfo] = useState<any>(null);
   const navigate = useNavigate();
 
+  useEffect(() => {
+    getVersion().then(setVersionInfo).catch(() => {});
+  }, []);
+
   const doLogin = async (username: string, password: string) => {
     const res: any = await login(username, password);
     setToken(res.access_token);
@@ -54,9 +59,9 @@ export default function LoginPage() {
         <div style={{ textAlign: 'center', marginBottom: 32 }}>
           <ThunderboltOutlined style={{ fontSize: 48, color: '#1890ff' }} />
           <Title level={3} style={{ marginTop: 12, marginBottom: 4 }}>
-            天普智慧能源管理平台
+            智慧能源管理平台
           </Title>
-          <Text type="secondary">零碳园区 · 智慧运维</Text>
+          <Text type="secondary">智慧能源 · 高效运维</Text>
         </div>
         <Form onFinish={onFinish} size="large">
           <Form.Item name="username" rules={[{ required: true, message: '请输入用户名' }]}>
@@ -82,6 +87,11 @@ export default function LoginPage() {
             </Text>
           </div>
         </Form>
+        {versionInfo && (
+          <div style={{ textAlign: 'center', marginTop: 16, opacity: 0.4, fontSize: 11 }}>
+            v{versionInfo.project_version} | Core: v{versionInfo.core_version || '—'}
+          </div>
+        )}
       </Card>
     </div>
   );

src/services/api.ts

@@ -342,6 +342,9 @@ export const getStrategySavingsReport = (params: Record<string, any>) => api.get
 export const getStrategyRecommendations = () => api.get('/strategy/recommendations');
 export const simulateStrategy = (data: any) => api.post('/strategy/simulate', data);
 
+// Version info (no auth required)
+export const getVersion = () => api.get('/version').then(r => r.data);
+
 // Weather (气象数据)
 export const getWeatherCurrent = () => api.get('/weather/current');
 export const getWeatherForecast = (params?: Record<string, any>) => api.get('/weather/forecast', { params });