BIM引擎底座 · 概要设计

文档版本：0.35 ｜ 最近核对日期：2026-11-09

1. 设计范围与当前事实

2026-11-09范围调整：用户将PAK支持及样本验证放到后续，首期按RVT收口；既有PAK预留不等于验证通过，也不因延期拆除存量结构。

本设计落实需求分析已确认的首期模型基础能力。2026-11-08 已按本设计实现前后端并在开发库建表：导航台账、资产与版本、引擎适配与持久任务、全量解析、预览上下文与检查后发布。内网真实 RVT 已完成转换、文件/构件枚举与分组属性读取，并按真实样本完成几何预览、检查后发布与历史版读取；PAK 与同工点多模型叠加仍属未验证范围。详见测试与验收。

相较此前讨论稿，首期移出进度、CAD、业务绑定及继承界面，增加明确的全量构件与属性入库要求。2026-11-08进一步确认模型归属单位工程、导航树作为主入口，工点用于汇总；不使用独立查询卡。平台保留后续接入能力，不提前建设下游规则。

2. 架构与责任边界

责任方	负责	不负责
工程基础	单位工程及线路/标段/工点/专业归属、双视图导航与专属授权	引擎数据集和构件存储
BIM应用服务	资产、版本、任务、解析快照、发布、数据权限	进度状态、CAD 图纸业务、工程量计算口径
黑洞适配器	服务端认证、上传/转换、状态归一、解析读取、资源描述转换	决定哪个业务版本已发布、直接授予平台用户权限
黑洞部署	文件转换、几何资源及引擎元数据能力	平台业务审批及工程数据授权
BimViewer	加载、视角、选择、显隐、树与属性交互	保存业务台账、处理进度规则、持有服务端管理员凭据
后续业务模块	自己的业务对象、统计口径及关联规则	重新建设模型上传转换与版本台账

后端拟设独立 BIM 模块，跨模块能力通过项目现有 API 契约层调用，不能直接依赖工程基础实现包形成循环依赖。若现有授权工具仅在业务实现模块可见，实施时提供薄的 API 服务桥接，继续复用其规则。

3. 核心数据模型

采用六张业务表：模型资产、模型版本、处理任务、版本内部文件、构件、构件属性。结构详见数据库设计。

• 模型资产只关联单位工程；线路、标段、工点和专业由工程主数据解析，不重复维护归属列。一个单位工程可有多个资产，当前发布版本是资产的一个指针。
• 版本关联一份原文件和一个独立黑洞数据集；转换、解析及发布各有独立含义。
• 每次处理尝试有任务记录。文件、构件及属性快照归属该任务；版本只将完整成功的一次任务作为可见解析快照。
• 内部文件用于保留转换产物中的文件作用域。构件运行时 ID 在版本与文件内解释；稳定标识允许缺失或重复，不将其强制当主键。
• 属性采用逐条存储，保留分组和原始值；不把整模型属性只存成一个不可检索的大 JSON。

首期构件树由后端适配引擎目录接口、按版本读取。全量构件和属性由平台数据库提供，不以每次点击实时读取引擎代替入库。不重复持久化整套引擎树；后续如果离线树读取成为真实需求，再评估持久化。

4. 版本隔离决策

首期采用一个平台版本对应一个独立黑洞数据集，记录该数据集成功转换版本及资源标识。平台业务版本号与引擎内部版本号互不替代。

理由：历史版本必须保持几何、树与属性一致，而黑洞部分全量属性接口没有版本入参。若多个业务版本共用可变数据集，容易发生旧画面读取新属性。每版独立数据集，使无版本入参接口也落在该版固定资源范围内，并简化已发布快照保护。

代价是保留多份资源和转换数据。首期不自动清理历史数据集，不调用厂商版本对比功能；后续容量治理单独明确保留周期。该选择仍需在目标部署验证资源不被覆盖、删除或后台整理；不能因为设计采用隔离就宣布历史访问已通过。

5. 主流程

上传原文件成功即形成版本。平台文件存储与黑洞远程调用不纳入一个长数据库事务。首期使用应用内任务执行器，复用公共 scheduledExecutorService 做轻量检查与远端状态轮询，并引入 BimTaskGuard（Redisson 分布式互斥）与引擎可达性探测保护多实例环境，以数据库任务记录补捞和恢复；不引入 RabbitMQ、新 SnailJob 服务或回调公网入口。具体阶段恢复见详细设计。

5.1 任务状态与阶段

任务状态：PENDING 待处理、RUNNING 处理中、SUCCEEDED 处理成功、FAILED 处理失败。任务阶段：REGISTER 占位登记、UPLOAD 后台传输与完成通知、CONVERT 转换、PARSE 解析入库、CHECK 完整性核查。

引擎转换原始状态单独保存并由适配器解释，不能复用黑洞其他接口同名状态枚举。引擎排队/转换百分比与平台解析完成数分别展示。

版本的处理状态通过当前任务得出；可见解析快照指针仅在成功后切换。发布标签通过发布时间及资产当前版本指针得出：未发布、当前发布、历史发布，不再维护另一套可能冲突的发布状态字段。

5.2 全量入库与失败恢复

先取得内部文件清单，再逐文件枚举全部构件，补齐分组属性，分批落库。每个成功响应的空属性结果都明确计数；错误响应不能记为空结果。核对预期构件集合、实际构件集合、成功属性读取数和入库属性数。

失败任务的部分数据只用于排障，不对普通查询暴露。重新处理产生新任务及新快照；旧失败数据暂保留，首期无自动批量清理。解析失败且转换成果有效时直接重新解析，不重新转换；上传中断需用已保存的上传记录和分片结果向引擎核实。已完成发布快照不被重新处理覆盖。远程请求结果不明时先核实，不盲目再次提交转换。

6. 预览设计

模型页以工程台账导航树定位范围，右侧展示台账和任务，不设置独立查询卡。复用单位工程台账的空间/合同视图与状态切换，BIM补单位工程叶节点；上层节点汇总模型，单位工程叶节点负责新建归属，空模型工程也可进入。模型名称和专业仅作工具栏轻量筛选。

预览作为同一业务下的沉浸式页面，共享 BimViewer 组件。待发布检查单独加载所选版本；集中查看按所选工点或单位工程的当前发布版本加载多个模型。带标段上下文时继续限定标段，不支持跨工点同场景叠加。返回保留工程导航位置。

后端生成经过授权的预览上下文，含平台版本、内部资源映射与有效加载配置。客户端不自行提交资源服务器地址、服务端数据集 ID 或任意代理目标。前端建立运行时数据集 ID 到平台版本的映射，点击构件后以该映射读取数据库属性，防止多模型同名或同 ID 串数据。

首次加载按 SDK 要求清空场景；后续增量加载使用相应参数。监听引擎创建完成后加载，逐模型判断就绪并显示结果；销毁页面时解绑事件、取消未完成请求、卸载场景。SDK/WASM/Worker 使用受控部署资产，不依赖开发者网站作为正式运行资源源站。

7. 权限与信任边界

业务访问严格按需求中的数据过滤策略执行，功能权限见详细设计。BIM 服务校验资产归属并传递受限上下文；后台任务只使用自身版本记录中已验证的归属。

模型跟随单位工程的标段工点专属范围，工点汇总是授权单位工程的并集，不沿用早期工点共享方案。单位工程删除和标段调整引起的间接删除须经BIM引用检查；实现包之间通过API契约协作。

首期保留平台登录、后端功能/工程权限及服务端凭据保护，几何按已核实的现有部署方式加载，验证SDK子资源、Worker、Range、跨域等实际兼容性。源站匿名旁路封闭、短期票据与撤权失效作为后续加固，不阻塞本期基础业务闭环，也不新开匿名资源入口或关闭现有保护。客户端认证材料仅使用厂商允许的客户端用途，不能返回服务端Token或管理员凭据。

8. 实施依赖与风险

依赖	影响与处理
内网转换及几何链路	当前记录有转换停滞及几何未显示，需定位转换组件、资源服务、SDK兼容性；原因未证实前不归咎单一部署配置
元数据接口契约	以目标部署实际RVT返回及覆盖证据固化适配器测试；2026-11-09用户将PAK支持延期，不作为本期完成门槛
全量导出与属性补齐成本	文件全量接口可能响应较大，采用流式读取和分批写入；按真实规模测量，不以 SDK 画面流畅推断解析性能
稳定标识	文件及构件标识是否跨版本稳定须实测；首期保存事实，未知时标为未知，不自动继承错误关联
同工点叠加	依赖源模型统一坐标；不额外建设配准工具
工程归属联动	需验证树上范围与列表一致、专属授权、单位工程引用保护及原台账回归
资源与历史保留	首期验证实际加载、已发布快照及历史资源；源站隔离与失效治理后置，不声称已实现完整资源安全闭环

2026-11-08 实施结果：开发库已建六表并启用「BIM底座 → 模型管理」菜单；应用侧新增独立 digital-construction-bim 模块、business 侧工程归属桥接与三处引用保护；未访问生产、未发布文档站。