CSG-Picker-Shipper-Helper/PICKER_INTEGRATION_PLAN.md

Coordination Plan: Barcode Picking & QR Print Integration

This document outlines the design and integration process of the CSG Part Verifier (mobile picking interface) and the QR Label printing logic. It is written to provide full context for other AI agents working on the desktop application.

---

1. Overview of the Integration

We are adding two features to the ecosystem:

1. Mobile Picking Client (Android & PC): Allows operators on the warehouse floor to scan invoice QR codes, pull up pick lists, and verify items by scanning box QR codes.
2. Label QR Code Printing: Updates GDI label generation so all printed labels contain layout-compliant QR codes (Invoice Number for shipping address labels, SKU string for part labels).

To keep this a drop-in solution without interfering with the active desktop app structure:

• No Direct Printing: The desktop app will no longer run direct GDI print calls locally via win32print. Instead, it will post all print requests to the existing qb_efficiency bridge server.
• Background Web Server: We will spawn a lightweight background Flask thread inside the desktop app. This thread will run on a separate port (5001) to serve the mobile picking client and lookup invoices.
• Zero Database Overhead: The picking server will read live invoice data from the existing qb_efficiency sync result folder.

---

2. Shared File Changes & Additions

Active Build: Part Lookup Program (1)

1. [NEW] app/picker_server.py:

   • Spawns a Flask web server on a background thread.
   • Listens on port 5001.
   • Serves static picker UI files (picker.html and picker.js) located in app/assets/.
   • GET /api/invoice/<ref_number>: Resolves invoice line items by reading and parsing the cached QuickBooks results from C:/Users/mario/OneDrive/Documents/Claude/Projects/qb_efficiency/qb-bridge/state/results/invoice_*.json.
   • POST /api/print-label: Forwards print requests to the local qb_efficiency print bridge (http://localhost:5000/api/label-jobs/enqueue).

2. [NEW] run_picker.py:

   • Standalone startup script that runs the Flask server on the host machine. Run it to launch the mobile picking assistant independently (keeps the desktop app completely separate).

3. [MODIFY] app/labels.py:

   • Refactor print_label and print_address_label to make HTTP POST requests to the qb_efficiency enqueue endpoint:

     # Example POST to http://localhost:5000/api/label-jobs/enqueue
     payload = {
         "label_data": {
             "order_id": sku_or_invoice_id,
             "source": "parts_lookup",
             "skus": [{"sku": sku, "description": desc, "line_qty": 1}]
         }
     }
     

4. [NEW] app/assets/picker.html & app/assets/picker.js:

   • HTML5 video element container and canvas processing script.
   • Integrates the html5-qrcode library for high-speed camera scanning.
   • Handles item checklists, verification matching, and audio success/error feedback.

5. [MODIFY] PartsLookup.spec:

   • Update PyInstaller datas config to copy app/assets/picker.html and app/assets/picker.js into the compiled bundle resources folder.

---

3. QB Efficiency: qb_efficiency

1. [MODIFY] qb-bridge/label_agent/csg_label_agent.py:
   • Install and import the qrcode library.
   • Update both GDI renderers (_render_sku_label and _render_shipping_label) to generate a QR image (containing either the SKU or Invoice Number).
   • Use Pillow's ImageWin.Dib to draw the QR code on the print context alongside the existing CSG logo and Made-in-USA logo.

---

4. Verification Details

• Dependencies: Run pip install qrcode pillow flask requests in the python environment.
• Port Mapping:
  • qb_efficiency Flask Bridge runs on 5000.
  • csg_label_agent.py print agent polls 5000 and prints labels.
  • Desktop app background picker thread runs on 5001.
  • Android device accesses picking page at http://<host-pc-ip>:5001/picker.