feat(供应商管理): 新增规则引擎与词典配置支持

refactor(处理器): 重构通用供应商处理器以支持规则引擎 docs: 更新README与文档说明供应商管理功能 build: 更新打包脚本注入版本信息 test: 添加规则引擎单元测试
2025-12-12 13:46:00 +08:00
parent 73d17836d7
commit fb12e63c4c
33 changed files with 8678 additions and 62 deletions
@@ -0,0 +1,43 @@
+## 问题与目标
+- 弹窗尺寸偏小，不便操作
+- 弹窗及文件选择后没有在最上层，易被其他窗口遮挡
+- 字段英文名不直观，需要显示中文对应（银豹模板列）
+
+## 改进方案
+### 1. 弹窗尺寸与置顶行为
+- 将列映射向导窗口尺寸调整为 `780x660`，保持自适应（子控件 `fill=tk.BOTH, expand=True`）
+- 打开向导时：`dlg.lift()`、`dlg.attributes('-topmost', True)`，`after_idle` 取消置顶但保持焦点；`dlg.transient(root)`、`dlg.grab_set()` 防止被遮挡
+- 选择文件后的回调中再次 `dlg.lift()` 和短暂置顶，确保返回后窗口在最上层
+- 同步为模板管理窗口应用同样策略
+
+### 2. 字段标签中文提示
+- 列映射向导的标准字段改为按 `ColumnMapper.STANDARD_COLUMNS` 动态生成（若可用），并为每个字段追加中文说明，例如：
+  - `barcode（条码）`
+  - `name（商品名称）`
+  - `specification（规格）`
+  - `quantity（数量）`
+  - `unit（单位）`
+  - `unit_price（采购单价）`
+  - `total_price（金额/小计）`
+  - `category（类别）`
+  - `brand（品牌）`
+  - `supplier（供应商）`
+- 若 `ColumnMapper` 不可用，则用内置 `friendly_labels` 字典生成上述标签
+
+### 3. 布局优化与可用性
+- 保持“文件路径 + 浏览 + 预览前30行 + 加载列”四项同一行，按钮设 `padx=6`，保证易点
+- 映射区使用 `ttk.Combobox(state='readonly')`，宽度适配，并确保行高足够（留白）
+- 预览区保留顶部表格（前30行），支持点击行自动填充表头行号；加载列时按指定行读取
+
+### 4. 代码改动位置
+- `启动器.py`：
+  - `open_column_mapping_wizard_alt`：调整几何尺寸与置顶；在“浏览”回调与预览/加载流程中补充 `lift/topmost`；扩展标准字段与中文标签
+  - `open_template_manager`：统一尺寸与置顶行为
+- 仅UI与行为改动，不影响处理逻辑；保存仍写入 `suppliers_config.json` 的 `header_row` 与 `column_mapping`
+
+### 5. 验证
+- 打开列映射向导：窗口足够大，居中且在最上层；选择文件后窗口仍在最上层
+- 字段标签显示为英+中：如 `name（商品名称）`
+- 预览前30行与加载列同一行；点击预览行自动写入表头行号；保存后提示成功并写入配置
+
+请确认以上方案，确认后我将立即实施并验证。
@@ -0,0 +1,41 @@
+## 目标
+- 在系统设置中提供“供应商管理”GUI，支持新增/编辑/删除供应商，无需手改代码或JSON。
+- 一站式配置：基本信息、表头与列映射、规则与词典、模板管理，保存后即时生效。
+
+## 界面设计
+- 入口：右侧“系统设置”新增按钮“供应商管理”。
+- 布局：
+  - 左栏：供应商列表（名称），支持搜索/新建/复制/删除。
+  - 右侧Tab：
+    1) 基本信息：`name`、`description`、`filename_patterns`、`content_indicators`、`header_row`
+    2) 列映射与表头：嵌入现有“列映射向导”核心（预览前30行、表头选行、加载列、智能映射、导入/导出）
+    3) 规则与词典：词典编辑（忽略词、单位同义词、包装倍数、名称正则、默认单位/包装）；规则预设与规则预览（原始→规范化）
+    4) 模板管理：`output_templates` 列表、当前选择与批量校验
+- 操作按钮：保存（写入`suppliers_config.json`）、重载处理器、导入/导出供应商配置（单个或全部）。
+
+## 数据流与验证
+- 加载/保存：统一读写`config/suppliers_config.json`；保存后调用`ProcessorService.reload_processors()`。
+- 校验：复用`ProcessorService._validate_suppliers_config`；保存前进行schema校验，错误弹窗聚合列表。
+- 预设：提供“基础拆分与推断”规则预设；可导入/导出自定义规则。
+
+## 增强逻辑（自动化建议）
+- 新建供应商时，可选择样例Excel：
+  - 自动检测表头与初始列映射；基于列名关键词给出映射建议。
+  - 词典预填：常见单位同义词、默认单位“瓶”、常见包装倍数（件/箱/提/盒）。
+
+## 实施步骤
+1) 创建`open_supplier_manager`弹窗（系统设置入口），左列表+右侧Tab结构。
+2) 基本信息Tab：表单与校验；保存更新到JSON。
+3) 列映射与表头Tab：复用现有向导组件（预览/加载/智能映射/导入/导出）。
+4) 规则与词典Tab：编辑词典与规则预览，保存写入`dictionary`与`rules`。
+5) 模板管理Tab：维护`output_templates`与`current_template_index`，批量校验与报告显示。
+6) 保存与重载：统一写入后调用处理器重载并日志提示。
+
+## 验证
+- GUI走查：新增/复制/删除供应商配置；规则预览正确；模板校验能识别缺失列。
+- 处理生效：保存后立刻按新规则规范化并填充模板输出。
+
+## 后续扩展
+- 多供应商批量校验与报告导出；词典共享/继承；规则预设库扩展。
+
+如果确认，我将开始实现该GUI及其数据流，并将现有向导整合到供应商管理中以形成一站式配置体验。
@@ -0,0 +1,70 @@
+## 痛点复盘
+- 不同供应商存在强差异：列名不统一、单位混杂在数量、规格隐藏在名称、供应商缺失等
+- 现有向导只解决列映射层面，规则与词典编辑、执行顺序与生效范围不清晰
+- 缺少可视化“从原始→规范化→模板填充”的贯通验证；流程易跑不通
+
+## 总体方案
+- 建立“供应商规则系统”：可配置、可视化、可预览，贯穿 映射→清洗→规则→模板 填充全链路
+- 提供“规则库 + 词典 + 执行管道”三层抽象，支持每家供应商自定义规则组合与执行顺序
+- 完善 GUI：供应商管理中的四大Tab一站式配置，规则编辑器内置预设与预览，落地即验证
+
+## 数据模型
+- `suppliers_config.json` 每个供应商对象结构：
+  - `name`、`description`
+  - `filename_patterns`、`content_indicators`
+  - `header_row`
+  - `column_mapping`（源列→标准列）
+  - `rules`: 有序规则数组（见下）
+  - `dictionary`: 解析词典（`ignore_words`、`unit_synonyms`、`pack_multipliers`、`name_patterns`、`default_unit`、`default_package_quantity`）
+  - `output_templates`: 模板列表；`current_template_index`: 当前模板索引
+
+## 规则库（首批）
+- `split_quantity_unit(source)`: 拆分数量中的单位（箱/件/提/盒/瓶），无单位用默认单位
+- `extract_spec_from_name(source)`: 从名称抽取规格/包装（容量×数量/简单双乘），应用忽略词与名称正则
+- `normalize_unit(target,map)`: 单位归一（同义词→统一单位），件/箱/提/盒按包装倍数转换数量为“瓶”
+- `compute_quantity_from_total()`: 数量缺失时用金额/单价回推数量
+- `fill_missing(fills)`: 缺失填充，例如单位默认“瓶”
+- `mark_gift()`: 金额/单价为0或名称含“赠品/O/o/空”标记赠品
+- 后续扩展：`classify_category(name)`, `extract_brand(name)`, `strip_noise(name)` 等
+
+## 执行管道
+- 处理器执行顺序：映射→清洗→规则（有序）→模板填充
+- 每条规则可访问 `dictionary`，执行结果在 DataFrame 上可追踪（供预览）
+- 提供“预览栈”：展示原始→每步规则输出（多步Diff），定位问题
+
+## GUI优化
+- 供应商管理：
+  - 左侧供应商列表（搜索/新建/复制/删除/导入/导出）
+  - 右侧四大Tab：
+    - 基本信息：必填校验与保存
+    - 列映射与表头：现有向导增强（滚动条、表头选行、智能映射、导入/导出）
+    - 规则与词典：
+      - 规则编辑器（顺序可调整：上/下移动、插入/删除规则）
+      - 词典编辑（忽略词、单位同义词、包装倍数、名称正则、默认值）
+      - 规则预设（常用组合）与“应用规则预览”（展示原始→规范化两列；可切换查看逐步Diff）
+    - 模板管理：模板列表/当前选择与批量校验，显示缺失/多余列报告
+- 性能与体验：所有弹窗置顶回焦；滚动与水平滚动；列宽拖拽与一键导出预览为CSV
+
+## 使用路径（推荐）
+1. 新建供应商→选样例Excel→自动表头与初始映射建议
+2. 规则预设：选择“基础拆分与推断”→应用规则预览→查看原始/规范化对比
+3. 细化词典：补充忽略词、单位同义词、包装倍数、名称正则→再次预览
+4. 保存并重载→跑一份真实文件→最近文件中打开结果核验→如有差异回到规则编辑器微调
+
+## 验证与可视化
+- 单元测试：表头识别/数量拆分/名称规格解析/单位归一/数量回推/赠品标记
+- 烟雾测试：5–10类典型供货商样本端到端验证（含极端情况：无单位、名称含噪声、数量混合单位）
+- 日志：每步规则执行计数与示例行输出（前/后5行），便于定位问题
+
+## 交付物
+- 规则引擎模块与规范接口；处理器接入
+- 供应商管理GUI（规则编辑器、词典编辑器、预设与预览）
+- 扩展配置示例与测试数据；打包脚本校验资源
+
+## 里程碑
+- Day 1：规则库与引擎扩展、处理器接入、预览栈接口
+- Day 2：GUI规则编辑器（顺序调整/增删）、词典编辑器、规则预设与预览
+- Day 3：模板批量校验、单元与烟雾测试、日志强化
+- Day 4：回归修正与打包交付
+
+确认后我将开始实现上述内容，确保不同供应商可独立配置精细规则并“所见即所得”验证，流程稳定可跑通。
@@ -0,0 +1,52 @@
+## 目标
+- 为具体供应商定制更细的解析规则（词典、包装倍数、忽略词、同义单位），并在列映射向导提供可视化编辑入口与预览。
+
+## 配置扩展
+- 扩展 `suppliers_config.json` 每个供应商对象新增：
+  - `dictionary`: 解析词典
+    - `ignore_words`: ["白膜","彩膜","赠品"]（在名称解析时剔除）
+    - `unit_synonyms`: {"箱":"件","提":"件","盒":"件","瓶":"瓶"}
+    - `pack_multipliers`: {"件": 24, "箱": 24, "提": 12, "盒": 10}（缺规格时用于单位归一）
+    - `name_patterns`: [正则表达式]（从名称抽取规格/容量×数量，如 `([\d\.]+)(ml|l|升|毫升)[*×xX](\d+)`）
+    - `default_unit`: "瓶"
+    - `default_package_quantity`: 1
+  - `rules`: 规则数组（与现有一致），规则在执行时可访问 `dictionary`
+  - `output_templates`: 模板列表；`current_template_index`: 当前选择索引
+
+## 规则引擎增强
+- 在 `app/core/handlers/rule_engine.py`：
+  - `apply_rules(df, rules, dictionary=None)` 接口增加 `dictionary` 参数
+  - `extract_spec_from_name`：先剔除 `ignore_words`，匹配 `name_patterns`，无匹配时按 `pack_multipliers` 推断包装数量
+  - `normalize_unit`：使用 `unit_synonyms` 统一单位；如单位为“件/箱/提/盒”且有 `package_quantity` 或 `pack_multipliers`，数量×包装并单位归一为“瓶”
+  - `split_quantity_unit`：解析数量中的单位，同义词归一；无单位时用 `default_unit`
+  - 其余规则（回推数量、填充、赠品标记）保持不变
+
+## 供应商处理器接入
+- `GenericSupplierProcessor`：
+  - 从 `supplier_config['dictionary']` 取词典并传入 `apply_rules`，保证每家供应商按自身词典执行
+  - 若未配置词典，使用默认空词典
+
+## 向导UI扩展（右侧系统设置→列映射向导）
+- 增加“供应商规则”区域：
+  - 可编辑列表：
+    - 忽略词（多行输入或表格）
+    - 单位同义词（键值对表格：原单位→统一单位）
+    - 包装倍数（单位→包装数量）
+    - 名称正则（多行，每行一个表达式）
+    - 默认单位、默认包装数量（输入框）
+  - 操作：新增/删除、导入（JSON）/导出（JSON）、保存
+  - 规则预览：
+    - 选择预设（基础拆分与推断或自定义），点击“应用规则预览”，显示“原始/规范化”两列树表对比
+  - 保存行为：将 `dictionary` 与 `rules` 写入对应供应商的 `suppliers_config.json` 并重载处理器
+
+## 验证与测试
+- 单元测试：
+  - 名称解析（容量×数量、简单乘法、忽略词影响、同义词归一）
+  - 数量拆分与单位归一（“4瓶/1箱/3件/2提/2盒”）
+  - 包装倍数应用与数量回推
+- 烟雾测试：构建 5–10 类供货商样本，验证端到端转换与模板填充可用
+
+## 交付
+- 完成词典与规则编辑入口、配置扩展与引擎接入，提交验证报告与示例配置；保留导入/导出便于你迭代调整。
+
+确认后我将按此方案实现：扩展配置→增强规则引擎→处理器接入→向导UI与预览→测试。
@@ -0,0 +1,30 @@
+## 原因
+
+* 按钮调用了 `safe_open_validation_panel`，其内部检查 `open_validation_panel` 是否存在；当前代码中未定义该函数，导致始终提示“程序未加载，请重启”。
+
+## 修复方案
+
+* 在 `启动器.py` 中新增顶层函数 `open_validation_panel(log_widget)`，与其它 `open_*` 工具函数并列，确保加载顺序稳定。
+
+* 保留按钮绑定到 `safe_open_validation_panel`，其将直接调用新定义的 `open_validation_panel`。
+
+## 实施
+
+* 添加 `open_validation_panel`：
+
+  * 入口参数：`log_widget`
+
+  * 实现与之前描述一致：供应商选择、原始文件/期望结果选择、运行验证生成差异、生成建议并“应用建议”写回配置。
+
+* 放置位置：`show_supported_processors` 与 `safe_open_validation_panel` 相邻区域，确保可见与可用。
+
+## 验证
+
+* 启动程序→系统设置→点击“验证匹配”，应正常打开面板无提示。
+
+* 选择“农夫山泉”与提供的文件后运行验证，查看差异与建议。
+
+## 预期
+
+* 面板不再提示重启；功能可用。
+
@@ -0,0 +1,57 @@
+## 目标
+- 用你提供的原始文件与期望结果跑通“验证闭环”，自动对比差异并生成修正建议。
+- 将“规则设置”改造成通俗易懂的“向导 + 快速模板 + 自动识别”，让普通用户也能完成操作。
+
+## 验证闭环（立即可用）
+- 新增“验证匹配”面板：
+  - 选择原始Excel：`data/output/微信图片_20251115212128_148_108.xlsx`
+  - 选择期望结果：`data/result/采购单_微信图片_20251115212128_148_108.xls`
+  - 一键运行当前供应商流程 → 自动生成临时结果 → 与期望结果进行单元格级对比
+  - 输出差异报告：
+    - 列差异（列缺失/多余/名称不一致）
+    - 行差异（按条码或名称对齐，数量/单位/单价/金额差异）
+    - 规则差异归因（例如：数量未拆分、单位未归一）
+  - 按“应用建议”自动调整当前供应商的规则/词典（可撤销）
+
+## 简化操作设计
+- 两种模式：
+  - 简单模式（默认）：
+    - 步骤：选择文件 → 选择供应商 → 选择快速模板 → 预览 → 生成
+    - 字段中文说明（name（商品名称）、quantity（数量）等）与自动建议
+  - 高级模式：
+    - 可编辑规则顺序与参数、词典、正则；具备步骤预览与Diff
+- 快速模板：
+  - “无数量/单位列”模板：自动配置拆分数量单位→名称提取规格→单位归一→缺省填充→标记赠品
+  - “纯金额/单价反推数量”模板：直接回推数量
+  - “条码驱动匹配”模板：条码为主键对齐
+
+## 自动识别与建议
+- 列名识别：从表头关键词自动映射常用字段
+- 单位与数量：从“订单数量”拆分，单位同义词与包装倍数自动套用
+- 名称提取规格：词典与正则库（容量×数量、双乘、“550水24白膜”）自动解析；失败行计数提示
+- 自动修正建议：
+  - 若数量为空：建议添加“split_quantity_unit(source=订单数量)”
+  - 若单位为“箱/件/提/盒”：建议添加“normalize_unit + pack_multipliers”
+  - 若金额与单价存在且数量为空：建议添加“compute_quantity_from_total”
+
+## 差异对比与一键修复
+- 差异可视化：原始→规范化→模板填充三栏对比；支持仅显示变化列、导出CSV
+- 一键修复：将建议以“卡片”列表展示，点击应用后立即刷新预览；支持撤销上一步
+
+## 交互流程
+1) 进入“验证匹配” → 选择原始与期望 → 运行 → 查看差异
+2) 点击“应用建议”直观修复规则/词典 → 差异减少直至匹配
+3) 切回“简单模式”一键生成采购单
+
+## 技术实现要点
+- 供应商配置：继续使用 `suppliers_config.json`，但在GUI中隐藏JSON细节，改为中文表单与下拉
+- 规则执行：保留引擎，新增“建议生成器”根据差异报告生成规则/词典变更
+- 对比对齐：优先按条码对齐；无条码时按名称近似匹配（去噪后模糊比对）
+
+## 里程碑
+- Day 1：验证面板与差异对比；建议生成器（数量/单位/规格/金额）
+- Day 2：简单/高级模式切换；快速模板与自动识别
+- Day 3：一键修复与撤销；导出差异报告
+- Day 4：回归测试与打包；提供“农夫山泉”预设并用你的样例验证匹配
+
+确认后我将实现“验证匹配”面板并接入建议修复，先用你提供的农夫山泉样例跑通闭环，再推广到其它供应商。
@@ -0,0 +1,54 @@
+## 目标
+- 按照优化实施计划，从第3周任务7/8开始全面落地，并同时推进第4周任务9/10，确保可视化、配置驱动和交付质量提升。
+
+## 任务7：列映射向导完善
+- 字段扩展与中文提示：标准字段统一以英+中展示，支持更多列（条码、名称、规格、数量、单位、单价、金额/小计、分类、品牌、供应商）。
+- 自动建议增强：结合样本数据统计（字符串比例、特殊关键词、数值特征）给出更可靠的映射建议。
+- 表头定位增强：支持预览选择，并保存 `header_row`；向导内清晰提示当前使用的表头行。
+- 配置管理：支持导入/导出映射方案（JSON），可一键应用到多供应商。
+- 热重载与快捷入口：保存后自动重载供应商处理器；在系统设置区和快捷键中提供入口。
+
+## 任务8：模板管理与校验完善
+- 模板组管理：支持为每个供应商选择/保存多个模板（默认、备用），UI下拉选择当前模板。
+- 差异检测：读取模板首行表头与系统标准列比较，列表显示缺失/多余字段与修复建议。
+- 批量校验：可一次性校验选定供应商的所有模板组并生成报告。
+- 示例生成：按标准列生成示例模板，便于对齐格式。
+
+## 任务9：单元测试与烟雾测试
+- 单元测试（pytest）：
+  - `_find_header_row` 不同格式表头识别（第一行/中间行/合并行/空白行混杂）。
+  - `GenericSupplierProcessor` 列映射、清洗规则（remove_rows/fill_na/convert_type）与公式计算。
+  - 模板填充的关键路径（必要列检测、数量/赠送量/单价写入）。
+- 烟雾测试：准备小样本（图片→OCR→Excel→采购单），验证端到端可用，记录日志与输出。
+
+## 任务10：打包与版本信息
+- 版本信息：主窗口标题与“关于”对话框显示版本号、构建时间、更新日志入口。
+- 打包校验：构建后检查模板与配置文件存在性；打包时拷贝资源并生成校验报告。
+- 更新脚本：完善 `build_exe.py` 支持版本号注入与资源校验失败时中止。
+
+## 实现要点
+- GUI：系统设置页整合入口；对话框使用 780×660/540 尺寸，`topmost`/`lift`/`focus_force` 保证焦点。
+- 配置：`suppliers_config.json` 增加 `header_row`、`column_mapping`、`output_templates`（数组）与当前选择索引。
+- 处理器：优先使用保存的表头行；模板管理选择的模板在处理时应用。
+- 日志与提示：保存/校验/重载操作统一写入日志面板并气泡提示。
+
+## 验证
+- 交互走查：向导流程顺畅、字段标签明确、置顶行为正常。
+- 单元测试通过率达标（≥90%覆盖关键模块）；烟雾测试输出正确文件且无异常。
+- 打包后 EXE 启动显示版本信息；资源齐备，最近文件可双击打开。
+
+## 变更范围
+- `启动器.py`（设置页UI、向导与模板管理弹窗）
+- `app/core/processors/supplier_processors/generic_supplier_processor.py`（读取与映射逻辑）
+- `app/core/excel/processor.py`（表头行识别与模板填充校验）
+- `config/suppliers_config.json`（结构扩展）
+- `tests/`（新增pytest用例与烟雾测试脚本）
+- `build_exe.py`（版本注入与校验）
+
+## 时间安排
+- Day 1：任务7 UI/配置完成，处理器联动与验证
+- Day 2：任务8 模板管理增强与批量校验
+- Day 3：任务9 单元测试与烟雾测试
+- Day 4：任务10 打包与版本信息，回归测试与文档补充
+
+确认后我将按以上计划开始实施并逐项提交验证结果。
@@ -0,0 +1,52 @@
+## 概览
+- 目标：让改动更可见并提升识别/处理准确性与可操作性
+- 范围：GUI入口与提示、表头识别与手动指定、供应商配置联动、交互一致性
+
+## 可见入口改造
+- 在“Excel处理→特殊处理”区新增两个明显按钮：
+  - “列映射向导”：加载 Excel 源列 → 映射到标准列 → 保存至 `config/suppliers_config.json`
+  - “模板管理”：选择模板、校验表头列是否包含必需项 → 保存路径至供应商配置
+- 在“快捷操作”区补充一个“显示处理器类型”入口，便于确认支持的文件类型
+- 在保存成功后增加气泡提示与日志条目（log 面板出现“列映射已保存”“模板路径已保存”）
+
+## 手动表头行支持
+- 在“列映射向导”弹窗增加“表头行号(从1开始)”输入框：
+  - 加载列时按照指定行重读 Excel 并展示源列
+  - 保存时将 `header_row`（零基索引）写入 `suppliers_config.json`
+- 通用供应商处理器读取时优先使用 `supplier_config['header_row']`；未设置时执行自动表头检测（关键词+非空比例+字符串比例）
+
+## 自动表头检测增强
+- Excel 单文件处理与通用供应商处理器：
+  - 扫描范围扩大到前 30 行
+  - 扩充关键词：加入金额类（“金额/小计/总计/合计/合计金额”）
+  - 综合评分：关键词命中+非空比例+字符串比例，阈值达到即判为表头；否则选第一个有效行
+
+## 交互与一致性
+- “单个识别”按钮直接弹出图片选择（只允许 `jpg/jpeg/png/bmp`），取消即终止
+- “单个处理”按钮弹出 Excel 选择（只允许 `xlsx/xls`），取消即终止，不再默认处理最新 Excel
+- 处理完成后不再自动打开 `result/output` 目录，改为通过“最近文件”双击打开
+- 最近文件仅记录图片/Excel，自动过滤无效并按修改时间降序展示，空历史时从 `data/output`、`data/result` 回填合规文件
+
+## 供应商配置联动
+- `suppliers_config.json`：
+  - `column_mapping`：保存源列→标准列映射
+  - `header_row`：保存手动指定的表头行（零基）
+  - `output_template`：保存模板路径（相对路径）
+- 处理器加载时校验并日志提示不合法项，保留已通过的配置
+
+## 验证与可视化
+- 操作日志：保存映射/模板时写入成功日志
+- 处理器信息：通过“显示处理器类型”对话框列出支持的扩展名和描述
+- 手动表头验证：在向导中“加载列”后，源列下拉应出现正确列名；处理后“最近文件”出现输出采购单
+
+## 预计改动位置
+- GUI按钮与向导弹窗：`启动器.py`（特殊处理区与工具函数）
+- 自动表头检测与手动表头使用：
+  - Excel处理：`app/core/excel/processor.py` 的 `_find_header_row`、`process_specific_file`
+  - 通用供应商处理：`app/core/processors/supplier_processors/generic_supplier_processor.py` 的 `_read_supplier_data`、`_find_header_row`
+- 供应商配置：`config/suppliers_config.json`
+
+## 交付
+- 提交代码改动后，更新打包 EXE，便携包包含上述 UI 与功能；提供操作说明与可见验证点。
+
+请确认以上计划，确认后我将按此逐项实现并验证。
@@ -0,0 +1,50 @@
+## 你现在就能这样做
+- 目标：在没有“规格/数量/单位”列、只有“订单数量”列（如“4瓶/1箱/5箱/3件”）时，拆分出数量与单位，并按名称提取规格，最终规范化为银豹模板字段。
+
+### A. 最小映射（只为模板填充）
+- 在“供应商管理 → 列映射与表头”页，只需映射这些常用列：
+  - name ← 商品名称
+  - barcode ← 条码（如有）
+  - unit_price ← 单价（如有）
+  - total_price ← 金额/小计（如有）
+- 不需要映射“数量/单位/规格”，后续用规则直接从原始列生成。
+
+### B. 规则与词典设置（关键）
+- 在“供应商管理 → 规则与词典”页：
+1) 规则列表按顺序添加：
+  - split_quantity_unit，参数：source=订单数量
+  - extract_spec_from_name，参数：source=商品名称
+  - normalize_unit，参数：target=unit，map={"箱":"件","提":"件","盒":"件"}
+  - fill_missing，参数：fills={"unit":"瓶"}
+  - mark_gift（可选）
+  - compute_quantity_from_total（可选，当只有金额/单价时）
+2) 词典设置：
+  - unit_synonyms：{"箱":"件","提":"件","盒":"件","瓶":"瓶"}
+  - pack_multipliers：{"件":24,"箱":24,"提":12,"盒":10}（根据你的供应商习惯调整）
+  - default_unit：瓶
+  - default_package_quantity：1
+  - ignore_words：如（白膜、彩膜、赠品）
+  - name_patterns（每行一个正则）：
+    - (\d+(?:\.\d+)?)(ml|l|升|毫升)[*×xX](\d+)
+    - (\d+)[*×xX](\d+)瓶
+    - 需要时加入供应商特有格式，如“550水24白膜”可匹配“(\d{2,3}).*?(\d{1,3})”并将第二组当作包装数
+
+### C. 预览与验证
+- 在“规则与词典”页选择Excel，点击“生成步骤预览”：
+  - 看“原始 → 规范化”两侧表，对比是否出现 quantity（数值）、unit（单位）、specification、package_quantity
+  - 在“预览步骤”中逐步查看每一条规则的结果；必要时导出CSV核对
+- 保存后会自动重载处理器；用真实文件跑一次，结果会出现在“最近文件”，双击打开核验。
+
+### D. 解释关键点
+- 映射是为了模板填充字段的命名统一；对于“订单数量”这种来源列，规则会直接读取 source=订单数量，不要求你把它映射成标准列。
+- 规则执行后，会产生标准字段：quantity、unit、specification、package_quantity，可被模板填充。
+- normalize_unit会用词典的pack_multipliers或name解析出的package_quantity，自动把“件/箱/提/盒”的数量换算成“瓶”，并将unit统一为“瓶”。
+
+## 我将继续优化的点（让流程更清晰）
+1) 规则表单中的“来源列”改为可选下拉（直接从Excel列名取值），无需手填。
+2) 步骤预览支持“仅显示变化的列（Diff模式）”与“错误计数”（未匹配的行统计）。
+3) 提供“无数量/单位列”的快速模版：自动添加上述规则与词典默认值，一键套用。
+4) 规则帮助提示：每条规则说明输入/输出字段与常见示例。
+5) 供应商级的“测试运行”：选文件→一键规范化→预览→导出结果，独立于正式处理。
+
+如果你同意，我将按上述方案完善GUI交互（来源列下拉、快速模板、Diff预览、错误计数与一键测试），并把默认规则与词典预设直接提供出来，确保“只有订单数量列”的场景开箱可用。
@@ -0,0 +1,42 @@
+## 目标
+- 通过规则引擎把不同供货商的OCR表格规范为统一字段，并自动拆分“数量+单位”、从名称推断规格、标记赠品，最终稳定填充银豹模板。
+
+## 配置与规则
+- 扩展 `suppliers_config.json`：
+  - `rules`: 规则数组（顺序执行）
+  - `output_templates`: 模板列表；`current_template_index`: 当前模板索引
+- 规则类型：
+  - `split_quantity_unit`（拆分“4瓶/1箱/3件/2提/2盒”）
+  - `extract_spec_from_name`（解析“1.8L×8瓶”“550水24白膜”等）
+  - `normalize_unit`（单位归一“箱/件/提/盒/瓶”→统一“瓶”，按包装转换数量）
+  - `compute_quantity_from_total`（数量缺失时用金额/单价反推）
+  - `infer_supplier`（文件名/内容推断供应商）
+  - `fill_missing`（填默认值）
+  - `mark_gift`（金额/单价=0或“赠品/O/o/空”）
+
+## 实现
+- 新建 `app/core/handlers/rule_engine.py`：输入DataFrame与规则列表，返回规范化DataFrame
+- 在 `GenericSupplierProcessor` 中：列映射→清洗→规则引擎→输出
+- 列映射向导增强：
+  - 增加“规则预设”选择与“应用规则预览”按钮，显示原始/规范化后的对比
+  - 支持导入/导出（映射+规则）JSON
+- 模板管理增强：模板组选择、批量校验、示例模板生成
+
+## 解析与正则
+- 名称解析：
+  - 容量×数量：`(\d+(?:\.\d+)?)(ml|l|升|毫升)[*×xX](\d+)`
+  - 简单数量×数量：`(\d+)[*×xX](\d+)`
+  - 词典忽略词：如“白膜”等
+- 数量拆分：`(?P<num>\d+(?:\.\d+)?)(?P<unit>箱|件|提|盒|瓶)`
+
+## 验证
+- 单元测试覆盖规则与表头识别；烟雾测试涵盖“无单位/规格/数量混杂”的样本
+- GUI预览确认规则效果；保存后热重载处理器
+
+## 里程碑
+- Day 1：规则引擎与处理器接入
+- Day 2：向导规则预览与导入/导出；模板组管理
+- Day 3：测试与样本库
+- Day 4：打包与交付验证
+
+请确认，我将立即开始实现并逐步提交验证结果。