Initial commit: Canteen Asset Geolocation Tool v2

2026-05-17 18:55:28 -04:00
commit 7da3f28c6a
50 changed files with 19509 additions and 0 deletions
@@ -0,0 +1,106 @@
+# Canteen Asset Geolocation Tool
+
+Mobile-friendly webapp for tracking physical assets with barcode scanning and GPS check-ins. Built with FastAPI + SQLite + vanilla JS.
+
+## Quick Start
+
+```bash
+./start.sh
+```
+
+Then open `https://<server-ip>:8901` on your phone. Accept the self-signed cert warning.
+
+## Default Login
+
+The server seeds a default admin account on first startup:
+
+| Field    | Value      |
+|----------|------------|
+| Username | `admin`    |
+| Password | `changeme` |
+
+**Change this password on first login** via the Settings → Users tab.
+
+## Features
+
+- **Scan tab** — Barcode scanning via camera. Auto-looks up assets or offers to create new ones.
+- **Assets tab** — Browse, search, filter, create, edit, delete assets. View check-in history per asset.
+- **Dashboard tab** — Stats: total assets, check-ins, breakdown by category and status. CSV export.
+- GPS auto-acquired on page load for location-tagged check-ins.
+
+## Tech Stack
+
+| Layer    | Tech                        |
+|----------|-----------------------------|
+| Backend  | FastAPI + SQLite (WAL mode) |
+| Frontend | Vanilla HTML/CSS/JS         |
+| Scanner  | ZXing library (CDN)         |
+| TLS      | Self-signed cert, port 8901 |
+
+## API
+
+Base URL: `https://<host>:8901`
+
+| Method | Endpoint                      | Description                        |
+|--------|-------------------------------|------------------------------------|
+| GET    | `/health`                     | Health check                       |
+| POST   | `/api/assets`                 | Create asset                       |
+| GET    | `/api/assets`                 | List assets (filterable)           |
+| GET    | `/api/assets/search?barcode=`   | Lookup by barcode                |
+| GET    | `/api/assets/{id}`            | Get single asset                   |
+| PUT    | `/api/assets/{id}`            | Update asset                       |
+| DELETE | `/api/assets/{id}`            | Delete asset + check-ins           |
+| POST   | `/api/checkins`               | Create check-in                    |
+| GET    | `/api/checkins`               | List check-ins (filterable)        |
+| GET    | `/api/stats`                  | Dashboard stats                    |
+| GET    | `/api/export/assets`          | Export assets CSV                  |
+| GET    | `/api/export/checkins`        | Export check-ins CSV               |
+| POST   | `/api/geofences`              | Create geofence (opt. `user_ids`)  |
+| GET    | `/api/geofences`              | List geofences (includes assigned users) |
+| PUT    | `/api/geofences/{id}`         | Update geofence (+ reassign users) |
+| DELETE | `/api/geofences/{id}`         | Delete geofence                    |
+| GET    | `/api/users/{id}/geofences`   | List geofences assigned to a user  |
+| GET    | `/api/locations`              | List locations                     |
+| GET    | `/api/locations/{id}`         | Get location with rooms            |
+| GET    | `/api/rooms`                  | List rooms                         |
+| GET    | `/api/activity`               | Activity feed                      |
+
+### Asset fields
+
+`barcode` (unique, required), `name` (required), `description`, `category` (Furniture/Appliances/Utensils & Serveware/Equipment/Other), `status` (active/maintenance/retired), `photo_path`, `created_at`, `updated_at`.
+
+### Check-in fields
+
+`asset_id` (required), `latitude`, `longitude`, `accuracy`, `photo_path`, `notes`, `created_at`.
+
+## Environment Variables
+
+| Variable        | Default                    | Description           |
+|-----------------|----------------------------|-----------------------|
+| `CANTEEN_PORT`  | `8901`                     | Listen port           |
+| `CANTEEN_DB_PATH` | `./assets.db`            | SQLite database path  |
+| `CANTEEN_WIPE_DB` | (empty)                  | Set to `1` to clear DB on start |
+
+## Running Tests
+
+```bash
+pip install -r requirements.txt
+python -m pytest tests/ -v
+```
+
+## Project Structure
+
+```
+canteen-asset-tracker/
+├── server.py          # FastAPI app (all routes, DB, error handling)
+├── start.sh           # One-command startup with cert gen
+├── static/
+│   └── index.html     # SPA frontend (3 tabs + scanner)
+├── tests/
+│   └── test_server.py # 47 integration tests
+├── uploads/           # Photo storage (gitignored)
+├── cert.pem           # Self-signed TLS cert (auto-generated)
+├── key.pem            # TLS private key (auto-generated)
+├── requirements.txt   # Python deps
+└── README.md
+```