Reorganize root: move docs, remove tracked credentials and data files
- Move USER_GUIDE, planning docs, and session logs to docs/ - Untrack FedexAPI.txt (contains live API credentials) and OnPart_inv.csv (large data file) - Update .gitignore to cover FedexAPI.txt and *_inv.csv going forward - Delete junk files: =1.23.0, Address.txt, stale screenshot Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Jonah
@@ -0,0 +1,73 @@
|
||||
# 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:
|
||||
```python
|
||||
# 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`.
|
||||
File diff suppressed because one or more lines are too long
Binary file not shown.
@@ -0,0 +1,154 @@
|
||||
# Parts & Invoice Lookup Application — Build Plan
|
||||
|
||||
A standalone Windows desktop application for non-technical users (packers and shipping associates) to look up parts and invoice/shipping information quickly. This document is self-contained so a new Claude session (e.g., in Cowork) has full context.
|
||||
|
||||
---
|
||||
|
||||
## Project context
|
||||
|
||||
**Users:** Packers and shipping associates who don't normally use computers. UI must be obvious, large, and free of complexity.
|
||||
|
||||
**Two distinct workflows:**
|
||||
|
||||
- **Packers** have a SKU or part description in hand. They need to search for that part and see its full SKU, picture, and pricing.
|
||||
- **Shipping associates** have an invoice number or customer name. They need to see the shipping address, email, and invoice number with easy copy buttons.
|
||||
|
||||
**Data sources:**
|
||||
|
||||
- **Parts:** A CSV file (`MM-DD-YYYY_OnPart_inv.csv`) updated periodically. Lives on a shared network drive.
|
||||
- **Invoices/customers:** QuickBooks Desktop Enterprise 24. Company file hosted on a server; every shipping workstation has QuickBooks installed and connected to that file.
|
||||
|
||||
**Part images:** Currently public URLs in the CSV (`Image URL` column). Plan is to migrate to a local SMB share with images named by SKU. The app should support both, with SMB as primary lookup and the CSV's URL as fallback once SMB is populated.
|
||||
|
||||
---
|
||||
|
||||
## What the parts CSV contains
|
||||
|
||||
Approximately 2,100 rows. Key columns:
|
||||
|
||||
| Column | Use |
|
||||
|---|---|
|
||||
| `STOCK NUMBER` | Full SKU shown to packer (e.g., `8620843-0423L`) |
|
||||
| `DESCRIPTION` | Human-readable name |
|
||||
| `Customer Price` | **Primary** price (this is the relevant one) |
|
||||
| `LIST` | Secondary price (shown smaller) |
|
||||
| `PART TYPE` | e.g., "AM" |
|
||||
| `GRADE` | e.g., "A" |
|
||||
| `YARD LOCATION` | e.g., "CSG" |
|
||||
| `AVAILABLE` | Y/N |
|
||||
| `QUANTITY` | Stock count |
|
||||
| `BIN LOCATION` | Physical location for picking |
|
||||
| `INTERCHANGE` | Cross-reference numbers (useful in fuzzy search) |
|
||||
| `WARRANTY TYPE` / `WARRANTY LENGTH` / `WARRANTY INFORMATION` | Shown as small footer |
|
||||
| `Image URL` | Current image source (public URL) |
|
||||
|
||||
Data quality is good — stock numbers are uniform and well-formed.
|
||||
|
||||
---
|
||||
|
||||
## Technical stack
|
||||
|
||||
| Component | Library |
|
||||
|---|---|
|
||||
| UI framework | **CustomTkinter** (modern look, easy to make large/friendly) |
|
||||
| Local cache | **SQLite** (built into Python) |
|
||||
| Fuzzy search | **rapidfuzz** |
|
||||
| QuickBooks integration | **pywin32 + QBFC** (QuickBooks Foundation Classes, COM-based) |
|
||||
| Image handling | **Pillow + requests** with on-disk caching |
|
||||
| Clipboard | **pyperclip** |
|
||||
| Packaging | **PyInstaller** (single `.exe`, no Python install needed on user machines) |
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
Each workstation runs a self-contained copy of the app.
|
||||
|
||||
**Startup sequence:**
|
||||
1. Load the parts CSV into local SQLite. Re-read if the file's modification time changed since last run.
|
||||
2. Start a background thread that pulls invoice and customer data from QuickBooks via QBFC into the same SQLite database.
|
||||
3. Open the main window with the Parts tab active by default (configurable per machine).
|
||||
|
||||
**All searches hit SQLite** — never QuickBooks directly during a lookup. This makes the UI instant.
|
||||
|
||||
**Background sync** refreshes QuickBooks data every few minutes. A "Last synced: 2 min ago" indicator at the bottom of the window shows freshness, with a manual "Refresh" button next to it.
|
||||
|
||||
**Sync scope:** Pull invoices from the last 90 days by default (configurable). Full historical sync only on first run.
|
||||
|
||||
**Network:** The parts CSV lives on the shared network drive so updates propagate to all machines automatically. QuickBooks access happens through each workstation's local QuickBooks installation, which already talks to the server-hosted company file.
|
||||
|
||||
---
|
||||
|
||||
## UI — Parts tab (packer workflow)
|
||||
|
||||
A single large search box at the top. As the user types, fuzzy matching runs across `STOCK NUMBER`, `DESCRIPTION`, and `INTERCHANGE`, showing up to ~15 results in a list. Clicking a result expands a detail panel showing:
|
||||
|
||||
- **Full SKU** in large bold text with a copy button
|
||||
- **Part image** (from SMB share if available, else the CSV's `Image URL`, cached to disk after first load)
|
||||
- **Customer Price** prominently displayed
|
||||
- **LIST price** shown smaller and clearly labeled as secondary
|
||||
- **Description**
|
||||
- **Practical fields:** `BIN LOCATION`, `YARD LOCATION`, `QUANTITY`, `AVAILABLE`, `GRADE`
|
||||
- **Warranty info** as a small footer line
|
||||
|
||||
---
|
||||
|
||||
## UI — Shipping tab (shipping associate workflow)
|
||||
|
||||
Same pattern: large search box at top, fuzzy match across customer name and invoice number, results list, click to expand. Detail panel shows each of these on its own line with its own copy button:
|
||||
|
||||
- **Company name**
|
||||
- **Street address**
|
||||
- **City, State, Zip**
|
||||
- **Email**
|
||||
- **Invoice number**
|
||||
|
||||
Plus a single **"Copy full address"** button at the top of the address block that copies the whole `Company / Street / City State Zip` formatted block in one click — this is what shipping label software typically expects.
|
||||
|
||||
---
|
||||
|
||||
## Phased rollout
|
||||
|
||||
### Phase 1 — Parts tab only (~1–2 weeks build)
|
||||
|
||||
No QuickBooks dependency. Load CSV, fuzzy search, image display, copy buttons, packaged as a working `.exe`. Ship to packers immediately. This de-risks deployment, packaging, and end-user feedback before adding QuickBooks complexity.
|
||||
|
||||
### Phase 2 — Shipping tab + QuickBooks integration (~2–3 weeks build)
|
||||
|
||||
QBFC integration, one-time authorization on each workstation (a QuickBooks admin must approve the app's connection request once per machine — this is normal and documented), sync logic, shipping tab UI.
|
||||
|
||||
### Phase 3 — Polish & migration
|
||||
|
||||
Flip the image source over to SMB when the share is populated. Reporting/logging if the team wants it. Auto-update mechanism (or simply replace the `.exe` on the shared drive — simpler).
|
||||
|
||||
---
|
||||
|
||||
## Open questions to resolve before Phase 2
|
||||
|
||||
These don't block Phase 1.
|
||||
|
||||
1. **Email location in QuickBooks:** Is the email on the customer record, the invoice itself, or both? (Open an invoice in QuickBooks and check whether there's a per-invoice email field populated, vs. just on the customer.)
|
||||
2. **Address type:** Should shipping search return the **billing address** or the **shipping address** from the invoice? These can differ in QuickBooks.
|
||||
3. **SKU matching:** Do the stock numbers in the CSV exactly match the item codes used on QuickBooks invoice line items? If yes, opens up future features like "this invoice contains these parts, here are the pictures."
|
||||
4. **Shipping software format:** What software is used for labels (ShipStation, UPS WorldShip, Stamps.com, etc.)? This determines the exact format of the "Copy full address" output.
|
||||
|
||||
---
|
||||
|
||||
## What to share with the next Claude session
|
||||
|
||||
When picking this up in a new Claude session (Cowork, etc.), provide:
|
||||
|
||||
1. **This plan document.**
|
||||
2. **The current parts CSV** (`MM-DD-YYYY_OnPart_inv.csv`) — Claude needs to see the actual data to write code against it.
|
||||
3. **A screenshot of a typical invoice in QuickBooks** showing the address, email, and line item area — this lets Claude know exactly which QBFC fields to pull.
|
||||
4. **A screenshot or sample of the shipping software** that consumes the address — so the "Copy full address" format matches what's expected.
|
||||
5. **Your answers to the four open questions above**, if you have them.
|
||||
|
||||
---
|
||||
|
||||
## Suggested next steps
|
||||
|
||||
1. Confirm this plan reflects what you want.
|
||||
2. Decide whether to build Phase 1 first (recommended — packers get value in ~2 weeks) or wait and build everything at once.
|
||||
3. Gather the screenshots and answers listed above for when Phase 2 starts.
|
||||
4. Identify which workstation will be used for development/testing so QuickBooks authorization is set up there first.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Session Hand-off Log — Parts & Invoice Lookup
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **To the next Claude Session:** Read this log to see all modifications. The facts details section is collapsible, resize performance is optimized, desktop icons are fully compiled and configured, and a thorough Stamps.com integration research report is available.
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
### 1. Collapsible Details Dropdown & Preserved Left-Alignment
|
||||
- **Component:** `_CollapsibleFrame` added in [app/ui_parts_tab.py](file:///c:/Users/mario/OneDrive/Documents/Claude/Projects/Part%20Lookup%20Program%20%281%29/app/ui_parts_tab.py).
|
||||
- **Behavior:** Wraps facts grid; starts **collapsed (closed)** by default. Preserves standard w-alignment (left-aligned) for maximum scan reading speed.
|
||||
|
||||
### 2. Resize Performance Optimization (Smooth Dragging)
|
||||
- **Problem:** Resizing the window caused high-frequency flashing/lag.
|
||||
- **Solution:** Swapped `fg_color="transparent"` for solid `fg_color=T.PANEL_BG` inside scrollable frames `self._results_scroll` and `self._detail`. It completely bypasses expensive recursive canvas calculations during resize ticks, resulting in zero-flash smooth resizing (fully visually transparent to users).
|
||||
|
||||
### 3. Desktop Icon Integration & Standalone Executable Custom Icon
|
||||
- **Task:** Integrate `icon_large.png` and `icon_small.png` into the app.
|
||||
- **Implementation Strategy:**
|
||||
1. **Assets Directory:** Copied the icons to `app/assets/`.
|
||||
2. **Automated Conversion:** Updated both `build.bat` and `run_dev.bat` to automatically convert `icon_small.png` into a high-quality Windows multi-resolution icon `icon.ico` using Pillow at execution time.
|
||||
3. **Window Icon (Runtime):** Programmed [app/ui.py](file:///c:/Users/mario/OneDrive/Documents/Claude/Projects/Part%20Lookup%20Program%20%281%29/app/ui.py) to automatically load and display the native icon (preferring the `.ico` file, falling back to `.png` using `ImageTk`) on the main window title bar.
|
||||
4. **Executable Icon (Windows Explorer):** Configured [PartsLookup.spec](file:///c:/Users/mario/OneDrive/Documents/Claude/Projects/Part%20Lookup%20Program%20%281%29/PartsLookup.spec) to use the generated `icon.ico` as the system icon for `PartsLookup.exe` under Windows File Explorer (`icon="app/assets/icon.ico"`), and corrected PyInstaller bundling destination paths.
|
||||
|
||||
### 4. Robust & Lock-Proof Scripting
|
||||
- **Improvements:** `build.bat` and `run_dev.bat` auto-activate `.venv` or `venv` virtual environments, select standard python commands automatically, force-kill any running background app processes to prevent PermissionErrors, and prompt users with a retry dialog if the output folder is locked by an open File Explorer window.
|
||||
|
||||
### 5. Stamps.com Shipping Integration Research
|
||||
- **Request:** Investigate the feasibility of adding Stamps.com connectivity to the Shipping Tab.
|
||||
- **Result:** Conducted research and compiled a detailed report at `C:\Users\mario\.gemini\antigravity\brain\b9bbe4ff-e586-4a85-a0b8-98f43d9ac965\stamps_integration_research.md`. It outlines direct API integration (REST/SOAP) and compares it to highly recommended middleware multi-carrier APIs (EasyPost/Shippo) with Python code blocks, Mermaid architecture diagrams, and development roadmap stages.
|
||||
|
||||
---
|
||||
|
||||
## How to Verify
|
||||
1. Run development server:
|
||||
```cmd
|
||||
run_dev.bat
|
||||
```
|
||||
2. Build standalone executable:
|
||||
```cmd
|
||||
build.bat
|
||||
```
|
||||
3. Verify that `dist\PartsLookup\PartsLookup.exe` displays the custom icon in Windows Explorer, and the running window displays the icon on the top-left taskbar natively.
|
||||
Reference in New Issue
Block a user