这是一个完全离线的 Windows 桌面工具，用来批量读取 Word 工艺卡、人工校对最终工序，并统一生成工单系统 Excel 导入文件。
重构后的完整业务规则见 REFACTOR_REQUIREMENTS.md，历次功能演进见 DEVELOPMENT_HISTORY.md。
项目维护入口：
需要 Windows 和 Python 3.10 或更高版本。首次使用在项目目录执行：
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt随后双击 run.bat 启动。脚本会优先使用项目 .venv 中的 pythonw.exe，界面启动后不会在背后保留命令行窗口。双击 DocSwift.vbs 可完全不显示终端。
程序带有提前单实例保护，重复双击不会同时打开两套任务数据库。免安装版在 Qt 组件加载前就会显示启动等待画面，主窗口恢复任务期间继续显示进度提示， 避免用户因启动延迟反复点击。
需要排查问题时，可以在命令行执行 run.bat --console，保留终端并显示完整错误。
程序同时把启动、识别、导出、更新和未捕获异常写入
%LOCALAPPDATA%\DocSwift\logs\docswift.log。顶部“查看日志”可以直接查看最近
记录并打开日志目录；日志按 2 MB 自动轮换，最多保留 5 份历史文件。
顶部“检查更新”会优先连接公司内部更新服务器，无法连接时再使用公开的 GitHub Release：
- 当前程序版本为
v0.3.3。 - 检查和下载在后台执行，不会卡住校对界面。
- 公司内部版本清单地址为
http://192.168.100.3/updates/docswift/latest.json。 - 内部服务器明确返回当前版本时，不会越过内部发布策略查询公网版本。
- 只接受名称为
DocSwift-v版本号-windows-portable.zip的正式包。 - 下载前必须取得 SHA-256，下载后校验不一致会立即删除临时文件。
- 免安装版下载并校验成功后会安全解压，征得确认后自动关闭、原地替换并重新启动。
- 新版必须在 60 秒内写入启动成功标记，否则更新辅助程序会自动恢复并重启旧版。
- 源码运行模式不会覆盖项目文件，只会下载并打开新版压缩包。
- 任务数据位于
%LOCALAPPDATA%\DocSwift，不参与程序目录替换，未完成的校对内容不会丢失。
仓库尚未创建正式 Release 时，按钮会明确提示“尚未发布”，这是正常状态。
- 添加一个或多个
.docx工艺卡，也可以添加整个文件夹。 - 选择 Excel 模板和目标 Excel。
- 自动识别默认关闭；选择工艺卡后点击“识别所选”。
- 在右下方检查并修改合并后的最终工序。
- 点击“确认当前工艺卡”，程序会自动进入下一张待确认工艺卡。
- 最后一张工艺卡确认后，程序会打开批量导出确认；也可以点击“导出已确认工艺卡”手动导出。
左侧状态会明确区分未识别、待识别、识别中、待确认、已确认和已导出，不再 使用文件变暗记录。多张卡会进入后台单通道识别队列，解析、原版预览和来源页 定位均不会占用界面主线程；当前卡识别时仍可查看或校对其他工艺卡。
误添加的工艺卡可在左侧多选后点击红色“移除”。待识别项目会同时从队列取消； 原始 Word 永远不会被删除。移除已确认项目会明确提示校对结果也将删除；移除 已导出项目只删除任务记录，不会反向修改已经生成的 Excel。
程序自动保存当前任务和人工修改，关闭后不会清空。下次启动自动恢复最后打开的任务。
- 左侧：工艺卡列表、状态、最终工序数量和拖动排序。
- 右上：完全离线的 Word 原版表格 PDF 预览。
- 右下：合并后的最终工序编辑表。
工序编辑支持修改、多行内容编辑、新增、删除、合并、拆分、上移、下移和恢复识别结果。长工序内容会自动展开，可使用表格右侧滚动条直接查看全文；点击工序可跳转到预览来源页。
预览会优先调用本机 WPS 的离线自动化接口，保留表格边框、合并单元格、列宽和原始分页；如果 WPS 不可用，则尝试 Microsoft Word，最后才使用内置 HTML 降级预览。整个过程不上传工艺卡。
待焊是不可删除的内置排除项。- “排除项”窗口可以添加自定义规则。
- 工序名称或内容包含排除文字时，不进入最终工序表和 Excel。
- 新增规则后，对相关工艺卡重新识别即可生效。
- 所有已确认且未导出的工艺卡统一追加到同一个 Excel。
- 待确认文件禁止导出，已导出文件自动跳过。
- 导出是原子操作：任何一张失败时，原 Excel 保持不变。
- 已导出的工艺卡重新编辑、确认后再次导出，会替换同一工艺路线旧数据，不会重复追加。
- 默认从第 2 行开始写入，并按表头名称匹配列。
- “工艺路线编号”列：
零件图号 + 零件名称 - “工艺路线名称”列：
零件图号 + 零件名称 - “工序/工艺路线列表”列：Word 工艺卡中的“工种”
- “工序内容”列：Word 工艺卡中的“工序内容”
- “工序号”列：使用 Word 工艺卡中的实际数字工序号，不按生成后的行数重新编号
- “类型”列：固定为
工序 - “报工数配比”列：固定为
1 - “是否锁定为最后一道工序”和“工时/分钟”列留空
程序会优先按第 1 行表头匹配列名，模板列顺序调整后仍可识别。
当前标准 9 列模板的 D1 保持空白，程序仍会按 D=工序号、E=工序内容 回退映射并写入数据。
如果一个有名称的工种后面存在一条或多条未重复填写工种的连续明细，程序会将它们输出为一行：
- “工序/工艺路线列表”和工序号保留该组第一条的值。
- 例如某个“车”工种包含工序 4～19，合并后工序号填写
4，下一工序继续使用工艺卡中的20。 - 每条工序内容在同一个单元格内单独换行。
- 行高会按合并后的步骤数量自动增加。
- 空白工种续行会并入上一条有名称的工种；如果文件开头出现无归属的空白工种明细，则保持独立。
- 每条输出数据的所有单元格都会添加黑色细框线，包括内容为空的列。
- 工种或工序内容中只要包含“待焊”，该工序就不会出现在预览和输出文件中。
- 删除“待焊”后，其他工序继续使用工艺卡中的原始工序号，不重新编号。
默认清理旧明细并重新生成：
python app.py --card "C:\path\card.docx" --template "C:\path\template.xlsx" --output "C:\path\output.xlsx" --start-row 2需要追加时：
python app.py --card "C:\path\card.docx" --template "C:\path\template.xlsx" --output "C:\path\output.xlsx" --start-row 2 --append运行内置回归测试：
python -m unittest discover -s tests -v任务数据库和预览缓存默认保存在：
%LOCALAPPDATA%\DocSwift
PowerShell 一键发布脚本在完成 v0.3.0 首次内部自动发布后已退役。后续将由
独立桌面发布工具统一管理测试、构建、公司 Gitea 发布版和 Ubuntu 自动更新源。
发布顺序、安全约束、重试策略及桌面工具需求见 RELEASE_AUTOMATION_DESIGN.md。