文档版本：v0.28　最后更新：2026-08-21　修改人：wang.yu　状态：开发中（演示数据已标注）

StationBuilder 产品与交互设计方案

1. 文档说明

本文档说明 StationBuilder（站点 / 领域方案 AI 生成工具）的整体结构、所有页面与菜单、每个交互元素的功能 / 数据来源 / 交互效果，以及端到端的生成流程。面向研发、设计与评审人员。

• 约定：标注 尚未实现 的项表示已在界面或方案中设计、但当前版本尚未打通能力（多为演示 / 占位）。
• 维护：本文件为单一 HTML 源（public/design-doc.html），后续功能改动需同步更新对应章节，未实现项持续标注，直到能力落地后移除标记。
• 截图：可按 MachineCube 手册的撰写方式，在相关章节插入页面截图——小节标题 + 一句话说明 +「下图」引用 + 配图 + 图注。图片统一放在 public/design-doc-assets/ 目录（PNG），在文中以 <figure><img src="design-doc-assets/xxx.png"><figcaption>…</figcaption></figure> 插入；图注会自动编号（图 1 / 图 2 …）。每次内容修改需同步升级文档小版本号并登记「版本变更记录」。
• 导出：顶部按钮分别导出 PDF（调用浏览器打印）、Word（.doc 兼容格式）、Markdown（由本页内容实时转换）。
• 目录：页面左侧为章节目录（自动生成），点击可跳转至对应章节；滚动阅读时自动高亮当前所在章节。

2. 产品概述

StationBuilder 是面向 iStation 团队的内部工具，用于通过 AI 大模型与 可视化生成 Skill 快速生成站点的大屏看板（Cube 仪表盘 JSON）、资产配置、功能菜单与领域方案，并可预览、反馈微调与打包下载。核心用户路径为：站点列表 → 站点详情（基本属性 / 资产 / 功能与菜单 / 生成确认）→ 站点结果 / 页面预览。

3. 整体导航与菜单

3.1 顶栏（Topbar）

3.2 左侧导航整体结构（side-nav）

左侧导航由固定顶部的「模块切换」+ 随当前模块/页面动态渲染的「分组与菜单项」组成。同一时刻仅一个模块高亮，菜单项按当前所在模块展示不同内容。完整结构如下：

side-nav
├─ 模块切换 module-switch（互斥，仅一个高亮）
│   ├─ StationBuilder        → 站点项目（站点列表）
│   ├─ 领域方案库             → 领域方案库页
│   └─ 页面样式库             → 页面样式库页
│
├─ 【StationBuilder 模块时】（当前页非 方案库/样式库）
│   ├─ 站点列表
│   │   └─ 站点项目           → projects
│   └─ 站点详情
│       ├─ 站点切换器 <select>（列出全部站点）
│       ├─ 生成向导
│       │   ├─ 1 基本属性     → basic
│       │   ├─ 2 资产         → assets
│       │   ├─ 3 功能与菜单   → functions
│       │   └─ 4 生成确认     → generate
│       └─ 方案交付
│           ├─ 站点结果        → result
│           └─ 页面预览        → preview
│
├─ 【领域方案库模块时】（domains / domainDetail / deviceTemplates）
│   ├─ 方案库导航
│   │   ├─ 领域方案            → domains（方案列表，支持列表/卡片切换；点击具体方案打开 domainDetail）
│   │   └─ 设备模版            → deviceTemplates（独立页面，编辑设备模版与采集点，供方案选用）
│   └─ 领域分类（动态二级菜单：来自 GET /api/domains；点击即按该领域筛选方案列表）
│       ├─ （领域 A）          → domains + domainFilter=领域A（自动列出该领域全部方案）
│       │   └─ ×（删除，仅非「其他」领域；确认后其方案归入「其他」）
│       ├─ （领域 B）          → domains + domainFilter=领域B（同上，含 × 删除）
│       ├─ …（按数据库 domains 表动态渲染）
│       └─ ＋ 新增领域          → 行内输入框（最多 6 字，Enter 确认 / Esc 取消）POST /api/domains 并刷新
│
└─ 【页面样式库模块时】（styleLibrary）
    └─ 样式库导航
        └─ 全部页面样式        → styleLibrary

3.3 模块切换（module-switch）

三个互斥模块，同一时刻仅一个高亮：

3.4 站点列表 / 站点详情 分组与站点切换器

StationBuilder 模块下分两类：

• 站点列表：站点项目页，负责站点的查看、搜索、编辑与删除（含批量删除）。
• 站点详情：含一个「站点切换器」下拉框（列出全部站点），选择即进入该站点详情；其下为生成向导（基本属性 / 资产 / 功能与菜单 / 生成确认）与方案交付（站点结果 / 页面预览）。

4. 页面详细说明

4.2 站点项目 / 站点列表（projects）

4.2.1 交互细节

① 字段 / 表格逐列（列表表格，仅展示 + 选择，不可就地文本编辑）：

统计条（全部 / 草稿 / 生成中 / 生成完成 / 部分失败）由 sites 列表本地聚合，纯展示。

② 按钮与操作

③ 导航流

• 入口：登录后默认页 / 侧栏「站点项目」。
• 上一步：无（站点模块顶层）。
• 下一步：点击站点 → 基本属性(basic) 或 站点结果(result)；点击「＋ 新建站点」→ 基本属性(新建)。

4.3 站点基本属性（basic）

4.3.1 交互细节

① 字段 / 表格逐列（左栏「站点基本信息」表单 + 右栏建议/AI 面板）：

② 按钮与操作

③ 导航流

• 入口：站点项目点击站点（未生成）/「＋ 新建站点」。
• 上一步：站点项目（projects）。
• 下一步：Asset 资产设置（assets）。

4.3.2 AI 智能补全（站点基本属性）

「开始补全」调用 POST /api/db/sites/:id/complete（流式 NDJSON）。终端（.modal-console）实时逐行输出 AI 的思考 / 分析过程（如「▶ 开始 AI 智能补全：基于站点名称 / 领域 / 描述分析并生成补充描述…」）；流结束后将生成的补充描述写入「补充要求」并自动保存。点击「查看提示词」可查看本次组合提示词。补全过程中「开始补全」按钮显示「补全中…」并禁用，避免重复触发 补充描述质量将按反馈持续优化。

4.4 Asset 资产设置（assets）

4.4.1 交互细节

① 字段 / 表格逐列（设备资产配置表格，行内编辑即保存）：

KPI 行（设备类型 / 设备实例 / 资产层级）与「资产层级预览」树由本地计算，随表格实时变化（3 层结构为展示占位，资产层级建模尚未实现）。

② 按钮与操作

③ 导航流

• 入口：基本属性「下一步」/ 侧栏「Asset 资产设置」。
• 上一步：基本属性（basic）。
• 下一步：功能与菜单（functions）。

4.4.2 AI 智能补全（Asset 资产设置）

「开始补全」调用 POST /api/db/sites/:id/complete-assets（流式 NDJSON）。终端实时输出 AI 对设备类型、数量与命名规则的推断过程；结果将追加在用户已填项下方（不改动已填内容），资产配置列表随之更新，资产层级预览重算；结束自动保存。点击「查看提示词」查看完整提示词。

4.5 功能与菜单（functions）

三个子页签：

4.5.1 交互细节

三个页签：MU 标准页面 / Cube 扩展页面 / 菜单结构。

① 字段 / 表格逐列

② 按钮与操作

③ 导航流

• 入口：Asset「下一步」/ 侧栏「功能与菜单」。
• 上一步：Asset 资产设置（assets）。
• 下一步：生成确认（generate）。（generate 之后无 UI 入口进入站点结果/页面预览，见 4.7 / 4.8）

4.5.2 AI 智能补全（功能与菜单 · Cube 扩展页面）

在「Cube 扩展页面」页签中点击「开始补全」，调用 POST /api/db/sites/:id/complete-cubes（流式 NDJSON）。终端实时输出 AI 对站点所需 Cube 扩展页面的推断（页面名称 + 详细内容）；结果追加在用户已建页面下方并自动保存。点击「查看提示词」可查看完整组合提示词。

4.6 生成确认（generate）

4.6.1 交互细节

① 字段 / 表格逐列

② 按钮与操作

③ 导航流

• 入口：功能与菜单「下一步」/ 侧栏「生成确认」。
• 上一步：无显式按钮（为向导末步）。
• 下一步：生成完成后无 UI 自动跳转（站点结果/页面预览当前无入口，见 4.7 / 4.8）。

4.7 站点结果（result）

页面结果卡片默认纵向单列排列（上下结构），每张卡片占满整行，便于在多个 Cube 页面间逐张查看与操作；每张卡片底部并排展示「预览 / JSON / 提示词 / 修改意见」四个按钮。

4.7.1 交互细节

① 字段 / 表格逐列（均为结果只读展示，无表单编辑）：

② 按钮与操作

③ 导航流

• 入口：站点项目点击已生成站点（go("result", id)）。（注：4.6 生成完成后不会自动跳转至此，需回站点项目点击该站点进入。）
• 上一步：修改配置 → Asset 资产设置（assets）。
• 下一步：无（末页）。

4.8 页面预览（preview）

4.8.1 交互细节

本页当前无 UI 入口，故无对应截图；功能说明见下文。

① 字段 / 表格逐列（当前为静态演示外壳，未接入真实生成数据）：

② 按钮与操作：演示画布内的「刷新数据 / 全屏」等仅触发提示，无业务副作用。实际 Cube 渲染区可展示真实生成结果。

③ 导航流

• 入口：当前无 UI 入口——代码中无 go("preview") 调用，无法从任何页面进入（与 4.7 站点结果不同）。
• 上一步 / 下一步：均不可达。

4.9 领域方案库（domains）

领域方案库已从硬编码演示改为真实数据库驱动。列表与详情编辑器同一页面内通过 openDomainTemplateId state 切换：null=列表，"create"=新增表单，number=该方案详情编辑器。列表支持列表 / 卡片两种视图切换（右上角视图切换按钮，view state 控制）。列表上方提供筛选栏：文本查找框（匹配 方案名称 / 创建人）、所属领域下拉、状态下拉，结果实时过滤并显示条数；列头 所属领域 / 方案名称 / 状态 / 创建人 可点击排序（升/降切换，带 ▲▼ 指示），卡片视图复用同一筛选与排序结果。

4.9.1 交互细节

① 字段 / 表格逐列（列表表格，仅展示 + 操作）：

顶部 domain-hero-stats 按领域统计方案数（本地计算），纯展示。列表列顺序为 所属领域 → 方案名称 → 版本 → 状态 → 创建人 → 设备/页面/文档 → 操作；其中 所属领域 / 方案名称 / 状态 / 创建人 四列点击列头可排序（升/降切换，表头右侧显示 ▲/▼）。

② 按钮与操作

③ 导航流

• 入口：侧栏「领域方案库」/「领域方案」。
• 上一步：无（领域模块顶层）。
• 下一步：点击「编辑」/ 卡片 → 方案详情（domainDetail）；点击「＋ 新增领域方案」→ CreateTemplate（保存后 → domainDetail）。

4.10 方案详情（domainDetail / 内嵌编辑器）

详情为同一页面内嵌编辑器，所有内容均可编辑，数据持久化到领域方案库相关表。各面板如下：

4.10.1 交互细节

① 字段 / 表格逐列

② 按钮与操作

③ 导航流

• 入口：领域方案库点击「编辑」/ 卡片，或「＋ 新增领域方案」保存后。
• 上一步：← 返回列表 → 领域方案库（domains）。
• 下一步：无（详情为末层）；可通过「选用设备模版 → ＋ 新增设备模版」跳到设备模版页（deviceTemplates）。

4.11 页面样式库（styleLibrary）

4.11.1 交互细节

① 字段 / 表格逐列

② 按钮与操作

③ 导航流

• 入口：侧栏「页面样式库」。
• 上一步：无（独立模块）。
• 下一步：无；样式被站点「功能与菜单」页的「站点页面样式」选择器引用。

4.12 设备模版（deviceTemplates）

独立的「设备模版」页，维护可复用的设备模版与采集点，供领域方案在详情中「选用设备模版」引用。设备模版数量可能成百上千，因此采用默认展开列表、点击进入详情的方式（而非整页卡片栅格）：列表为紧凑表格（.device-tpl-list），含缩略图 / 名称 / 说明 / 采集点数 / 操作，并支持按名称或说明实时搜索；点击任意行进入该设备模版的详情编辑区，详情内「← 返回列表」回到列表。列表上方「＋ 新增设备模版」进入新建表单（创建后定位到新建设备的详情）。

4.12.1 交互细节

① 字段 / 表格逐列（列表表格，仅展示 + 操作；详情为编辑区）：

详情编辑区（DeviceTemplateCard）字段：

② 按钮与操作

③ 导航流

• 入口：侧栏「设备模版」。
• 上一步：← 返回列表 → 设备模版列表。
• 下一步：无（详情为末层）；亦可由领域方案详情「选用设备模版 → ＋ 新增设备模版」跳转至此新建。

4.12.2 AI 采集点补全

采集点是设备监控运营的核心数据点。StationBuilder 提供两处 AI 补全入口，统一由后端 buildCompleteCollectionPointsPrompt 构造提示词、runCodebuddy（模型 hy3）生成、extractCollectionPoints 解析为 {name, collect_note, unit, value_range, description}[] 后批量写入 device_collection_points。

① 领域方案生成时自动补全（Part A）：在领域方案详情「AI 资产补全」(POST /api/db/domain-templates/:id/complete-assets) 中，每当 AI 推理出某设备类型并新创建对应设备模板（resolveDeviceTemplate 返回 created:true）后，后端立即以该设备名称为设备模板生成 6~12 个合适采集点并写库（追加模式，单个失败不影响整体；推导过程实时回流到资产补全控制台）。已存在的设备模板（created:false）不重复补全，避免覆盖用户数据。

② 单独打开设备模板时补全（Part B）：设备模板详情（DeviceTemplateCard）新增「AI 智能补全 · 采集点」面板，含「开始补全」与「查看提示词」按钮。点击「开始补全」调用 POST /api/db/device-templates/:id/complete-collection-points（流式 NDJSON），后端用 codebuddy 生成采集点并写库，前端补全完成后重新拉取详情刷新采集点表格；「查看提示词」弹窗展示将发送给模型的完整组合提示词（设备名称/所属领域/说明 + 领域知识）。

补全策略：默认追加模式——保留用户已手动录入的采集点，仅新增 AI 推荐、且与已有采集点名称不重复的条目（按 name 去重），不覆盖已录入数据；数值范围优先从预设集合（0~100 / 0~1000 / -20~80 / -40~85 / 0~50 / 0~5 / 0~1 / 0~100%）中选取。

4.13 界面截图（UI 总览）

以下截图覆盖了当前 StationBuilder 原型的主要页面。截图在 1440×900 视口下使用 Playwright + Chromium 自动抓取，图片存放于 public/design-doc-assets/。各页的字段、按钮与导航流逐项说明见 4.2–4.12 的「交互细节」子章；其中 4.3 / 4.4 / 4.5 另含「AI 智能补全」子章（4.3.2 / 4.4.2 / 4.5.2），展示 AI 流式输出过程。

可达性说明：站点项目、基本属性、Asset、功能与菜单、生成确认、站点结果（站点项目点击已生成站点进入）、领域方案库、方案详情、页面样式库、设备模版均可正常访问；页面预览（4.8）当前无 UI 入口（代码中无 go("preview") 调用），故未单独截图，其演示外壳见 4.8.1。

5. 生成流程（端到端）

6. AI 问答（悬浮按钮 + 对话框）

7. 模态框（Modal）

8. 数据与存储

9. 尚未实现功能汇总

• 真实登录 / 账号体系（当前为演示登录） 尚未实现
• 领域方案库真实数据 CRUD（领域模板 / 设备模板 / 采集点 / 领域页面 / 模板菜单 / 知识文档）已落地；「直接使用 / 加入站点」将从方案一键建站 尚未实现
• 运维流程内容编辑（当前仅占位记录） 尚未实现
• 领域方案按领域分类筛选（左侧「领域分类」动态二级菜单，点击即按 domainFilter 筛选方案列表）
• Asset Excel 生成与下载 尚未实现
• 资产三级层级建模（当前为展示占位） 尚未实现
• 页面预览中「站点监控」真实数据接入（当前为静态演示） 尚未实现
• 版本历史真实多版本管理（当前仅 V1 占位） 尚未实现
• 列表搜索 / 筛选的服务端查询（当前为前端过滤） 尚未实现
• 生成模型可切换（当前后端固定配置） 尚未实现
• 单页生成（functions 页）的实时日志 尚未实现
• 顶栏汉堡按钮的移动端菜单 尚未实现

10. 维护与导出说明

10.1 版本变更记录（Changelog）

• 功能变更后请同步更新本文档对应章节，未实现项持续标注 尚未实现，落地后移除。
• 下载 PDF：调用浏览器打印，在打印对话框选择「另存为 PDF」；勾选「页眉和页脚」可加页码，输出真实文字无乱码。
• 下载 Word：将本文档内容以 Word 兼容的 .doc 格式导出（Word 可直接打开，含页脚页码与默认目录）。
• 下载 Markdown：由本页 DOM 实时转换为 Markdown 文本导出。