AIBEMS 前端深度开发提示词方案

使用方法：每次新对话先贴「总纲约束」，再贴对应模块的提示词。每个模块独立对话完成。

总纲约束（每轮对话开头必贴）

## 开发规范约束（本轮所有任务必须遵守）

参考文档：docs/AIBEMS-2.0-master-plan.md 第 3.3 节 + 第 3.4 节（四业务域划分）+ 第 4 节（控制分级）

质量标准：
1. 【功能完备】规划文档定义的每一个功能点，必须有对应的前端页面/组件 + 后端 API 端点，不允许省略或合并
2. 【前后端闭环】每个功能必须：前端有 UI 展现 → 调用后端 API → 后端返回结构化数据（可以是模拟数据但必须结构真实）→ 前端渲染并支持交互
3. 【交互深度】每个功能不是一个静态展示卡片，而是可操作的：支持筛选、排序、时间范围选择、详情展开、状态切换等至少 2 种交互
4. 【数据可视化】涉及时序数据的功能必须使用 Recharts 图表（折线/面积/柱状），不接受纯数字或 CSS 条形图
5. 【功能扩展】在实现规划定义的基础功能后，对每个功能点至少扩展 1-2 个合理的子功能（例如"冷机效率"不只是显示数值，还应有趋势对比、效率衰减预警、与标称值对比等）
6. 【后端 API 规范】所有 API 使用 RESTful 风格，返回 JSON，包含分页（page/page_size/total）、筛选（query params）、排序（sort_by/sort_order）支持
7. 【状态完整】每个页面必须有：加载态（skeleton）、空数据态（引导提示）、错误态（重试按钮）、正常态

技术栈：React + TypeScript + Tailwind + Recharts（前端），Go + Gin（后端 API Gateway），保持现有项目结构不变。

模块 1：楼宇接入中心（交付配置域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.1 节「楼宇接入中心」的完整功能。

本模块属于"交付配置域"，服务对象为暖通工程师和平台管理员。需要实现以下 9 个功能，每个功能必须有独立的前端页面或 Tab 面板 + 对应后端 API：

### 1. 楼宇档案
- 楼宇基本信息卡片（名称、地址、建筑面积、楼层数、建造年份、空调系统类型、BAS 品牌）
- 支持编辑、照片上传区域
- 扩展：楼宇接入状态时间线（何时开始接入、何时完成联调、何时投入运行）

### 2. 设备拓扑
- 树形结构展示：楼宇 → 楼层 → 区域 → 设备，可展开/折叠
- 每个节点显示在线状态（绿/黄/红点）
- 扩展：拓扑图可视化模式（简单的层级图，节点间连线表示物理关系）

### 3. 点位导入与映射
- 支持 CSV/Excel 文件上传导入点位
- 导入后展示映射表：原始点位名 → 标准语义名，支持批量修改
- 扩展：智能匹配建议（基于点位名称模式自动推荐语义标签）

### 4. 协议配置
- 表单式配置：BACnet（IP/Port/Device ID）、Modbus（IP/Port/SlaveID/寄存器映射）、MQTT（Broker/Topic）
- 配置完成后"测试连接"按钮，显示连通性结果
- 扩展：协议通信质量仪表盘（成功率、延迟、丢包率时序图）

### 5. 语义标注
- 对已导入的点位进行语义分类标注（温度/湿度/CO2/开关量/设定值/运行状态...）
- 批量标注 + 单个手动标注两种模式
- 扩展：标注完成度进度条 + 未标注点位高亮提醒

### 6. 传感器校验
- 展示各传感器当前读数 vs 合理范围，异常值标红
- 校验操作：手动输入校准值，记录校验历史
- 扩展：传感器漂移检测（连续 N 天偏移趋势图）

### 7. 设备台账
- 设备列表：型号、厂家、安装日期、维保到期日、额定参数
- 支持搜索、按类型/楼层筛选、导出 Excel
- 扩展：设备生命周期状态标签（在保/即将过保/已过保）

### 8. 联调进度
- 甘特图或步骤条展示每个设备/区域的联调阶段（待接入 → 协议通 → 数据验证 → 控制验证 → 验收完成）
- 支持手动推进阶段 + 记录备注
- 扩展：整体接入进度百分比、阻塞项高亮

### 9. 接入健康度
- 综合评分面板（通信质量 + 数据完整性 + 传感器健康 + 控制响应的加权分）
- 各维度得分雷达图（Recharts RadarChart）
- 扩展：健康度趋势（近 7 天变化折线图）、自动生成改进建议列表

前端路由建议：/onboarding 作为入口页，内部用 Tab 切换各子功能。后端 API 前缀：/api/v1/onboarding/

模块 2：实时运行中心（运行管理域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.2 节「实时运行中心」的完整功能。

本模块属于"运行管理域"，是运维人员日常使用频率最高的主界面。要求做成类似"驾驶舱"大屏感受，信息密度高但层次清晰。

### 1. 今日能耗
- 大字显示今日累计能耗 kWh，环比昨日同时段增减百分比
- 小时粒度能耗柱状图（Recharts BarChart），当前小时高亮
- 扩展：按楼层/区域/设备类型的能耗分解堆叠图

### 2. 当前功率
- 实时总功率仪表盘（半圆 gauge 样式，标注额定容量占比）
- 峰值标记 + 当前值与近1小时均值对比
- 扩展：功率预测曲线（未来 2h 预测虚线）

### 3. 系统负荷
- 冷站负荷率（当前冷负荷/总装机容量），以进度条 + 百分比展示
- 各冷机运行状态列表（运行/待机/故障），COP 实时值
- 扩展：负荷与室外温度的散点相关图

### 4. 舒适度
- 全楼平均 PMV 指数（或简化为温度达标率百分比）
- 各区域舒适度热力色块（绿=达标，黄=偏离，红=投诉级）
- 扩展：最近 24h 投诉热点统计（哪个区域投诉最多）

### 5. 热力图
- 以楼层平面简图为背景，区域色块按温度着色（蓝-绿-黄-红渐变）
- 支持切换显示维度：温度 / CO2 / 占用人数 / 湿度
- 扩展：时间滑块回放（选择过去某时刻查看当时分布）

### 6. 设备状态
- 关键设备（冷机、水泵、AHU、FCU）运行/停止/故障汇总统计
- 可点击展开设备列表查看详情
- 扩展：设备启停时间线（今日哪台设备何时启动/停止的时间轴图）

### 7. 当前策略
- 当前各区域正在执行的控制策略简报卡片（策略名称 + 控制级别 L0-L4 + 生效时间）
- 点击可跳转到 AI 策略中心
- 扩展：策略变更通知条（"5 分钟前区域 A 策略切换为预冷"）

### 8. 异常告警
- 未处理告警列表（严重/警告/信息分级标签）
- 最新 5 条 + "查看全部"跳转
- 扩展：告警趋势（今日 vs 昨日 vs 上周同日对比柱状图）

### 9. 控制动作
- 最近 10 条控制指令卡片流（设备名 → 控制点 → 目标值 → 执行状态 → 耗时）
- 实时刷新（轮询 5s）
- 扩展：指令成功率环形图 + 平均响应时间

### 10. 预计收益
- 今日预计节能量（kWh）和金额（元），与实际已确认节能对比
- 本月累计节能进度条（目标 vs 已达成）
- 扩展：节能量组成分析（预冷贡献 X%，回退贡献 Y%，关停贡献 Z%）

前端路由：/operations 作为运行中心主页面，10 个功能以仪表盘网格布局呈现（不用 Tab，一屏展示核心指标，滚动展示详细面板）。后端 API 前缀：/api/v1/operations/

模块 3：AI 策略中心（控制优化域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.3 节「AI 策略中心」的完整功能。

本模块属于"控制优化域"，核心用户是暖通工程师和企业管理员。参考文档第 4 节（控制分级 L0-L4）确保策略界面能体现控制级别。

### 1. 当前策略
- 全楼活跃策略列表：策略名称、适用区域、控制级别（L0-L4 徽章）、生效起止时间、当前状态（运行中/暂停/待审批）
- 支持按区域、级别、状态筛选
- 扩展：策略互斥/依赖关系展示（A策略激活时B策略自动暂停）

### 2. 触发原因
- 每条策略展示触发条件链：温度偏移 > 阈值 AND 占用预测 < N AND 时段属于 XX
- 条件以卡片化展示（类似逻辑表达式可视化）
- 扩展：历史触发频率统计（该策略近30天触发了多少次）

### 3. 预计收益
- 策略执行前的预估节能量（kWh）和金额
- 与策略执行后实际收益对比（预估 vs 实际）
- 扩展：收益置信区间展示（乐观/中性/悲观三档）

### 4. 舒适度影响
- 策略执行后对区域温度/湿度的影响预估值
- 红黄绿标记：无影响/轻微偏移/可能引起投诉
- 扩展：历史舒适度投诉与策略执行的关联分析

### 5. 风险等级
- 策略风险评分（0-100），基于控制点类型、影响范围、是否可回滚
- 风险分解：设备风险 + 舒适风险 + 能源风险的三维度评分
- 扩展：风险等级与审批流程自动关联（高风险自动升级审批）

### 6. 执行时窗
- 甘特图展示策略计划执行的时间段
- 支持拖拽调整时窗起止
- 扩展：与电价时段叠加展示（峰谷平色带背景）

### 7. 回滚条件
- 每条策略的自动回滚规则列表（如：温度超过 28°C 则回滚、执行超过 30min 无效果则回滚）
- 回滚条件可编辑、可启停
- 扩展：回滚触发历史记录 + 触发后的恢复时间统计

### 8. 审批记录
- 策略审批时间线：提交 → 一审 → 二审 → 执行/拒绝，每步记录操作人、时间、意见
- 支持按审批状态筛选（待审/已通过/已拒绝）
- 扩展：审批 SLA 统计（平均审批耗时、超时率）

### 9. 策略复盘
- 已完成策略的效果总结报告：预期 vs 实际节能量、舒适度变化、异常事件
- Recharts 折线图对比策略执行前后的能耗/温度曲线
- 扩展：策略评分机制（根据节能效果和舒适度影响综合评分，作为后续策略推荐依据）

前端路由：/strategies 作为入口（已有），扩展为 Tab 面板包含以上 9 个子视图。后端 API 前缀：/api/v1/strategies/

模块 4：中央空调优化中心（控制优化域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.4 节「中央空调优化中心」的完整功能。

本模块属于"控制优化域"，是核心业务差异化模块。每个功能需要包含参数配置界面 + 当前执行状态 + 历史效果统计三层。

### 1. 预冷/预热
- 当前预冷/预热计划面板：目标区域、启动时间、目标温度、预计耗时
- 新建预冷计划表单（选择区域、目标温度、期望到达时间，系统自动计算提前启动时间）
- 运行中可视化：实时温度下降曲线 + 目标线
- 扩展：历史预冷效果统计（平均提前量、达标率、能耗对比）

### 2. 供水温度设定
- 当前冷冻水/冷却水供回水温度显示 + 设定值
- 支持手动调整设定值（滑块或输入框），带安全范围限制
- 温度变化趋势图（供水温度 + 回水温度 + 室外温度三线对比）
- 扩展：基于负荷的供水温度优化建议（当前负荷率建议升/降 X°C）

### 3. AHU/PAU 运行时段
- 各 AHU/PAU 设备的启停时间表（周一至周日，表格式编辑）
- 当前运行状态指示
- 扩展：运行时段 vs 区域占用的匹配分析图（重叠率）

### 4. 新风量
- 各区域当前新风量（m³/h）显示 + CO2 浓度关联
- 新风量调节接口（基于 CO2 浓度的自动/手动模式切换）
- 扩展：CO2 浓度与新风量的时序关联图 + 能耗影响估算

### 5. 区域设定值
- 各区域温度设定值列表（当前值、范围限制、锁定状态）
- 支持批量调整 + 单个修改
- 扩展：设定值与实际温度的偏差分析（长期欠冷/过冷区域高亮）

### 6. 节假日策略
- 日历视图展示节假日/工作日/特殊日标记
- 节假日策略模板编辑（完全关闭/值守模式/低负荷模式）
- 扩展：节假日节能效果复盘（对比节假日节能量 vs 工作日平均值）

### 7. 夜间策略
- 夜间模式配置：触发时间、降温幅度、设备关闭列表、保留区域
- 当前夜间策略状态（已激活/未激活）
- 扩展：夜间能耗基线对比（开启夜间策略前后的能耗差异趋势）

### 8. 高峰负荷削减
- 负荷削减事件管理：手动触发 / 自动触发条件配置
- 削减执行时的实时功率下降曲线
- 扩展：需求响应历史记录 + 响应速度统计 + 奖励金额估算

### 9. 末端分区优化
- 分区控制矩阵：各区域末端（FCU/VAV）的控制权限和当前模式
- 分区联动规则配置（相邻区域协同、热量再平衡）
- 扩展：分区能效排名 + 低效区域改进建议

前端路由：/hvac-optimization 作为入口，9 个功能以左侧导航子菜单呈现。后端 API 前缀：/api/v1/hvac/

模块 5：设备健康中心（运行管理域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.5 节「设备健康中心」的完整功能。

本模块属于"运行管理域"，服务暖通工程师和值班运维人员。核心价值是预测性维护减少宕机。

### 1. 冷机效率
- 各冷机实时 COP（制冷量/输入功率），对比额定 COP
- COP 趋势折线图（近 30 天），标注异常下降拐点
- 扩展：冷机效率衰减预警（COP 连续 N 天低于阈值时报警）+ 同类型冷机横向对比

### 2. 水泵效率
- 各水泵扬程/流量/功率实时值，计算运行效率
- 效率 vs 设计工况偏差百分比
- 扩展：水泵特性曲线与当前运行点标注（是否偏离高效区）

### 3. 风机效率
- AHU/PAU 风机风量/静压/功率监测
- 滤网压差指示（提醒更换滤网）
- 扩展：风机运行频率分布直方图（是否长期运行在低效频段）

### 4. 阀门异常
- 阀门列表：开度指令 vs 实际开度反馈，偏差超限标红
- 阀门卡死/泄漏检测（开度指令为 0 但温度仍变化）
- 扩展：阀门异常地图（在楼层平面图上标注异常阀门位置）

### 5. 传感器漂移
- 各传感器读数与相邻传感器/计算值的偏差
- 漂移趋势图：偏差量随时间的变化
- 扩展：自动标记"疑似故障"传感器 + 生成校验工单建议

### 6. 控制未达
- 控制指令下发后未在规定时间内达到目标的事件列表
- 未达原因分类统计（设备故障/通信超时/负荷过大/传感器异常）
- 扩展：控制达标率趋势图 + 与设备老化的相关性分析

### 7. 运行小时
- 各设备累计运行小时数 + 本月运行小时
- 对比计划运行时间，显示超时运行设备
- 扩展：运行小时与维保周期关联（距下次保养还剩 XX 小时）

### 8. 预测性维护
- 基于运行数据的设备健康评分（0-100），综合效率衰减、运行时间、异常频率
- 预计剩余可靠运行天数
- 扩展：维护优先级排序（紧急/计划中/观察）+ 一键生成维护工单

### 9. 工单建议
- 系统自动生成的维护工单建议列表（来源于以上各项检测）
- 支持确认创建工单 / 忽略 / 标记误报
- 扩展：工单建议接受率统计 + 忽略原因分析

前端路由：/equipment-health 作为入口（可复用现有 /device-health 路由），9 个功能以 Tab + 子面板组合展示。后端 API 前缀：/api/v1/equipment-health/

模块 6：节能验证中心（经营验证域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.6 节「节能验证中心」的完整功能。

本模块属于"经营验证域"，服务能源审计和节能顾问。是平台商业化的核心能力——可审计的节能量证明。

### 1. 基线建模
- 基线模型参数配置界面：训练时段选择、自变量选择（室外温度、湿度、人流、日期类型）
- 模型训练结果展示：R²、CV-RMSE、拟合曲线 vs 实际曲线对比图
- 扩展：多种模型对比（线性回归 / 多项式 / 变点模型），支持选择最优

### 2. 天气归一化
- 当前采用的气象数据源显示 + 数据质量指示
- 归一化前后能耗对比图（消除天气影响后的净节能量）
- 扩展：气象数据缺失处理策略配置（插值/临近站点替代）

### 3. 人流归一化
- 人流数据源配置（门禁/WiFi探针/摄像头计数）
- 归一化系数展示：单位人均能耗基线 vs 实际
- 扩展：人流数据异常检测（某日人流数据明显异常时标注，避免影响归一化）

### 4. 时段修正
- 运行时间修正配置：标记非标准运行时段（加班日、特殊活动日）
- 修正前后对比
- 扩展：自动识别非常规运行时段（能耗模式突变检测）

### 5. 节能量
- 核心看板：日/周/月/年节能量数值 + 趋势折线图
- 节能量计算明细：基线预测值 - 实际值 = 节能量，逐日展示
- 扩展：节能量置信区间（考虑模型误差的上下限）

### 6. 节能率
- 节能率 = 节能量 / 基线预测 × 100%
- 节能率目标线 + 实际达成对比
- 扩展：按区域/策略类型的节能率分解排名

### 7. 碳减排
- 根据节能量 × 电网排放因子计算碳减排量（tCO₂e）
- 碳减排累计曲线
- 扩展：排放因子配置（支持不同地区电网因子）+ 等价指标（相当于种了多少棵树）

### 8. 报告导出
- M&V 验证报告自动生成（PDF/Word 格式），包含：项目概况、基线模型、归一化方法、逐月节能量、图表
- 支持自定义报告时段和包含章节
- 扩展：报告模板管理（不同客户不同模板）+ 一键发送给指定审计邮箱

### 9. 第三方审计支持
- 审计数据包导出：原始数据 + 模型参数 + 计算过程，供第三方独立验证
- 审计意见上传与管理
- 扩展：审计状态跟踪（待审计/审计中/已通过/需补正）+ 审计问题回复记录

前端路由：/mv-center（可扩展现有 /mv 页面），9 个功能以左侧步骤导航展示（符合 M&V 的流程化特征）。后端 API 前缀：/api/v1/mv/

模块 7：多楼宇运营中心（经营验证域）

请实现 docs/AIBEMS-2.0-master-plan.md 3.3.7 节「多楼宇运营中心」的完整功能。

本模块属于"经营验证域"，服务资产管理层和省级代理商。核心价值是跨楼宇对比和批量管理。

### 1. 集团级看板
- 顶部：集团总楼宇数、总面积、总节能量、总碳减排的 KPI 卡片
- 楼宇列表卡片网格：每栋楼宇显示关键指标缩略（节能率、舒适度评分、告警数）
- 扩展：地图视图（百度/高德地图标注各楼宇位置，点击跳转详情）

### 2. 区域排名
- 多维度排名表格：按节能率 / 舒适度 / 能效(kWh/m²) / 告警数排序
- 支持切换时间范围（本周/本月/本季度）
- 扩展：排名变动趋势（本月 vs 上月名次变化箭头）

### 3. 能效基准
- 各楼宇单位面积能耗（kWh/m²/年）对比条形图
- 行业基准线标注（GB/T XXXXX 标准值）
- 扩展：能效等级标签（A/B/C/D/E 类似能效标识）+ 达标/未达标统计

### 4. 策略复制
- 从标杆楼宇选择成功策略 → 选择目标楼宇 → 参数适配调整 → 批量部署
- 策略复制历史记录
- 扩展：策略适配检查（目标楼宇设备能力是否支持该策略）

### 5. 批量配置
- 跨楼宇批量操作：批量调整温度设定值、批量切换策略模式、批量更新控制级别
- 操作确认弹窗 + 执行进度追踪
- 扩展：批量操作模板保存（"周末统一模式"、"节假日统一模式"等可复用模板）

### 6. 异常对比
- 多楼宇异常指标并排对比（选择 2-4 栋楼宇，对比其能耗曲线、舒适度曲线、告警频率）
- 异常偏离楼宇自动标注
- 扩展：异常根因关联分析（该楼宇近期是否有设备故障/策略变更等事件）

### 7. 合同与服务状态
- 各楼宇服务合同列表：合同期限、服务等级、费用类型（SaaS/节能分成/混合）
- 即将到期合同预警
- 扩展：合同执行状态（节能量目标 vs 实际达成进度、服务 SLA 达标情况）

前端路由：/portfolio（多楼宇运营中心），7 个功能以 Dashboard 网格 + Tab 详情组合展示。后端 API 前缀：/api/v1/portfolio/

执行节奏指南

步骤	操作	注意事项
1	新建对话	每个模块用独立对话，避免上下文溢出
2	粘贴「总纲约束」	每次都贴，保证质量标准一致
3	粘贴对应模块提示词	一次只给一个模块
4	等待 Claude 完成	不要中途打断
5	运行验证	`npm run dev` 检查页面渲染 + API 调用
6	修复问题	发现 bug 单独发消息修复
7	确认完成，进入下一模块	开新对话重复步骤 1-6

建议执行顺序

模块 2（实时运行中心）— 日常使用率最高，优先完善
模块 3（AI 策略中心）— 核心差异化能力
模块 4（中央空调优化中心）— 业务核心
模块 5（设备健康中心）— 运维必备
模块 6（节能验证中心）— 商业化关键
模块 1（楼宇接入中心）— 交付阶段使用
模块 7（多楼宇运营中心）— 规模化后需要

常见问题处理

如果 Claude 实现的功能过于简单，追加以下话术：

你实现的 [具体功能名] 只有基础展示，缺少以下必要交互：
1. [具体缺失的交互，如"没有时间范围筛选器"]
2. [具体缺失的交互，如"图表没有 tooltip 和 hover 效果"]
3. [具体缺失的交互，如"没有空状态处理"]

请补全以上交互，保持其他功能不变。

如果后端 API 只返回空数据：

后端 API /api/v1/xxx 返回空数据，请补充合理的模拟数据生成逻辑：
- 数据量：至少 20 条记录
- 时序数据：覆盖近 30 天，有合理波动
- 状态分布：包含正常/异常/警告等多种状态
- 数值范围：符合暖通工程实际参数范围（温度 18-30°C，CO2 400-1200ppm，COP 3.5-6.5 等）

第二部分：系统审查问题修复提示词

基于 docs/review/SYSTEM_AUDIT_2026-06-11.md 审查报告，按优先级 P0→P1→P2→P3 逐项修复。
修复顺序建议：P0 全部完成 → P1 全部完成 → P2 批量处理 → P3 按需安排。
每个修复项独立一轮对话，开头粘贴下方的「修复总纲」。

修复总纲（每轮修复对话开头必贴）

## 修复规范约束

参考文档：
- docs/AIBEMS-2.0-master-plan.md（产品规划，特别是第 4/5/6/8 节）
- docs/review/SYSTEM_AUDIT_2026-06-11.md（审查报告，了解当前缺陷全貌）

修复原则：
1. 【最小改动】只修复指定问题，不改动其他已通过审查的功能
2. 【向后兼容】新增的模块/中间件不能破坏现有 API 的请求/响应格式
3. 【可测试】每个修复完成后，说明如何验证修复生效（API 测试命令或前端操作步骤）
4. 【真实逻辑】不接受"只是多了一个字段但没有校验逻辑"的假修复，必须有实际的 if/else 判断或中间件拦截
5. 【数据模型先行】如需新增数据库字段/表，先写 migration 文件，再写 handler 逻辑
6. 【前后端同步】后端新增的字段/接口，前端必须同步展示或调用

技术栈约束：保持 Go + Gin（后端）、React + TypeScript + Tailwind（前端）不变。

P0-1：控制权限矩阵集成到指令下发流程

## 修复目标
将已有的 R0-R5 控制权限矩阵从"仅展示"升级为"实际拦截"——所有控制指令下发前必须经过权限校验。

## 当前状态
- ControlMatrix.tsx 页面已有权限矩阵展示（zones × point_types × roles → R0-R5）
- 后端 /control-matrix 返回矩阵数据
- 但 handlers_bas.go 和 handlers_hvac_optimization.go 中的指令下发接口未调用任何权限检查

## 具体要求

### 后端
1. 新建中间件 `internal/middleware/control_permission.go`：
   - 拦截所有 POST /api/v1/commands、POST /api/v1/hvac/* 等写入类控制接口
   - 从请求中解析目标 zone_id、point_type、当前用户 role
   - 查询权限矩阵获取该组合的 R 级别
   - 校验逻辑：
     - R0（不接入）/ R5（永久禁控）→ 直接返回 403 + 错误原因
     - R1（只读）→ 拒绝写入，返回 403
     - R2（可建议不可写）→ 拒绝直接执行，建议存入 pending_suggestions 表
     - R3（人工确认后可写）→ 指令进入审批队列，状态为 pending_approval
     - R4（低风险可自动写）→ 直接执行
   - 每次校验结果写入 audit_log（包含：谁、对哪个点位、尝试了什么操作、权限判定结果）

2. 修改 handlers_bas.go：
   - POST /commands 接口在业务逻辑前调用权限中间件
   - 如果指令被拦截为 R3，自动创建 decision 记录（status=pending_approval）

3. 修改 handlers_hvac_optimization.go：
   - 所有修改设定值的接口（冷冻水设定、区域温度、AHU启停等）均经过权限中间件

### 前端
4. 修改 Commands 相关页面：
   - 指令被拒绝时显示明确的错误 toast："该点位权限为 R1（只读），无法下发控制指令"
   - 指令进入审批时显示提示："指令已提交审批（权限级别 R3），等待管理员确认"

5. 修改 ControlMatrix.tsx：
   - 增加"权限校验日志"Tab，展示最近被拦截/审批的指令记录

### 验证方式
- 以 building_operator 角色对一个 R1 点位下发指令 → 预期返回 403
- 以 enterprise_admin 角色对一个 R3 点位下发指令 → 预期进入审批队列
- 以 enterprise_admin 角色对一个 R4 点位下发指令 → 预期直接执行
- 审计日志中有完整的拦截记录

P0-2：实现真实控制闭环（L2+）

## 修复目标
建立从"AI 产生决策"到"指令真实下发到设备并确认执行结果"的完整控制闭环，至少覆盖 L2（人工确认后执行）和 L3（低风险自动执行）。

## 当前状态
- Decisions 页面有决策展示和审批按钮
- Commands 页面有指令列表
- 但审批通过后无真实的"指令下发→等待确认→效果验证"链路
- 决策 approve 后只是改了数据库状态，没有触发后续动作

## 具体要求

### 后端：新建控制执行引擎

1. 新建 `internal/control/engine.go`，实现控制闭环状态机：

决策生成 → 安全校验 → [L2:审批 / L3:自动] → 指令下发 → 等待回执 → 效果验证 → 记录结果

2. 状态机定义（command_status 枚举扩展）：
- `generated` → 决策生成，待校验
- `validated` → 安全校验通过
- `pending_approval` → 等待人工审批（L2）
- `approved` → 审批通过，待执行
- `dispatched` → 已下发到边缘
- `ack_received` → 边缘确认收到
- `executed` → 执行完成
- `verified` → 效果验证通过
- `failed` → 执行失败
- `rolled_back` → 已回滚

3. POST /api/v1/decisions/{id}/approve 修改：
- approve 后不只是改 status，而是触发 engine.Dispatch()
- engine.Dispatch() 做以下事情：
  a. 查询该决策关联的控制点
  b. 调用权限中间件（P0-1）校验
  c. 生成 command 记录（状态 dispatched）
  d. 模拟边缘确认（5 秒后回调更新为 ack_received）
  e. 模拟效果验证（30 秒后检查温度变化，更新为 verified 或 failed）
- 如果决策的 control_level 为 L3 且对应点位为 R4，跳过审批直接进入 Dispatch

4. 新建 POST /api/v1/control/execute：
- 手动触发单条指令执行（用于运维人员直接操作）
- 同样经过完整的状态机流转

5. 新建 GET /api/v1/control/pipeline：
- 返回当前所有"正在流转中"的指令及其状态机阶段
- 用于前端展示控制管道

### 前端

6. 新建 ControlPipeline.tsx 页面（或在 Dashboard 增加面板）：
- 可视化展示当前控制管道：每条指令的状态机流转进度（步骤条样式）
- 实时刷新（轮询 3s）
- 点击可展开详情：每个阶段的时间戳、校验结果、执行日志

7. 修改 DecisionDetail.tsx：
- approve 后显示指令执行进度（不再只是状态文字变化）
- 增加"执行结果"面板：下发时间 → 确认时间 → 验证时间 → 最终判定

8. 修改 Commands.tsx：
- 增加状态机完整状态筛选器（10 个状态）
- 列表中每条指令显示当前所处阶段的进度指示器

### 数据模型
9. 新建 migration：
- commands 表增加 `control_level` (enum L0-L4)、`dispatched_at`、`ack_at`、`verified_at`、`verification_result` (jsonb) 字段
- 新建 control_pipeline_log 表：记录每条指令在每个状态机阶段的转换时间和详情

### 验证方式
- 创建一条 L2 决策 → approve → 观察指令状态从 approved → dispatched → ack_received → verified 自动流转
- 创建一条 L3 决策（对应 R4 点位）→ 无需审批自动进入 dispatched
- Pipeline 页面实时展示流转中的指令
- 模拟一条 failed 指令 → 观察是否触发回滚逻辑

P0-3：12 项保护能力实现

## 修复目标
实现规划文档 4.6 节定义的 12 项保护能力，作为控制执行引擎的安全校验层。

## 当前状态
- 仅"全量审计日志"完整实现
- "人工优先级最高"有 E-Stop 按钮但未集成到引擎
- 其余 10 项均为缺失或概念级

## 具体要求

### 后端：新建 safety_engine 模块

新建 `internal/safety/engine.go`，实现 SafetyEngine 结构体，包含以下 12 个 checker：

1. **参数白名单 (WhitelistChecker)**
   - 维护可控制的点位类型白名单（supply_temp_setpoint, zone_temp_setpoint, ahu_on_off, fan_speed 等）
   - 非白名单点位一律拒绝
   - 白名单可通过 API 管理（GET/POST /api/v1/safety/whitelist）

2. **幅度限制 (RangeLimiter)**
   - 每种点位类型的允许调整范围（如 supply_temp: ±3°C/次, zone_temp: ±2°C/次）
   - 超出范围返回 rejected + 原因
   - 配置可通过 API 管理（GET/PUT /api/v1/safety/limits）

3. **频率限制 (RateLimiter)**
   - 同一点位 N 分钟内只允许调整 M 次（默认：同一设备 15min 内最多 1 次）
   - 使用内存计数器（或 Redis 如有）

4. **最小启停间隔 (MinIntervalChecker)**
   - 大型设备（冷机、水泵）启停间隔不小于配置值（默认：冷机 30min，水泵 10min）
   - 查询该设备最后一次启停时间，间隔不足则拒绝

5. **模型置信度门槛 (ConfidenceGate)**
   - 决策的 confidence 低于阈值（默认 0.6）时，不允许自动执行（L3→降级为 L2 需审批）
   - 低于 0.3 时直接拒绝

6. **数据质量门槛 (DataQualityGate)**
   - 执行前检查目标区域传感器数据：最近 10min 内是否有有效读数
   - 如果数据缺失/过期（超过 15min 无更新），拒绝执行并报告原因

7. **区域锁定 (ZoneLock)**
   - 支持锁定特定区域禁止自动控制（手动锁定/告警自动锁定）
   - GET/POST /api/v1/safety/zone-locks 管理锁定状态
   - 锁定区域内的指令一律拒绝

8. **人工优先级最高 (HumanOverride)**
   - 集成现有 E-Stop：当 E-Stop 激活时，所有自动指令拒绝
   - 人工手动指令（带 manual_override=true 标记）仅需通过白名单和幅度检查，跳过其他 checker

9. **云端不可用禁止高风险 (OfflineGuard)**
   - 模拟：如果后端检测到与边缘节点通信延迟 > 5s，禁止 risk_level=high 的指令
   - GET /api/v1/safety/connectivity-status 返回各边缘节点通信状态

10. **指令失败自动回滚 (AutoRollback)**
    - 指令执行后 N 分钟（可配置，默认 15min）效果验证失败时，自动下发回滚指令
    - 回滚指令 = 恢复到执行前的设定值
    - 回滚记录写入 control_pipeline_log

11. **全量审计日志 (AuditLogger)** — 已有，确保集成
    - 每次 SafetyEngine 执行的完整检查结果（哪些 checker 通过、哪些拒绝）写入 audit

12. **一键恢复 BAS 模式 (BasRestore)**
    - POST /api/v1/safety/restore-bas：记录所有已被 AIBEMS 修改的点位的原始值，一键批量恢复
    - 前端增加按钮（仅 enterprise_admin + national_operator 可见），带二次确认

### SafetyEngine 集成

- 所有指令执行前必须调用 `SafetyEngine.Check(command)`
- Check 返回 `CheckResult{Passed bool, Rejections []Rejection, Downgrades []Downgrade}`
- 集成到 P0-2 的控制执行引擎的 `validated` 阶段

### 前端

新建 SafetyDashboard.tsx 页面（路由 /safety）：
- 12 项保护能力状态总览：每项显示启用/禁用开关 + 最近触发次数
- 安全事件时间线：最近被拦截的指令列表（时间、原因、checker 名称）
- 配置面板：白名单管理、幅度限制管理、区域锁定管理

### 验证方式
- 对白名单外的点位下发指令 → 被 WhitelistChecker 拒绝
- 对同一设备 15min 内连续下发 2 条指令 → 第二条被 RateLimiter 拒绝
- 置信度 0.5 的 L3 决策 → 被 ConfidenceGate 降级为 L2
- E-Stop 激活后下发自动指令 → 被 HumanOverride 拒绝
- SafetyDashboard 显示所有拦截记录

P0-4：智能体工程合同补全

## 修复目标
为所有已注册的智能体补全 6 个"工程合同"要素，并补充缺失的 2 个智能体（人流预测 + M&V）。

## 当前状态
- 11 个规划智能体中已注册 7 个
- 每个智能体目前只有 name、skills 列表和部分有 system_prompt
- 缺失：输入 schema、输出 schema、不可越权事项、评估指标、失败降级方式

## 具体要求

### 数据模型

1. 新建 migration，agents 表增加以下 JSONB 字段：
   - `input_schema` — 该智能体接受的输入数据结构定义（JSON Schema 格式）
   - `output_schema` — 该智能体产出的输出数据结构定义
   - `boundaries` — 不可越权事项列表（字符串数组）
   - `metrics` — 评估指标定义（KPI 名称 + 计算方式 + 达标阈值）
   - `degradation_strategy` — 失败降级策略（失败条件 + 降级动作 + 通知方式）

### 后端

2. 修改 handlers_agents.go：
   - GET /api/v1/agents/{id} 返回完整 6 要素
   - PUT /api/v1/agents/{id}/contract 用于更新工程合同
   - GET /api/v1/agents/{id}/metrics 返回该智能体的实时评估指标数据

3. 为现有 7 个智能体填充工程合同数据（写在 seed 或 migration 中）：

   **ag_building_profile（楼宇画像）**：
   - input: {building_id, weather_7d, occupancy_history, energy_history}
   - output: {thermal_inertia, usage_pattern, energy_structure, baseline_recommendation}
   - boundaries: ["不可修改设备配置", "不可下发控制指令", "不可访问其他楼宇数据"]
   - metrics: [{name: "画像准确率", threshold: 0.85}, {name: "更新延迟", threshold: "<1h"}]
   - degradation: {condition: "数据缺失>30%", action: "使用上一版画像+标记stale", notify: "building_operator"}

   **ag_data_quality（数据质量）**：
   - input: {zone_id, point_readings_15min, expected_ranges}
   - output: {quality_score, anomalies[], missing_points[], drift_alerts[]}
   - boundaries: ["不可修改原始数据", "不可触发控制动作"]
   - metrics: [{name: "漏检率", threshold: "<5%"}, {name: "误报率", threshold: "<10%"}]
   - degradation: {condition: "计算超时>10s", action: "返回上一周期结果+标记degraded", notify: "system_admin"}

   **（其余 5 个智能体类似填充，每个必须有完整且符合业务逻辑的合同内容）**

4. 新增 2 个缺失的智能体：

   **ag_occupancy_forecast（人流预测）**：
   - skills: ["query_occupancy_history", "query_calendar", "query_wifi_probe", "predict_tft"]
   - input: {zone_id, horizon_minutes, features[]}
   - output: {predictions[{time, occupancy, confidence}], model_version}
   - boundaries: ["不可访问个人身份数据", "不可直接触发控制", "预测范围≤4h"]
   - metrics: [{name: "MAPE_30min", threshold: "<15%"}, {name: "预测覆盖率", threshold: ">95%"}]
   - degradation: {condition: "模型推理失败", action: "使用历史同时段均值", notify: "data_engineer"}

   **ag_mv_verification（M&V 验证）**：
   - skills: ["query_baseline", "query_energy", "normalize_weather", "normalize_occupancy", "calculate_savings"]
   - input: {building_id, period_start, period_end, baseline_model_id}
   - output: {savings_kwh, savings_rate, carbon_reduction_t, confidence_interval, audit_evidence_url}
   - boundaries: ["不可修改基线模型参数", "不可篡改原始计量数据", "不可自动生成最终审计结论"]
   - metrics: [{name: "CV-RMSE", threshold: "<25%"}, {name: "报告生成时间", threshold: "<30s"}]
   - degradation: {condition: "数据完整度<80%", action: "标记报告为provisional+列出缺失项", notify: "energy_auditor"}

### 前端

5. 修改 AgentDetail.tsx：
   - 增加"工程合同"Tab，分 6 个面板展示：
     - 输入 Schema（JSON 树形可视化）
     - 输出 Schema（JSON 树形可视化）
     - 可调用工具（已有 skills 列表）
     - 禁止事项（红色标签列表）
     - 评估指标（表格：指标名 | 当前值 | 阈值 | 状态✅⚠️❌）
     - 降级策略（条件→动作→通知 的流程卡片）

6. 修改 AgentRegistry.tsx 列表页：
   - 每个智能体卡片增加"合同完整度"指示（6 项中已填几项）
   - 合同不完整的标黄色警告

### 验证方式
- GET /agents 返回 11 个智能体（含新增的 2 个）
- GET /agents/{id} 返回完整 6 要素 JSON
- AgentDetail 页面正确渲染所有合同信息
- 评估指标有实时数值（可以是 mock 但结构真实）

P1-1：四阶段验收流程

## 修复目标
实现规划文档 8.5 节定义的四阶段验收流程（接入验收→试运行验收→阶段价值验收→年度节能验收），为项目交付提供完整的里程碑管理。

## 当前状态
- onboarding/commissioning 有联调进度（部分覆盖"接入验收"）
- 无试运行、阶段价值、年度节能三个验收阶段

## 具体要求

### 数据模型
新建 migration：
- 新建 acceptance_milestones 表：building_id, phase(enum: onboarding/trial/value/annual), status(pending/in_progress/passed/failed), started_at, completed_at, reviewer, evidence_urls(jsonb), notes
- 新建 acceptance_criteria 表：phase, criterion_name, description, check_type(auto/manual), threshold

### 后端
- GET /api/v1/acceptance/{building_id} — 返回该楼宇 4 个阶段的验收状态
- POST /api/v1/acceptance/{building_id}/advance — 推进到下一阶段（需前置阶段已通过）
- GET /api/v1/acceptance/{building_id}/{phase}/criteria — 返回该阶段的验收条件及完成情况
- POST /api/v1/acceptance/{building_id}/{phase}/evaluate — 触发自动评估（检查各项条件是否满足）

四阶段验收条件定义：
1. 接入验收：协议连通率>95%、点位映射完成度100%、数据完整性>90%、传感器校验通过
2. 试运行验收：连续 7 天无 P0 告警、指令成功率>95%、控制偏差<2°C、数据质量评分>80
3. 阶段价值验收：30 天累计节能量>0、舒适度达标率>90%、M&V 报告已生成、无安全事故
4. 年度节能验收：12 个月节能率达标（合同约定值）、基线模型 CV-RMSE<25%、第三方审计通过

### 前端
新建 Acceptance.tsx 页面（路由 /acceptance）：
- 顶部：4 阶段步骤条，已完成的绿色，当前阶段蓝色脉冲，未到的灰色
- 当前阶段面板：验收条件 checklist（自动项显示实时计算结果，手动项支持勾选+上传证据）
- 历史记录：各阶段通过时间、审核人、备注
- 支持按楼宇切换查看

### 验证方式
- 新建楼宇默认处于"接入验收"阶段
- 手动触发评估 → 返回各条件达成情况
- 全部条件满足后可推进到下一阶段
- 尝试跳过阶段（如直接推到年度验收）→ 返回 400 错误

P1-2：不同角色不同首页

## 修复目标
实现不同角色登录后跳转到各自业务域的专属首页，而非所有角色统一进入 /dashboard。

## 当前状态
- App.tsx 所有用户登录后统一 Navigate to /dashboard
- Dashboard.tsx 根据 role 展示不同面板，但结构相同

## 具体要求

### 后端
无需修改（角色信息已在 /auth/me 返回）

### 前端
1. 修改 App.tsx 中的登录后路由逻辑：
   - national_operator → /analytics（全国运营总览 = 经营验证域首页）
   - provincial_agent → /sub-agents（代理商管理 = 经营驱动）
   - enterprise_admin → /operations（实时运行中心 = 运行管理域首页）
   - building_operator → /dashboard（当日运维仪表盘）

2. 修改 Layout.tsx 侧边栏：
   - 将导航分组标题改为对应业务域名称：
     - "交付配置" 包含：楼宇接入、协议接入、BAS 设备
     - "运行管理" 包含：仪表盘、实时运行中心、区域监控、告警、设备健康、工单
     - "控制优化" 包含：AI 决策、控制策略、HVAC 优化、智能体管理、Copilot
     - "经营验证" 包含：节能验证、CCER、多楼宇运营、计费分润、报表
     - "系统管理" 包含：账号、审计、安全配置、设置
   - 分组标题以小号灰色字体显示，组间有细分隔线

3. 修改 Login.tsx：
   - 登录成功后根据用户 role 跳转到对应首页（而非写死 /dashboard）

### 验证方式
- 以 building_operator 登录 → 自动跳转 /dashboard
- 以 enterprise_admin 登录 → 自动跳转 /operations
- 以 national_operator 登录 → 自动跳转 /analytics
- 侧边栏展示清晰的业务域分组

P1-3：补充缺失的 2 个智能体注册

## 修复目标
补充"人流预测智能体"和"M&V 智能体"的注册，使 11 个核心智能体全部在系统中存在。

## 说明
此项已包含在 P0-4 中（要求新增 ag_occupancy_forecast 和 ag_mv_verification）。如 P0-4 已完成则跳过此项。如单独执行则参照 P0-4 中对应部分。

P1-4：交叉审查机制（反方审查 + 影子模式）

## 修复目标
实现规划文档 6.5 节要求的"提案→反方审查→规则引擎→审批/执行"链路，增加反方审查智能体和影子模式。

## 当前状态
- AgentWorkflow 页面展示了流程图但无实际执行
- 无反方审查智能体
- 无影子模式（shadow mode）

## 具体要求

### 后端

1. 新增反方审查智能体 ag_adversarial_reviewer：
   - input: {proposed_action, context, risk_level}
   - output: {approval: bool, concerns: [], alternative_suggestions: [], confidence}
   - 职责：对策略生成智能体的提案进行质疑，检查是否有被忽略的风险
   - 实现逻辑（可用规则模拟 LLM 审查）：
     - 检查提案是否在历史上导致过问题（查询 control_pipeline_log 中类似指令的失败记录）
     - 检查提案影响范围是否超出合理边界
     - 检查当前时间是否适合执行该操作（如深夜执行高风险操作需额外理由）

2. 修改控制执行引擎（P0-2 的 engine.go）：
   - 在 `validated` 到 `approved/dispatched` 之间增加 `reviewed` 阶段
   - risk_level >= medium 的指令必须经过 ag_adversarial_reviewer
   - reviewer 的 concerns 不为空时，指令降级为 L2 需人工确认

3. 新增影子模式 API：
   - POST /api/v1/control/shadow-mode/{zone_id}/enable — 该区域进入影子模式
   - 影子模式下：决策正常流转但 dispatched 阶段只记录"本应下发的指令"而不真实执行
   - GET /api/v1/control/shadow-results — 返回影子模式的历史决策记录 + 如果执行了预计效果
   - 用于新策略上线前的验证：先跑 7 天影子模式，对比预期收益

4. 新建 migration：
   - commands 表增加 `shadow` boolean 字段
   - commands 表增加 `review_result` jsonb 字段（反方审查结果）

### 前端

5. 修改 AgentWorkflow.tsx：
   - 流程图中增加"反方审查"节点（标红色，表示对抗验证）
   - 点击节点可查看最近的审查记录

6. 新建 ShadowMode.tsx 页面或在 Strategies 中增加 Tab：
   - 区域影子模式开关管理
   - 影子执行历史列表：时间、决策内容、预计效果、实际对比（如果已退出影子模式）
   - 影子模式评估报告：N 天内命中率、预计节能量、可信度

### 验证方式
- 发起一个 risk_level=high 的决策 → 观察是否经过反方审查
- 审查发现问题 → 指令自动降级为 L2 待人工确认
- 开启某区域影子模式 → 决策流转正常但指令标记为 shadow=true，无实际执行

P1-5：M&V 数据缺失处理逻辑

## 修复目标
为节能验证计算增加数据缺失处理逻辑，确保在数据不完整时有合理的降级策略而非静默计算错误结果。

## 当前状态
- /mv/savings 返回计算结果但未处理数据缺失情况
- 无数据完整度检查

## 具体要求

### 后端
修改 handlers_mv_center.go：

1. 基线计算前增加数据完整度检查：
   - 计算报告期内每日数据完整度（有效小时数/24）
   - 完整度 < 80% 的日期标记为 `excluded`
   - 完整度 80%-95% 的日期标记为 `interpolated`（使用线性插值补全）
   - 完整度 > 95% 的日期标记为 `complete`

2. GET /api/v1/mv/data-quality 新接口：
   - 返回报告期内每日的数据完整度详情
   - 返回缺失数据的处理方式说明
   - 返回因数据缺失导致的不确定性增量

3. 修改 GET /api/v1/mv/savings 返回结构增加：
   - `data_coverage_pct` — 数据覆盖率
   - `excluded_days` — 被排除的天数及原因
   - `interpolated_days` — 被插值的天数
   - `uncertainty_adjustment` — 因数据缺失导致的额外不确定性
   - `report_quality` — 报告质量等级（A=完整/B=可用/C=有保留/D=不可靠）

4. 当 report_quality 为 D 时：
   - 返回 warning 字段提示"数据完整度不足，节能量计算结果不可靠"
   - 不允许生成正式审计报告（/mv/reports 接口返回 422）

### 前端
修改 MVCenter.tsx 节能量 Tab：
- 增加数据质量指示条：绿(A)/蓝(B)/黄(C)/红(D)
- 点击展开数据完整度日历热力图（每天一个格子，按完整度着色）
- 被排除/插值的日期在节能量曲线上用虚线/特殊标记

### 验证方式
- 模拟一段时间数据缺失 > 20% → 返回 report_quality=C 且 excluded_days 列表非空
- 模拟数据缺失 > 50% → 返回 report_quality=D 且尝试生成报告时返回 422

P1-6：权限系统数据库化

## 修复目标
将当前硬编码在 auth.go 中的角色权限定义迁移到数据库，支持动态调整权限而无需重启服务。

## 当前状态
- rolePermissions 为 Go map 硬编码
- 只有一个 perm 级别粒度（view:audit）
- 修改权限需改代码重新部署

## 具体要求

### 数据模型
新建 migration：
- roles 表：id, name, display_name, description, is_system(bool)
- permissions 表：id, resource, action, description
  - resource 示例：buildings, zones, commands, strategies, agents, mv, settings, users
  - action 示例：view, create, edit, delete, approve, execute
- role_permissions 表：role_id, permission_id（多对多）
- 初始数据 seed：将当前硬编码的 4 个角色和权限迁移为数据库记录

### 后端
1. 新建 `internal/auth/rbac.go`：
   - 从数据库加载角色-权限映射（启动时加载 + 缓存，修改时刷新）
   - 提供 `HasPermission(role, resource, action) bool` 方法

2. 修改 auth 中间件：
   - 用 rbac.HasPermission 替代当前硬编码检查
   - 保持向后兼容：原有角色的权限不变

3. 管理 API（仅 national_operator 可操作）：
   - GET /api/v1/admin/roles — 角色列表
   - GET /api/v1/admin/roles/{id}/permissions — 角色权限详情
   - PUT /api/v1/admin/roles/{id}/permissions — 更新角色权限
   - GET /api/v1/admin/permissions — 全量权限列表

### 前端
修改 Settings.tsx 或新建 RoleManager.tsx：
- 角色列表卡片
- 点击角色展开权限矩阵：资源 × 操作 的 checkbox 网格
- 修改后保存（PUT）+ 成功 toast

### 验证方式
- 修改某角色权限（如取消 building_operator 的 commands:execute）→ 该角色用户立即无法下发指令
- 不重启服务的情况下权限变更生效

P2-1：批量补全 Empty 空态

## 修复目标
为当前缺少 Empty 空态处理的 42 个页面批量补全空数据状态展示。

## 当前状态
- 51 个页面中只有 9 个有显式空态处理
- 其余页面数据为空时显示空白区域，用户无法判断是"无数据"还是"加载中"

## 具体要求

### 新建公共组件
在 frontend/src/components/ 新建 EmptyState.tsx：
- Props: { icon?: LucideIcon, title: string, description?: string, action?: { label: string, onClick: () => void } }
- 样式：居中显示，icon 用灰色 48px，title 大字，description 小字灰色，action 为 teal 色按钮
- 变体预设（通过 variant prop）：
  - "no-data"：图标 Inbox，标题"暂无数据"
  - "no-result"：图标 Search，标题"未找到匹配结果"，描述"尝试修改筛选条件"
  - "no-permission"：图标 Lock，标题"无权限访问"
  - "error"：图标 AlertTriangle，标题"加载失败"，action="点击重试"

### 批量修改规则
对以下所有列表页面，在 `loading === false && items.length === 0` 时渲染 EmptyState：
- Alarms, Decisions, Commands, WorkOrders, Inspections, EdgeNodes, Equipment, Strategies
- AgentRegistry, SkillLibrary, AuditLog, Sessions, SubAgents, Accounts
- Telemetry, ProtocolLog, LLMLog, Reports, Billing, CCER
- Buildings, Zones, DeviceHealth（各 Tab 内也需要）
- HvacOptimization（9 个 Tab 各自的列表为空时）
- MVCenter（9 个 Tab 各自无数据时）
- Portfolio（7 个 Tab）
- Onboarding（9 个 Tab）
- Operations（各面板无数据时用 mini 版空态）

对于有筛选功能的页面：
- 初始无数据 → "no-data" 变体
- 筛选后无结果 → "no-result" 变体 + "清除筛选"按钮

### 验证方式
- 新建一个空楼宇 → 进入各页面均显示合理的空态引导
- 在有数据的页面使用筛选条件筛到 0 结果 → 显示"未找到匹配结果"

P2-2：批量补全 Error 错误态

## 修复目标
为当前缺少 Error 态处理的 29 个页面补全网络错误/接口异常时的用户反馈。

## 当前状态
- 22/51 页面有 error 处理，29 个页面 fetch 失败时静默（显示永久 loading 或空白）

## 具体要求

### 新建公共组件
在 frontend/src/components/ 新建 ErrorBoundary.tsx（或在 Layout 中增加）：
- 包裹所有 API 调用的 try-catch
- 错误时显示：红色警告图标 + "加载失败，请检查网络连接" + "重试"按钮
- 支持 inline 模式（在面板内显示）和 fullpage 模式（替代整个页面）

### 新建 hooks/useFetch.ts 通用 hook：
```typescript
function useFetch<T>(url: string, options?: { interval?: number }) {
  return { data: T | null, loading: boolean, error: string | null, refetch: () => void }
}

自动处理 loading/error/data 三态
支持定时轮询（interval 参数）
非 2xx 响应自动设置 error

批量修改

逐个修改缺少 error 处理的 29 个页面：

将裸 fetch().then() 替换为 useFetch hook（或至少增加 .catch 设置 error 状态）
error 非 null 时渲染 ErrorBoundary inline 组件
重试按钮触发 refetch

验证方式

关闭后端服务 → 所有页面显示错误态 + 重试按钮（而非空白或永久转圈）
点击重试 → 重新发起请求

---

## P2-3：列表页分页补全

修复目标

为当前仅 4 个页面有分页的列表型页面批量增加分页支持。

当前状态

只有 Alarms, DeviceHealth, WorkOrders, Onboarding 有分页
其他列表页一次性加载所有数据，当数据量大时性能差且不便浏览

具体要求

新建公共分页组件

frontend/src/components/Pagination.tsx：

Props: { page, pageSize, total, onChange }
样式：「上一页 | 1 2 3 … N | 下一页」，当前页高亮
显示“共 X 条，第 Y/Z 页”

后端规范

确认所有列表 API 支持 ?page=1&page_size=20 参数，返回 { items: [], total: N, page: N, page_size: N }
（大部分已支持，检查并补全缺失的）

需要增加分页的页面（约 15 个）

Decisions, Commands, Equipment, Strategies, AgentRegistry
AuditLog, Sessions, SubAgents, Accounts, LLMLog
ProtocolLog, Reports, Billing, EdgeNodes, SkillLibrary

每个页面：

默认 page_size=20
URL query params 同步（切换页码时更新 URL，刷新不丢失）
配合筛选使用：切换筛选条件时重置为第 1 页

验证方式

任意列表页数据 > 20 条时自动出现分页器
点击第 2 页 → 正确加载第 2 页数据
刷新页面 → 保持在当前页（URL 参数持久化）

---

## P2-4：Brick/Haystack 语义兼容（可延后）

修复目标

在语义标注系统中增加 Brick Schema 兼容层，使点位语义可映射到国际通用标准。

当前状态

有自定义语义标注系统（温度/湿度/CO2/开关量等类型）
无 Brick/Haystack 映射

具体要求

后端

新建 semantic_mapping 表：internal_type, brick_class, haystack_tag, description
- 示例：supply_air_temp → brick:Supply_Air_Temperature_Sensor → haystack:air,supply,temp,sensor
API：
- GET /api/v1/semantic/mappings — 返回映射表
- GET /api/v1/semantic/export/brick — 导出 Brick TTL 格式
- GET /api/v1/semantic/export/haystack — 导出 Haystack JSON 格式

前端

在 Onboarding 语义标注 Tab 中增加“标准映射”列，显示每个点位对应的 Brick class
增加“导出”按钮：导出为 Brick TTL 或 Haystack JSON

验证方式

标注完成的点位可查看对应的 Brick class
导出 TTL 文件内容结构正确

---

## P2-5：策略仿真引擎（概念实现）

修复目标

将当前的策略“验证”（仅检查参数合法性）升级为真正的“仿真”（预测执行效果）。

当前状态

/strategies/validate 仅检查参数是否在合法范围内
无“如果执行这个策略，温度/能耗会怎么变化”的预测能力

具体要求

后端

新建 internal/simulation/engine.go：

简化版 3R2C 热模型仿真：
- 输入：当前温度、室外温度、设定值变化、区域热参数（热阻、热容）
- 输出：未来 30/60/120 分钟的温度预测曲线
- 使用欧拉法数值积分（无需精确，重在有预测能力）
能耗影响估算：
- 基于设定值变化估算功率变化（每°C 变化 ≈ X kW，系数可配）
- 输出：预计节能/增耗 kWh
API：
- POST /api/v1/strategies/simulate
  - body: { zone_id, action_type, params: {target_temp, duration_min}, current_conditions: {temp, outdoor_temp, occupancy} }
  - response: { temperature_curve: [{min, temp}], energy_impact_kwh, comfort_risk, confidence }

前端

修改 StrategyEditor.tsx：

增加“仿真预览”按钮
点击后调用 /simulate，展示：
- 温度变化预测曲线（Recharts LineChart，实线=当前趋势，虚线=执行策略后）
- 能耗影响数值（正数=节能，负数=增耗）
- 舒适度风险标签（绿/黄/红）

验证方式

对某区域模拟“降低设定值 2°C” → 返回温度下降曲线 + 能耗节省估算
对某区域模拟“关闭 AHU” → 返回温度回升曲线 + 舒适度风险=高

---

## P2-6：时序数据存储方案（架构标记）

修复目标

明确标记当前 mock 数据为技术债务，设计时序数据存储的接口抽象层，为后续接入 TimescaleDB/InfluxDB 做好准备。

说明

此项不要求引入真实时序数据库（属于基础设施改造），但要求：

后端新建 internal/timeseries/interface.go：
- 定义 TimeseriesStore 接口：Write(points), Query(metric, timeRange, aggregation), Latest(metric)
- 当前实现为 MockTimeseriesStore（返回 seedInt 生成的数据）
- 接口设计为后续可替换为 TimescaleDB/InfluxDB 适配器
将所有生成 mock 时序数据的逻辑收敛到 MockTimeseriesStore 中：
- 当前分散在各 handler 中的 seedInt() 时序数据生成统一通过此接口
- handler 只调用接口方法，不再直接生成 mock
前端无需修改
在 README 或 ARCHITECTURE 文档中标记：
- “时序数据当前使用 MockTimeseriesStore 实现（确定性伪随机数据）”
- “生产部署时需替换为 TimescaleDB 或 InfluxDB 适配器”
- 给出预估的接入工作量和接口契约

验证方式

现有功能不受影响（mock 数据照常返回）
新接口文件存在且定义清晰
未来可通过实现 TimeseriesStore 接口无痛替换存储后端

---

## P3-1：边缘层真实能力（本地规则/断网保护/缓存）

修复目标

设计并实现边缘层的核心能力框架，使 Edge 节点在断网时仍能执行本地安全策略。

说明

此项工作量大（L），建议分步实施。本提示词定义第一步：设计接口 + 实现断网保护逻辑模拟。

具体要求

后端

新建 internal/edge/simulator.go：
- 模拟边缘节点的行为（本项目为单体架构，用 goroutine 模拟边缘节点独立运行）
- 实现以下能力的 mock：
  - 本地规则缓存：从云端同步的策略规则保存在内存中
  - 断网检测：模拟与云端心跳超时（可通过 API 触发模拟断网）
  - 断网降级：心跳超时后进入 fallback 模式，仅执行本地缓存中的安全规则
  - 恢复同步：重新连通后上报断网期间的操作日志
API：
- POST /api/v1/edge/{id}/simulate-disconnect — 触发该节点模拟断网
- POST /api/v1/edge/{id}/simulate-reconnect — 模拟恢复连接
- GET /api/v1/edge/{id}/local-rules — 查看该节点缓存的本地规则
- GET /api/v1/edge/{id}/offline-log — 查看断网期间的操作记录
断网期间行为规则：
- 已在执行的策略继续按最后同步的参数运行
- 不接受新的高风险指令（risk_level >= high）
- 低风险指令（维持当前设定值、回到安全模式）可执行
- 超过 30 分钟无恢复则自动切换为“安全模式”（所有设定值回到保守值）

前端

修改 EdgeNodes.tsx 节点详情：

增加“模拟断网”按钮（开发调试用）
节点状态增加“离线-本地运行”状态标识
断网期间操作日志面板

验证方式

触发节点模拟断网 → 节点状态变为 offline_local
断网期间对该节点下发高风险指令 → 被拒绝
恢复连接后 → 上报断网期间日志，状态恢复 online

---

## P3-2：数字孪生运营层

修复目标

将当前的静态 SVG 楼层图升级为可交互的“运营孪生”（第一层），支持实时状态查询和控制操作入口。

当前状态

Building3D.tsx 为静态 SVG 色块，无真实交互

具体要求

前端重构 Building3D.tsx → DigitalTwin.tsx

楼层选择器：左侧楼层列表，点击切换显示该楼层平面
平面图渲染：
- 每个区域(zone)为可点击色块
- 色块颜色表示当前状态（按选择的维度：温度/占用/能耗/控制状态）
- 设备图标叠加在区域上（AHU/FCU/传感器/阀门，小图标）
- 设备在线状态用绿/红点表示
交互：
- hover 区域显示 tooltip（区域名、当前温度、设定值、占用人数、当前策略）
- 点击区域弹出侧边详情面板（等同于 ZoneDetail 的精简版）
- 点击设备弹出设备状态卡片
顶部维度切换器：温度 / CO2 / 占用 / 控制级别 / 能耗强度
时间轴：底部可拖动时间滑块，回放历史某时刻的状态（调用 /operations/heatmap?time=xxx）

后端

确保 /operations/heatmap 支持 ?time= 参数（返回指定时间的历史快照）
确保每个 zone 数据包含 x/y/width/height 字段（用于平面图定位）

验证方式

切换楼层 → 显示对应楼层的区域布局
切换维度 → 色块颜色随之变化
点击区域 → 弹出详情面板
拖动时间轴 → 显示历史状态

---

## P3-3：MPC 优化器接口设计

修复目标

设计 MPC（模型预测控制）优化器的接口抽象层，为后续实现真实优化求解做好架构准备。

说明

不要求实现真实的 MPC 求解器，但需要定义清晰的接口，并提供基于规则的简化实现。

具体要求

后端

新建 internal/optimizer/rule_based.go：
- 实现 RuleBasedOptimizer（满足 Optimizer 接口）
- 基于简单规则生成建议（如：占用低+电价高 → 建议回退，占用即将上升 → 建议预冷）
- 不是真正的数学优化，但行为合理
API：
- POST /api/v1/optimizer/solve — 接受 OptimizationRequest，返回 OptimizationResult
- GET /api/v1/optimizer/config — 返回当前目标函数权重和约束配置
- PUT /api/v1/optimizer/config — 更新权重配置

新建 internal/optimizer/interface.go：

type OptimizationRequest struct {
    ZoneIDs       []string
    Horizon       time.Duration  // 优化时域（默认 2h）
    Objectives    []Objective    // 目标函数项
    Constraints   []Constraint   // 约束条件
    CurrentState  SystemState    // 当前系统状态
    Predictions   Predictions    // 负荷/天气/占用预测
}

type Objective struct {
    Type   string  // energy_cost, comfort_deviation, equipment_wear, carbon
    Weight float64
}

type OptimizationResult struct {
    Actions       []ProposedAction  // 建议的控制序列
    ExpectedCost  float64
    ExpectedComfort float64
    Confidence    float64
    SolveTimeMs   int
}

type Optimizer interface {
    Solve(req OptimizationRequest) (OptimizationResult, error)
}

前端

在 Strategies 或 HvacOptimization 中增加“优化建议”面板：

显示优化器最近一次求解结果
展示目标函数各项权重（可调节滑块）
展示建议的控制动作列表 + “采纳”按钮（将建议转为决策）

验证方式

调用 /optimizer/solve → 返回合理的建议动作列表
修改权重（如增大 comfort_deviation 权重）→ 建议倾向保守（维持温度优先于节能）

---

## P3-4：离线执行/断网降级完整方案

修复目标

此项为 P3-1 的完整版，包含 P3-1 的模拟断网 + 完整的离线策略管理。

说明

如 P3-1 已完成，本项在其基础上扩展；如未完成，本项包含 P3-1 全部内容。

具体要求（在 P3-1 基础上增加）

后端

离线策略管理：
- 每个 Edge 节点可配置“离线策略包”（一组在断网时执行的规则）
- POST /api/v1/edge/{id}/offline-policy — 上传离线策略包
- 离线策略包内容：
  - 安全模式温度设定值（各区域）
  - 最大允许偏差（超出则报警但不执行新动作）
  - 定时规则（如 22:00 后关闭非必要设备）
  - 紧急处理规则（如温度超过 35°C 时全速制冷）
离线策略同步机制：
- 云端修改后自动推送到对应 Edge（模拟：通过心跳接口返回需更新标记）
- Edge 确认接收后标记版本号
- GET /api/v1/edge/{id}/policy-version — 查看策略版本对齐情况
断网恢复对账：
- 恢复连接后对比断网期间 Edge 执行的操作 vs 云端此期间生成的决策
- 如有冲突则标记为需人工审核
- GET /api/v1/edge/{id}/reconciliation — 返回对账结果

前端

扩展 EdgeNodes 详情页：

“离线策略”Tab：编辑/查看离线策略包内容
“同步状态”指示：策略版本号 + 最后同步时间
“断网对账”面板：恢复后的冲突列表 + 人工确认按钮

验证方式

配置离线策略 → 同步到 Edge → 版本号一致
模拟断网 → Edge 按离线策略运行
恢复后 → 对账报告显示差异（如有）

---

## P3-5：CCER 碳资产对接

修复目标

将 CCER.tsx 从简单列表升级为完整的碳资产申报管理模块。

当前状态

CCER.tsx 仅有基础列表展示
后端 /ccer 返回简单 mock

具体要求

后端

完善数据模型：
- ccer_projects 表：project_name, building_id, methodology, monitoring_period_start/end, status(draft/submitted/reviewing/approved/rejected), estimated_reduction_t, actual_reduction_t
- ccer_monitoring_records 表：project_id, period, energy_data_source, baseline_reference, calculation_method, result_t, evidence_files(jsonb)
API：
- GET /api/v1/ccer/projects — 项目列表
- POST /api/v1/ccer/projects — 新建申报项目
- GET /api/v1/ccer/projects/{id} — 项目详情
- POST /api/v1/ccer/projects/{id}/submit — 提交审核
- GET /api/v1/ccer/projects/{id}/monitoring — 监测记录
- POST /api/v1/ccer/projects/{id}/monitoring — 新增监测期记录
- GET /api/v1/ccer/methodology — 可用方法学列表（建筑节能 CCER 方法学）

前端

重构 CCER.tsx：

项目看板：卡片式展示各申报项目状态（草稿/已提交/审核中/已通过）
新建项目向导：选择楼宇 → 选择方法学 → 定义监测边界 → 关联 M&V 基线
监测记录管理：按监测期列出碳减排量 + 计算依据
碳收益估算：基于当前碳价（可配置）估算经济收益
申报进度时间线：从草稿到获批的状态流转

验证方式

创建 CCER 项目 → 关联到楼宇和 M&V 基线
录入监测期数据 → 自动计算碳减排量
提交审核 → 状态变更为 submitted

---

## P3-6：多能协同预留接口（远期标记）

修复目标

为规划路线图中 24-36 个月的“多能协同”（光伏/储能/充电桩）预留数据模型和接口定义，不实现具体功能。

具体要求

后端

新建 migration（仅建表，不填数据）：
- energy_sources 表：id, building_id, type(pv/wind/grid/diesel), capacity_kw, status
- storage_systems 表：id, building_id, type(battery/ice_storage), capacity_kwh, soc_pct, status
- ev_chargers 表：id, building_id, capacity_kw, current_load_kw, status
在 README/ARCHITECTURE 文档中标记：
- “多能协同模块为预留接口，计划在 24-36 月路线图实现”
- “当前数据表为空，接口无具体实现”

新建 internal/multi_energy/interface.go：

// 预留接口，当前无实现
type EnergySource interface {
    GetCurrentOutput() (float64, error)    // 当前出力 kW
    GetForecast(horizon time.Duration) ([]TimeValue, error)  // 预测出力
    GetCapacity() float64                  // 装机容量
}

type StorageSystem interface {
    GetSOC() float64                       // 当前荷电状态
    GetCapacity() float64                  // 容量 kWh
    Charge(kw float64) error
    Discharge(kw float64) error
}

type MultiEnergyCoordinator interface {
    OptimizeDispatch(demand float64, sources []EnergySource, storage []StorageSystem) DispatchPlan
}

前端

无需新增页面
在 Settings 中增加“多能协同（即将推出）“灰色卡片，标注”规划中“

验证方式

接口文件存在且定义清晰
数据表存在（可为空）
不影响现有功能

---

## 修复执行总结

| 优先级 | 项数 | 预计总工时 | 核心目标 |
|--------|------|-----------|---------|
| P0 | 4 项 | 3-5 天 | 让系统从"展示层"变成"有真实控制能力" |
| P1 | 6 项 | 3-4 天 | 补全业务流程和架构完整性 |
| P2 | 6 项 | 2-3 天 | 工程质量批量提升 |
| P3 | 6 项 | 5-7 天 | 远期架构预备，按需安排 |

建议执行节奏：
1. P0 四项按顺序串行完成（P0-1 → P0-2 → P0-3 → P0-4，因为后者依赖前者）
2. P1 可并行，但 P1-6 建议在 P0-1 之后做
3. P2 三项批量处理可以一轮对话完成
4. P3 按业务需要选择性实施

---

## 全项目系统性审查提示词（所有模块完成后使用）

> 用途：在 7 个模块全部开发完成后，用本提示词对整个项目进行一次全面审查，找出规划文档定义了但代码未实现或实现不完整的所有缺口。

AIBEMS 全项目系统性审查

请对照 docs/AIBEMS-2.0-master-plan.md 全文，对本项目前后端代码进行全面审查。审查目的是找出“规划文档定义了但代码未实现或实现不完整”的所有缺口。

审查范围（按文档章节逐项核对）

A. 产品功能覆盖度（对应文档 3.3 节，7 个模块共 64 个功能点）

逐一检查每个功能点是否有：

对应的前端页面/组件（列出文件路径）
对应的后端 API（列出路由和 handler 文件）
实际的业务逻辑（不只是空壳或硬编码 mock）
可操作的交互（筛选、编辑、状态切换等）

B. 业务域与角色体系（对应 3.2 + 3.4 节）

文档定义了 6 种用户角色，前端是否每种角色有差异化首页和权限隔离
文档建议分为 4 个业务域（交付配置/运行管理/控制优化/经营验证），前端导航是否体现这个分层
各角色登录后看到的菜单项是否正确按权限过滤

C. 控制分级与安全体系（对应第 4 节）

L0-L4 五级控制在代码中是否有完整定义和区分逻辑
R0-R5 点位权限矩阵是否在后端数据模型中实现
4.6 节列出的 12 项保护能力（白名单、限幅、频率限制、回滚等），后端是否每项都有对应的校验逻辑
控制闭环链路（采集→质量检查→预测→候选→优化→安全校验→审批→执行→反馈）是否在代码中有完整流转

D. 多智能体系统（对应第 6 节）

文档定义了 11 个核心智能体，代码中是否有对应的 Agent 注册和调度
6.3 节要求每个智能体有 6 个“工程合同”（输入/输出 schema、工具、禁止项、评估指标、降级方式），后端是否有此元数据定义
6.5 节要求“交叉审查”链路（提案→反方审查→规则引擎→审批），代码是否实现

E. M&V 验证体系（对应第 8 节）

8.3 节列出 10 个 M&V 方案要素（测量边界、基准期、归一化方法等），节能验证模块是否全部覆盖
8.4 节推荐的 9 个首批 KPI 是否在仪表盘或报告中有展示
8.5 节的四阶段验收（接入→试运行→阶段价值→年度节能）是否在流程中体现

F. 技术架构一致性（对应第 5 节）

5.3 节边缘层的 11 项必须能力，Edge 模块是否都有对应实现
5.4 节云端关键服务列表，后端微服务是否覆盖
5.5 节语义层设计（Building→Floor→Zone→Equipment→Point 层级），数据模型是否对齐

G. 前后端工程质量

所有前端页面的四态（加载/空数据/错误/正常）是否完整
前端调用的 API 路由与后端注册的路由是否一一匹配（无死调用、无孤儿 API）
TypeScript 编译是否无错误（npm run build）
Go 后端编译是否无错误（go build ./…）
路由注册（App.tsx）vs 侧边栏导航（Layout.tsx）是否一致

输出格式要求

总览评分卡：A-G 每项给分（满分 10），标注最严重的 Top 10 问题
逐项详细报告：按 A-G 每个维度展开，列出所有缺口
修复优先级清单：按 P0（阻塞性）/P1（核心缺失）/P2（体验不足）/P3（优化项）分级，每项标注预估工作量（S = <2h / M = 2-8h / L = >8h）

约束

不要自行修复任何问题，只做审查诊断和输出报告
如果某个维度代码量太大无法逐行检查，至少抽样检查 3-5 个代表性文件并说明覆盖率
对于“后端有但前端没展示”和“前端有但后端没实现”的情况要分别标注

---

## 第二轮深度审计：P0 实现质量验证

> 使用时机：P0-P2 任务标记完成后，验证实现是"真实逻辑"还是"表面覆盖"。

深度审计指令：验证 P0 实现质量

上一轮审计发现系统得分 41.5/70，主要短板在控制/安全层。随后执行了 100+ 项修复任务，P0-P4 均标记为完成，编译通过。

但我们必须验证这些实现是否真实——历史上存在将 stub/概念代码标记为完成的情况。本次审计不关心功能点覆盖率（上次已是 97%），只关心核心逻辑是否真实运行。

审计重点 1：P0-3 安全引擎（最高优先级）

定位 internal/safety/ 或 internal/control/ 下的安全引擎代码，逐行读取并回答：

WhitelistChecker：白名单数据从哪里来？是从数据库查询 (SELECT ... FROM control_whitelist ...)，还是硬编码切片/空切片？
RateLimiter：是否有真实的时间窗口计数逻辑（如 Redis TTL 或内存 map + time.Now()）？还是只有函数签名返回 true？
MinIntervalChecker：最小启停间隔的“上次操作时间”从哪里读取？有数据库查询吗？
ConfidenceGate：置信度阈值从哪里取？写死的 0.7 还是从 agent 工程合同中读取？
AutoRollback：回滚触发逻辑在哪里？是主动轮询比较执行前后的目标温度，还是只有一个注释说“TODO: implement”？
SafetyEngine.Check() 是否真正集成到控制 pipeline 中：找到 P0-2 的控制执行入口，确认 SafetyEngine.Check() 调用在真实的 POST 处理路径上，而不是在测试文件或注释里。

对每个 Checker，给出：状态（✅真实实现 / ⚠️部分实现有实际逻辑 / ❌stub或TODO）+ 核心代码片段（关键 3-5 行）。

审计重点 2：P0-2 控制闭环

定位 handlers_control_engine.go 或 internal/control/pipeline.go，逐行读取核心 POST 处理函数，回答：

指令状态机：control_commands 表是否真实存在（找对应的 migration 文件）？status 字段的状态流转（received→checking→approved→executing→succeeded/failed）是否在代码中有显式更新？
L2 待审批流程：L2 级别指令进入“待审批”后，前端 ControlPipeline.tsx 是如何轮询或订阅这条指令状态的？后端是否有 GET /control-pipeline/pending 或类似接口？
实际执行层：executing 阶段调用了什么？是调用 BAS 模拟器的真实接口，还是直接 status = "succeeded" 跳过执行？
失败回滚：执行失败时，代码如何触发回滚？找到具体的 rollback 调用点。

审计重点 3：P0-1 权限集成

找到 enforceControlPermission 或类似中间件函数，回答：

权限数据是从哪里查询的？SELECT ... FROM control_matrix ... 查数据库，还是内存硬编码表？
control_matrix 表是否有对应 migration（找 V0xx 文件）？表结构是否有 role, zone_id, point_type, permission_level 字段？
被拒绝时的 403 响应体是否包含 required_level 和 current_level 字段（按原设计要求）？

审计重点 4：P0-4 工程合同

找到 agents 表相关的 migration（应在 V030 左右），回答：

input_schema, output_schema, boundaries, metrics, degradation_strategy 这 5 个字段是否真实存在于 migration SQL 中？
找一个具体 agent 的 seed/init 数据，这些字段是否填充了有意义的内容（JSON schema 定义），还是空 JSON {}？
执行时是否有 schema 校验逻辑（在 agent 执行入口检查输入是否符合 input_schema）？

审计重点 5：数据库 migration 一致性

列出最新的 5 个 migration 文件名（V026-V030 或更新），对每个文件：

文件名是什么
主要建了什么表/加了什么字段
是否有对应的后端代码实际使用这些新表（还是建了表但没有任何 SELECT/INSERT）

输出格式

对每个审计重点，给出：

P0-X 评估

实现质量：✅真实 / ⚠️部分 / ❌空壳
核心逻辑摘录（关键代码 3-10 行，不需要完整代码）
如果是 ⚠️ 或 ❌，说明缺少什么

最后给出更新后的 C 维度得分估算（原 4.5/10，本次基于实际代码评估）。

约束

不要修复任何问题，只做诊断
每个审计点必须找到并引用真实代码，不接受“应该已实现”或“从任务列表推断”的回答
找不到对应代码时，明确说“未找到”而不是推测

---

## 阶段纠偏指令（P0 结构性修复优先）

> 使用时机：当开发会话完成了审计并开始偏向表面优化时，用本段指令强制拉回到结构性修复轨道。

立即停止当前工作方向

你刚完成的 104 项任务大幅提升了功能覆盖率（97%），这是好的。但是，你现在正在做的事情——SubAgents 页面从 62 行扩展到 425 行、Analytics 页面的 UI 美化——属于表面优化，优先级为 P2/P3。

审计报告 docs/review/SYSTEM_AUDIT_2026-06-11.md 揭示了系统的核心问题：

总分 41.5/70（59%），最致命短板是 C 维度（控制分级与安全）仅 4.5/10
12 项保护能力实现率仅 33%（2 完整 + 4 部分 + 6 缺失）
智能体工程合同完成度仅 2/6
控制矩阵 R0-R5 只是前端展示，未接入指令下发链路
L2 以上控制级别无真实执行路径

这意味着：系统当前只是一个“能看不能用”的展示平台。无论 SubAgents 页面多好看、Analytics 图表多花哨，只要 P0 不解决，这个系统就无法作为真实产品交付。

当前执行优先级（严格按顺序）

禁止事项：在 P0 全部完成之前，不得对以下内容做任何修改：

不得优化现有页面 UI/UX（包括 SubAgents、Analytics、Dashboard 等）
不得新增展示型页面
不得做代码美化、重构或 CSS 调整
不得扩展已有功能的前端交互

必须做的（按此顺序逐个完成）：

第 1 步：P0-1 控制权限矩阵集成（预估 4-6h）

目标：让 ControlMatrix.tsx 中展示的 R0-R5 权限真正生效——任何控制指令下发前必须校验该操作者对该点位的权限级别。

具体要求：

后端新建 internal/control/permission.go 中间件：
- 函数签名：CheckControlPermission(userRole, zoneID, pointType, actionLevel) → (allowed bool, reason string)
- actionLevel 定义：R0=无权, R1=只读, R2=可建议, R3=人工确认后执行, R4=自动执行, R5=永久禁控
- 从数据库（control_matrix 表）实时查询权限，不硬编码
将此中间件集成到所有指令下发入口：
- handlers_bas.go 中 POST /api/v1/bas/commands — 下发前调用
- handlers_hvac_optimization.go 中所有 POST apply 端点 — 下发前调用
- 被拒绝时返回 HTTP 403 + {code: "PERMISSION_DENIED", required_level: "R4", current_level: "R2", point: "..."}
前端在指令被拒绝时显示明确提示：“当前角色对该点位的控制权限为 R2（可建议），执行此操作需要 R4（自动执行）权限”

验收标准：

building_operator 对 L3 级控制指令返回 403
enterprise_admin 可执行 R3 级需确认操作
权限变更后（通过 ControlMatrix 修改）立即生效，无需重启

第 2 步：P0-2 真实控制闭环（预估 8-12h）

目标：实现 L2+ 级别的完整控制链路，让系统从“展示平台”变为“可执行控制的平台”。

具体要求：

Pipeline 各阶段：
- received: 接收指令，记录 audit log
- permission_checked: 调用 P0-1 的权限校验
- safety_validated: 调用 P0-3 的安全引擎（先用 placeholder，P0-3 完成后替换）
- approval_routed: L2 需人工确认(推送审批)，L3 低风险直接通过，L4 全自动
- executing: 调用 BAS 适配层下发指令（模拟器实现即可）
- feedback: 记录执行结果，更新状态
指令状态持久化：新建 control_commands 表
- id, building_id, zone_id, point_type, action, params(jsonb), level(L0-L4)
- status(enum: received/checking/approved/rejected/executing/succeeded/failed/rolled_back)
- requested_by, approved_by, executed_at, result(jsonb)
前端 ControlPipeline.tsx 改造为实时 pipeline 展示：
- 每条指令显示当前所处阶段（流程图高亮当前步骤）
- 待审批指令列表（L2 级别）+ 审批操作按钮
- 执行历史（成功/失败/回滚）

新建 internal/control/pipeline.go 控制执行引擎，实现完整 pipeline：

收到控制请求 → 权限校验(P0-1) → 安全校验(P0-3) → 审批路由 → 执行/模拟 → 结果反馈

验收标准：

通过 Copilot 发起一个 L2 控制建议 → 进入待审批 → 人工批准 → 执行成功 → ControlPipeline 页面全程可追踪
L3 指令自动通过安全检查后直接执行
执行失败的指令状态正确更新为 failed

第 3 步：P0-3 安全引擎（预估 8-12h）

目标：实现规划文档 4.6 节定义的 12 项保护能力，作为独立模块嵌入控制 pipeline 的 safety_validated 阶段。

具体要求：

新建 internal/safety/engine.go：
- SafetyEngine struct 持有 12 个 Checker
- Check(ctx, command Command) → CheckResult{Passed, Violations[]}
- 每个 Checker 是独立 interface，可单独启用/禁用
12 个 Checker 全部实现（不是 stub）：
- WhitelistChecker: 点位白名单校验（从 DB 读取允许控制的点位列表）
- RangeLimiter: 调整幅度限制（如温度设定 ±3℃，频率 ±5Hz）
- RateLimiter: 对同一设备的指令频率限制（如 15min 内最多 1 条）
- MinIntervalChecker: 最小启停间隔（压缩机 ≥5min）
- ConfidenceGate: AI 决策置信度必须 >0.7 才可自动执行
- DataQualityGate: 输入数据质量分 >0.8 才可执行 L3+
- ZoneLock: 锁定区域内禁止自动控制
- HumanOverride: E-Stop 激活时拒绝所有自动指令
- OfflineDegradation: 云端通信中断时禁止高风险操作
- AutoRollback: 执行后 5min 内如目标温度偏差 >2℃ 自动回滚
- AuditLogger: 所有安全事件写入 audit_log
- BASRestore: 一键恢复原始 BAS 设定值
将 SafetyEngine.Check() 接入 P0-2 pipeline 的 safety_validated 阶段
前端 SafetyDashboard.tsx 改造：
- 12 项保护能力状态面板（启用/禁用/最近触发时间/触发次数）
- 实时安全事件流（被拦截的指令列表）
- 配置管理（白名单编辑、阈值调整、区域锁定开关）

验收标准：

白名单外点位 → 被拦截并记录
同一设备 15min 内第二条指令 → 被 RateLimiter 拦截
置信度 0.5 的 L3 决策 → 被降级或拦截
E-Stop → 所有自动指令被拒
SafetyDashboard 显示所有拦截事件

第 4 步：P0-4 智能体工程合同（预估 6-8h）

目标：为所有智能体补全 6 个工程合同要素，确保 Agent 行为可控可预测。

具体要求：

agents 表增加 JSONB 字段：input_schema, output_schema, boundaries, metrics, degradation_strategy
为现有 7+2（新增人流预测、M&V）共 9 个智能体填充完整工程合同
AgentDetail.tsx 增加“工程合同”展示 Tab
运行时校验：Agent 执行前检查输入是否符合 input_schema，输出是否符合 output_schema

验收标准：

GET /agents 返回 9 个智能体（原 7 + 新增 2 个）
每个智能体的 6 要素全部非空且语义合理
Agent 执行时输入校验生效（传入不符合 schema 的数据返回错误）

工作流程要求

严格串行：完成一个 P0 后再开始下一个。不要并行或跳跃。
每个 P0 完成后运行验证：确保 npx tsc --noEmit --skipLibCheck 和 go build ./cmd/ 通过，然后对照验收标准逐条验证。
如果某步骤遇到阻塞（如需要修改已有代码的多处位置、数据模型冲突等），先说明阻塞原因和你的解决方案，等确认后再动手。
P0 全部完成后，再回头处理 P1（按 docs/frontend-development-prompts.md 中 P1-1 到 P1-6 的顺序）。
完成进度汇报：每完成一个 P0 后，简要报告：做了什么、改了哪些文件、验收结果。

参考文档

审计报告：docs/review/SYSTEM_AUDIT_2026-06-11.md
修复提示词详情：docs/frontend-development-prompts.md（P0-1 到 P0-4 段落）
需求基准：docs/AIBEMS-2.0-master-plan.md 第 4 节（控制分级）、第 6 节（智能体）

现在开始，从 P0-1 开始执行。

---

## 第三轮工作：四阶段强化指令

> 使用时机：P0 深度审计确认真实实现后，按以下 4 个阶段依次执行。每完成一个阶段后汇报，确认后再开始下一个。

---

### 阶段 1/4：全系统 A-G 重新评分（预估 1-2h）

全系统重新评分

P0-P2 修复已确认真实落地。现在需要重新评估系统整体水平，建立新基线。

参照 docs/review/SYSTEM_AUDIT_2026-06-11.md 的原始评分维度和标准，对当前代码库做一次完整的 A-G 重新评分。

评分维度（与原报告一致）

维度	满分	原始得分	本次重评
A. 产品功能覆盖	10	6.5	?
B. 业务域与角色	10	7.0	?
C. 控制分级与安全	10	4.5	?
D. 多智能体系统	10	5.0	?
E. M&V 验证体系	10	6.0	?
F. 技术架构	10	5.5	?
G. 工程质量	10	6.5	?

评分要求

逐维度重新打分，每个维度必须引用至少 3 个具体代码证据（文件名+行号或函数名）
与原分数对比，标注提升幅度和剩余缺口
识别新的 Top 5 短板——上一轮最大短板（C 维度）已修复，新的最弱项是什么？
对每个维度给出“距离 9/10 还差什么”的具体清单

输出格式

更新后的评分卡（含原分→新分→提升幅度）
每维度 3-5 行评估理由 + 代码证据
新 Top 5 短板清单（按影响程度排序）
下一步建议（哪些短板值得继续投入）

约束

只做评估不做修复
写入 docs/review/SYSTEM_AUDIT_2026-06-12.md
如果某维度与上次相同（无变化），注明“无变化”即可，不需要重新展开论述

---

### 阶段 2/4：内存硬编码转 DB 驱动（预估 4-6h）

内存硬编码 → 数据库驱动

深度审计确认了一个系统性问题：权限矩阵、白名单、安全阈值等核心配置当前都是内存硬编码（Go 代码中的 map/slice），无法运行时动态修改。这意味着：

新增楼宇/区域需要改代码重部署
客户无法自行调整安全阈值
权限变更不可审计

需要数据库化的 5 个数据源

2.1 控制权限矩阵

当前：controlMatrixBaseline 内存 map
目标：control_matrix 表，前端 ControlMatrix.tsx 的编辑操作直接写入 DB

具体要求：

新建 migration：control_matrix 表 (role, building_id, zone_id, point_type, permission_level, updated_by, updated_at)
Seed 数据从当前 controlMatrixBaseline 导入
enforceControlPermission() 改为从 DB 查询（加缓存，5min TTL）
POST /control-matrix 端点改为真实写入 DB（当前可能是 mock 响应）
权限变更写入 audit_log

2.2 安全白名单

当前：WhitelistChecker 的 init() 预置 map
目标：safety_whitelist 表

具体要求：

新建 migration：safety_whitelist 表 (building_id, point_id, point_type, allowed_actions[], created_by, created_at)
WhitelistChecker 改为 DB 查询（加缓存，变更时失效）
SafetyDashboard.tsx 的白名单编辑操作写入 DB
白名单变更写入 audit_log

2.3 安全阈值配置

当前：RateLimiter 的 maxPerHour、MinIntervalChecker 的间隔时间、ConfidenceGate 的 minConf、RangeLimiter 的 ±3℃ 等均为代码常量
目标：safety_thresholds 表

具体要求：

新建 migration：safety_thresholds 表 (checker_name, param_key, param_value, building_id nullable, updated_by, updated_at)
每个 Checker 启动时从 DB 加载阈值，fallback 到代码默认值
SafetyDashboard.tsx 增加“阈值配置”面板，可修改并保存
阈值变更写入 audit_log

2.4 区域锁定状态

当前：ZoneLock 的锁定状态在内存中
目标：zone_locks 表

具体要求：

新建 migration：zone_locks 表 (building_id, zone_id, locked_by, locked_at, reason, expires_at nullable)
ZoneLock checker 从 DB 查询
SafetyDashboard.tsx 的区域锁定开关写入 DB
锁定/解锁操作写入 audit_log

2.5 E-Stop 状态

当前：store.estop[bid] 内存 map
目标：estop_state 表

具体要求：

新建 migration：estop_state 表 (building_id, activated, activated_by, activated_at, deactivated_by, deactivated_at)
EStopChecker 从 DB 查询
E-Stop 按钮操作写入 DB + audit_log

通用要求

所有新表都要有对应的 CRUD handler（至少 GET 列表 + PUT 更新）
缓存策略：读取时先查内存缓存，缓存未命中查 DB。写入时更新 DB + 失效缓存。
每完成一项运行 go build ./cmd/ 确认编译通过
保持现有 API 接口不变（前端无需改路由，只是底层存储变更）

验收标准

通过 API 修改某个 zone 的权限级别 → 下次指令校验使用新权限（无需重启）
通过 SafetyDashboard 修改 RateLimiter 阈值从 4/h 改为 2/h → 第 3 条指令被拦截
通过 SafetyDashboard 锁定某区域 → 该区域指令被 ZoneLock 拦截
所有变更在 AuditLog 页面可查

---

### 阶段 3/4：系统可演示化（预估 6-8h）

系统可演示化改造

当前系统所有数据由 seedInt() 确定性生成，时序数据为静态快照。要让系统可演示，需要一个“活”的数据层——不需要真实设备接入，但需要数据随时间变化、指令有可见效果、AI 决策有可观测过程。

3.1 动态模拟数据引擎

新建 internal/simulator/engine.go，实现一个后台时钟驱动的模拟器：

时钟：内部维护模拟时间（可加速，如 1 秒 = 5 分钟），通过 GET /simulator/clock 查询当前模拟时间
温度模型：每个 zone 的温度随时间变化（基于简化热力学：外温影响 + 空调出力 + 人员负荷）
设备状态：冷机、水泵、AHU 有运行/待机/故障状态，按策略自动切换
能耗计算：基于设备状态和负荷实时计算 kW，累积为 kWh
事件生成：随机注入故障事件（传感器漂移、阀门卡死、冷机过载），触发告警

3.2 Telemetry 实时推送

改造 GET /telemetry/stream：使用 SSE (Server-Sent Events) 每 2 秒推送一帧模拟器最新数据
前端 Telemetry.tsx 使用 EventSource 接收实时数据，图表追加点（保留最近 200 点）
Operations 运行中心的仪表盘同样接入实时数据

3.3 控制指令可见效果

当前控制指令发出后，系统状态不会变化（因为数据是静态 seed）。改造：

控制指令执行成功后，修改 simulator 中对应 zone 的设定值
模拟器根据新设定值调整温度曲线（如设定温度降低 1℃ → 温度在接下来 15min 模拟时间内逐步下降）
前端实时看到温度变化 → 形成“发指令 → 看到效果”的完整演示闭环

3.4 演示场景脚本

新建 internal/simulator/scenarios.go，预置 3 个演示场景：

正常运行：稳态运行，温度在设定值 ±0.5℃ 波动，能耗稳定
高温来袭：外温从 32℃ 升至 38℃，触发 AI 预冷策略建议 → 等待审批 → 执行 → 温度回归
设备故障：1 号冷机突发故障 → 告警 → 负荷转移到 2 号冷机 → 工单生成 → 安全引擎限制高风险操作

通过 POST /simulator/scenario 切换场景。

3.5 演示入口页面

新建 DemoControl.tsx 页面（仅 national_operator 可见）：

模拟器时钟控制（暂停/继续/加速）
场景选择器（3 个预置场景）
实时状态概览（温度、能耗、设备状态、活跃告警数）
快捷操作：一键触发各种事件（故障注入、E-Stop、区域锁定）

验收标准

启动系统后 Telemetry 页面自动显示动态变化的温度曲线
通过 Copilot 发起“降低 A 区设定温度 1℃” → ControlPipeline 走完流程 → Telemetry 上 A 区温度开始下降
切换到“设备故障”场景 → 告警页面出现新告警 → 安全引擎拦截高风险操作
DemoControl 页面可控制模拟时钟和切换场景

---

### 阶段 4/4：P3 深度实现（预估 12-20h）

P3 深度实现

系统已具备真实控制能力和演示能力。最后一步是补齐规划文档中的远期目标，让系统从“MVP”走向“完整产品”。

按优先级排序（投入产出比最高的先做）：

P3-1 边缘层真实化（8-12h）

当前 EdgeNodes 页面纯展示。改造为真实的边缘模拟：

新建 internal/edge/node.go——模拟边缘节点行为：
- 本地规则引擎：在网络延迟 >500ms 时本地执行 L1 级控制
- 数据缓存：模拟网络断开时缓存遥测数据，恢复后批量上传
- 断网保护：网络中断时禁止 L3+ 操作，仅允许保守模式
- 指令确认：收到云端指令后确认执行（模拟 ACK 延迟）
改造 EdgeNodes.tsx：
- 显示每个节点的连接状态（在线/离线/延迟高）
- 显示本地规则触发次数和缓存数据量
- 支持模拟断网（按钮点击 → 该节点进入离线状态 → SafetyEngine 触发 OfflineDegradation）
通信协议模拟：
- POST /edge/{id}/disconnect — 模拟断网
- POST /edge/{id}/reconnect — 模拟恢复
- GET /edge/{id}/buffer — 查看缓存的未上传数据

验收标准：

模拟断网 → 安全引擎拦截该节点的 L3 指令 → 恢复连接 → 缓存数据上传 → L3 指令恢复可用

P3-2 策略仿真引擎（6-8h）

当前 StrategyEditor 的“验证”只检查参数合法性，不做效果预测。

新建 internal/simulator/strategy_sim.go：
- 输入：策略配置（如“预冷提前 30min、设定温度降 2℃”）+ 当前楼宇参数
- 输出：预测未来 24h 的温度曲线、能耗曲线、舒适度评分、节能率
- 使用简化热力学模型（与 3.1 的模拟器共享参数）
新增 API：POST /strategies/simulate
- 请求体：策略 JSON + building_id + 模拟时长
- 响应：时间序列数据（温度、能耗、舒适度）+ 汇总指标
改造 StrategyEditor.tsx：
- “验证”按钮改为“仿真预览”
- 显示对比图：当前策略 vs 修改后策略（双线叠加）
- 显示关键指标：预计节能 X%、舒适度影响 Y%

验收标准：

在 StrategyEditor 修改预冷时间 → 点击“仿真预览” → 看到对比曲线和节能预测
极端参数（如降温 10℃）→ 仿真结果显示舒适度严重下降 → 给出风险提示

P3-3 数字孪生增强（4-6h）

当前 Building3D.tsx 是静态 SVG。增强为运营级数字孪生：

改造为楼层热力图 + 实时覆盖层：
- 楼层平面图（仍用 SVG，但按 zone 分区着色）
- 颜色映射：zone 温度 → 色温（蓝=冷, 绿=舒适, 红=热）
- 接入模拟器实时数据，每 5 秒刷新着色
交互增强：
- 点击 zone → 弹出详情面板（当前温度、设定值、设备状态、活跃策略）
- 在详情面板中可直接发起控制指令（通过 ControlPipeline）
- 设备故障的 zone 标记特殊图标（闪烁警告）
图层切换：
- 温度层（默认）
- 能耗密度层（kW/m²）
- 舒适度层（PMV 指数）
- 设备状态层（正常/告警/故障）

验收标准：

进入 Building3D → 看到按 zone 着色的楼层图 → 颜色随模拟器温度变化实时更新
点击某 zone → 看到详情 → 发起“降温”指令 → ControlPipeline 推进 → zone 颜色逐渐变蓝

P3-4 CCER 碳申报增强（3-4h）

当前 CCER.tsx 为简单列表。增强为完整的碳申报流程：

新增数据模型：ccer_projects 表 (building_id, methodology, baseline_year, monitoring_period, status enum)
流程实现：
- 项目注册（填写方法学、基准年、监测期）
- 自动计算减排量（从 MVCenter 的节能数据换算：kWh × 排放因子 = tCO2e）
- 生成申报文件（PDF 格式，含计算过程和证据链）
- 状态管理（草稿→提交→核查→签发）
改造 CCER.tsx：
- 项目创建向导
- 减排量仪表盘（按月/季/年）
- 申报状态跟踪
- PDF 报告生成按钮

验收标准：

创建 CCER 项目 → 选择方法学和基准年 → 系统从 MVCenter 拉取节能数据 → 计算减排量 → 可生成 PDF

P3-5 多能协同基础（4-6h）

为未来的光伏/储能/充电桩协同打下基础：

数据模型：新建 energy_assets 表 (building_id, asset_type enum[pv/battery/ev_charger], capacity, status)
简化模拟器扩展：
- 光伏：基于时刻+天气的发电曲线
- 储能：充放电状态 + SOC (State of Charge)
- 充电桩：负荷曲线
新建 MultiEnergy.tsx 页面：
- 能源流向桑基图（电网→建筑、光伏→建筑、储能⇄建筑）
- 各资产实时状态面板
- 简单的调度策略（峰时放电、谷时充电）
注册路由 /multi-energy 并加入 Layout 导航

验收标准：

MultiEnergy 页面展示能源流向图 → 光伏在白天有发电 → 储能在峰时放电 → 电网购电减少
数据与模拟器时钟联动

工作流程

严格按 P3-1 到 P3-5 顺序执行，每完成一个汇报
每步结束后编译验证：npx tsc --noEmit --skipLibCheck + go build ./cmd/
P3-1（边缘）和 P3-2（仿真）与阶段 3 的模拟器共享代码，注意复用 internal/simulator/ 而非重复实现
如果时间不够，P3-4 和 P3-5 可以只做数据模型 + 基础页面，不需要完整流程

---

## 第四轮工作：工程质量强化（测试 + 分页）

> 使用时机：P0-P3 功能全部落地后，补齐工程质量短板。

---

### 阶段 5/6：单元测试覆盖（预估 6-10h）

单元测试覆盖

当前系统零测试覆盖（0 个 *_test.go 文件）。安全引擎和控制 pipeline 是系统最关键的业务逻辑，必须有测试保障。

优先级排序

按“出错后果严重性”排序，先测最危险的模块：

5.1 安全引擎测试（最高优先级）

新建 services/api-gateway/internal/safety/engine_test.go（如果 safety 包在 cmd 下则建 cmd/safety_engine_test.go）

每个 Checker 至少 3 个测试用例：

WhitelistChecker
- 白名单内点位 → 通过
- 白名单外点位 → 拦截，violation 包含点位 ID
- 空白名单 → 全部拦截（安全保守原则）
RateLimiter
- 第 1 条指令 → 通过
- 连续 5 条（超过阈值）→ 第 5 条被拦截
- 超过时间窗口后（模拟时间推进）→ 计数重置，新指令通过
MinIntervalChecker
- 首次操作 → 通过
- 间隔不足（如 2min 内再次操作）→ 拦截
- 超过最小间隔后 → 通过
ConfidenceGate
- confidence=0.8 → 通过
- confidence=0.5 → 拦截
- confidence=0.7（边界值）→ 通过（>=0.7 通过）
RangeLimiter
- 设定值在范围内 → 通过
- 设定值超上限 → 拦截，报告超出量
- 设定值低于下限 → 拦截
EStopChecker
- E-Stop 未激活 → 通过
- E-Stop 已激活 → 所有指令拦截
- 激活后解除 → 恢复通过
ZoneLock
- 区域未锁定 → 通过
- 区域已锁定 → 拦截
- 锁定过期（expires_at < now）→ 通过
SafetyEngine.Check() 集成测试
- 全部 checker 通过 → 返回 Passed=true
- 任意一个 checker 拦截 → 返回 Passed=false + Violations 包含该 checker 信息
- 多个 checker 同时拦截 → Violations 包含所有违规项

5.2 控制权限测试

新建 cmd/control_permission_test.go

lookupPermissionLevelDB
- national_operator 对任意点位 → R5
- building_operator 对 L3 操作 → R2（权限不足）
- enterprise_admin 对 L2 操作 → R3（需确认）
enforceControlPermission 中间件
- 权限足够 → 不返回 403，正常 next
- 权限不足 → 返回 403 + JSON body 含 required_level/current_level
- 无认证 → 返回 401

5.3 控制 Pipeline 测试

新建 cmd/control_engine_test.go

dispatchDecision
- L1 建议型决策 → 直接记录，不下发指令
- L2 辅助控制 → 进入 pending_approval 状态
- L3 自动控制 + safety check 通过 → 直接执行
newCommand 状态机
- 创建 → status=dispatched
- 确认 → status=ack
- 验证 → status=verified
安全引擎集成
- safety check 拦截 → 指令不执行，记录违规
- safety check 通过 → 指令正常执行

5.4 模拟器测试

新建 internal/simulator/engine_test.go

温度模型
- 空调开启 → 温度逐步降低
- 空调关闭 + 高外温 → 温度逐步升高
- 设定值变更 → 温度向新设定值收敛
能源资产
- 白天 → PV 发电 > 0
- 夜间 → PV 发电 = 0
- 峰时 → 电池放电（SOC 下降）
- 谷时 → 电池充电（SOC 上升）
场景切换
- normal → heat_wave → 外温升高 + 功率增加
- normal → device_failure → 设备状态变为 fault

5.5 Agent Schema 校验测试

新建 cmd/agent_schema_test.go

validateInputSchema
- 符合 schema → 返回 nil
- 缺少 required 字段 → 返回错误，包含缺失字段名
- type 不匹配（期望 number 给 string）→ 返回错误
- minimum/maximum 越界 → 返回错误

测试基础设施

使用标准库 testing 包，不引入第三方测试框架
对于需要数据库的测试，使用 mock 数据或内存 map 模拟（不需要真实 PG 连接）
测试文件命名遵循 Go 约定：xxx_test.go，包名与被测代码一致
每个测试函数使用 Table-Driven 风格（[]struct{ name string; ... }）

验收标准

go test ./... 全部通过（0 failures）
安全引擎测试 ≥ 24 个用例（8 checker × 3 cases）
控制权限测试 ≥ 6 个用例
控制 pipeline 测试 ≥ 6 个用例
模拟器测试 ≥ 9 个用例
Agent schema 测试 ≥ 4 个用例
总计 ≥ 49 个测试用例
运行 go test ./... -count=1 -v 输出全部 PASS

---

### 阶段 6/6：全量分页补齐（预估 4-6h）

全量分页补齐

当前仅 9/56 页面实现了分页（16% 覆盖率）。所有包含列表的页面都需要支持后端分页。

分页标准规范

后端规范

所有列表 API 统一支持以下 query 参数：

page (int, default 1) — 页码
page_size (int, default 20, max 100) — 每页条数
sort_by (string, optional) — 排序字段
sort_order (string, “asc”/“desc”, default “desc”) — 排序方向

响应格式统一为：

{
  "items": [...],
  "total": 156,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

前端规范

创建通用分页组件（如果尚未存在）：components/Pagination.tsx

显示：第 X-Y 条 / 共 Z 条
翻页按钮：首页、上一页、页码列表、下一页、末页
每页条数选择器：10/20/50/100
与 URL query 参数同步（刷新页面保留分页状态）

需要补齐分页的页面清单

按模块分组，标注每个页面的列表数据源：

运行监控模块

页面	列表 API	当前状态
Alarms.tsx	/alarms	✅ 已有分页
Commands.tsx	/commands	需补齐
WorkOrders.tsx	/workorders	✅ 已有分页
Equipment.tsx	/equipment	需补齐
Telemetry.tsx	/telemetry/points	非列表页(图表),跳过

AI 控制模块

页面	列表 API	当前状态
Decisions.tsx	/decisions	需补齐
Strategies.tsx	/strategies	需补齐
AgentRegistry.tsx	/agents	需补齐
SkillLibrary.tsx	/agents/skills	需补齐
AuditLog.tsx	/audit	需补齐

运维管理模块

页面	列表 API	当前状态
Buildings.tsx	/buildings	需补齐
Zones.tsx	/zones	需补齐
EdgeNodes.tsx	/edge	需补齐
Sessions.tsx	/sessions	需补齐
LLMLog.tsx	/llm-log	需补齐
ProtocolLog.tsx	/protocol-log	需补齐

经营验证模块

页面	列表 API	当前状态
Reports.tsx	/reports	需补齐
Billing.tsx	/bills	需补齐
CCER.tsx	/ccer/projects	需补齐

系统管理模块

页面	列表 API	当前状态
Accounts.tsx	/accounts	需补齐
SubAgents.tsx	/sub-agents	需补齐

HVAC/设备健康子 Tab

页面	说明	当前状态
HvacOptimization.tsx 各 Tab	子列表（历史记录等）	需补齐
EquipmentHealth.tsx 各 Tab	设备列表	需补齐
MVCenter.tsx 各 Tab	记录列表	需补齐

实施策略

先建后端通用分页工具函数 paginateSlice(items, page, pageSize) → (pagedItems, total, totalPages)
- 由于当前数据来自内存（seed/simulator），用 slice 分页即可
- 函数放在 cmd/pagination.go
再建前端通用分页组件 Pagination.tsx
- 接收 props: page, pageSize, total, onPageChange, onPageSizeChange
- Tailwind 样式，与现有 UI 风格一致
逐个页面改造（每改一个前后端编译验证一次）：
- 后端 handler：对返回结果调用 paginateSlice，新增 total/page/total_pages 字段
- 前端页面：引入 Pagination 组件，管理 page/pageSize 状态，请求时传参
排序支持：对核心列表（Alarms、Commands、Decisions、AuditLog）额外实现 sort_by + sort_order

验收标准

通用分页组件 Pagination.tsx 存在且被 15+ 页面引用
所有列表 API 响应包含 total、page、total_pages 字段
前端分页组件正确显示页码和总数
切换页码 → 列表内容正确更新
每页条数切换 → 重新加载正确数量
npx tsc --noEmit --skipLibCheck ✅
go build ./cmd/ ✅
go test ./... ✅（不破坏已有测试）

工作流程

先完成后端 pagination.go + 前端 Pagination.tsx 基础设施
然后批量改造：先改 5 个高频页面（Alarms/Commands/Decisions/AuditLog/Equipment），验证模式正确
再批量改造剩余 15+ 页面
最后统一编译验证