From 89921977752479cde000e4929e4eeda35cab480e Mon Sep 17 00:00:00 2001 From: root Date: Fri, 21 Aug 2026 07:16:19 +0800 Subject: [PATCH] =?utf8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3=E7=AB=A0?= =?utf8?q?=E8=8A=82=E9=87=8D=E7=BC=96=E5=8F=B7=EF=BC=9A=E5=88=A0=E9=99=A4?= =?utf8?q?=E7=AC=AC3=E7=AB=A0=E5=90=8E=EF=BC=8C=E5=8E=9F=E7=AC=AC4?= =?utf8?q?=E7=AB=A0=E8=B5=B7=E6=95=B4=E4=BD=93=E5=89=8D=E7=A7=BB=E4=B8=80?= =?utf8?q?=E4=BD=8D=EF=BC=884=E2=86=923=E2=80=A611=E2=86=9210=EF=BC=89?= =?utf8?q?=EF=BC=8C=E5=90=AB=20h2/h3/h4=20=E6=A0=87=E9=A2=98=E3=80=81?= =?utf8?q?=E6=AD=A3=E6=96=87=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8=E4=B8=8E?= =?utf8?q?=E5=8F=98=E6=9B=B4=E6=97=A5=E5=BF=97=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit --- public/design-doc.html | 108 ++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/public/design-doc.html b/public/design-doc.html index c8c964d..d9bf7f6 100644 --- a/public/design-doc.html +++ b/public/design-doc.html @@ -131,9 +131,9 @@

2. 产品概述

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

-

4. 整体导航与菜单

+

3. 整体导航与菜单

-

4.1 顶栏（Topbar）

+

3.1 顶栏（Topbar）

@@ -143,7 +143,7 @@
元素功能数据来源交互效果
汉堡按钮 ☰布局占位（移动端菜单预留）—当前无行为 尚未实现
登录者头像 W / 邮箱当前登录身份展示静态演示演示态，点击头像返回登录页 登录态尚未实现（登录页不在本文档单列章节）
-

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

+

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

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

side-nav
 ├─ 模块切换 module-switch（互斥，仅一个高亮）
@@ -180,7 +180,7 @@
 
   
-    
+    
@@ -191,7 +191,7 @@
     

     
导航元素所属模块 / 分组功能数据来源交互效果
模块切换三个按钮module-switch切换三大模块前端 state（page）互斥高亮；点击切换至模块首页（见 4.3）
模块切换三个按钮module-switch切换三大模块前端 state（page）互斥高亮；点击切换至模块首页（见 3.3）

     
站点项目StationBuilder / 站点列表进入站点列表—点击 go("projects")；当前页高亮

     
站点切换器 <select>StationBuilder / 站点详情在已建站点间快速切换GET /api/db/sites选择后加载该站点并跳转（在列表页则进基本属性，在详情页则停留在当前子页）

     
1 基本属性 / 2 资产 / 3 功能与菜单 / 4 生成确认StationBuilder / 生成向导生成向导分步导航前端 state点击 go 对应页；当前步骤高亮；已完成步骤可回跳
全部页面样式页面样式库 / 样式库导航样式库列表GET /api/db/page-styles点击 go("styleLibrary")；当前页高亮

   

 
-  
4.3 模块切换（module-switch）

+  
3.3 模块切换（module-switch）

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

   
@@ -200,7 +200,7 @@
     

     
模块功能点击效果
页面样式库可复用的 Cube 视觉样式进入「页面样式库」页

   

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

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

   
StationBuilder 模块下分两类：

   
 
-  
5.13 界面截图（UI 总览）

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

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

+  
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。

 
   
站点项目
站点项目：全部站点列表、统计概览、筛选与新建入口。

   
站点基本属性
站点基本属性：站点名称、域名、业务描述、关键词、文件上传等基本信息维护。

@@ -688,7 +688,7 @@
   
设备模版详情
设备模版详情：设备基本信息、图片、采集点表格编辑。

   
页面样式库
页面样式库：样式缩略图网格与新增/编辑入口。

 
-  
6. 生成流程（端到端）

+  
5. 生成流程（端到端）

   

     
    
       
  1. 发起：在「生成确认」点「开始生成」→ 前端 POST /api/db/sites/:id/generate-all（携带各 Cube 的名称与内容）。
    2. 
@@ -706,7 +706,7 @@
     
    性能优化（本轮）：在不影响显示效果的前提下做了四项优化 —— ① 代码级自动修复：校验失败优先用 fixDashboard 程序化修正，避免为小问题重跑模型；② 精简模拟数据：提示词约束时序 ≤16 点、样例 ≤6 行，缩小输出 token；⑤ 重试降级：模型调用由最多 3 次降为最多 2 次（首次失败先走代码修复）；⑥ 并行生成：整站各 Cube 由顺序改为 Promise.all 并发。综合效果：整站生成约 4–9× 提速（75–90% 耗时下降），单次超时页（16 面板）约 60% 提速；已较快的单页提升约 30%。
    
   

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

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

   
@@ -714,7 +714,7 @@
     

     
元素功能数据来源交互效果

     
右下角悬浮按钮（AI 图标）打开 / 收起 AI 助手—点击开对话框；可拖动改变位置，双击复位（光标为 pointer，拖动时 grabbing）
模型选择弹层切换问答模型前端 MODELS仅免费模型可选

   

 
-  
8. 模态框（Modal）

+  
7. 模态框（Modal）

   
@@ -723,7 +723,7 @@
     

     
类型功能交互效果

     
提出修改意见（feedback）对单页提反馈并重新生成弹窗顶部即「修改意见」输入框（自动聚焦），下方展示影响范围（仅当前页 / 模拟数据 / 不受影响项）；提交后弹窗内出现黑底白字的 AI 生成工作流 终端，实时滚动 AI/Skill 生成进度；流结束后立即复位「重新生成中…」按钮并自动刷新站点、关闭弹窗，并设有 >10 分钟超时看门狗兜底，避免界面卡在「生成中」
生成提示词（prompt）查看/复制组合提示词展示发送给模型的完整提示词，可复制到剪贴板

   

 
-  
9. 数据与存储

+  
8. 数据与存储

   
@@ -732,7 +732,7 @@
     

     
对象说明接口

     
sites站点主记录（名称/领域/描述/状态/style_id）/api/db/sites
SQLite 文件持久化库（位于仓库 data/db/StationBuilder.sqlite，纳入 Git）db-sidecar 读写

   

 
-  
10. 尚未实现功能汇总

+  
9. 尚未实现功能汇总

   
 
-  
11. 维护与导出说明

+  
10. 维护与导出说明

 
-  
11.1 版本变更记录（Changelog）

+  
10.1 版本变更记录（Changelog）

   
@@ -761,18 +761,18 @@
     
-    
-    
+    
+    
-    
-    
-    
-    
-    
-    
+    
+    
+    
+    
+    
+    
-- 
2.43.0



     
版本日期修改人说明

     
v0.242026-08-20wang.yuAI 并发调用统一限流：新增全局信号量 AI_CONCURRENCY = 2，包裹 runCodebuddy（db-sidecar.mjs），使站点生成（含批内并行）、各项补全（complete / complete-assets / complete-cubes）、领域方案补全（dt-complete 系列）等全部 AI 功能任意时刻最多 2 个 codebuddy 子进程并发，避免无脑全并行抢占资源导致超时。站点「生成全部」批内并行数 GEN_CONCURRENCY 由硬编码 3 改为复用 AI_CONCURRENCY，对应日志文案同步为「最多 2 个并行调用」。AI 聊天侧（ai-sidecar.mjs /api/chat）本身以 running 布尔量串行（同一时刻仅 1 个），已满足 ≤2。
v0.202026-08-20wang.yu领域分类管理增强：① 默认分类调整——移除「工业制造 / 工业园区 / 智慧楼宇」，新增「其他」（DEFAULT_DOMAINS 同步更新，重启不再复活被删分类）；② 领域方案库新增「管理领域」面板，列出全部领域及其方案数，「其他」标注「默认保留」且不可删除，其余领域提供「删除」按钮，经自定义确认弹窗二次确认后调用 DELETE /api/domains/:id；③ 后端新增 DELETE /api/domains/:id：禁止删除「其他」，删除前将待删领域的 domain_templates 与 device_template_domains 关联迁移至「其他」（避免 ON DELETE CASCADE 误删方案），再删除领域；④ 删除后前端刷新领域列表，并在当前筛选命中该领域时自动清除筛选。

     
v0.192026-08-20wang.yu修复领域方案「功能与菜单 → Cube 扩展页面」两处问题：①「生成」按钮改为流式请求（消费 NDJSON 响应体以保持连接），生成期间按钮显示「生成中…」并禁用、底部「AI 生成页面」控制台实时输出进度并据服务端 {status:failed} 事件弹失败提示；此前前端用普通 fetch 不读取响应体，连接被提前关闭导致服务端 AI 生成中断（status='failed'）、Json 未写入。② AI 智能补全（complete-cubes）由「逐条静默 .catch(()=>{}) 插入」改为「收集结果后逐个 await 插入、失败显式 notify」，并捕获服务端 {status:failed} 事件弹失败提示，避免补全内容静默丢失、列表无变化。

     
v0.172026-08-19wang.yu修复左侧目录（TOC）点击章节后消失：根因为顶部版本说明段落含全角空格不换行，在 flex 布局下把 main#doc 撑到约 2238px 宽（flex item 默认 min-width:auto 不收缩），点击锚点时浏览器水平滚动将 sticky 目录推出左边界。给 main#doc 增加 min-width:0 使其可收缩、内容正常折行，消除水平滚动，目录任意宽度常驻可见。
v0.182026-08-20wang.yu领域方案「功能与菜单 → Cube 扩展页面」表格增强：① 新增「来源」列，以徽标区分 上传 / AI生成 / 手动；② 原「生成文件」列更名为「Json文件」，对上传页面提供原始 .json 文件名下载、对 AI 生成页面提供生成的 Cube .json 下载（未生成显示"未生成"）；③ domain_pages 新增 source 字段，上传/生成时分别写入 source=upload/ai 与 gen_filename；④ 生成确认页状态徽标区分「AI已生成 / 已上传 / 未生成 · 来源」。同步更新 5.10 章节。
v0.162026-08-19wang.yu设计方案文档修订：① 左侧目录改为任意宽度常驻可见（移除窄屏 display:none，窄屏下列表转为顶部可滚动常驻栏），点击章节后目录不再消失；② 移除「内部登录」章节（5.1）及 5.13 登录截图，可达性说明去掉登录；③ 新增 AI 智能补全子章（5.3.2 / 5.4.2 / 5.5.2），附 AI 流式输出终端截图（ai-complete-basic/assets/functions.png）；④ 修复 PDF 导出图片被分页截断（@media print 增加 page-break-inside:avoid 与图片适配）；⑤ 修复 Word 导出无图片（downloadWord 将图片转为 base64 data URI 内嵌）。
v0.182026-08-20wang.yu领域方案「功能与菜单 → Cube 扩展页面」表格增强：① 新增「来源」列，以徽标区分 上传 / AI生成 / 手动；② 原「生成文件」列更名为「Json文件」，对上传页面提供原始 .json 文件名下载、对 AI 生成页面提供生成的 Cube .json 下载（未生成显示"未生成"）；③ domain_pages 新增 source 字段，上传/生成时分别写入 source=upload/ai 与 gen_filename；④ 生成确认页状态徽标区分「AI已生成 / 已上传 / 未生成 · 来源」。同步更新 4.10 章节。
v0.162026-08-19wang.yu设计方案文档修订：① 左侧目录改为任意宽度常驻可见（移除窄屏 display:none，窄屏下列表转为顶部可滚动常驻栏），点击章节后目录不再消失；② 移除「内部登录」章节（4.1）及 4.13 登录截图，可达性说明去掉登录；③ 新增 AI 智能补全子章（4.3.2 / 4.4.2 / 4.5.2），附 AI 流式输出终端截图（ai-complete-basic/assets/functions.png）；④ 修复 PDF 导出图片被分页截断（@media print 增加 page-break-inside:avoid 与图片适配）；⑤ 修复 Word 导出无图片（downloadWord 将图片转为 base64 data URI 内嵌）。

     
v0.152026-08-19wang.yu领域方案库列表增强：列顺序调整为「所属领域 → 方案名称 → 版本 → 状态 → 创建人 → 设备/页面/文档 → 操作」，版本/状态列收窄、所属领域/方案名称列加宽；新增筛选栏（查找 方案名称/创建人 + 所属领域下拉 + 状态下拉 + 条数）与可排序列头（所属领域/方案名称/状态/创建人，升降切换带 ▲▼），卡片视图复用同结果。

     
v0.142026-08-19wang.yu左侧目录（TOC）贴齐浏览器最左侧：.doc-layout 取消 margin:0 auto 自动居中（改为 margin:0; padding-left:12px），宽屏下不再左右留白，目录紧贴视口左缘。

     
v0.132026-08-18wang.yu截图显示宽度由 500px 调整为 360px（.figure img 的 max-width），等比例缩放并居中，适配常见浏览宽度。

     
v0.122026-08-18wang.yu统一文档内所有截图显示尺寸：修改 .figure img 为 max-width:500px; height:auto 并居中，所有页面截图等比例压缩至 500px 宽，宽度一致。
v0.112026-08-18wang.yu补齐每个交互细节小节（5.1.1–5.12.1）的对应截图：新增 result.png（由 generated 站点「北方污水厂」进入结果页截取），将 5.9–5.12 的截图移入对应子节，5.13 截图总览同步加入 result.png。5.8 页面预览因无 UI 入口保留文字说明；5.1–5.7 子节补嵌实图。
v0.102026-08-18wang.yu细化设计文档：为每个页面（5.1–5.12）新增「交互细节」子章（5.x.1），统一按「① 字段 / 表格逐列（数据来源 / 是否可编辑 / 编辑类型 / 上线范围）② 按钮与操作（点击效果 / 编辑方式 / 确定·取消·关闭）③ 导航流（入口 / 上一步 / 下一步）」三段式逐项描述，覆盖表格每一列、每个按钮与弹窗的确认/取消/关闭语义及前后页跳转。修正可达性说明：站点结果可由站点项目点击已生成站点进入；页面预览当前无 UI 入口。
v0.92026-08-18wang.yu使用 Chromium + Playwright 自动抓取全站可访问页面截图，统一嵌入设计文档：新增 5.13「界面截图（UI 总览）」，覆盖登录页、站点项目、站点基本属性、Asset 资产、功能与菜单、生成确认、领域方案库、领域方案详情、设备模版列表/详情、页面样式库（共 11 张）。替换 5.9 / 5.10 中两张 placeholder.svg 为真实截图；在 5.11 / 5.12 补充真实界面图。截图文件置于 public/design-doc-assets/。
v0.82026-08-18wang.yu设备模版改为「默认展开列表、点击进入详情」：列表为紧凑表格（缩略图 / 名称 / 说明 / 采集点数 / 操作），支持按名称或说明实时搜索；点击行进入该设备模版的详情编辑区（名称 / 说明 / 图片 / 采集点），可「← 返回列表」；「＋ 新增设备模版」进入新建表单，创建后定位到新建设备的详情。面向成百上千设备模版的可扩展性。同步更新 4.2 导航表、5.12 章节。
v0.72026-08-18wang.yu设备模版页交互优化：设备图片改为长方形预览区（点击上传，不再溢出）；移除设备侧「所属领域」多选（改为由领域/方案侧选用设备）；采集点改为整宽表格编辑，支持新增一行、勾选批量删除、保存，数值范围改为下拉选择器（预设 + 自定义）；修复打开卡片时 collection_points 未加载导致的 runtime error，列表接口补充返回 collection_points。后端新增 GET /api/db/device-templates/:id/image 图片服务。新增 5.12 章节。
v0.62026-08-18wang.yu领域方案库重构为多菜单：列表页支持「列表 / 卡片」视图切换与按领域分类筛选；新增独立的「设备模版」页（前端 DeviceTemplates，独立维护设备模版与采集点）；方案详情的设备面板改为「选用设备模版」（DeviceTemplatePicker，勾选即重写 device_template_domain_templates 关联，未找到可跳转新增）；领域分类改为由 GET /api/domains 动态渲染的二级菜单。后端 domain-templates 更新支持 device_template_ids 重关联。同步更新 4.2 / 5.9 / 5.10 章节。
v0.112026-08-18wang.yu补齐每个交互细节小节（4.1.1–4.12.1）的对应截图：新增 result.png（由 generated 站点「北方污水厂」进入结果页截取），将 4.9–4.12 的截图移入对应子节，4.13 截图总览同步加入 result.png。4.8 页面预览因无 UI 入口保留文字说明；4.1–4.7 子节补嵌实图。
v0.102026-08-18wang.yu细化设计文档：为每个页面（4.1–4.12）新增「交互细节」子章（4.x.1），统一按「① 字段 / 表格逐列（数据来源 / 是否可编辑 / 编辑类型 / 上线范围）② 按钮与操作（点击效果 / 编辑方式 / 确定·取消·关闭）③ 导航流（入口 / 上一步 / 下一步）」三段式逐项描述，覆盖表格每一列、每个按钮与弹窗的确认/取消/关闭语义及前后页跳转。修正可达性说明：站点结果可由站点项目点击已生成站点进入；页面预览当前无 UI 入口。
v0.92026-08-18wang.yu使用 Chromium + Playwright 自动抓取全站可访问页面截图，统一嵌入设计文档：新增 4.13「界面截图（UI 总览）」，覆盖登录页、站点项目、站点基本属性、Asset 资产、功能与菜单、生成确认、领域方案库、领域方案详情、设备模版列表/详情、页面样式库（共 11 张）。替换 4.9 / 4.10 中两张 placeholder.svg 为真实截图；在 4.11 / 4.12 补充真实界面图。截图文件置于 public/design-doc-assets/。
v0.82026-08-18wang.yu设备模版改为「默认展开列表、点击进入详情」：列表为紧凑表格（缩略图 / 名称 / 说明 / 采集点数 / 操作），支持按名称或说明实时搜索；点击行进入该设备模版的详情编辑区（名称 / 说明 / 图片 / 采集点），可「← 返回列表」；「＋ 新增设备模版」进入新建表单，创建后定位到新建设备的详情。面向成百上千设备模版的可扩展性。同步更新 3.2 导航表、4.12 章节。
v0.72026-08-18wang.yu设备模版页交互优化：设备图片改为长方形预览区（点击上传，不再溢出）；移除设备侧「所属领域」多选（改为由领域/方案侧选用设备）；采集点改为整宽表格编辑，支持新增一行、勾选批量删除、保存，数值范围改为下拉选择器（预设 + 自定义）；修复打开卡片时 collection_points 未加载导致的 runtime error，列表接口补充返回 collection_points。后端新增 GET /api/db/device-templates/:id/image 图片服务。新增 4.12 章节。
v0.62026-08-18wang.yu领域方案库重构为多菜单：列表页支持「列表 / 卡片」视图切换与按领域分类筛选；新增独立的「设备模版」页（前端 DeviceTemplates，独立维护设备模版与采集点）；方案详情的设备面板改为「选用设备模版」（DeviceTemplatePicker，勾选即重写 device_template_domain_templates 关联，未找到可跳转新增）；领域分类改为由 GET /api/domains 动态渲染的二级菜单。后端 domain-templates 更新支持 device_template_ids 重关联。同步更新 3.2 / 4.9 / 4.10 章节。

     
v0.52026-08-18wang.yu设计方案支持页面截图：新增 figure / 图注 样式（自动编号），撰写方式参考 MachineCube 手册（小节标题 + 说明 +「下图」引用 + 配图 + 图注）；图片置于 public/design-doc-assets/。新增「版本变更记录」，每次修改升级小版本号并登记修改人 / 日期。

     
v0.42026-08-18wang.yu领域方案库升级为真实数据库驱动 CRUD：新增 schema（领域模板 / 设备模板 / 采集点 / 领域页面 / 模板菜单 / 知识文档 / 运维流程占位）；全套接口（/api/domain-templates、/api/device-templates、/api/collection-points、/api/domain-pages、/api/template-menu-items、/api/knowledge-docs、/api/ops-flows）；前端列表 + 内嵌编辑器，openDomainTemplateId 控制 列表·新增·详情 切换。

     
v0.32026-08-18wang.yu基线版本：整站生成超时修复（提示词精简 + 最多 2 次重试 + 超时 300s→480s）、AI 智能补全（基本属性 / 资产 / 功能与菜单三页）、功能与菜单重构、导入 Cube 后空白修复（flatten custom + normalizePanelCustom）、下载 Markdown 兼容 Azure DevOps Wiki。运维流程 / 领域分类筛选 / 从方案一键建站等仍标注「尚未实现」。