EnergizeOS™ EMS

EnergizeOS™ EMS Grid-Tie / Island Transition 控制页面

前端开发手册  ·  功能与使用说明书
版本：V8.0  |  适用分辨率：1280×800px  |  发布状态：开发基线
文档适用对象：HMI/Web UI 开发工程师

第一章　文档目的与阅读方式

本手册面向负责将 HTML 原型转化为可交付生产页面的前端工程师。手册内容覆盖：

• 页面整体布局与尺寸约束
• 每个 UI 区块的功能定义与数据来源
• 按钮的所有状态、色值、CSS 类名、启用/禁用逻辑
• 状态指示灯（dot）的颜色含义与动画规格
• 控制模式（Relay / EMS）的电气工程语义
• 交互流程与操作员引导顺序（光标优先级）
• 同步参数（Sync）的趋势箭头逻辑
• 日志区（Log Bar）的事件驱动机制
• 安全联锁规则与工程师禁止事项

⚠ 本文档与 HTML 原型文件 GridTie_Island_v8_final.html 配套使用。遇到描述与代码不一致时，以 HTML 源码为准。

第二章　页面规格与分辨率约束

2.1 硬性尺寸限制

本页面针对工控触摸屏设计，分辨率固定，严禁出现横向或纵向滚动条。

2.2 布局层级

页面采用 Flex 纵向堆叠结构，从上到下固定高度分配：

Body 内横向分为两列：

• 左栏：宽度 420 px，含 A 区（反孤岛逻辑）+ R 区（反逆流检测）
• 右栏：剩余 712 px，含联锁进度条 + 同步栏 + C 表格 + 引导步骤

⚠ Sidebar 占 148 px，已从 Main Content 左侧内嵌，padding-left:148px 处理对齐。

第三章　设计令牌（Design Tokens）—— 色值规范

所有颜色通过 CSS 变量统一管理，禁止在组件内硬编码色值。以下为完整 Token 表：

3.1 主色板

3.2 语义色板（状态指示）

3.3 特殊色值

⚑ 工程师注意：色值为精确 HEX，不允许四舍五入或替换为近似色。配色已通过 WCAG AA 对比度验证，任何调整须重新验证。

第四章　UI 区块详解

4.1 顶部导航栏（Top Nav）

高度 48px，白色背景，左侧为 Logo + 产品名，右侧为页面标签。

4.2 状态栏（Status Bar）

高度 36px，显示系统实时状态，所有数据来自后端 Modbus/API 轮询，刷新频率建议 ≤2s。

⚠ Breaker Opened 状态下，Grid Voltage/Frequency 显示"—"，表示断网侧无有效参考，而非数据错误。

4.3 侧边栏（Sidebar）

宽度 148px，白色背景，左侧品牌导航。含 Dashboard / Monitoring / Strategy / Message / Setting 五个菜单项。Strategy 为当前激活页。

• 图标 + 文字标签，18×18px SVG stroke 风格
• 激活态：背景 #EFF6FF，文字/图标颜色 #1D3461，左侧 3px 蓝色竖条
• Message 图标右上角红色角标（数字），来自未读消息计数
• Setting 图标固定在底部（margin-top:auto）

4.4 左栏 — A 区（反孤岛自动解列）

Section Header：标题"Auto Disconnection Logic (Anti-Islanding): Relay Control"，右侧蓝色 badge "Relay Control"。

表格 3 列：Code | Auto Trip Criteria | Current Status。以下为各条目的状态定义：

🔴 A 区为只读监视区，所有状态由继电器硬件触发，EMS 仅接收信号不发出控制命令。禁止在此区域添加任何控制按钮。

4.5 左栏 — R 区（反逆流保护）

Section Header：标题"Anti-Reverse Power Detection: Enabled"，右侧"Enabled/Disable"模式切换（文字按钮）。

R 区下方附三行实时数值（KV行）：

• POI Active Power（绿色，正值）— 来自电表
• Reverse Power Limit（静态值）— 来自配置项
• BESS Output（橙色，运行中；绿色，停止后=0）— 来自PCS

4.6 右栏 — 联锁进度条（Progress Dots Strip）

水平排列 5 个圆点节点（C1→C2→C3→C4→C5→CLOSE），用连线连接，直观展示联锁完成进度。

节点状态与渲染规则：

节点之间连线（.dline）：

• 默认：height:2px，background:#E2E8F0（灰色）
• 已完成（.dline.done）：background:#22C55E（绿色），transition:background .4s

⚠ 连线变绿的条件：左侧节点的条件为 true 时，该段连线变绿。实现为 JS 中根据状态动态切换 class。

4.7 右栏 — 同步参数栏（Sync Bar）

显示 ΔV / Δf / Δθ 三个同步偏差值，以及各自的上限，加上总体同步状态 badge。

趋势箭头（Trend Arrow）：

• 每次刷新对比上一帧值：cur < prev → ↓（绿色，偏差收敛）；cur > prev → ↑（红色，偏差发散）；变化 < 0.003 → →（灰色，稳定）
• 趋势箭头通过 textContent 更新，禁止使用 innerHTML 以避免 XSS 和性能问题

右侧 Sync Badge：

• 未同步：background:#FEF2F2，color:#DC2626，border:#FCA5A5，文字"NOT SYNCHRONIZED"，.sdot 脉冲
• 已同步：background:#F0FDF4，color:#16A34A，border:#86EFAC，文字"SYNCHRONIZED"

4.8 右栏 — C 表格（重并网联锁条件 C1-C5）

表格 4 列：Code | Prerequisite | Status | Description。各条目说明：

C3 行特殊处理：

• 当 C3 未满足时，该行整行底色变为 #FFF7ED（橙黄警告色），tr 加 class="blocked"
• 同时显示 Primary Blocking Condition 面板（见9）

C4 三态逻辑（重要）：

• 未允许（c4=false, c4Req=false）：chip 红色"Not Allowed"，进度点 .dd.idle
• 请求中（c4Req=true）：chip 蓝色"Requesting…"，进度点 .dd.req 蓝色脉冲，持续 2 秒
• 已授权（c4=true）：chip 绿色"Authorized"，进度点 .dd.done

⚠ C4 的"Requesting…"状态是操作员的重要反馈窗口。2秒延迟模拟真实EMS授权RTT。生产环境应替换为真实API响应。

4.9 主阻塞条件面板（Primary Blocking Condition Panel）

当 C3 未满足时显示，C3 满足后自动隐藏（display:none）。样式规格：

• 外框：margin:8px 12px，padding:10px 13px
• 背景色：#FFF7ED，边框：1px solid #FED7AA，左侧边框：3px solid #EA580C
• 代码标签：font-family:monospace，font-size:14px，font-weight:800，color:#9A3412
• 原因文字：color:#C2410C，前置"▲"三角符号
• 动作说明：橙色左边框，背景 rgba(255,255,255,.55)
• 影响说明：font-size:11px，color:#9A3412，opacity:.8

4.10 操作员引导步骤（Operator Guidance）

5个步骤展示当前重并网操作进度，状态随系统条件自动切换：

第五章　按钮完整规格与状态机

5.1 按钮 CSS 类系统

所有按钮使用统一基类 .btn，通过附加状态类改变外观。禁用状态统一通过 HTML disabled 属性实现，不允许用 pointer-events:none 替代。

🔴 btn-done 状态必须同时设置 disabled=true，防止操作员重复触发已完成的操作。禁止仅靠视觉样式来阻止点击。

5.2 脉冲动画规格（@keyframes rp）

• btn-now：::after 元素，8s ease-in-out infinite，0%/100%: opacity .7 scale(1)，50%: opacity .15 scale(1.04)
• btn-final：::after 元素，2s ease-in-out infinite，同上参数
• 进度点 block：box-shadow 1.4s，0%/100%: rgba(234,88,12,.18)，50%: rgba(234,88,12,.35)
• 进度点 req（C4请求中）：同上，9s，颜色 rgba(56,189,248,...)（蓝色系）

5.3 各按钮完整状态机

Open Breaker（A区按钮）

⚠ 这是防止操作员在断路器已开状态下误按的关键联锁。Open Breaker 按钮的 dot 图标（绿色）不能移除，它是断路器已开的视觉确认。

Close Breaker（控制栏按钮）

🔴 Close Breaker 的 disabled 状态是安全关键联锁，禁止通过任何方式绕过（包括JS调用、事件模拟、API直调）。生产环境须在后端也维护相同的联锁逻辑（双重保护）。

Force Stop BESS / Force Stop PV（控制栏按钮）

⚠ 两个 Force Stop 按钮同时为 btn-now 状态（均需操作），体现"两步必做"的操作引导。任一按下后变绿，另一仍保持橙色脉冲直到完成。

Start BESS/PV Grid-Tie（控制栏按钮）

第六章　控制模式（Relay / EMS Control）电气工程语义

6.1 两种模式的本质区别

这不是一个普通的"功能开关"，而是对电气控制权的明确声明。工程师必须理解两者的本质差异：

6.2 默认模式选择逻辑

页面加载时默认选中 EMS Control（蓝色高亮），理由：

• 运维人员打开此页面的目的 = 执行重并网，而重并网 = EMS授权合闸
• Relay Control 是被动监视，不需要操作员"选择"它——继电器始终在工作
• 将 EMS Control 作为默认符合最小操作步骤原则（减少一次额外点击）

⚠ 继电器（Relay）和EMS并非互斥——继电器永远在独立监视电网状态，无论模式如何。"Relay Control"仅表示"此页面 EMS 不发出合闸命令"。

6.3 模式 UI 规格

采用药丸形分段控件（Segmented Control），不使用单选框或下拉框：

• Relay Control 激活态：background:#FFFBEB，color:#D97706，带闪电图标
• EMS Control 激活态：background:#EFF6FF，color:#1D3461，带显示器图标
• 非激活态：background:#F8F9FA，color:#94A3B8（浅灰）
• 整体容器：border:1px solid #D1D9E6，border-radius:5px，overflow:hidden

切换 EMS→Relay 后，在右栏顶部显示"模式横幅"（Mode Banner）：

• EMS模式横幅：background:#EFF6FF，文字："EMS Control active — Operator can authorize breaker close."
• Relay模式横幅：background:#FFFBEB，文字："Relay Control mode — EMS close authorization is read-only. Switch to EMS Control to reconnect."

第七章　操作员引导顺序（光标优先级系统）

本页面最核心的设计哲学：在任何时刻，操作员只需看"哪个按钮在闪橙光"，就知道下一步该做什么。

7.1 视觉优先级层级

7.2 完整操作流程（Happy Path）

以下是操作员从"断路器开/离网"到"合闸成功/并网"的完整交互序列：

1. 打开页面 → 断路器状态为"Breaker Opened"（绿色pill），Force Stop BESS/PV 均为橙色脉冲
2. 点击 Force Stop BESS → 弹出红色确认对话框 → 点"Force Stop"确认 → BESS按钮变绿"✓ BESS Stopped"
3. 点击 Force Stop PV → 同上 → PV按钮变绿 → C3 满足（行变绿）→ 阻塞面板消失
4. C4 自动进入"Requesting…"状态（蓝色脉冲，2秒）→ 2秒后变"Authorized"（绿色）
5. C5 同步参数开始收敛（ΔV↓ ΔΔf↓ Δθ↓）→ 全部达标后变"Synchronized"（绿色badge）
6. Close Breaker 按钮变为深蓝脉冲"btn-final"→ 控制栏右侧显示"READY TO CLOSE BREAKER"（绿色）
7. 点击 Close Breaker → 弹出警告确认对话框 → 确认 → 断路器关闭 → 成功弹窗显示时间戳/操作员/52a/52b状态
8. 点击"Acknowledge & Continue"关闭弹窗 → 状态栏变"Breaker Closed"（红色pill），Mode变"Grid-Tied"

第八章　日志系统（Log Bar）事件驱动机制

8.1 设计原则

日志条区高度固定 28px，深色背景（#0D1117）。日志条目为事件驱动推入：有操作/状态变化才产生一条新日志，无任何自动循环播放。

8.2 技术实现

• 新条目通过 appendChild 追加到 #log-row 右端
• 每条新日志触发 CSS 动画：translateX(50px → 0)，时长32s，ease-in-out
• 超出 6 条时，移除最老的 firstChild
• 左侧渐变遮罩（::before，宽 24px）软化截断效果
• 新条目 animation 类在 400ms 后移除，防止重触发

8.3 日志级别色彩

8.4 必须记录的事件清单（对照开发文档§16）

• EMS 初始化完成
• C1/C2/C3/C4/C5 每个条件的满足和失去
• Force Stop BESS/PV 操作执行
• EMS 授权请求发送 / 授权通过
• 断路器 Open/Close 操作
• 合闸被拒绝（含具体阻塞代码）
• 控制模式切换（Relay↔EMS）
• Grid-Tie 启动序列触发
• C5 同步达标/失去

第九章　Toast 通知与确认对话框

9.1 Toast 通知

• 位置：fixed，bottom:74px，right:14px（置于控制栏+日志栏之上，不遮挡内容区）
• 方向：column-reverse（新消息在上方，旧消息向下堆叠）
• 动画：translateX(14px → 0)，22s ease-in
• 自动消失：4000ms 后 opacity fade，再过 420ms 移除 DOM
• 手动关闭：右上角 × 按钮

四种类型规格：

9.2 确认对话框（Confirm Dialog）

• 遮罩层：rgba(15,25,35,.45)，点击遮罩可关闭
• 对话框：width:400px，padding:24px，border-radius:6px，白色背景
• 图标圆：warn 用橙色（#FFFBEB），err 用红色（#FEF2F2）
• Cancel 按钮：.btn-cancel，灰色边框，与确认按钮区分

各操作的对话框类型：

9.3 合闸成功弹窗（Success Modal）

合闸完成后 600ms 延迟显示，包含操作追溯信息：

• 时间戳（精确到秒）
• 操作员名称（Admin）
• 系统状态（GRID_TIED）
• 52a 状态（CLOSED TRUE）
• 52b 状态（OPEN FALSE）
• 确认按钮："Acknowledge & Continue"，全宽，深蓝色

✅ 合闸成功弹窗是法规合规审计的重要节点，生产环境应同步写入审计数据库，字段参考开发文档§16.3。

第十章　JS 架构与性能要求

10.1 状态管理原则

• 单一状态对象 S，包含所有页面状态（bkrOpen, mode, c3, c4, c5 等）
• 状态只在用户操作函数中修改，interval 中禁止修改结构性状态
• render() 函数：只读取状态，纯粹更新 DOM，可被反复调用（幂等）
• render() 只在状态变化时调用（用户操作后 / C5 状态变化时），不在 interval 中循环调用

10.2 数据更新分离

• setInterval（1800ms）：只更新遥测数值（POI, BESS Output, 同步偏差），调用 syncRender()
• syncRender()：极轻量，只修改 textContent 和 className，不操作结构性 DOM
• C5 状态变化检测在 interval 中：newC5 !== S.c5 时才调用完整 render()

🔴 禁止在 setInterval 中调用完整 render()——这是 v4 版本页面卡死的根本原因，已通过架构拆分修复。

10.3 DOM 操作规范

• 按钮状态变更：只修改 className 和 disabled 属性，不使用 innerHTML 重建按钮（会导致事件绑定丢失）
• 状态 chip 内容：使用 innerHTML（因为包含dot），但仅在 render() 中，不在 interval 中
• 趋势箭头：使用 textContent 更新，不使用 innerHTML
• 日志条目：createElement + appendChild，不使用字符串拼接整块 HTML

第十一章　工程师安全注意事项与禁止事项

11.1 电气安全硬性要求

🔴 Close Breaker 的联锁逻辑（C1-C5）必须在后端也有对应实现，前端禁用仅是第一道防线，后端API接收合闸请求前必须再次校验所有条件。

🔴 禁止添加"强制合闸"（Force Close）按钮，无论出于任何理由。合闸必须经过完整联锁链。

🔴 禁止修改 Close Breaker 按钮的 disabled 逻辑以绕过任何 C 条件。如发现条件不满足时仍需合闸的场景，必须经过工程评审并更新开发文档。

🔴 禁止实现"自动重合闸"（Auto Reclose）逻辑。重合闸必须由操作员主动触发，不得基于定时器自动执行。

11.2 UI 实现禁止事项

• 禁止用 pointer-events:none 替代 disabled 属性——键盘操作仍可触发
• 禁止删除确认对话框——所有危险操作必须两步确认
• 禁止在 interval 中修改按钮状态——只读取遥测数据
• 禁止用 innerHTML 更新趋势箭头——XSS 风险且性能差
• 禁止移除 btn-done 的 disabled 属性——已完成操作不得重复触发
• 禁止缩短或去掉 Toast 消息——操作员需要足够时间阅读反馈
• 禁止将 overflow:hidden 改为 overflow:auto——会破坏1280×800不可滚动约束

11.3 对接后端 API 时的注意事项

• C4 当前为 2 秒模拟延迟，生产环境替换为真实 EMS 授权 API 调用，保留 c4Req 中间态显示
• C5 当前为前端模拟收敛，生产环境替换为从同期装置读取实时 ΔV/Δf/Δθ，由后端判断是否满足阈值
• 断路器状态（bkrOpen）生产环境来自 52a/52b DI 点，需要处理 52a=52b 的冲突状态（见开发文档17.4）
• Force Stop 命令生产环境发送至 PCS CMD_Stop_BESS / CMD_Stop_PV，需等待设备反馈后才能将 bessStop/pvStop 置 true
• 所有动作必须写入审计日志，字段格式参考开发文档16.3（timestamp, event, user, breaker_52a, breaker_52b 等）

11.4 同期（Sync）相关注意事项

• ΔV 阈值：≤ 2.0 V（警告区间：0~3.5V 显示橙色 .warn，>3.5V 红色 .fail）
• Δf 阈值：≤ 0.05 Hz（无警告区间，超过即红色）
• Δθ 阈值：≤ 5°（无警告区间，超过即红色）
• C5 满足需三个参数同时在范围内，缺一不可
• 生产环境同期数据刷新频率建议 ≤500ms（比 UI 刷新间隔更快，以免错过短暂同期窗口）

附录 A　CSS 变量完整清单

附录 B　页面文件清单

附录 C　版本历史

EMS_GridTie_Island_Dev_Manual.docx

GridTie_Island_v8_final.html