# catia-step

**Repository Path**: zy188-code-wizard/catia-step

## Basic Information

- **Project Name**: catia-step
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CATIA STEP Exporter

一个面向 Windows + CATIA COM 的批量导出工具，用于把 `CATPart` / `CATProduct` 批量导出为 `STP` 文件。

它适合处理大批量目录，并针对长时间跑批补了几项实用能力：

- 支持目录递归扫描
- 支持只导出 `CATPart`
- 支持断点续跑
- 支持失败日志落盘
- 支持运行状态心跳、当前文件跟踪与卡死预警
- 支持周期性重启 CATIA 会话，降低长批处理内存膨胀风险
- 支持单文件子进程隔离超时，避免疑难文件卡死整批任务
- 支持历史目录映射，兼容已有的 STEP 输出目录结构

## 环境要求

- Windows
- 已安装 CATIA，并可通过 COM 启动 `CATIA.Application`
- Python 3.10+
- `pywin32`

安装依赖：

```powershell
pip install pywin32
```

## 仓库结构

根目录按“源码 / 测试 / 示例 / 问题归档”分层：

```text
catia_step_exporter/
  cli.py                   命令行入口与参数解析
  converter.py             批量任务编排、断点、状态与统计
  catia_com.py             CATIA COM 导出器
  subprocess_exporter.py   单文件子进程隔离导出
  docs/                    维护文档
  tests/                   回归测试
  examples/                示例配置
  问题档案/                历史问题、根因与处理记录
  README.md                使用说明
  CHANGELOG.md             重要变更记录
  LICENSE                  开源许可证
```

如果你是第一次接手这个仓库，建议阅读顺序：

1. 先看本文档，了解命令行用法和运行约束。
2. 再看 `cli.py`、`converter.py`，理解主流程和批处理能力。
3. 遇到历史兼容问题时，再看 `问题档案/README.md` 和对应专题档案。

## 文档导航

- 示例映射文件：`examples/path-map.example.json`
- 问题归档总览：`问题档案/README.md`
- 维护说明：`docs/维护说明.md`
- 变更记录：`CHANGELOG.md`
- 单元测试入口：`tests/`

## 支持的输入

- `CATPart`
- `CATProduct`

默认输出后缀为 `.stp`。

如果你只想导出零件，建议使用 `--parts-only` 跳过 `CATProduct` 装配体。

## 快速开始

### 导出单个文件

```powershell
python cli.py --input "<单个CATIA文件>" --output "<STEP输出目录>"
```

### 导出整个目录

```powershell
python cli.py --input "<CATIA输入根目录>" --output "<STEP输出根目录>" --recursive
```

### 只导出零件，跳过装配体

```powershell
python cli.py --input "<CATIA输入根目录>" --output "<STEP输出根目录>" --recursive --parts-only
```

### 长批处理推荐命令

```powershell
python cli.py --input "<CATIA输入根目录>" --output "<STEP输出根目录>" --recursive --restart-every 50
```

## 断点续跑与失败日志

默认情况下，程序会在输出目录根部自动生成两个文件：

- `.catia_step_exporter_checkpoint.jsonl`
- `.catia_step_exporter_failures.jsonl`
- `.catia_step_exporter_status.json`

用途：

- `checkpoint` 用于记录每个文件的处理结果，程序中断后可直接续跑
- `failures` 单独记录失败项，便于后续筛选重试
- `status` 用于记录当前正在处理的文件、最近心跳、整体进度和预警状态

如果某个文件已经成功导出，且目标 `.stp` 仍然存在，续跑时会直接跳过。

可以自定义这两个文件的位置：

```powershell
python cli.py ^
  --input "<CATIA输入根目录>" ^
  --output "<STEP输出根目录>" ^
  --recursive ^
  --checkpoint-file "<日志目录>/catia-checkpoint.jsonl" ^
  --failure-log "<日志目录>/catia-failures.jsonl" ^
  --status-file "<日志目录>/catia-status.json"
```

## 运行状态心跳与卡死预警

长时间跑批时，即使当前文件很大、断点文件暂时不增长，程序也会持续刷新状态文件。

默认状态文件：

- `.catia_step_exporter_status.json`

状态文件里会包含这些关键字段：

- `run_state`：当前状态，常见值有 `running`、`warning`、`completed`
- `updated_at`：最近一次心跳时间
- `current_source_path`：当前正在处理的源文件
- `current_target_path`：当前输出文件
- `current_job_elapsed_seconds`：当前文件已持续处理的秒数
- `processed_count` / `total_jobs` / `progress_percent`：整体进度
- `warning_active` / `warning_message`：是否触发疑似卡死预警

### 查看当前状态

```powershell
Get-Content "<STEP输出根目录>\\.catia_step_exporter_status.json" | ConvertFrom-Json | Format-List
```

### 自定义心跳和预警阈值

```powershell
python cli.py ^
  --input "<CATIA输入根目录>" ^
  --output "<STEP输出根目录>" ^
  --recursive ^
  --parts-only ^
  --heartbeat-interval-seconds 10 ^
  --hang-warning-seconds 900
```

说明：

- 心跳间隔只影响状态写盘频率，不会中断导出
- 预警只负责提示“这个文件处理太久，可能卡住”，不会强制终止任务
- 如果 `run_state` 变为 `warning`，建议结合断点文件、最新 `.stp` 修改时间和 `CNEXT` 进程资源变化一起判断

## 内存保护

长时间跑批时，单个 CATIA 会话可能越来越重。工具提供 `--restart-every` 参数，用来定期重启 CATIA：

```powershell
python cli.py --input "<CATIA输入根目录>" --output "<STEP输出根目录>" --recursive --restart-every 10
```

建议：

- 小零件较多：`50` 到 `100`
- 大装配较多：`10` 到 `50`
- 最保守模式：`1`

`restart-every` 越小越稳，但总耗时也会增加。

## 单文件隔离超时

如果你已经遇到少数疑难文件导出完成后迟迟不返回，可以对重试任务启用 `--file-timeout-seconds`。

```powershell
python cli.py ^
  --input "<疑难文件或失败清单目录>" ^
  --output "<STEP输出根目录>" ^
  --recursive ^
  --parts-only ^
  --file-timeout-seconds 1200
```

建议：

- 整库 2 万级文件长批处理，优先只用 `--restart-every`，不要默认开启单文件子进程超时
- `--file-timeout-seconds` 更适合失败样本重试、疑难目录二次清洗、单个大文件排障
- 超时后该文件会写入失败日志，其他文件继续跑

## 历史目录映射

如果你的旧 STEP 目录名和当前源目录名不一致，可以通过映射文件把“源目录前缀”改写成“旧输出目录前缀”。

例如：

- 当前源目录：`03-帝豪GL-FE5 混动`
- 旧 STEP 目录：`帝豪`

此时可以使用 `--path-map-file`。

### 映射文件格式

映射文件是一个 JSON 对象，键和值都使用相对路径：

```json
{
  "03-帝豪GL-FE5 混动": "帝豪",
  "04-奥迪A6L": "STEP-A6",
  "车型A/标准件": "车型A-标准件专用目录"
}
```

最长前缀优先。也就是说：

- `车型A` 可以映射到一个总目录
- `车型A/标准件` 可以覆盖更具体的子目录

### 使用示例

```powershell
python cli.py ^
  --input "<CATIA输入根目录>" ^
  --output "<STEP输出根目录>" ^
  --recursive ^
  --path-map-file "examples/path-map.example.json"
```

## 参数说明

- `--input`：CATIA 文件或目录
- `--output`：STEP 输出目录
- `--recursive`：递归扫描输入目录
- `--overwrite`：覆盖已存在的输出文件
- `--format`：导出格式，当前保留 `step`
- `--visible`：导出时显示 CATIA 窗口
- `--restart-every`：每处理 N 个文件重启一次 CATIA；`0` 表示不自动重启
- `--checkpoint-file`：自定义断点文件路径
- `--failure-log`：自定义失败日志路径
- `--path-map-file`：历史目录映射 JSON 文件
- `--parts-only`：只导出 `CATPart`，跳过 `CATProduct`
- `--file-timeout-seconds`：单文件导出超时秒数；超时后记失败并继续
- `--status-file`：自定义运行状态文件路径
- `--heartbeat-interval-seconds`：状态文件心跳刷新间隔秒数；`0` 表示关闭心跳线程
- `--hang-warning-seconds`：单文件持续处理超过该秒数时写入预警；`0` 表示关闭预警

## 目录结构说明

如果 `--input` 传的是目录，程序会保留相对目录结构。

例如：

- 输入根目录：`<CATIA输入根目录>`
- 输出根目录：`<STEP输出根目录>`

则输出会类似：

```text
<STEP输出根目录>/
  车型目录A/
  车型目录B/
  车型目录C/
  .catia_step_exporter_checkpoint.jsonl
  .catia_step_exporter_failures.jsonl
  .catia_step_exporter_status.json
```

如果 `--input` 传的是单个文件，输出会直接落在输出根目录，不会自动补齐更高层目录。

## 测试

运行全部测试：

```powershell
python -m unittest discover -s tests -v
```

## 开源许可证

本项目采用 `MIT License` 开源，详见仓库根目录下的 `LICENSE` 文件。

## 注意事项

- 本工具依赖 CATIA COM，不能在未安装 CATIA 的普通环境中完成真实导出
- 对超大装配，建议先做抽样验证，再做整库批处理
- 整库只导零件时，优先使用 `--parts-only`
- 程序在单次打开/导出期间会临时关闭 `DisplayFileAlerts`，尽量减少钣金件等文件触发手动确认框
- 如果钣金件仍然弹出确认框，优先核对 CATIA 版本；官方已记录旧版本在钣金打开阶段可能忽略静默设置
- 状态文件中的 `warning` 代表“疑似卡住”，不是已经判定死锁
- 断点续跑依赖输出文件仍然存在；如果手动删除了输出文件，程序会重新导出