从工勘图到资源库：提交 nVisual Studio 与机房设计全生命周期的闭环

摘要：工勘图纸的价值在「进入可检索、可复用资源库」之后才被放大——本地文件解决现场与交付，平台解决长期资产。DCDesigner 的「提交 nVisual Studio」把工勘 JSON 一键回传平台：平台按机柜 U/宽深高匹配型号、由接口配置生成 PDU、按坐标还原对象。本文说明回传链路、平台还原口径、错误处理，以及单文件离线、安全发布等工程化落地要点。
一、为什么工勘成果需要「入库」

用文件管理的机房产出，有三个天然上限：

  1. 检索上限：文件按项目名存放，想查「A 机房 A01 机柜的功率和接口配置」，得先找到那个文件再打开；
  2. 复用上限：新建机房时的参考布局、设备型号、配电配置散落在各个文件里，无法跨项目复用；
  3. 生命周期上限：工勘图是「一次性交付物」，之后的上架、扩容、变更、退役记录落在别处，图纸很快过期。

机房的真实生命周期是：现场工勘 → 平面设计 → 校核 → 交付 → 资源入库 → 运维变更。DCDesigner 覆盖前四步，nVisual Studio 承担后两步——回传接口就是把两者接上的那个动作。

二、提交什么：就是那份工勘 JSON

顶栏「导出」按钮右侧的「提交 nVisual Studio」（云朵上传图标，中英阿西四语跟随界面语言）打开提交对话框，一次性填写三项配置：

字段nVisual Studio 地址（URL）无协议自动补http://、去末尾斜杠API Key第二个字段；已保存时只以23 个星号掩码显示，聚焦输入框即清空可重填、留空则沿用已保存 Key视图节点 ID（diagramId）目标机房/视图节点的数字 ID，如

三项配置只存本浏览器 localStorage（idc2d_nvisual_v1），下次打开自动回显。对疑似被截断的 JWT（签名段短于算法应有长度）给出内联提示，避免复制残缺 token 造成平台 401。

上传内容与「保存」写出的文件完全同源：{ name, meta, objects }，单位毫米、西南角为原点。其中：

  • name→ 目标视图节点名称；
  • meta（勘测人/日期/园区楼宇/结构层高/吊顶/架空地板/等级/供电容量/制冷架构/电力模块/承重/温湿度）→ 节点属性；
  • objects→ 带全部类型与属性（机柜u/w/d/h/power/rpdu/voltage/current/sockets/wireSize、墙板厚/墙高/材质、门窗/格栅挂墙wallId+t、桥架kind/structure/height、通道kind/enclosed等）。

组装由纯函数buildSurveyPayload完成（深拷贝 + 与保存同一套清洗：失墙门窗与无效对象剔除、数值强转），不改动页面数据——提交失败也不会影响正在编辑的项目。

三、通路设计：经本机服务代理，不碰 CORS

浏览器直接向第三方平台 POST 会撞上跨域限制。DCDesigner 的做法是固定经本机服务代理：

页面 → POST /api/nvisual（同源） → 运行本页面的服务端 → POST {url}/diagramApi/wapi/v1/migration/import_survey?diagramId=…

服务端（Nodeserver.js/ GoDCDesigner.exe）负责：

  • 把工勘 JSON 组装为平台要求的multipart/form-data（文件字段file，文件名机房名+勘测日期.json，如CFD-TEST20261005.json；非 ASCII 文件名按 RFC 5987 编码）；
  • 注入Authorization: BearerX-Api-Key双请求头（平台以 Bearer 为准）；
  • 凭据随请求体内存转发，不落盘不记日志

代理本身也做了收敛：仅允许 POST、目标必须与所填 URL 同源、路径以单个/开头、查询参数走白名单（防 SSRF/注入）、请求体 ≤16MB、响应 ≤16MB、超时 60 秒。若本机服务未提供该代理（例如把页面丢给纯静态托管），会给出明确提示，不回退浏览器直连——宁可失败得清楚，也不静默降级成不可控请求。

子路径反代部署（如在线版/designer/）下，接口经统一基路径解析自动拼为/designer/api/nvisual，无需额外配置（见docs/子路径反向代理部署-NGINX-designer.md）。

四、平台侧怎么还原，以及 800119 这类前置条件

平台（SurveyImportService）按以下规则把工勘对象还原为资源：

  • 机柜：按 U/宽深高自动匹配型号；无完全一致型号时使用近似型号并给出警告；
  • 电源：由机柜sockets接口配置生成 PDU 电源；
  • 其他类型：按名称关键字 + 尺寸最近邻匹配（列头柜、UPS、蓄电池、灭火器、空调、墙体、门窗、柱子、格栅、风口、桥架、通道等）；
  • 坐标mm ÷ diagramScale（默认 10）并自动翻转 Y 轴，按包围盒归一化与自适应画布。

目标视图节点下必须为空——已有内容时平台直接拒收（错误码800119）。这属于平台的防覆盖保护，不是接口故障。对话框对此的处理值得单独指出：

  • 不再写成「提交失败」，而是黄底给出可操作说明：① 在 nVisual Studio 新建空视图节点，粘贴其节点 ID 到上方（输入框已自动聚焦并全选旧值，可直接粘贴替换）；② 或在平台清空目标视图下的对象后重试；
  • 附平台原文供排查；识别不依赖错误码（500/其他 code + 同一句提示同样按此处理）。

其他失败路径也被区分处理：地址与节点 ID 非法时内联报错且不发请求；平台以 HTTP 200 +code≠200表达业务错误时按失败处理并展示message；成功时对话框逐项展示平台返回的data.{roomId, roomName, counts, racks, skipped, warnings}（机房名 + 节点 ID、机柜台数、各类型创建数量、跳过项前 5 条含原因、警告前 3 条）并同步状态栏。

五、成果之外的工程化：运行、部署、安全与升级

回传只是闭环的一环，能长期稳定使用还需要几件工程化的事，DCDesigner 在这几处都有明确取舍：

5.1 运行与部署

  • Go 单文件 exe：静态资源//go:embed内嵌，双击运行、自动打开浏览器（默认 3999 端口，PORT可改；不需要自动开浏览器设NO_BROWSER=1）；无需安装 Go/Node，data/目录自动创建在 exe 旁；
  • 零依赖 Node 版node server.jsnpm start，两者接口与行为一致；
  • 六个平台产物：Windows x86_64 / Windows on ARM / Linux x86_64 / Linux arm64（鲲鹏/飞腾/树莓派）/ macOS Intel / macOS Apple Silicon，全部CGO_ENABLED=0交叉编译 +-trimpath，单文件免装运行时；
  • 子路径反代：在线版部署在/designer/时，前后端都无需改代码（基路径自动识别）。
5.2 多语言

界面支持中文 / English / العربية / Español四种语言，切换即时生效、无需刷新：语言记忆在 localStorage，首次访问按浏览器语言识别；阿拉伯语下布局镜像但画布坐标系不受影响（建模数据与图纸方向始终一致），编号模板等拉丁技术串做双向文字隔离处理。对象属性中的枚举值以中文为数据键存储——旧项目文件任意语言互相打开均兼容。

5.3 安全发布与授权（面向商业交付）

默认构建内嵌明文前端，适合开发；面向客户交付使用安全发布构建：前端资源加密嵌入 + 混淆 + garble 符号混淆 + 可选离线授权（Ed25519 许可证、机器指纹、完整性自检、宽限期），产物同样单文件。开发链路不受影响（dev 构建不启用授权检查），回归测试覆盖资源包往返、篡改检测、多指纹解包、到期与宽限等场景。

5.4 升级不丢数据

版本清单latest.js在启动后静默检查（4 秒超时，离线/失败零打扰），发现新版本弹窗提示（更新说明/发布日期），不做「忽略记忆」——每次启动都会提醒。数据保存在可执行文件旁data/目录，直接替换程序文件即可升级，已存档项目不受影响。

六、落地路径建议

工具本身的落地，建议按三步走，每一步都有可验证的产出而非口号：

阶段动作可验证产出试点选 1~2 个机房，工勘即用向导记录，交付前跑自检项目 JSON + 四类交付物 + 自检报告；对比「现场记录到交付」的实际工时标准化固化编号模板、通道/净距阈值、导出物命名与提交流程团队级参数约定（默认值注册表、自检阈值配置）、复查清单平台化统一 nVisual Studio 目标节点规范，工勘完成即回传资源库中可检索的机房对象；后续变更在平台上延续

评估指标建议用可测量的定义，而非主观感受：单机房从现场测量完成到交付物齐备的日历时长、交付后因图纸问题产生的修正次数、资源库中可检索对象占比、自检问题关闭率。

七、边界与注意事项

  • 平台类型映射是近似的：机柜无完全匹配型号时用近似型号并给警告，其他类型按名称关键字 + 尺寸最近邻匹配——回传后建议在平台上复核一遍关键设备型号；
  • 目标视图必须为空：这是平台保护机制，规划节点时应为每个机房准备独立空视图；
  • 多人共用一套服务端有已知风险：AI 中继为全局单队列单活动页，data/*.json是共享命名空间（同名项目互相覆盖、无鉴权）；多人协作建议以文件方式各自保存、通过平台回传汇总；
  • 合规自检为经验参考：不构成规范符合性结论，阈值应按项目标准调整；
  • 工勘数据主权：项目数据保存在本机（文件或data/），AI 使用自带 Key 且服务端不落盘，平台回传需使用者显式配置地址与凭据。

附：事实来源与核验方式

  • 提交功能与对话框：README.md「提交到 nVisual Studio」；实现见public/js/nvsubmit.jspublic/js/nvsubmit_core.js
  • 接口契约、字段映射、错误码对照：docs/nVisual提交接口-import_survey.md
  • 代理行为（multipart、鉴权双头、白名单、体积与超时）：server.jsmain.go/api/nvisual）；回归node tests/nvisual-proxy.test.mjs（加go参数可测 Go 版）
  • 配置与错误分类：node tests/nvsubmit.test.mjs；端到端（含 800119 场景）：node tests/nvisual-submit.cdp.mjs；真实平台联调（凭据走环境变量，人工运行）：tests/nvisual-live.mjs
  • 运行与构建：README.md「运行方法」；多语言：public/js/i18n/；安全发布：docs/加密与授权方案.md；反代部署：docs/子路径反向代理部署-NGINX-designer.md
  • 可复现核验：

node tests/nvsubmit.test.mjsnode tests/nvisual-proxy.test.mjsnode tests/nvisual-proxy.test.mjs gonode tests/nvisual-submit.cdp.mjs    # 需先启动服务与无头 Chrome 调试端口