Armor/KSP_project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(topology): design database-driven presentation layer

Browse Source
This commit is contained in:
Armor
2026-07-09 22:51:14 +08:00
parent f5cbe1b028
commit 479e37e00f
1 changed files with 627 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-07-09-guanghan-topology-presentation-db-design.md
+627
View File
@@ -0,0 +1,627 @@
# 广寒基地拓扑图表现层数据库化设计
日期：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 仓库。