feat: Implement supplier export functionality with workbook generation

- Add `writeSupplierWorkbook` function to create Excel workbooks for supplier analysis results.
- Introduce `SupplierExportSummary` type for summarizing export data.
- Create tests for `writeSupplierWorkbook` to ensure correct sheet creation and data population.
- Implement supplier scoring logic in `supplier-scoring.ts` to evaluate product profitability and demand.
- Add tests for supplier scoring to validate scoring logic and verdict determination.
- Enhance UPC file analysis to integrate supplier scoring and export results to Excel.
- Update database writing logic to accommodate new supplier analysis results.
- Refactor types to include supplier-specific data structures and scoring metrics.
- Ensure proper cleanup of temporary files after tests.

README.md

@@ -21,21 +21,21 @@ cp .env.example .env
 ## Usage
 
 ```bash
-bun run src/index.ts <input.csv|xlsx> [--out results.csv]
+bun run src/index.ts input/<input.csv|xlsx> [--out output/results.xlsx]
 ```
 
 Examples:
 
 ```bash
-bun run src/index.ts leads.xlsx
-bun run src/index.ts leads.csv --out results.xlsx
+bun run src/index.ts input/leads.xlsx
+bun run src/index.ts input/leads.csv --out output/results.xlsx
 ```
 
 Large-file behavior:
 
 - If the input has more than 50 products, processing is done in chunks of 50.
-- Each chunk is analyzed and written to a numbered output file, for example: `results_part_001.xlsx`, `results_part_002.xlsx`, ...
-- If `--out` is omitted for large files, the base output name defaults to `<input>_results.xlsx` and chunk files are still written with numbered suffixes.
+- Each chunk is analyzed and written to a numbered output file under `output/`, for example: `output/results_part_001.xlsx`, `output/results_part_002.xlsx`, ...
+- If `--out` is omitted for large files, the base output name defaults to `output/<input>_results.xlsx` and chunk files are still written with numbered suffixes.
 
 Quick SP-API connectivity tests:
 
@@ -130,27 +130,36 @@ curl -X POST "http://localhost:3000/api/upc/lookup" \
 
 ## Large UPC File Analysis (XLS/XLSX)
 
-For very large Excel files that contain UPC values, use the dedicated UPC-file process. It runs in batches:
+For supplier price lists that contain UPC/EAN values and unit cost, use the
+dedicated UPC-file process. It runs in batches and produces a deterministic
+ranked sourcing workbook:
 
 1. Reads UPC rows in batches (`.xlsx` uses streaming reader, `.xls` uses fallback row-window parsing).
-2. Resolves UPCs to ASINs with Keepa.
-3. Runs the same sellability + Keepa/SP-API enrichment + LLM verdict pipeline as lead analysis.
-4. Persists output into existing `runs` + `results` tables, so it appears in current reporting APIs/UI.
+2. Resolves UPCs to ASINs with SP-API catalog lookup first, then falls back to Keepa for no-match/request-failure cases.
+3. Enriches resolved ASINs with Keepa demand/competition data and SP-API sellability + FBA fees.
+4. Scores products with deterministic BUY/WATCH/SKIP logic; this path does not call LM Studio.
+5. Writes a ranked Excel workbook and persists rows into the existing `runs` + `results` tables.
 
 CLI usage:
 
 ```bash
-bun run upc-file --input huge-upcs.xlsx
-bun run upc-file --input huge-upcs.xls --input-batch-size 500 --upc-lookup-batch-size 100 --max-rows 10000
+bun run upc-file --input input/huge-upcs.xlsx
+bun run upc-file --input input/supplier.xlsx --out output/supplier_ranked.xlsx
+bun run upc-file --input input/huge-upcs.xls --input-batch-size 500 --upc-lookup-batch-size 100 --max-rows 10000
 ```
 
+Workbook output includes `Ranked Leads`, `Skipped`, and `Summary` sheets with
+UPC, ASIN, cost, sale price, FBA fee, profit, margin, ROI, BSR, rank drops,
+monthly sold, seller count, Amazon Buy Box share, sellability, score, verdict,
+and reason columns.
+
 API usage (when `bun run start:web` is running):
 
 ```bash
 curl -X POST "http://localhost:3000/api/process/upc-file" \
   -H "content-type: application/json" \
   -d '{
-    "inputFile": "/absolute/path/to/huge-upcs.xlsx",
+    "inputFile": "/absolute/path/to/input/huge-upcs.xlsx",
     "inputBatchSize": 300,
     "upcLookupBatchSize": 100
   }'
@@ -222,7 +231,7 @@ Numeric parsing accepts plain numbers as well as formatted values like `$12.50`,
 
 ## Persistent Storage with SQLite
 
-Results from each run are now stored in a SQLite database named `results.db` in the project root. The SQLite implementation details are handled in `src/database.ts`. This allows you to:
+Results from each run are now stored in a SQLite database named `db/results.db` by default. The SQLite implementation details are handled in `src/database.ts`. This allows you to:
 
 - Revisit past analysis results.
 - Query and analyze historical data.