线下门店订单自动录入伯俊智能 POS 客户端。
给定一份类似 docs/orders.xlsx 的订单明细表，在 Windows 电脑上自动操作已经打开并停留在收银页面的 伯俊智能POS 客户端，逐单完成：
- 根据订单号前 8 位选择单据日期：OCR 识别下拉列表中的日期并直接点击目标日期，目标不在列表中则点击最早可选日期，选后回读校验。
- 将商品 条码 逐个录入并回车，OCR 校验商品列表（条码齐全、数量正确）。
- 对数量大于 1 的商品默认重复录入同一 条码 累加数量。
- 全选商品后设置订单总金额为 Excel 中的订单实收。
- 收银并按业务规则触发小票打印。
当前实现只保留正式录单路径，自动化统一通过视觉识别和键鼠模拟完成。
核心技术栈：
Python 3.11+Tkinter：桌面 UI。openpyxl：读取订单 Excel、写结果表。pyautogui：控制鼠标、键盘、快捷键。opencv-python/numpy：识别 POS 界面按钮、输入框等视觉节点。rapidocr-onnxruntime：OCR 识别日期下拉列表和日期显示，确保单据日期选择正确。pyperclip：通过剪贴板粘贴条码、日期、金额。Pillow：截图与失败留痕。PyInstaller：在 Windows 上打包 exe。
字段：
| 字段 | 说明 |
|---|---|
| 订单号 | 每个订单第一行有值，后续商品行为空时继承上一行订单号 |
| 订单实收 | 作为总额折扣弹窗中“特价”的订单总金额 |
| 商品总数 | 用于校验，不直接参与 POS 输入 |
| 支付方式 | 暂不使用，预览核对 |
| 条码 | 需要输入到 POS 条码输入区域 |
| 数量 | 商品数量，数量为 1 时保持 POS 默认值；大于 1 时默认重复录入同一 条码累加数量 |
| 尺码/颜色 | 预览和人工排查 |
| 商品实收 | 预览和人工排查；0 元订单常填成 ---，会被按“无值”处理，不会导致整表解析失败 |
| 录单状态（可选列） | 断点续传用。标为 成功 的订单在重新上传时会自动跳过；列不存在时行为不变 |
订单日期规则：
- Excel 没有单独日期列。
- 使用
订单号前 8 位作为订单日期。 - 例如
20260706004对应2026-07-06。
断点续传（重新上传时自动跳过已成功的订单）：
- 权威记录在
outputs/entry_status.json（每完成一单立即落盘），订单 Excel 的录单状态列是人工可读的镜像，批次结束后回写。 - 只有
成功会被跳过。失败/条码查不到/跳过的订单仍会重新进入队列， 需要人工先核对 POS 里没有残留单据，避免重复开单。 - Excel 正被打开导致状态列回写失败时，只提示不报错，续传依然以 json 为准。
正式录单前：
- 打开
伯俊智能POS。 - 登录账号。
- 进入并停留在收银页面。
- 建议 POS 在外接显示器上全屏显示，本软件在笔记本主屏显示。
每个订单：
- 打开
单据日期下拉框；OCR 识别下拉列表中的日期，目标日期存在则直接点击目标日期，不存在则点击最早/最新可选日期；下拉的“最新可选日期”和“项数”优先按实测值推算（不再用系统日期 + 硬编码项数），选后回读日期显示校验，不一致立即终止。 - 逐个录入商品条码，并回车加入商品列表；约 1 秒内未新增商品则终止。
- 条码在 POS 中查不到（回车后未加入待售列表，或 POS 提示“商品不存在”）时：跳过该订单、按
全选 + Delete清空购物车，然后继续下一单，不中止整批。 - 商品数量为 1 时不修改；数量大于 1 时默认重复录入同一 条码，让 POS 自动累加数量。
- OCR 校验商品列表：每个条码都在列表中、每行数量与 Excel 一致、右下角总数量与订单合计一致，任一不符立即终止。
- 全选商品。
- 按
F9打开改总额逻辑；多商品订单先确认批量改折扣提示框。 - 在改折扣弹框中选择
特价（点击前先判断是否已选中，点击后用像素 + OCR 双信号确认，避免重复点击把已选中的点掉），输入 Excel 的订单实收，点击确定。填入金额依次尝试“自动聚焦直接输入 → OCR 定位输入框后输入 → 键盘 Tab 循环填充”三条路径，任一条通过金额强校验即成功。 - 按
F5前校验商品存在（金额已在改价步骤强校验，默认不重复校验）。 - 按
F5收银。 - VIP 绑定页面优先模板识别后按
ESC取消，未识别到时按原策略兜底。 - 第一次回车提交订单。
- 非 0 元订单等待约 0.5 秒后第二次回车调取小票打印。
- 识别到 Windows 打印框后按
ESC取消打印，未识别到时按原策略兜底按ESC。 - 下一单开始前重新校验收银页面关键节点。
本软件已按“软件在笔记本主屏、POS 在外接显示器全屏”的场景设计：
- 程序会先定位
伯俊智能POS窗口。 - OpenCV 模板匹配默认只截取 POS 窗口区域，不扫描本软件所在主屏。
- 坐标兜底以 POS 窗口左上角为基准，支持外接屏在左侧时出现的负坐标。
- POS 不建议跨两个屏幕显示。
- Windows 缩放比例建议固定。
- 视觉模板建议在目标电脑、目标缩放比例、POS 全屏状态下截取。
模板目录：assets/templates/。
可从参考视频自动生成初版模板候选：
python scripts/extract_video_templates.py生成后可查看 assets/templates/template_preview.jpg，并参考 assets/templates/video_template_metadata.json 中的来源视频、时间点和裁剪区域。视频模板受录屏压缩和分辨率影响，正式录单前仍建议在目标 Windows 外接屏全屏 POS 环境下复核。
order_entry_bot/
app.py # Tkinter 桌面 UI
cli.py # 命令行入口
config.py # 自动化配置、模板、快捷键、POS窗口内相对坐标
driver_factory.py # 根据配置创建 POS 驱动
excel_reader.py # Excel 读取和校验
ocr.py # RapidOCR 日期文本识别
models.py # Order / OrderItem / OrderResult
pos_driver/
base.py # POS 操作接口
visual_driver.py # pyautogui + opencv 真实 POS 驱动
vision.py # 多屏截图和模板匹配工具
workflow.py # 订单录入主流程
logger.py # logs/YYYY-MM-DD.txt 日志
result_writer.py # 结果 Excel
screenshots.py # 失败截图
assets/templates/ # POS 视觉模板
scripts/build_windows.ps1 # Windows 打包脚本
scripts/extract_video_templates.py # 从参考视频生成模板候选
run_app.py # PyInstaller GUI 入口
安装依赖：
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtWindows PowerShell：
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt预览订单：
python -m order_entry_bot.cli preview docs/orders.xlsx启动桌面 UI：
python run_app.py生成默认配置：
python -m order_entry_bot.cli save-config config/local.jsonGUI 启动录单时会自动加载 config/local.json（存在才使用）；命令行真实录单可通过 --config 指定其他配置路径。
命令行真实录单：
python -m order_entry_bot.cli run docs\orders.xlsx --output-dir outputs注意：真实录单命令会操作 POS，请确认 POS 已经停留在收银页面。
- 调试日志：
logs/YYYY-MM-DD.txt - 结果表：
outputs/result.xlsx - 录单状态（断点续传权威记录）：
outputs/entry_status.json - 失败截图：
outputs/screenshots/
在 Windows PowerShell 中运行：
.\scripts\build_windows.ps1打包产物默认在：
dist\OrderEntryBot\OrderEntryBot.exe
第一次打包后，请在目标 Windows 机器上用测试订单完整验证：
- Excel 解析正确。
- POS 窗口识别正确。
- 外接显示器上的 POS 全屏区域截图正确。
- 日期下拉选择正确，超出可选范围时能选择最早可用日期。
- 条码录入正确，条码 错误或接口查询失败时能及时终止并截图。
- 数量大于 1 时能通过重复录入同一 条码累加数量。
- 商品列表 OCR 校验能识别所有条码、逐行数量单元格和右下角总数量。
- 全选商品成功。
- 多商品订单能确认批量改折扣提示框。
- 总额折扣选择特价并改价成功。
- 下单前商品存在校验通过，OCR 金额校验能识别金额数字并正确比对订单实收。
- 收银、ESC 取消 VIP 绑定、提交订单成功。
- 非 0 元订单触发打印并按 ESC 取消打印框。
- 失败时生成日志、结果表和截图。
docs/软件设计文档.mddocs/软件使用说明文档.mdassets/templates/README.md