628 lines
18 KiB
Markdown
628 lines
18 KiB
Markdown
# 广寒基地拓扑图表现层数据库化设计
|
||
|
||
日期：2026-07-09
|
||
状态：待用户审核
|
||
范围：广寒基地工程总图的视觉表现层数据设计，不包含本轮代码实现
|
||
|
||
## 1. 背景
|
||
|
||
当前 `guanghan_topology_demo.html` 已经从后端快照读取大部分拓扑数据：
|
||
|
||
- 任务与时间点决定快照时间；
|
||
- 组件、端口、连接、状态来自 PostgreSQL；
|
||
- SVG 节点坐标、尺寸、分组、标签覆盖、显示提示和散热器标记来自 `diagram_layouts`、`diagram_nodes`、`diagram_node_members`；
|
||
- 页面会按快照隐藏尚未出现的组件和连接。
|
||
|
||
但页面仍然保留了一部分视觉语义：
|
||
|
||
- `core-card`、`power-card`、`vehicle-card` 等样式键对应什么颜色，由前端 CSS 决定；
|
||
- `structural_mount`、`pressurized_passage`、`fuel`、`power` 等连接类型如何映射成线条颜色、线宽、虚实线，由前端 JS/CSS 决定；
|
||
- 图例项由 HTML 硬编码；
|
||
- 散热器虽然由数据库标记是否显示，但具体形状、颜色、标签仍由前端决定。
|
||
|
||
因此当前状态是“半数据库驱动”。本设计把它推进到 B1 级别：数据库决定工程图的主要视觉语义，前端只保留通用渲染和交互壳。
|
||
|
||
## 2. 目标
|
||
|
||
本设计的目标是让后端数据库决定以下内容：
|
||
|
||
1. 节点矩形的位置、尺寸、圆角、填充色、描边色、描边宽度。
|
||
2. 连接线的颜色、线宽、虚实线、图例文案。
|
||
3. 装饰件的基础视觉参数，例如散热器的颜色、描边、标签。
|
||
4. 工程图图例的项目、顺序、显示名称和示例样式。
|
||
5. 节点 `style_key`、连接 `connection_type`、装饰件 `decoration_key` 到具体视觉参数的映射。
|
||
|
||
验收时应能做到：
|
||
|
||
- 修改数据库中 `pressurized_passage` 的颜色后，页面加压走道颜色随之变化，不需要改 HTML/CSS；
|
||
- 修改数据库中 `core-card` 的填充/描边后，核心舱视觉随之变化；
|
||
- 图例完全由 API 返回，不再在页面硬编码；
|
||
- GHC-01 到 GHC-05 的历史快照仍按数据库事实正确显示；
|
||
- 当前已确认的空间结构不变。
|
||
|
||
## 3. 非目标
|
||
|
||
B1 方案不把整个页面变成数据库控制的 UI 系统。以下内容仍属于前端通用壳：
|
||
|
||
- 页面字体族、整体背景、工具栏、弹窗、按钮、hover/focus 效果；
|
||
- 文本截断算法、SVG 元素创建方式、键盘可访问性；
|
||
- 响应式断点和滚动容器；
|
||
- 模块详情弹窗的排版；
|
||
- 业务时态表的结构重写；
|
||
- 数据库直接存储完整 SVG 或 HTML。
|
||
|
||
这条边界很重要：数据库掌握“工程图是什么样”，前端掌握“页面如何交互”。
|
||
|
||
## 4. 设计原则
|
||
|
||
### 4.1 表现层不是业务事实
|
||
|
||
组件、任务、连接、状态仍然是业务事实。布局和样式是对这些事实的可视化表达。
|
||
|
||
因此：
|
||
|
||
- 快照时间继续只决定哪些组件、连接、状态存在；
|
||
- 默认情况下，视觉主题不随历史时间变化；
|
||
- 早期任务快照可以使用同一张当前工程总图布局，只隐藏当时尚不存在的组件。
|
||
|
||
这能保持不同时刻的空间比较稳定，避免 GHC-01、GHC-03、GHC-05 每次切换都“重排整张图”。
|
||
|
||
### 4.2 数据库保存语义映射，不保存前端实现
|
||
|
||
数据库可以保存：
|
||
|
||
- `stroke_color = '#51e89c'`
|
||
- `stroke_width = 9`
|
||
- `dash_array = null`
|
||
- `legend_label = '加压走道'`
|
||
|
||
数据库不保存：
|
||
|
||
- CSS 选择器；
|
||
- JavaScript 函数名；
|
||
- HTML 片段；
|
||
- 浏览器专用的布局技巧。
|
||
|
||
### 4.3 可迁移、可扩展、可回退
|
||
|
||
新增表现层表应与现有 `diagram_layouts` 兼容。实现时可以分阶段上线：
|
||
|
||
1. 先建表并 seed 当前样式；
|
||
2. API 同时返回旧字段和新 `presentation`；
|
||
3. 前端切换到新字段；
|
||
4. 测试通过后，保留旧 CSS 类作为安全兜底，但不再作为事实来源。
|
||
|
||
## 5. 数据模型
|
||
|
||
### 5.1 `diagram_themes`
|
||
|
||
主题表表示一套工程图视觉风格。广寒基地初期只需要一个主题。
|
||
|
||
建议字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | `uuid` | 主键 |
|
||
| `base_id` | `uuid` | 所属基地 |
|
||
| `theme_key` | `text` | 例如 `guanghan_dark_engineering_v1` |
|
||
| `name` | `text` | 显示名称 |
|
||
| `description` | `text` | 可空 |
|
||
| `tokens` | `jsonb` | 少量通用色值，例如文字色、弱文字色；不放完整 CSS |
|
||
| `is_default` | `boolean` | 是否默认主题 |
|
||
| `created_at` / `updated_at` | `timestamptz` | 审计字段 |
|
||
|
||
约束：
|
||
|
||
```sql
|
||
UNIQUE (base_id, theme_key)
|
||
```
|
||
|
||
`tokens` 示例：
|
||
|
||
```json
|
||
{
|
||
"textColor": "#eaf2ff",
|
||
"mutedTextColor": "#91a3bd",
|
||
"labelColor": "#f4df7b"
|
||
}
|
||
```
|
||
|
||
### 5.2 `diagram_node_styles`
|
||
|
||
节点样式表把现有 `diagram_nodes.style_key` 从“前端 CSS 类名”变成“数据库样式键”。
|
||
|
||
建议字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | `uuid` | 主键 |
|
||
| `theme_id` | `uuid` | 所属主题 |
|
||
| `style_key` | `text` | 例如 `core-card`、`power-card` |
|
||
| `display_name` | `text` | 管理用途 |
|
||
| `fill_color` | `text` | SVG 填充色 |
|
||
| `stroke_color` | `text` | SVG 描边色 |
|
||
| `stroke_width` | `numeric` | SVG 描边宽度 |
|
||
| `corner_radius` | `numeric` | 矩形圆角 |
|
||
| `title_color` | `text` | 可空，默认使用主题文字色 |
|
||
| `meta_color` | `text` | 可空 |
|
||
| `hint_color` | `text` | 可空 |
|
||
| `created_at` / `updated_at` | `timestamptz` | 审计字段 |
|
||
|
||
约束：
|
||
|
||
```sql
|
||
UNIQUE (theme_id, style_key)
|
||
```
|
||
|
||
现有样式键继续保留：
|
||
|
||
- `node-card`
|
||
- `core-card`
|
||
- `power-card`
|
||
- `power-node-card`
|
||
- `vehicle-card`
|
||
|
||
这样数据迁移最小，页面也容易渐进切换。
|
||
|
||
### 5.3 `diagram_edge_styles`
|
||
|
||
连接样式表按业务连接类型定义线条表现。
|
||
|
||
建议字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | `uuid` | 主键 |
|
||
| `theme_id` | `uuid` | 所属主题 |
|
||
| `connection_type` | `text` | 对应 `topology_connections.connection_type` |
|
||
| `display_name` | `text` | 例如 `加压走道` |
|
||
| `stroke_color` | `text` | 线条颜色 |
|
||
| `stroke_width` | `numeric` | 线宽 |
|
||
| `dash_array` | `text` | 可空，例如 `13 10` |
|
||
| `line_cap` | `text` | 例如 `square` |
|
||
| `legend_group` | `text` | 可空，用于多个连接类型共用一个图例 |
|
||
| `legend_order` | `integer` | 图例排序辅助 |
|
||
| `created_at` / `updated_at` | `timestamptz` | 审计字段 |
|
||
|
||
约束：
|
||
|
||
```sql
|
||
UNIQUE (theme_id, connection_type)
|
||
```
|
||
|
||
当前建议映射：
|
||
|
||
| `connection_type` | 默认图例 | 默认表现 |
|
||
|---|---|---|
|
||
| `structural_mount` | 结构直连 | 灰蓝色实线 |
|
||
| `pressurized_passage` | 加压走道 | 绿色实线 |
|
||
| `fuel` | 燃料 / 供电 | 紫色虚线 |
|
||
| `power` | 燃料 / 供电 | 紫色虚线 |
|
||
| `cooling` | 冷却 | 预留，可暂不显示图例 |
|
||
| `docking` | 对接口 | 预留 |
|
||
|
||
如果 `fuel` 和 `power` 继续共用图例，可以让两条记录使用同一个 `legend_group = 'utility'`。
|
||
|
||
### 5.4 `diagram_decoration_styles`
|
||
|
||
装饰件样式表定义散热器等非组件元素的表现。装饰件是否出现仍由 `diagram_nodes.decorations` 决定。
|
||
|
||
建议字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | `uuid` | 主键 |
|
||
| `theme_id` | `uuid` | 所属主题 |
|
||
| `decoration_key` | `text` | 例如 `radiator` |
|
||
| `display_name` | `text` | 例如 `大型折叠散热面板` |
|
||
| `fill_color` | `text` | 主体填充色 |
|
||
| `stroke_color` | `text` | 主体描边色 |
|
||
| `stroke_width` | `numeric` | 主体描边宽度 |
|
||
| `label` | `text` | 图上短标签，例如 `散热器` |
|
||
| `label_color` | `text` | 标签颜色 |
|
||
| `render_params` | `jsonb` | 小规模绘制参数 |
|
||
| `legend_order` | `integer` | 图例排序辅助 |
|
||
| `created_at` / `updated_at` | `timestamptz` | 审计字段 |
|
||
|
||
约束：
|
||
|
||
```sql
|
||
UNIQUE (theme_id, decoration_key)
|
||
```
|
||
|
||
`render_params` 示例：
|
||
|
||
```json
|
||
{
|
||
"widthRatio": 0.55,
|
||
"maxWidth": 130,
|
||
"height": 16,
|
||
"offsetXRatio": 0.55,
|
||
"offsetY": -18,
|
||
"ribCount": 3
|
||
}
|
||
```
|
||
|
||
`render_params` 只用于装饰件的小型形状参数。它不承载任意 SVG，也不允许注入脚本或 HTML。
|
||
|
||
### 5.5 `diagram_legend_items`
|
||
|
||
图例可以从节点、连接和装饰件样式自动推导，但为了保证顺序和文案稳定，建议单独建表。
|
||
|
||
建议字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | `uuid` | 主键 |
|
||
| `theme_id` | `uuid` | 所属主题 |
|
||
| `legend_key` | `text` | 例如 `pressurized` |
|
||
| `label` | `text` | 例如 `加压走道` |
|
||
| `item_type` | `text` | `edge`、`decoration`、`node` |
|
||
| `style_ref` | `text` | 引用 `connection_type`、`decoration_key` 或 `style_key` |
|
||
| `display_order` | `integer` | 显示顺序 |
|
||
| `is_visible` | `boolean` | 是否显示 |
|
||
|
||
约束：
|
||
|
||
```sql
|
||
UNIQUE (theme_id, legend_key)
|
||
CHECK (item_type IN ('edge', 'decoration', 'node'))
|
||
```
|
||
|
||
当前图例建议：
|
||
|
||
1. `structural`：结构直连，引用 `structural_mount`
|
||
2. `pressurized`：加压走道，引用 `pressurized_passage`
|
||
3. `utility`：燃料 / 供电，引用 `fuel` 或 `power` 中任一代表样式
|
||
4. `radiator`：大型折叠散热面板，引用 `radiator`
|
||
|
||
### 5.6 `diagram_layouts` 扩展
|
||
|
||
为布局绑定默认主题：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `theme_id` | `uuid` | 引用 `diagram_themes(id)`，可空；为空时使用基地默认主题 |
|
||
|
||
建议约束：
|
||
|
||
```sql
|
||
ALTER TABLE topology.diagram_layouts
|
||
ADD COLUMN theme_id uuid REFERENCES topology.diagram_themes(id);
|
||
```
|
||
|
||
### 5.7 `diagram_nodes` 扩展
|
||
|
||
现有字段基本足够，但建议补一个可选字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `render_meta` | `jsonb` | 节点级小规模渲染参数，例如特殊文本锚点；首期可不使用 |
|
||
|
||
首期可以不新增 `render_meta`，只让 `style_key` 指向 `diagram_node_styles`。如果后续发现某个节点需要特殊文本位置，再引入该字段。
|
||
|
||
## 6. API 设计
|
||
|
||
### 6.1 快照响应结构
|
||
|
||
现有 `/api/v1/bases/guanghan/snapshot` 继续返回 `base`、`query`、`components`、`connections`、`layout`。新增 `layout.presentation`。
|
||
|
||
建议结构：
|
||
|
||
```json
|
||
{
|
||
"layout": {
|
||
"layout": {
|
||
"key": "engineering_overview_v1",
|
||
"name": "工程总图 v1",
|
||
"canvasWidth": 1500,
|
||
"canvasHeight": 1900,
|
||
"themeKey": "guanghan_dark_engineering_v1"
|
||
},
|
||
"nodes": [
|
||
{
|
||
"nodeKey": "core_cabin",
|
||
"styleKey": "core-card",
|
||
"x": 630,
|
||
"y": 470,
|
||
"width": 240,
|
||
"height": 200,
|
||
"memberKeys": ["core_cabin"]
|
||
}
|
||
],
|
||
"presentation": {
|
||
"theme": {
|
||
"key": "guanghan_dark_engineering_v1",
|
||
"name": "广寒深色工程图",
|
||
"tokens": {
|
||
"textColor": "#eaf2ff",
|
||
"mutedTextColor": "#91a3bd"
|
||
}
|
||
},
|
||
"nodeStyles": {
|
||
"core-card": {
|
||
"fillColor": "#3b250d",
|
||
"strokeColor": "#ffad42",
|
||
"strokeWidth": 5,
|
||
"cornerRadius": 16,
|
||
"titleColor": "#eaf2ff",
|
||
"metaColor": "#a6b5c9",
|
||
"hintColor": "#71849e"
|
||
}
|
||
},
|
||
"edgeStyles": {
|
||
"pressurized_passage": {
|
||
"displayName": "加压走道",
|
||
"strokeColor": "#51e89c",
|
||
"strokeWidth": 9,
|
||
"dashArray": null,
|
||
"lineCap": "square",
|
||
"legendGroup": "pressurized"
|
||
}
|
||
},
|
||
"decorationStyles": {
|
||
"radiator": {
|
||
"displayName": "大型折叠散热面板",
|
||
"fillColor": "#6b5814",
|
||
"strokeColor": "#f0d869",
|
||
"strokeWidth": 2,
|
||
"label": "散热器",
|
||
"labelColor": "#f4df7b",
|
||
"renderParams": {
|
||
"widthRatio": 0.55,
|
||
"maxWidth": 130,
|
||
"height": 16,
|
||
"offsetXRatio": 0.55,
|
||
"offsetY": -18,
|
||
"ribCount": 3
|
||
}
|
||
}
|
||
},
|
||
"legendItems": [
|
||
{
|
||
"key": "pressurized",
|
||
"label": "加压走道",
|
||
"itemType": "edge",
|
||
"styleRef": "pressurized_passage",
|
||
"displayOrder": 20
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 缺省与错误处理
|
||
|
||
API 查询布局时：
|
||
|
||
1. 使用默认布局；
|
||
2. 如果布局绑定了主题，使用该主题；
|
||
3. 如果布局未绑定主题，使用基地默认主题；
|
||
4. 如果节点引用的 `style_key` 不存在，API 应返回明确错误或在响应中标记 `presentationWarnings`。
|
||
|
||
建议首期采用“API 返回 500/配置错误，不静默降级”的策略。拓扑图是工程资料，缺失样式不应伪装成正确页面。
|
||
|
||
前端可以有开发兜底色，但只用于防止页面彻底空白，不能作为测试验收依据。
|
||
|
||
### 6.3 样式值安全
|
||
|
||
API 应只返回白名单字段。颜色值应校验为：
|
||
|
||
- `#RGB`
|
||
- `#RRGGBB`
|
||
- `rgb(...)`
|
||
- `rgba(...)`
|
||
- 少量受控命名色如 `transparent`
|
||
|
||
首期建议只使用 `#RRGGBB`，简单、稳定、可测试。
|
||
|
||
`dash_array` 只允许数字和空格，例如 `13 10`。
|
||
`line_cap` 只允许 `butt`、`round`、`square`。
|
||
`render_params` 只允许预定义键，不允许任意 SVG 属性透传。
|
||
|
||
## 7. 前端渲染设计
|
||
|
||
### 7.1 节点
|
||
|
||
当前逻辑：
|
||
|
||
```text
|
||
rect.class = node.styleKey
|
||
CSS 决定 fill/stroke/stroke-width
|
||
```
|
||
|
||
目标逻辑：
|
||
|
||
```text
|
||
style = presentation.nodeStyles[node.styleKey]
|
||
rect.setAttribute('fill', style.fillColor)
|
||
rect.setAttribute('stroke', style.strokeColor)
|
||
rect.setAttribute('stroke-width', style.strokeWidth)
|
||
rect.setAttribute('rx', style.cornerRadius)
|
||
```
|
||
|
||
文本颜色同理从节点样式或主题 token 获取。
|
||
|
||
### 7.2 连接
|
||
|
||
当前逻辑：
|
||
|
||
```text
|
||
connection.type -> connectionClass(type)
|
||
CSS 决定颜色和虚实线
|
||
```
|
||
|
||
目标逻辑：
|
||
|
||
```text
|
||
style = presentation.edgeStyles[connection.type]
|
||
line.stroke = style.strokeColor
|
||
line.strokeWidth = style.strokeWidth
|
||
line.strokeDasharray = style.dashArray
|
||
line.strokeLinecap = style.lineCap
|
||
```
|
||
|
||
连接合并逻辑保留：多个数据库连接如果落在同一对视觉节点之间，并且使用同一种连接类型或同一个视觉样式，可以合并成一条线。
|
||
|
||
### 7.3 装饰件
|
||
|
||
当前逻辑：
|
||
|
||
```text
|
||
if node.decorations.radiator:
|
||
createRadiator(node)
|
||
```
|
||
|
||
目标逻辑：
|
||
|
||
```text
|
||
for each decorationKey in node.decorations:
|
||
style = presentation.decorationStyles[decorationKey]
|
||
createKnownDecoration(decorationKey, node, style)
|
||
```
|
||
|
||
首期只实现 `radiator` 这一种已知装饰件。后续新增装饰件时，应先在前端注册一个安全的已知 renderer，再允许数据库使用该 `decoration_key`。
|
||
|
||
### 7.4 图例
|
||
|
||
当前图例由 HTML 写死。目标是：
|
||
|
||
1. 页面保留空的 `<div id="legend">`；
|
||
2. 前端遍历 `presentation.legendItems`；
|
||
3. 根据 `itemType` 和 `styleRef` 找到对应样式；
|
||
4. 创建线段或色块示例。
|
||
|
||
这样图例顺序、文案和显示/隐藏由数据库决定。
|
||
|
||
## 8. Seed 数据建议
|
||
|
||
首期 seed 应把当前用户已认可的视觉效果完整落库：
|
||
|
||
### 8.1 节点样式
|
||
|
||
| `style_key` | 用途 |
|
||
|---|---|
|
||
| `core-card` | 广寒核心舱 |
|
||
| `node-card` | 普通舱段 |
|
||
| `power-card` | 电力模块分支 |
|
||
| `power-node-card` | 电力模块中心节点 |
|
||
| `vehicle-card` | 吴刚/冰轮等车辆 |
|
||
|
||
### 8.2 连接样式
|
||
|
||
| `connection_type` | 图例 | 要求 |
|
||
|---|---|---|
|
||
| `structural_mount` | 结构直连 | 灰蓝实线 |
|
||
| `pressurized_passage` | 加压走道 | 绿色实线 |
|
||
| `fuel` | 燃料 / 供电 | 紫色虚线 |
|
||
| `power` | 燃料 / 供电 | 紫色虚线 |
|
||
|
||
### 8.3 装饰件样式
|
||
|
||
| `decoration_key` | 用途 |
|
||
|---|---|
|
||
| `radiator` | 电力模块四个大分支顶部的大型折叠散热面板 |
|
||
|
||
散热器继续不是独立组件，不出现在弹窗里，不覆盖加压走道。
|
||
|
||
## 9. 测试策略
|
||
|
||
### 9.1 API 测试
|
||
|
||
新增测试应覆盖：
|
||
|
||
- snapshot 响应包含 `layout.presentation`；
|
||
- `nodeStyles` 包含所有 `diagram_nodes.style_key`；
|
||
- `edgeStyles` 包含当前快照里所有 `connections.type`；
|
||
- `legendItems` 按 `displayOrder` 排序；
|
||
- `radiator` 装饰件样式存在；
|
||
- 缺失样式时返回明确配置错误。
|
||
|
||
### 9.2 前端源码测试
|
||
|
||
源码测试应确认：
|
||
|
||
- 页面不再硬编码图例文字；
|
||
- 页面不再通过 `.core-card`、`.pressurized` 等 CSS 类决定业务颜色；
|
||
- 页面读取 `presentation.nodeStyles`、`presentation.edgeStyles`、`presentation.decorationStyles`、`presentation.legendItems`。
|
||
|
||
### 9.3 浏览器端到端测试
|
||
|
||
E2E 应覆盖：
|
||
|
||
- GHC-01、GHC-05 正常渲染；
|
||
- GHC-05 有两条绿色加压走道；
|
||
- 图例来自 API；
|
||
- 打开模块弹窗正常；
|
||
- 修改测试数据库中的 `pressurized_passage.stroke_color` 后，浏览器渲染颜色变化；
|
||
- 修改 `core-card.fill_color` 后，核心舱填充颜色变化；
|
||
- 历史任务节点/连接/散热器数量不回退。
|
||
|
||
### 9.4 截图验收
|
||
|
||
实现阶段每次页面修改后仍遵循现有要求：必须自己截图检查效果。
|
||
|
||
至少保留：
|
||
|
||
- GHC-05 顶部/中部/底部截图；
|
||
- GHC-01 早期快照截图；
|
||
- 图例截图；
|
||
- 修改测试主题颜色后的验证截图。
|
||
|
||
## 10. 实施分期建议
|
||
|
||
### Phase 1：数据库与 API
|
||
|
||
- 新增表现层迁移；
|
||
- seed 当前已认可样式；
|
||
- API 返回 `layout.presentation`；
|
||
- 增加 API 单元测试。
|
||
|
||
### Phase 2：前端切换
|
||
|
||
- 图例改为从 `presentation.legendItems` 生成；
|
||
- 节点、连接、散热器改为使用 API 样式；
|
||
- 移除业务颜色 CSS 的事实来源角色；
|
||
- 保留通用 CSS 和交互样式。
|
||
|
||
### Phase 3：验证与清理
|
||
|
||
- 跑完整单元测试和 E2E；
|
||
- 截图核对 GHC-01 到 GHC-05；
|
||
- 用测试数据临时改颜色，验证前端无代码修改即可变化；
|
||
- 更新验收报告。
|
||
|
||
## 11. 与未来扩展的关系
|
||
|
||
未来核心舱北、东、西三方向会继续扩展十字结构，北部成为多台吴刚着陆器连接点，西部成为多个 rover 连接点。B1 表现层设计支持这种扩展：
|
||
|
||
- 新节点继续写入 `diagram_nodes`；
|
||
- 新节点使用已有或新增 `style_key`；
|
||
- 新连接类型如果需要新视觉表现，只新增 `diagram_edge_styles` 和 `diagram_legend_items`；
|
||
- 未来扩展锚点仍不在页面显示，只有实际组件在快照时间存在后才渲染。
|
||
|
||
如果将来需要同时支持“工程总图”“简化拓扑图”“施工阶段图”等多个视图，可以新增不同 `diagram_layouts.layout_key`，并让 API 支持 `layout=` 参数。但这不是本轮 B1 的首期目标。
|
||
|
||
## 12. 决策摘要
|
||
|
||
本设计采用 B1：表现层数据库化。
|
||
|
||
明确放入数据库：
|
||
|
||
- 节点位置和尺寸；
|
||
- 节点颜色、描边、圆角；
|
||
- 连接线颜色、线宽、虚实线；
|
||
- 散热器基础视觉参数；
|
||
- 图例项。
|
||
|
||
明确留在前端：
|
||
|
||
- 页面壳、弹窗、工具栏、响应式；
|
||
- hover/focus；
|
||
- 文本截断；
|
||
- SVG 创建和交互事件；
|
||
- 安全的已知装饰件 renderer。
|
||
|
||
这个边界能满足“由后台数据库决定各组件渲染位置、颜色等信息”，同时避免把数据库变成一个难维护的 HTML/CSS 仓库。
|