Initial commit

parts_invoice_lookup_app_plan.md

@@ -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.