# OCR订单处理系统优化实施建议与周计划

## 目标
- 提升稳定性与可维护性：统一日志、进度回调、错误提示与配置持久化
- 优化用户体验：一致的弹窗与目录打开、清晰进度与结果摘要
- 控制成本与性能：合理并发、避免重复处理、日志滚动归档

## 范围
- 应用层（GUI、设置、交互）
- 服务层（OCR、Excel、合并）
- 工具层（日志、配置、校验）

## 已完成优化
- 日志滚动归档：单文件5MB，保留3个备份（RotatingFileHandler）
- 统一GUI日志挂载：`init_gui_logger`/`dispose_gui_logger`
- 统一进度显示：`ProgressReporter` 接入主要流程
- 结果目录一致化：Excel/合并/完整流程优先打开 `data/result`
- Excel引擎错误提示：统一弹窗附带安装建议（openpyxl/xlrd）
- 用户设置持久化：窗口尺寸与主题记忆（`data/user_settings.json`）

## 待实施优化（按周迭代）

### 第1周：基础能力统一与设置面板扩展
- 任务1：系统设置面板扩展
  - 新增设置项：日志级别、并发参数（`max_workers`/`batch_size`）、模板路径、输入/输出/结果目录
  - 写入 `user_settings.json` 并同步到 `config.ini`（通过 `ConfigManager.update/save_config`）
  - 验收：设置变更后重启仍生效；操作流程读取最新参数
- 任务2：进度回调全链路接入（服务层）
  - 为合并流程（`PurchaseOrderMerger`）添加 `progress_cb`（97%→100%），UI显示阶段进度
  - 完整流程串联 OCR→Excel→合并 三段进度
  - 验收：状态栏进度从0→100%，阶段文案一致、无跳变
- 任务3：错误提示模板统一
  - 抽象错误弹窗生成：标题/描述/建议操作（缺依赖、模板列缺失、文件格式异常）
  - 在服务层捕获常见错误并附带建议（不用泄露敏感信息）
  - 验收：触发典型错误时弹窗一致、日志有详细堆栈

### 第2周：兼容性与可维护性增强
- 任务4：供应商配置校验（schema）
  - 对 `suppliers_config.json` 加载前校验：字段完整、列映射存在、清洗/计算规则可执行
  - 失败时聚合错误列表并弹窗提示
  - 验收：错误配置阻止加载且提示清晰；正确配置即时生效
- 任务5：拖拽与最近文件
  - 日志面板上方增加拖拽区域（图片/Excel），拖入即处理
  - 最近处理文件列表（持久化、可清空）
  - 验收：拖拽成功处理；最近列表记忆与操作正常
- 任务6：线程池复用与批次自适应
  - OCR批量识别的线程池复用；根据 CPU 核心数与文件量自适应 `max_workers`、`batch_size`
  - 验收：大批量处理性能平稳，无过载或明显阻塞

### 第3周：数据处理与模板管理
- 任务7：列映射向导
  - 弹窗展示识别到的列与标准列，支持手动修正并保存到供应商配置
  - 验收：手动修正列映射后处理成功；配置热重载生效
- 任务8：多模板管理与校验
  - 支持按供应商选择模板；校验模板表头与系统标准列，给出差异提示
  - 验收：不同模板无错填；差异提示友好

### 第4周：测试与交付质量
- 任务9：单元测试与烟雾测试
  - 核心逻辑单元测试（规格解析、数量反推、列映射、模板填充）
  - 端到端小样本烟雾测试（OCR→Excel→采购单）
  - 验收：测试通过率达标；烟雾测试稳定
- 任务10：打包与版本信息
  - 打包资源校验（模板与配置存在性）；显示版本号与更新日志入口
  - 验收：打包可用；启动显示版本信息；更新日志可查看

## 验收标准与度量
- 功能验收：设置变更生效、进度准确、错误提示一致
- 稳定性：长时间运行日志不会膨胀；批量处理无明显卡顿
- 可维护性：配置驱动、模块职责清晰、代码重复显著减少

## 风险与回滚
- 配置同步风险：提供回滚策略（保留最近一次有效 `config.ini` 与 `user_settings.json` 备份）
- 依赖安装风险：提供一键安装与离线安装说明
- 模板差异风险：在校验失败时阻断流程并提示修复路径

## 实施说明
- 每周开始前将与您确认要启动的任务；每个任务完成后提交变更摘要与验证结果
- 如发现新需求或变化，计划将滚动更新，并在执行前与您确认