24 KiB
Geopro 3.0 桌面客户端技术选型与架构规约
版本 v1.1 · 适用范围:Geopro 3.0 桌面版「项目分析视图」首版及后续演进
1. 文档概述
1.1 目的
本文档为 Geopro 3.0 桌面客户端的技术选型结论、技术栈与依赖库规约、界面组件规约、配置与缓存规约、动态升级规约、许可证合规要求,以及面向 AI 辅助编码的工程实践规约。文档作为开发团队的技术基线,后续编码、依赖引入、架构设计均应以本文档为准。
1.2 适用范围
首版(v1)聚焦于「项目分析视图」这一核心页面,即包含对象列表、二维/三维地图、数据集列表、数据集详情等板块的多面板工作台。启动登录、项目管理、设备连接、平台后台、Web 端等模块不在首版范围内,但本文档的技术选型已为其后续演进预留了架构空间。
1.3 读者对象
项目技术负责人、架构师、开发团队,以及负责许可证与商务合规审查的相关人员。
1.4 重要约定
关于编码方式的前提 本项目开发团队 100% 依赖 AI 辅助编码(Claude Code)完成实现。这一前提显著影响了选型逻辑:传统意义上「某语言开发更快」的人力效率差异在 AI 编码下被大幅抹平,因此选型回归到软件本身的长期质量属性——性能上限、部署形态、可维护性、生态契合度、代码资产保护。 本文档不包含任何代码实现,仅规定技术方向、依赖边界与工程约束。
2. 功能范围概要
本章为桌面客户端功能的概要清单,仅作范围界定,每项一句话;详细需求以需求文档与原型为准。
2.1 客户端基础能力
| 功能 | 概要 |
|---|---|
| 启动 / 登录 | 用户登录与启动画面展示。 |
| 工作空间切换 | 在企业空间与个人空间之间切换。 |
| 项目列表 / 选择 | 浏览并进入当前空间下的项目。 |
| 平台通知 | 接收平台推送的消息。 |
| 个人资料 / 登录状态 | 查看个人信息与登录状态管理。 |
| 偏好设置 | 配置客户端的本地偏好。 |
| 在线更新 | 检测并升级客户端版本。 |
2.2 项目分析视图(核心工作台)
| 功能 | 概要 |
|---|---|
| 对象列表 | 展示并管理项目下的对象。 |
| 数据集列表 | 展示当前对象下的数据集。 |
| 二维视图 | 在地图底图上展示对象与数据集的平面视图。 |
| 三维视图 | 以三维形式展示剖面、切片、模型等数据。 |
| 对象属性 / 异常 | 查看对象属性,管理异常与异常体。 |
| 数据集属性 / 任务 | 查看数据集属性及其处理任务。 |
| 数据集详情 | 集中展示数据集的详情内容。 |
范围说明:首版(v1)交付范围为「项目分析视图」及其依赖的客户端基础能力。数据集在二维/三维视图中能否显示及显示方式,均由其 dd 类型定义;各板块间的联动(对象勾选驱动视图刷新、列表与详情定位)构成该视图的主要复杂度。
3. 目标平台与最低版本
3.1 最低系统版本
| 平台 | 最低版本 | 说明 |
|---|---|---|
| Windows | Windows 10 64 位(22H2) | 仅支持 64 位;仅限 Win10 最终功能版本 22H2,不兼容更早版本。 |
| macOS | macOS 12 Monterey | Apple 用户升级积极,支持过老版本收益极低;如目标用户机器较新可提至 macOS 13。 |
3.2 版本约束链条
- Qt 锁定 6.8 LTS:该版本同时覆盖上述两端最低版本,并提供五年长期支持,与产品生命周期匹配。
- Windows 10 与 Qt 版本上界绑定:Qt 6.12 为最后一个支持 Windows 10 的版本;在仍需支持 Win10 的周期内,Qt 不得升级越过 6.12。
- Windows 10 现状:微软已于 2025 年 10 月终止 Win10 支持(消费者 ESU 延至 2026 年 10 月),但行业现场作业机器存量大,首版保留支持;路线图中应明确未来某大版本起转向 Windows 11-only,届时方可解锁 Qt 6.12 以上版本。
- 编译器:Windows 侧 MSVC 2022,macOS 侧对应较新 Xcode/Clang;语言标准 C++17(可渐进使用 C++20 特性)。
3.3 macOS 专项约束与风险
- 构建为 Universal Binary(arm64 + x86_64),优先保证 arm64 原生:Mac 已全面转向 Apple Silicon 且 Intel 支持临近终止;VTK 重渲染负载经 Rosetta 转译损失可观,所有依赖须具备 arm64 构建。
- OpenGL 废弃风险(挂入风险清单):Apple 已废弃 OpenGL(停留 4.1)并主推 Metal,而 VTK 默认渲染后端为 OpenGL;短期可用,长期须持续跟踪 VTK 的 Metal/WebGPU 后端成熟度。
4. 技术选型决策
4.1 选型结论
桌面客户端采用 Qt(C++)+ VTK(C++) 作为核心技术栈。
核心依据:Geopro 3.0 桌面客户端在本质上是一款科学可视化软件,其数据类型(电法、地质雷达、地震、磁法、电磁、钻探等)与可视化范式(剖面、切片、点云、三维属性模型、三维结构模型、地图叠加)与 ParaView、QGIS、3D Slicer、地质/油气勘探软件属于同一谱系。这一谱系的行业标准技术栈即为 Qt + VTK 的 C++ 实现。
4.2 关键质量属性与选型对应
| 质量属性 | 说明 | Qt C++ + VTK 的契合度 |
|---|---|---|
| 大数据渲染上限 | 三维地震体、亿级 LiDAR 点云、电法全波形等大体量数据的流畅交互 | 最高,可直接调用 OpenGL/并行,无 WebGL 天花板 |
| 专业可视化表达 | 色阶、图例、切片、等值面、glyph、标注的精细控制 | VTK 原生能力最完整 |
| 设备集成深度 | 厂商设备 SDK 多为 C/C++ 动态库,需直接链接 | 同语言直链,无桥接层 |
| 桌面工作流 | 多窗口、停靠面板、拖拽、快捷键、文件关联、打印 | Qt 提供原生桌面体验 |
| 代码资产保护 | 反演算法、设备协议等核心资产的反编译防护 | 编译产物逆向门槛高 |
| 部署形态 | 安装包体积、运行时依赖、跨平台一致性 | 单一原生可执行,依赖可控 |
4.3 备选方案及其适用条件
| 备选方案 | 唯一应当选用的条件 | 当前是否命中 |
|---|---|---|
| PySide6 + VTK(Python) | 团队重度依赖 Python 地球物理算法生态(如 SimPEG、ResIPy、ObsPy 等),且不希望承担跨语言桥接成本 | 取决于算法语言,见 4.4 |
| Electron + vtk.js | 数据规模长期稳定在中等水平、不触及 WebGL 上限,且对跨平台 UI 一致性与启动体验有极高要求 | 未命中 |
关于 PySide6 的补充说明:PySide6 与 Qt C++ 共享同一套底层 Qt 引擎,UI 渲染与 VTK 渲染性能几乎无差异,API 亦近乎一一对应。两者的真实差异在于:算法生态(Python 占优)、部署体积(C++ 占优)、代码保护(C++ 占优)。若后续确有强 Python 算法依赖,推荐的折中路径是:主框架保持 Qt C++,将 Python 算法以「进程隔离」方式接入(见第 8 章动态升级中的插件架构),而非整体改用 PySide6。
4.4 待确认的关键前提
本选型结论成立的关键前提是反演与数据处理算法的语言归属,需在开发启动前确认:
- 若算法为自研 C++ 或计划用 C++ 实现 —— Qt C++ + VTK C++ 形成完美闭环,无需跨语言。
- 若算法重度依赖 Python 生态(注:ResIPy 反演框架本身即为 Python 包)—— 应采用进程隔离架构接入 Python 算法,主框架仍为 Qt C++。
- 两者并存 —— 主框架 Qt C++,C++ 算法内嵌,Python 算法经进程隔离接入。
5. 技术栈与依赖库规约
「必选」为项目基线,「推荐」依据实际需求引入。所有第三方依赖须经第 9 章许可证矩阵审查后方可正式引入。
5.1 框架内核
| 项 | 选用 | 说明 |
|---|---|---|
| 框架 | Qt 6.5/6.8 LTS | 采用 Qt 6 LTS;不使用 Qt 5。UI 主框架采用 QtWidgets,不采用 QML 作为主框架。 |
| 核心模块 | QtCore/Gui/Widgets | 对象系统、信号槽、控件体系。 |
| 网络模块 | QtNetwork/WebSockets | REST 通信与设备实时数据流、平台通知推送。 |
| 数据库模块 | QtSql | SQLite 访问抽象层。 |
| 并发模块 | QtConcurrent | 耗时任务线程池。 |
| Web 嵌入 | QtWebEngine | 后续嵌入 Web 端页面(设备管理、企业大屏、报告预览等)。 |
| 设备串口 | QtSerialPort | 串口设备通信。 |
| 国际化 | Qt Linguist(内置) | 中英文双语。 |
Qt 许可证须优先决策:Qt 提供 LGPLv3 / GPLv3 / 商业授权。闭源商用若走 LGPLv3,须严格动态链接并允许用户替换 Qt 库;部分模块(QtWebEngine、QtCharts)限制不同。此为商务与法务问题,优先级高于技术实现。
5.2 三维可视化
| 项 | 选用 | 说明 |
|---|---|---|
| 渲染核心 | VTK 9.3+ | 经 QVTKOpenGLNativeWidget 集成进 Qt;需协调 VTK 交互器与 Qt 事件循环。 |
| 体绘制 | VTK Volume 模块 | 三维属性模型(dd_Property3D)所需。 |
| 切片/等值面 | VTK Filters 模块 | 水平切片、任意角度切片、isosurface。 |
| 点云高级处理 | PCL(推荐) | 如需 KD-tree 加速、配准、分割;仅显示则 VTK 自带即可。 |
5.3 二维地图
| 方案 | 定位 | 说明 |
|---|---|---|
| VTK 一统(首选) | 首版采用 | 二维视图为相机俯视锁定的 VTK 渲染;底图作地面纹理,矢量对象用 VTK actor 渲染。二维/三维共享对象、色阶与坐标系。底图瓦片经 GDAL/网络层下载缓存。 |
| MapLibre Native | 备选 | BSD 许可,矢量瓦片支持完整。若 VTK 二维地图交互体验达不到预期,作为独立二维引擎并列。 |
| QGIS Core 嵌入 | 谨慎 | GIS 能力最强,但依赖复杂且 GPL 许可,闭源商用须高度谨慎。 |
5.4 构建与依赖管理
| 项 | 选用 | 说明 |
|---|---|---|
| 构建系统 | CMake 3.21+ | Qt 6 官方推荐;不采用 qmake。 |
| 包管理 | vcpkg(推荐) | 统一管理依赖,严禁手动管理(手动依赖降低 AI 编码上下文准确度)。Conan 备选。 |
| 编译数据库 | compile_commands.json | 供 clangd、静态分析与 AI 工具获取完整上下文。 |
5.5 网络与通信
| 项 | 选用 | 说明 |
|---|---|---|
| HTTP/REST | QtNetwork | 与 Qt 事件循环原生集成。 |
| 实时通信 | QtWebSockets | 在线监测数据流、设备状态、平台推送。 |
| JSON | nlohmann/json(推荐) | 现代 C++ JSON 库,header-only。 |
| 大数据传输 | FlatBuffers / Protobuf(推荐) | 三维数据、点云等大体量下载远优于 JSON。 |
| 客户端代码生成 | openapi-generator(推荐) | 若 Web 端有 OpenAPI 文档,生成 C++ DTO。 |
5.6 数据存储
| 项 | 选用 | 说明 |
|---|---|---|
| 结构化数据库 | SQLite(QtSql) | 项目本地缓存、对象/数据集元数据、关系索引、操作历史。 |
| 大文件存储 | HDF5 / VTK 原生格式 | 严禁大二进制以 BLOB 入 SQLite;「元数据进库、大文件进文件系统」。 |
| 轻量封装 | SQLiteCpp(可选) | 简化访问。 |
配置与缓存的存储归属另见第 7 章,与 SQLite 职责严格区分。
5.7 数学与算法库
| 项 | 选用 | 说明 |
|---|---|---|
| 线性代数 | Eigen | C++ 数值计算事实标准。 |
| 坐标系/投影 | PROJ(推荐) | WGS84/UTM/本地坐标系转换,必备。 |
| 地理数据 I/O | GDAL/OGR(推荐) | 支撑 dd_KML/dd_GeoJson/dd_shp/dd_dem 导入。 |
| 几何运算 | GEOS | 多边形相交、缓冲、空间关系。 |
| 点云 I/O | PDAL(推荐) | LAS/LAZ 等;LiDAR 必备。 |
| 通用工具 | fmt | 字符串格式化。 |
| 按需子库 | Boost(按需) | 不默认全量引入。 |
5.8 文件格式与导入导出
| 需求 | 选用 | 说明 |
|---|---|---|
| GIS 矢量/栅格/DEM | GDAL/OGR | KML、GeoJSON、Shapefile、GeoTIFF、DEM。 |
| BIM(IFC) | IfcOpenShell | dd_bim 解析。 |
| 地震 SEG-Y | libsegyio(按需) | 直接读 SEG-Y。 |
| Excel 报告 | OpenXLSX / libxlsxwriter | 读写 Excel。 |
| Word/PPT 报告 | 模板填充方案待定 | 无理想 C++ 库;LibreOffice headless 或外部服务。 |
| DWG/DXF 报告 | libDXFrw(DXF) | DWG 完整支持需商业库或 GPL 的 LibreDWG,须审查许可证。 |
| PDF 报告 | QPdfWriter / PoDoFo | 简单用 Qt 自带,复杂版面用 PoDoFo。 |
| 报表引擎 | LimeReport(可选) | 复杂模板可选用。 |
5.9 设备通信
| 类型 | 选用 | 说明 |
|---|---|---|
| 串口 | QtSerialPort | Qt 官方串口模块。 |
| USB / HID | libusb / hidapi | USB 与 HID 设备。 |
| 工业总线 | libmodbus(按需) | Modbus 设备。 |
| 厂商 SDK | C++ 直接链接 | 厂商动态库直链,无桥接层。 |
5.10 日志、监控与测试
| 项 | 选用 | 说明 |
|---|---|---|
| 日志 | spdlog | 结构化、分级、滚动文件;禁止 qDebug 作生产日志。 |
| 崩溃监控 | Sentry C++ / Crashpad | 自动采集崩溃栈;数据安全要求高则自有服务器上报。 |
| 单元测试 | Qt Test + Google Test | Qt Test 测 UI/Qt 相关,gtest 测纯业务。 |
| Mock | Google Mock / trompeloeil | 配合测试框架。 |
| 静态分析 | clang-tidy + cppcheck | 强制纳入 CI。 |
| Sanitizers | ASan/UBSan/TSan | Debug 构建启用。 |
5.11 安全
| 项 | 选用 | 说明 |
|---|---|---|
| 传输/加密 | OpenSSL | HTTPS、JWT、签名校验;Windows 须随包分发。 |
| 现代加密 | libsodium(可选) | X25519/ChaCha20-Poly1305/Argon2。 |
| 凭证存储 | QtKeychain(推荐) | 对接三平台密钥库;凭证严禁明文存储。 |
6. 界面组件规约
Qt C++ 的 UI 组件生态不如前端繁荣,因 QtWidgets 本身已是完整组件库,第三方库多为「补充特定缺失」。
6.1 UI 技术路线
主框架采用 QtWidgets,不采用 QML 作为主框架。IDE 风格「窗口 + 菜单 + 停靠面板」工作台正是 QtWidgets 的设计本位;QML 可局部用于色阶编辑器等视觉化小组件。
6.2 停靠布局框架(核心)
| 框架 | 定位 | 说明 |
|---|---|---|
| Qt-Advanced-Docking-System (ADS) | 首选 | 体验接近 Visual Studio;LGPL v2.1,商用友好。 |
| KDDockWidgets | 备选 | KDAB 出品,质量顶级;GPL/商业双授权,闭源商用须购买。 |
布局/透视图状态序列化后与 QSettings 配合持久化。该框架须早期确定并据此设计窗口架构。
6.3 主题与外观
| 项 | 选用 | 说明 |
|---|---|---|
| 皮肤机制 | QSS(内置) | Qt 样式表,零依赖。 |
| 现成主题打底 | QDarkStyleSheet / BreezeStyleSheets | 成熟深色主题,套用后按品牌定制。科学软件主流为深色主题。 |
| 终极定制 | 自定义 QStyle | 一般不必。 |
6.4 专业控件与图标
| 需求 | 选用 | 说明 |
|---|---|---|
| 图标 | QtAwesome | 图标字体,矢量、可染色、随主题变色。 |
| 科学曲线 | QCustomPlot / QWT | 测井曲线、时序监测曲线。QWT 商用友好;QCustomPlot 有商业版。 |
| 脚本编辑器 | QScintilla(按需) | 「电法脚本与装置」编辑;注意许可证。 |
| 节点管线编辑 | QtNodes(按需) | 「数据→模型→输出」可视化连线。 |
| 属性表单 / 色阶编辑器 | 自研 | 「按对象类型动态生成表单」「多模态显示」「色阶命名保存」需高度定制;色阶可基于 VTK 颜色传递函数构建。 |
7. 配置与缓存管理规约
核心原则:按「数据的生命周期与归属」分类存储。Qt 原生能力基本覆盖,无需第三方库(QtKeychain 除外)。
7.1 路径定位基础
所有本地落盘路径一律经 QStandardPaths 获取平台规范目录,严禁手动拼接。须严格区分 AppConfigLocation(配置)、CacheLocation(可丢弃缓存)、AppDataLocation(持久数据)、DocumentsLocation(用户导出)、TempLocation(临时)。缓存目录被清空时应用必须能正常重建。
7.2 配置管理
- 用户偏好(主题、字体、启动停留时间、默认大屏等)→ QSettings。
- 窗口几何与停靠布局状态 → 序列化后存入 QSettings,与 ADS 配合。
- 为支持绿色部署,Windows 可强制 QSettings 使用 INI 格式而非注册表。
- 项目级业务设置(坐标系、底图、异常类型、自动任务、告警级别等)严禁使用 QSettings,因其属「项目数据」,须跟随项目存储(SQLite 或项目目录文件)以便整体导出、迁移与共享;复杂嵌套配置采用 JSON(nlohmann/json)。
7.3 缓存管理
| 缓存类型 | 选用 | 说明 |
|---|---|---|
| 内存缓存 | QCache / QPixmapCache | 容量上限 + LRU 淘汰;解析后对象、缩略图。 |
| 网络/瓦片缓存 | QNetworkDiskCache | 按 HTTP 缓存语义自动缓存 REST 响应与地图瓦片。 |
| 大文件缓存 | 文件系统 + SQLite 索引 | 大二进制存文件系统,元数据与淘汰索引存 SQLite;自行实现按大小/LRU 淘汰。 |
7.4 安全凭证
需持久化的 token/凭证严禁明文存入 QSettings 或 SQLite,一律经 QtKeychain 存入平台密钥库。
7.5 存储归属总表
| 数据类型 | 存储位置 | 理由 |
|---|---|---|
| 用户偏好 | QSettings | 少量键值,跟随用户/机器 |
| 窗口几何、停靠布局 | QSettings(字节数组) | Qt 序列化直接支持 |
| 项目业务设置 | SQLite / 项目文件 | 属项目数据,须随项目导出 |
| 对象/数据集元数据、关系、索引 | SQLite | 需查询、关联、事务 |
| 操作历史、任务记录 | SQLite | 结构化、需查询 |
| 内存中间数据、缩略图 | QCache / QPixmapCache | 临时、带淘汰 |
| REST 响应、地图瓦片 | QNetworkDiskCache | HTTP 缓存语义、可丢弃 |
| 大文件(地震/点云/原始数据) | 文件系统 + SQLite 索引 | 大二进制不入库 |
| token / 凭证 | QtKeychain(密钥库) | 安全要求 |
8. 动态升级规约
结合业务特征(算法模型、设备驱动、报告模板需独立更新),采用三通道更新架构。
8.1 三通道更新架构
| 通道 | 对象 | 更新频率 / 生效方式 |
|---|---|---|
| 通道一:应用本体 | 主程序、核心库 | 低频 / 重启生效。差分整包更新。 |
| 通道二:算法插件 | 反演、处理等算法模型 | 中高频 / 进程隔离,替换插件文件后下次调用生效,不影响主程序。 |
| 通道三:资源数据 | 报告模板、设备驱动、配置 | 高频 / 从平台 API 按需同步,无需重启。 |
8.2 通道一:应用本体更新
自实现差分更新流程,统一三平台逻辑并自主控制下载源:
- 客户端定期向更新服务器请求版本清单(manifest)。
- 比对版本,下载差分包或整包至临时目录。
- 校验数字签名与哈希,全部通过后方可替换。
- 由独立的 updater 进程在主程序退出后完成文件替换,再重启主程序。
差分库推荐 HDiffPatch 或 zstd patch-from。
必须守住的工程约束:
- 文件占用:运行中的可执行文件无法被覆盖(Windows 尤甚),须由独立 updater 进程在主程序退出后替换。
- 原子性:校验全部通过后一次性替换;失败可回滚(旧版本重命名或双目录指向切换)。
- 签名验证:更新包以离线私钥签名,客户端内置公钥验证;私钥严禁进入代码库。
- 灰度与回滚:manifest 支持灰度比例;客户端记录上一可用版本,升级后启动失败可自动回滚。
- 强制更新:manifest 标记最低支持版本,低于此版本强制升级。
8.3 通道二:算法插件架构
算法插件采用进程隔离架构:每个算法为独立子程序,主程序经本地 socket / 共享内存与之通信。理由:
- 崩溃隔离:科学计算易因数值问题崩溃,隔离后不拖垮主程序。
- 语言无关:插件可用 C++、Python、Rust 等任意语言实现,不受 C++ ABI 约束(直接支撑 ResIPy 等 Python 算法接入)。
- 更新简单:替换子程序文件即完成更新,不影响主程序。
- 可并行、可做资源限制。
ABI 兼容性提示:若未来确有同进程 C++ 插件需求(Qt Plugin 机制),主程序与插件必须使用兼容编译器、相同 C++ 运行时与相同 Qt 版本编译,且插件接口仅暴露 C ABI 兼容类型。进程隔离架构从根本上规避了这一整类问题,故为首选。
8.4 统一版本清单
三通道由统一 manifest 描述,至少包含:应用本体的版本号、最低支持版本、下载地址、差分基线、签名;各算法插件的版本与哈希;各设备驱动与模板的版本与地址。
9. 许可证合规矩阵
强制要求:C++ 依赖的许可证直接决定能否闭源商用。AI 编码工具不会主动提示许可证风险,须由人工管理。所有依赖正式引入前须经法务复核,并随项目维护更新。
| 依赖 | 许可证 | 闭源商用 | 备注 |
|---|---|---|---|
| Qt 6 | LGPLv3 / 商业 | ⚠️ 需决策 | LGPL 须动态链接;或购商业授权 |
| VTK | BSD | ✅ 友好 | 宽松许可 |
| Eigen | MPL2 | ✅ 友好 | |
| GDAL / PROJ / GEOS | MIT / X11 类 | ✅ 友好 | |
| PDAL | BSD | ✅ 友好 | |
| PCL | BSD | ✅ 友好 | |
| nlohmann/json | MIT | ✅ 友好 | |
| spdlog / fmt | MIT | ✅ 友好 | |
| OpenSSL | Apache 2.0 | ✅ 友好 | 1.1.1 起为 Apache 2.0 |
| QtKeychain | BSD | ✅ 友好 | |
| ADS(停靠框架) | LGPL v2.1 | ✅ 友好 | 动态链接 |
| KDDockWidgets | GPL / 商业 | ⚠️ 需购授权 | 闭源商用须购买 |
| QWT | QWT License(LGPL 变体) | ✅ 友好 | |
| QCustomPlot | GPL / 商业 | ⚠️ 需购授权 | 有商业版 |
| QScintilla | GPL / 商业 | ⚠️ 需购授权 | 须审查 |
| QGIS Core | GPL | ❌ 高风险 | 嵌入可能要求开源,慎用 |
| LibreDWG | GPL | ❌ 高风险 | DWG 需求建议另寻方案 |
| HDiffPatch | MIT 类 | ✅ 友好 | 差分更新 |
10. 面向 AI 编码的工程实践规约
团队 100% 依赖 Claude Code 编码,以下为强制规约。
10.1 代码与上下文基础设施
- clang-format:强制统一代码风格,约束 AI 输出风格漂移。
- clangd LSP + .clangd 配置:为 AI 工具提供精确类型信息。
- compile_commands.json:由 CMake 生成,提供完整依赖上下文。
- cmake-format:CMake 文件亦统一格式。
10.2 质量兜底
- clang-tidy + cppcheck 纳入 CI:捕获 AI 易产生的冗余拷贝、生命周期与反模式问题。
- Debug 构建启用 Sanitizers(ASan/UBSan/TSan):兜底未定义行为与数据竞争。
- 跨平台 CI(Windows/macOS):平台相关逻辑(文件占用、.app bundle、权限)须显式封装并提醒 AI 处理差异。
- 失败路径测试:AI 易只写正常路径;更新中断、签名错误、替换失败等失败分支须明确要求覆盖。
10.3 架构与规范约束
- 清晰分层目录:core(纯业务,不依赖 Qt)/ data(数据访问)/ view(视图)/ controller(控制)/ app(入口装配)。
- 架构规约文档供 AI 读取:明确诸如「VTK actor 统一由视图模型管理,禁止 Widget 直接持有」「信号槽连接集中于初始化方法」等约束。
- 强类型与文档注释:public API 强制 Doxygen 注释。
- 严格锁定依赖版本:经 vcpkg/Conan 锁版本,避免 AI 在不同版本 API 间混用。
- 私钥与密钥不入库:明确禁止 AI 将示例密钥写入代码;签名私钥离线保管。
10.4 须保留的人工角色
AI 编码降低了「编写业务代码」的成本,但「构建、部署、工程化」的成本几乎不变。须保留至少一名具备 C++ 工程化能力的工程师,负责构建系统、依赖管理、跨平台打包,以及对 CMake、打包脚本等 AI 输出不稳定产物的复核。
11. 待决策事项汇总
| 编号 | 事项 | 影响 |
|---|---|---|
| D-1 | 反演/处理算法的语言归属 | 决定是否需进程隔离接入 Python 算法,以及是否动摇 Qt C++ 主框架的最终成立(见 4.4)。 |
| D-2 | Qt 许可证:LGPL 严格动态链接 vs 购买商业授权 | 商务与合规前提,优先级高于技术实现(见 5.1)。 |
| D-3 | 首版是否即建立完整插件架构,或先硬编码少数算法、后续再抽象 | 影响 v1 工作量与架构投入(见 8.3)。 |
| D-4 | 算法插件是否需支持第三方/客户自行开发 | 进一步强化进程隔离的必要性。 |
| D-5 | 二维地图首版采用 VTK 一统是否满足交互体验预期 | 若不满足则引入 MapLibre Native(见 5.3)。 |
| D-6 | 全部第三方依赖的许可证法务复核 | 决定可否闭源商用(见第 9 章)。 |
| D-7 | Word/PPT 报告的生成方案 | 目前无理想 C++ 库,须确定模板填充路径(见 5.8)。 |
| D-8 | 目标客户中 Windows 10 机器的实际占比 | 决定首版是否保留 Win10 支持,或直接 Windows 11-only 以解除 Qt 版本上界束缚(见第 3 章)。 |
本文档由技术选型讨论整理而成,作为开发基线;随项目推进应持续维护版本。