CAD 转换器能力说明

为支持 CAD 类文件的在线预览，系统内置 CAD 转换器，用于将 DWG / DXF 等 CAD 图纸文件转换为可预览的中间格式（如 PDF）。 该能力通过配置即可启用，支持灵活的渲染参数控制，并与整体转换调度体系无缝集成。

一、CAD 转换器配置说明

系统通过 application.yml 对 CAD 转换能力进行统一管理，核心配置如下：

# CAD 转换配置
cad:
  convert:
    cad2x:
      enable: true  # 是否启用转换器

# CAD2X 转换器配置
cad2x:
  converter:
    # cad2x 可执行文件路径（留空则自动检测）
    # 建议生产环境显式配置
    path: 
  temp:
    # 转换临时目录（留空使用系统临时目录）
    dir: /var/app/fileview-backend/fileTemp/cad2x
  conversion:
    timeout: 120  # 转换超时时间（秒）
  options:
    center: true
    encoding:
    font:
    fontDirs:
    page: 2970x2100
    margins: 2.0,2.0,2.0,2.0

二、核心配置项语义说明

1. CAD 转换能力开关

• 配置项：cad.convert.cad2x.enable
• 作用：控制 CAD2X 转换器是否参与 CAD 文件转换。

行为说明：

• 当配置为 false 时：
  • 系统将直接判定 CAD 转换服务不可用
  • 不再尝试调用外部 CAD2X 进程

适用场景：

• 精简部署（无 CAD 需求）
• 临时下线 CAD 能力
• 多引擎环境中的能力控制

2. CAD2X 可执行文件路径

• 配置项：cad2x.converter.path
• 作用：指定实际调用的 CAD2X 二进制文件。

行为说明：

• 若显式配置路径：
  • 优先使用该路径
• 若未配置：
  • 系统将根据运行环境自动检测：
    • Linux：linux_x64 / linux_arm64

生产环境建议

生产环境建议 显式指定 CAD2X 可执行文件路径，避免依赖自动探测逻辑，提高可控性与可观测性。

3. 临时目录与运行环境控制

• 临时目录：cad2x.temp.dir
• 超时时间：cad2x.conversion.timeout

作用说明：

• 临时目录用于：
  • CAD2X 进程的工作目录
  • 转换结果的中间输出兜底路径
• 超时时间用于：
  • 限制外部 CAD2X 进程最大运行时长
  • 防止复杂或异常 CAD 文件导致进程长期挂起

当超时发生时：

• 转换进程将被强制终止
• 当前转换任务判定为失败
• 系统可进入回退或错误处理流程

4. CAD 渲染与版式控制参数

cad2x.options.* 配置项会被直接映射为 CAD2X 命令行参数，用于控制最终图纸渲染效果：

配置项	含义	对应参数
center	图纸居中	-ac
encoding	文本编码	-e <encoding>
font	使用字体	-f <font>
fontDirs	字体目录	-l <dir1:dir2>
page	页面尺寸	-p 2970x2100
margins	页边距	-m 2.0,2.0,2.0,2.0

该机制使 CAD 转换效果可以通过 配置 灵活调整，而无需修改代码。

三、CAD 转换整体执行流程

1. CAD 文件进入 CAD 转换链路

• CAD 文件扩展名（如 .dwg、.dxf）
  • 在系统启动时注册为 CAD 文件类型
• 在转换调度阶段：
  • CAD 文件被识别为 CAD 转换策略
  • 路由至 CAD 转换处理流程

2. CAD 转换策略执行逻辑

在 CAD 转换过程中，系统依次完成：

1. 校验源文件与目标格式是否受支持
2. 检查 CAD2X 服务是否可用：
   • 是否启用
   • 可执行文件是否存在且可执行
   • 临时目录是否可写
3. 调用 CAD2X 执行实际转换
4. 根据输出文件是否生成且非空判定转换结果

3. CAD2X 执行与结果处理

在实际执行阶段：

• 系统根据配置动态构建 CAD2X 命令行
• 使用独立进程方式运行外部 CAD2X
• 按配置的超时时间进行控制

转换完成后：

• 若生成 PDF，自动识别并整理输出路径
• 若输出文件未出现在预期位置，进行兜底查找与移动

该流程保证了在不同 CAD 文件复杂度下，转换结果的 稳定性与可预期性。

四、总结

• 统一开关控制
  通过 cad.convert.cad2x.enable 支持一键启停 CAD 转换能力。

• 生产级路径控制
  支持显式指定 CAD2X 可执行文件路径，避免环境不确定性。

• 稳定性保障机制
  通过临时目录 + 进程超时控制，防止 CAD 转换异常拖垮系统。

• 高可配置渲染能力
  渲染参数与命令行直连，满足不同 CAD 图纸的版式与展示需求。