From eaa165a43b2b9bfca684b27bde0aeacab5eafbd2 Mon Sep 17 00:00:00 2001
From: Shawn <shawn@ourpad.casa>
Date: Sun, 24 May 2026 18:33:23 -0400
Subject: [PATCH] Initial scaffold: project skeleton, README, requirements,
 main.py stub

---
 .gitignore       | 20 ++++++++++++++++++
 README.md        | 55 ++++++++++++++++++++++++++++++++++++++++++++++++
 main.py          | 31 +++++++++++++++++++++++++++
 requirements.txt | 13 ++++++++++++
 4 files changed, 119 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 main.py
 create mode 100644 requirements.txt

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..21e3b20
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+
+# Data (gitignored but tracked via seed-data/*.csv pattern)
+seed-data/*.csv
+
+# Database
+*.db
+*.db.bak
+*.db-*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Reports
+reports/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e2393b2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# 🌱 Canteen Seed Data Import Tool
+
+Standalone seed data import tool for the [Canteen Asset Tracker](https://canteen.ourpad.casa).
+Conceptualizes the import pipeline before integration into the admin panel.
+
+## Purpose
+
+Import Cantaloupe seed data (CSV export) into the canteen assets database with:
+
+- **Header Mapping** — Raw Excel headers → CSV headers → DB column names
+- **Location Extraction** — Parse Customer & Place columns into structured fields
+- **GPS Derivation** — Handle multi-floor GPS offsets
+- **Serial Validation** — OCR corrections, unknown machine identification
+- **Type/Class/Make/Model Normalization** — Consolidate to Class, Make, Model
+- **Pricing Status Decoding** — Remote pricing status meanings
+- **Telemetry Decoding** — Card reader brand/type from telemetry IDs
+- **Alert Interpretation** — Alert code meanings
+- **Sales Priority Scoring** — Low/mid/high business value
+- **Backup & Restore** — Preserve existing GPS + check-in data
+- **Validation Reports** — Detailed import summary
+
+## Data Files
+
+```
+seed-data/
+├── header_modified.csv    # Header mapping: raw Excel → CSV → DB
+├── import_seed.csv        # Seed data (vending machine export)
+└── reference_handbook.md  # Extraction rules & reference docs
+```
+
+## Usage
+
+```
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+python main.py seed-data/import_seed.csv --db /path/to/assets.db [--dry-run]
+```
+
+## Integration
+
+Once validated, this tool will be integrated into the [Canteen Admin Server](https://admin.canteen.ourpad.casa).
+
+## Database Schema
+
+Shares the same `assets.db` schema as the Canteen Asset Tracker:
+
+- **assets** table with columns: machine_id, serial_number, name, make, model, address, building_name, building_number, floor, room, trailer_number, latitude, longitude, company, location_area, place, category, status, priority, pricing_status, card_reader_brand, card_reader_model, dex_report_date, install_date, deployed, pulled_date, disney_park, is_disney, etc.
+- **checkins** table for GPS check-in records
+- See main project for full schema.
+
+## Priority
+
+This tool is a conceptual prototype. Once the pipeline is stable, the logic will be ported to the admin panel as a feature.
diff --git a/main.py b/main.py
new file mode 100644
index 0000000..6469ecb
--- /dev/null
+++ b/main.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+🌱 Canteen Seed Data Import Tool
+
+Standalone import pipeline for Cantaloupe CSV exports.
+Run with --help for usage.
+
+Pipeline stages:
+  1. Backup existing GPS + check-ins from target DB
+  2. Parse & map CSV headers
+  3. Extract location data from Customer/Place columns
+  4. Derive GPS coordinates (with multi-floor support)
+  5. Validate & correct serial numbers
+  6. Normalize Class/Make/Model
+  7. Apply pricing status, telemetry, alert metadata
+  8. Score priority from sales data
+  9. Write to DB (preserving existing GPS/check-ins)
+  10. Generate validation report
+"""
+
+import sys
+
+
+def main():
+    print("🌱 Canteen Seed Data Import Tool")
+    print("  Coming soon — pipeline modules pending.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..a1db36a
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,13 @@
+# CSV parsing + data processing
+pandas>=2.0
+numpy>=1.24
+
+# Database
+sqlite-utils>=3.0
+
+# Geocoding (for GPS derivation)
+httpx>=0.24
+
+# CLI
+rich>=13.0
+click>=8.0