从工勘图到资源库提交 nVisual Studio 与机房设计全生命周期的闭环摘要工勘图纸的价值在「进入可检索、可复用资源库」之后才被放大——本地文件解决现场与交付平台解决长期资产。DCDesigner 的「提交 nVisual Studio」把工勘 JSON 一键回传平台平台按机柜 U/宽深高匹配型号、由接口配置生成 PDU、按坐标还原对象。本文说明回传链路、平台还原口径、错误处理以及单文件离线、安全发布等工程化落地要点。一、为什么工勘成果需要「入库」用文件管理的机房产出有三个天然上限检索上限文件按项目名存放想查「A 机房 A01 机柜的功率和接口配置」得先找到那个文件再打开复用上限新建机房时的参考布局、设备型号、配电配置散落在各个文件里无法跨项目复用生命周期上限工勘图是「一次性交付物」之后的上架、扩容、变更、退役记录落在别处图纸很快过期。机房的真实生命周期是现场工勘 → 平面设计 → 校核 → 交付 → 资源入库 → 运维变更。DCDesigner 覆盖前四步nVisual Studio 承担后两步——回传接口就是把两者接上的那个动作。二、提交什么就是那份工勘 JSON顶栏「导出」按钮右侧的「提交 nVisual Studio」云朵上传图标中英阿西四语跟随界面语言打开提交对话框一次性填写三项配置字段说明nVisual Studio 地址URL无协议自动补http://、去末尾斜杠API Key第二个字段已保存时只以23 个星号掩码显示聚焦输入框即清空可重填、留空则沿用已保存 Key视图节点 IDdiagramId目标机房/视图节点的数字 ID如24000000000001三项配置只存本浏览器 localStorageidc2d_nvisual_v1下次打开自动回显。对疑似被截断的 JWT签名段短于算法应有长度给出内联提示避免复制残缺 token 造成平台 401。上传内容与「保存」写出的文件完全同源{ name, meta, objects }单位毫米、西南角为原点。其中name→ 目标视图节点名称meta勘测人/日期/园区楼宇/结构层高/吊顶/架空地板/等级/供电容量/制冷架构/电力模块/承重/温湿度→ 节点属性objects→ 带全部类型与属性机柜u/w/d/h/power/rpdu/voltage/current/sockets/wireSize、墙板厚/墙高/材质、门窗/格栅挂墙wallIdt、桥架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_BROWSER1无需安装 Go/Nodedata/目录自动创建在 exe 旁零依赖 Node 版node server.js或npm start两者接口与行为一致六个平台产物Windows x86_64 / Windows on ARM / Linux x86_64 / Linux arm64鲲鹏/飞腾/树莓派/ macOS Intel / macOS Apple Silicon全部CGO_ENABLED0交叉编译 -trimpath单文件免装运行时子路径反代在线版部署在/designer/时前后端都无需改代码基路径自动识别。5.2 多语言界面支持中文 / English / العربية / Español四种语言切换即时生效、无需刷新语言记忆在 localStorage首次访问按浏览器语言识别阿拉伯语下html dirrtl布局镜像但画布坐标系不受影响建模数据与图纸方向始终一致编号模板等拉丁技术串做双向文字隔离处理。对象属性中的枚举值以中文为数据键存储——旧项目文件任意语言互相打开均兼容。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.js、public/js/nvsubmit_core.js接口契约、字段映射、错误码对照docs/nVisual提交接口-import_survey.md代理行为multipart、鉴权双头、白名单、体积与超时server.js/main.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.mjs node tests/nvisual-proxy.test.mjs node tests/nvisual-proxy.test.mjs go node tests/nvisual-submit.cdp.mjs # 需先启动服务与无头 Chrome 调试端口