feat(#51): 图表组件配置化渲染引擎（CockpitLayout→RenderPlan，PRD 5.5 配置化驾驶舱渲染层适配器）
在 #50 布局 JSON Schema 之上实现渲染层适配器，把 CockpitLayout 编译为与前端框架无关的 RenderPlan： - 新增 core/cockpit/renderer.py：RenderPlan/WidgetRendererSpec/GridPlacement 渲染描述符，栅格整数坐标→CSS Grid 定位+百分比换算，widget type→前端组件映射（ProcessView/TrendChart/KpiCard/AlarmPanel/NlQuery）+ props 组装（四状态/趋势窗口/KPI标签兜底/告警订阅/NL占位），dark/light 两套主题 CSS 变量注入，组件数≥30 触发全局+逐组件性能策略（虚拟滚动/采样降频/WebWorker，PRD 5.5），render_layout 复用 #50 校验器防篡改。 - plan_to_dict/plan_to_json 序列化：切换行业模板=换 RenderPlan，前端组件注册表固定即可「切换模板零改码」。 - 28 个单元测试全通过 + verify_renderer.py sanity check 通过（氯化车间示例 + 树脂模板兼容 + 主题切换 + 序列化往返）。全 cockpit 模块 58 测试无回归。
This commit is contained in:
@@ -0,0 +1,373 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""图表组件配置化渲染引擎（issue #51 / PRD 5.5「⑤ 配置化驾驶舱」）。
|
||||
|
||||
本模块在 ``layout.py``（#50 布局 JSON Schema）之上实现**渲染层适配器**：
|
||||
把一份 ``CockpitLayout`` 内存模型，编译成一份与前端框架无关的**渲染计划
|
||||
（``RenderPlan``）**——每个 widget 被翻译成一个 ``WidgetRendererSpec``，
|
||||
描述它该用哪个前端组件、摆在栅格的哪个位置、绑定什么数据、套用哪套主题
|
||||
token、是否启用性能优化策略。
|
||||
|
||||
设计目标（PRD 5.5 验收口径「切换模板零改码」）：
|
||||
前端只需一个固定的「组件注册表」+ 一个通用 ``<WidgetHost>``，
|
||||
按 ``RenderPlan`` 逐个挂载组件；切换行业模板 = 换一份 ``RenderPlan``，
|
||||
**前端代码零改动**。
|
||||
|
||||
本模块不依赖任何第三方库（与 #50 一致，避免引入运行时依赖），只消费
|
||||
``cockpit.layout`` 的内存模型，输出可 ``json.dumps`` 的纯数据结构。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Dict, List, Optional, Tuple
|
||||
|
||||
from .layout import ( # 复用 #50 已定义的布局模型与常量
|
||||
DEFAULT_GRID_COLUMNS,
|
||||
LAYOUT_SCHEMA_ID,
|
||||
PERF_WIDGET_THRESHOLD,
|
||||
VALID_THEMES,
|
||||
VALID_WIDGET_TYPES,
|
||||
CockpitLayout,
|
||||
Grid,
|
||||
Widget,
|
||||
validate_layout,
|
||||
)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 主题 token（PRD 5.5「配置点：主题」dark / light 两套调色）
|
||||
# ---------------------------------------------------------------------------
|
||||
# 工业驾驶舱约定配色：dark 偏深蓝底 + 青绿强调（车间大屏常用）；
|
||||
# light 偏白底 + 蓝色强调（白天值班室）。前端按这些 CSS 变量渲染，
|
||||
# 切换主题 = 切一套变量，组件代码不动。
|
||||
THEME_TOKENS: Dict[str, Dict[str, str]] = {
|
||||
"dark": {
|
||||
"--cockpit-bg": "#0b1220",
|
||||
"--cockpit-surface": "#13203a",
|
||||
"--cockpit-fg": "#e6edf6",
|
||||
"--cockpit-fg-muted": "#8aa0bd",
|
||||
"--cockpit-accent": "#18d3c8", # 青绿（KPI / 趋势主线）
|
||||
"--cockpit-warn": "#f5a623", # 告警强调
|
||||
"--cockpit-grid-line": "rgba(255,255,255,0.06)",
|
||||
},
|
||||
"light": {
|
||||
"--cockpit-bg": "#f5f7fb",
|
||||
"--cockpit-surface": "#ffffff",
|
||||
"--cockpit-fg": "#1f2d3d",
|
||||
"--cockpit-fg-muted": "#6b7c93",
|
||||
"--cockpit-accent": "#2f7af2", # 蓝
|
||||
"--cockpit-warn": "#e08600",
|
||||
"--cockpit-grid-line": "rgba(0,0,0,0.06)",
|
||||
},
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# widget type → 前端组件名映射（PRD 5.5 能力清单）
|
||||
# ---------------------------------------------------------------------------
|
||||
# 前端「组件注册表」的键；``<WidgetHost>`` 据此选择具体组件实现。
|
||||
# 命名遵循 Vue3 大驼峰组件约定，便于 ``app.component()`` 注册。
|
||||
WIDGET_COMPONENT: Dict[str, str] = {
|
||||
"process_view": "ProcessView", # 四状态工艺流程视图（SVG 资源）
|
||||
"trend": "TrendChart", # 实时趋势曲线
|
||||
"kpi_card": "KpiCard", # KPI 卡片
|
||||
"alarm_panel": "AlarmPanel", # 告警面板
|
||||
"nl_query": "NlQuery", # 自然语言查询入口
|
||||
}
|
||||
|
||||
# 各组件类型向渲染描述里注入的「绑定字段」：来自布局 widget 的哪个属性。
|
||||
# 例如 trend 组件的 series 绑定 = widget.bind（点位/指标 ID）。
|
||||
_WIDGET_BINDING_SOURCE: Dict[str, Tuple[str, ...]] = {
|
||||
"process_view": ("src",), # 流程图资源
|
||||
"trend": ("bind",), # 趋势点位/指标
|
||||
"kpi_card": ("metric", "label"), # 指标键 + 展示标签
|
||||
"alarm_panel": (), # 无特有绑定，订阅告警流即可
|
||||
"nl_query": (), # 无特有绑定，固定入口
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 异常
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class RenderError(ValueError):
|
||||
"""渲染计划生成失败。``render_layout`` 在布局非法或组件缺失时抛出。"""
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 渲染描述符（dataclass）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass
|
||||
class GridPlacement:
|
||||
"""单个 widget 在 CSS Grid 中的定位（``grid-column/grid-row`` 语法）。
|
||||
|
||||
PRD 5.5 栅格基线默认 12 列；这里把布局资产里的整数坐标 (x,y,w,h)
|
||||
换算成 CSS Grid 的 ``column-start / span`` / ``row-start / span``，
|
||||
以及占比百分比（便于非 Grid 容器/截图场景使用）。
|
||||
|
||||
约定（与 #50 schema 一致）：x/y/w/h 为栅格单位，x≥0、y≥0、w>0、h>0。
|
||||
"""
|
||||
|
||||
column_start: int # CSS Grid 列起点的 1-based 编号（= x + 1）
|
||||
column_span: int # 跨列数（= w）
|
||||
row_start: int # CSS Grid 行起点的 1-based 编号（= y + 1）
|
||||
row_span: int # 跨行数（= h）
|
||||
width_pct: float # 占栅格总宽的百分比（= w / columns * 100，保留 4 位）
|
||||
style: str # 直接可用的 ``grid-column/grid-row`` CSS 文本
|
||||
|
||||
def to_dict(self) -> Dict[str, Any]:
|
||||
return {
|
||||
"columnStart": self.column_start,
|
||||
"columnSpan": self.column_span,
|
||||
"rowStart": self.row_start,
|
||||
"rowSpan": self.row_span,
|
||||
"widthPct": self.width_pct,
|
||||
"style": self.style,
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class WidgetRendererSpec:
|
||||
"""单个驾驶舱组件的渲染描述符（``<WidgetHost>`` 的单一挂载项）。
|
||||
|
||||
前端渲染约定::
|
||||
|
||||
<component :is="registry[spec.component]" v-bind="spec.props"
|
||||
:style="spec.grid.style" :perf="spec.perf" />
|
||||
"""
|
||||
|
||||
id: str # 渲染层唯一标识（type + 序号），便于 diff / 虚拟滚动 key
|
||||
component: str # 前端组件名（见 ``WIDGET_COMPONENT``）
|
||||
type: str # 原始 widget type（调试/审计用）
|
||||
grid: GridPlacement
|
||||
description: Optional[str] = None
|
||||
# 前端组件 props（绑定字段 + 展示参数），按组件类型组装
|
||||
props: Dict[str, Any] = field(default_factory=dict)
|
||||
# 性能策略：是否对该组件启用虚拟滚动/采样降频/WebWorker（仅 perf 触发时 True）
|
||||
perf: Dict[str, bool] = field(default_factory=lambda: {
|
||||
"virtualScroll": False,
|
||||
"downsample": False,
|
||||
"worker": False,
|
||||
})
|
||||
|
||||
def to_dict(self) -> Dict[str, Any]:
|
||||
return {
|
||||
"id": self.id,
|
||||
"component": self.component,
|
||||
"type": self.type,
|
||||
"grid": self.grid.to_dict(),
|
||||
"description": self.description,
|
||||
"props": dict(self.props),
|
||||
"perf": dict(self.perf),
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class RenderPlan:
|
||||
"""整份驾驶舱布局的渲染计划（``<WidgetHost>`` 的总输入）。
|
||||
|
||||
前端拿到本对象即可完成整屏渲染：``themeTokens`` 注入到根容器 CSS 变量，
|
||||
``specs`` 逐项挂载组件，``perfFlags`` 控制全局性能策略开关。
|
||||
"""
|
||||
|
||||
schema: str # 继承自布局资产的 $schema（审计/版本对齐）
|
||||
title: str
|
||||
theme: str
|
||||
theme_tokens: Dict[str, str] # 该主题下的 CSS 变量（来自 ``THEME_TOKENS``）
|
||||
grid_columns: int # 栅格基线（用于前端百分比校验）
|
||||
specs: List[WidgetRendererSpec]
|
||||
widget_count: int
|
||||
# 全局性能标志：组件数 ≥ PERF_WIDGET_THRESHOLD 时为 True（PRD 5.5 复杂仪表盘性能）
|
||||
perf_flags: Dict[str, bool] = field(default_factory=lambda: {
|
||||
"virtualScroll": False,
|
||||
"downsample": False,
|
||||
"worker": False,
|
||||
})
|
||||
perf_hint: Optional[str] = None # 来自 #50 布局校验的人类可读提示（透传）
|
||||
|
||||
def to_dict(self) -> Dict[str, Any]:
|
||||
return {
|
||||
"$schema": self.schema,
|
||||
"title": self.title,
|
||||
"theme": self.theme,
|
||||
"themeTokens": dict(self.theme_tokens),
|
||||
"grid": {"columns": self.grid_columns},
|
||||
"widgets": [s.to_dict() for s in self.specs],
|
||||
"widgetCount": self.widget_count,
|
||||
"perfFlags": dict(self.perf_flags),
|
||||
"perfHint": self.perf_hint,
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 栅格换算
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def compute_grid_placement(widget: Widget, grid_columns: int) -> GridPlacement:
|
||||
"""把布局资产里的栅格整数坐标换算成 CSS Grid 定位 + 占比百分比。
|
||||
|
||||
- CSS Grid 的列/行起点是 1-based，布局资产里的 x/y 是 0-based，
|
||||
因此 ``column_start = x + 1``、``row_start = y + 1``。
|
||||
- 跨度直接等于 w/h（栅格单位）。
|
||||
- 宽度百分比 = w / grid_columns * 100（便于非 Grid 容器降级）。
|
||||
"""
|
||||
if grid_columns <= 0:
|
||||
raise RenderError(f"栅格列数必须 > 0，实际 {grid_columns}")
|
||||
column_start = widget.x + 1
|
||||
row_start = widget.y + 1
|
||||
width_pct = round(widget.w / grid_columns * 100, 4)
|
||||
style = (
|
||||
f"grid-column: {column_start} / span {widget.w}; "
|
||||
f"grid-row: {row_start} / span {widget.h};"
|
||||
)
|
||||
return GridPlacement(
|
||||
column_start=column_start,
|
||||
column_span=widget.w,
|
||||
row_start=row_start,
|
||||
row_span=widget.h,
|
||||
width_pct=width_pct,
|
||||
style=style,
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 组件 props 组装
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _build_props(widget: Widget) -> Dict[str, Any]:
|
||||
"""按 widget type 组装前端组件 props（绑定字段 + 展示参数）。
|
||||
|
||||
绑定字段来源见 ``_WIDGET_BINDING_SOURCE``；缺字段视为该组件不依赖它
|
||||
（布局层 #50 已对必填字段做过校验，这里做防御性容错）。
|
||||
"""
|
||||
props: Dict[str, Any] = {}
|
||||
|
||||
if widget.type == "process_view":
|
||||
# 流程图视图：资源名 + 四状态语义（前端按 SVG 内联渲染 + 状态着色）
|
||||
props["src"] = widget.src or ""
|
||||
props["states"] = ["running", "warning", "alarm", "offline"] # PRD 四状态
|
||||
elif widget.type == "trend":
|
||||
# 实时趋势：绑定点位/指标 ID，前端订阅时序总线
|
||||
props["series"] = widget.bind or ""
|
||||
props["window"] = "PT30M" # 默认 30 分钟滚动窗口（可由模板覆盖）
|
||||
elif widget.type == "kpi_card":
|
||||
# KPI 卡片：指标键 + 标签
|
||||
props["metric"] = widget.metric or ""
|
||||
props["label"] = widget.label or widget.metric or ""
|
||||
elif widget.type == "alarm_panel":
|
||||
# 告警面板：固定订阅告警流，无特有绑定
|
||||
props["subscribe"] = "alarm_stream"
|
||||
elif widget.type == "nl_query":
|
||||
# NL 查询入口：固定能力，无特有绑定
|
||||
props["placeholder"] = "输入自然语言查询（配方 / 质量 / 能耗）"
|
||||
|
||||
return props
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 渲染入口
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def render_widget(
|
||||
widget: Widget,
|
||||
index: int,
|
||||
grid_columns: int,
|
||||
perf_enabled: bool = False,
|
||||
) -> WidgetRendererSpec:
|
||||
"""渲染单个 widget 为 ``WidgetRendererSpec``。
|
||||
|
||||
- ``index`` 用于生成稳定 id（type + 序号），作为虚拟滚动 key。
|
||||
- ``perf_enabled`` 为 True（全局性能策略开启）时，trend/alarm_panel 这类
|
||||
高频刷新组件启用采样降频 + WebWorker（PRD 5.5）。
|
||||
"""
|
||||
if widget.type not in WIDGET_COMPONENT:
|
||||
# 布局层 #50 已挡住非法 type，这里再防御一次，避免渲染出未注册组件
|
||||
raise RenderError(
|
||||
f"widget[{index}] type='{widget.type}' 无对应前端组件，"
|
||||
f"已注册 {list(WIDGET_COMPONENT)}"
|
||||
)
|
||||
|
||||
spec = WidgetRendererSpec(
|
||||
id=f"{widget.type}-{index}",
|
||||
component=WIDGET_COMPONENT[widget.type],
|
||||
type=widget.type,
|
||||
grid=compute_grid_placement(widget, grid_columns),
|
||||
description=widget.description,
|
||||
props=_build_props(widget),
|
||||
)
|
||||
|
||||
if perf_enabled:
|
||||
# 高频刷新组件才需要逐组件性能策略：趋势曲线 / 告警面板
|
||||
if widget.type in ("trend", "alarm_panel"):
|
||||
spec.perf["downsample"] = True
|
||||
spec.perf["worker"] = True
|
||||
# 大流程图（process_view）启用虚拟滚动分块
|
||||
if widget.type == "process_view":
|
||||
spec.perf["virtualScroll"] = True
|
||||
|
||||
return spec
|
||||
|
||||
|
||||
def render_layout(layout: CockpitLayout) -> RenderPlan:
|
||||
"""把一份合法 ``CockpitLayout`` 编译为 ``RenderPlan``。
|
||||
|
||||
先复用 #50 的 ``validate_layout`` 再校验一次（防御构造后被篡改），
|
||||
再逐 widget 渲染，最后汇总主题 token 与全局性能标志。
|
||||
|
||||
校验失败抛 ``RenderError``（包装 #50 的错误清单），便于配置台定位。
|
||||
"""
|
||||
# 1) 复用 #50 校验器，确保布局恒为合法资产
|
||||
result = validate_layout(layout.to_dict())
|
||||
if not result.ok:
|
||||
raise RenderError(result.errors)
|
||||
|
||||
# 2) 主题 token
|
||||
if layout.theme not in THEME_TOKENS:
|
||||
raise RenderError(
|
||||
f"theme='{layout.theme}' 无调色方案，已支持 {list(THEME_TOKENS)}"
|
||||
)
|
||||
theme_tokens = dict(THEME_TOKENS[layout.theme])
|
||||
|
||||
# 3) 全局性能标志（PRD 5.5：组件数 ≥ 阈值 → 虚拟滚动 + 采样降频 + WebWorker）
|
||||
perf_on = result.widget_count >= PERF_WIDGET_THRESHOLD
|
||||
perf_flags = {
|
||||
"virtualScroll": perf_on,
|
||||
"downsample": perf_on,
|
||||
"worker": perf_on,
|
||||
}
|
||||
|
||||
# 4) 逐 widget 渲染
|
||||
specs: List[WidgetRendererSpec] = [
|
||||
render_widget(w, idx, layout.grid.columns, perf_enabled=perf_on)
|
||||
for idx, w in enumerate(layout.widgets)
|
||||
]
|
||||
|
||||
return RenderPlan(
|
||||
schema=layout.schema,
|
||||
title=layout.title,
|
||||
theme=layout.theme,
|
||||
theme_tokens=theme_tokens,
|
||||
grid_columns=layout.grid.columns,
|
||||
specs=specs,
|
||||
widget_count=len(specs),
|
||||
perf_flags=perf_flags,
|
||||
perf_hint=result.perf_hint,
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 序列化
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def plan_to_dict(plan: RenderPlan) -> Dict[str, Any]:
|
||||
"""渲染计划 → 可发布的 dict（前端直接消费 / 落盘缓存）。"""
|
||||
return plan.to_dict()
|
||||
|
||||
|
||||
def plan_to_json(plan: RenderPlan, indent: Optional[int] = 2) -> str:
|
||||
"""渲染计划 → JSON 字符串（确保 ASCII 安全，中文转义不影响前端解析）。"""
|
||||
return json.dumps(plan.to_dict(), ensure_ascii=False, indent=indent)
|
||||
Reference in New Issue
Block a user