137 lines
6.6 KiB
Markdown
137 lines
6.6 KiB
Markdown
# Canteen Asset Geolocation Tool
|
|
|
|
Mobile-friendly webapp for tracking physical assets with barcode scanning, OCR sticker reading, and GPS check-ins. Built with FastAPI + SQLite + vanilla JS.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cd ~/projects/canteen-asset-tracker
|
|
./start.sh
|
|
```
|
|
|
|
Then open `https://canteen.ourpad.casa` on your phone. HTTPS via NPMPlus reverse proxy → backend on :8901.
|
|
|
|
## Default Login
|
|
|
|
The server seeds a default admin account on first startup:
|
|
|
|
| Field | Value |
|
|
|----------|-------------|
|
|
| Username | `admin` |
|
|
| Password | `Brett85!@` |
|
|
|
|
**Change this password on first login** via the Settings → Users tab.
|
|
|
|
## Features
|
|
|
|
- **Add Asset tab** — Three entry modes:
|
|
- **Barcode** — Live camera scanning via ZXing. Uses 1D-only format hints (Code 128, Code 39, EAN/UPC, ITF, Codabar) with `decodeFromVideoDevice` for fast, accurate detection. Auto-looks up assets or offers to create new ones.
|
|
- **OCR** — Snap a photo of the Connect ID sticker. Extracts the last 5 digits from the `XXXXX-XXXXXX` pattern (e.g., `05912-095330` → `95330`).
|
|
- **Manual** — Full form with photo capture, customer/location assignment, keys, and badges.
|
|
- **Auto check-in** — Every new asset (from any entry mode) gets an automatic GPS check-in on creation. If GPS isn't available yet, the manual check-in button remains.
|
|
- **Assets tab** — Browse, search, filter, create, edit, delete assets. View check-in history per asset with map.
|
|
- **Dashboard tab** — Stats: total assets, check-ins, breakdown by category and status. CSV export.
|
|
- **Activity tab** — Full activity feed with user filtering.
|
|
- **Map tab** — View all assets and check-ins on an interactive Leaflet map.
|
|
- 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 (single file, ~280KB) |
|
|
| Scanner | @zxing/library 0.20.0 (CDN) |
|
|
| OCR | Tesseract (pytesseract + PIL) |
|
|
| Maps | Leaflet + Leaflet.Draw + Leaflet.Heat |
|
|
| TLS | Self-signed cert, port 8901, proxied via NPMPlus |
|
|
|
|
## API
|
|
|
|
Base URL: `https://canteen.ourpad.casa`
|
|
|
|
Auth: Bearer token (obtained via `/api/auth/login`)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|---------------------------------|-------------------------------------|
|
|
| POST | `/api/auth/login` | Login, returns token |
|
|
| GET | `/api/auth/me` | Current user info |
|
|
| POST | `/api/assets` | Create asset |
|
|
| GET | `/api/assets` | List assets (filterable) |
|
|
| GET | `/api/assets/search?machine_id=`| Lookup by machine ID |
|
|
| 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 (GPS + photo) |
|
|
| GET | `/api/checkins` | List check-ins (filterable) |
|
|
| POST | `/api/ocr` | OCR sticker image → machine_id |
|
|
| GET | `/api/stats` | Dashboard stats |
|
|
| GET | `/api/export/assets` | Export assets CSV |
|
|
| GET | `/api/export/checkins` | Export check-ins CSV |
|
|
| GET | `/api/activity` | Activity feed |
|
|
| * | `/api/settings/{entity}` | Dynamic CRUD for 6 entity types |
|
|
| * | `/api/customers` | Customer CRUD |
|
|
| * | `/api/locations` | Location CRUD + rooms |
|
|
| * | `/api/users` | User CRUD |
|
|
| * | `/api/geofences` | Geofence CRUD + user assignment |
|
|
| * | `/api/visits` | Visit CRUD + stats |
|
|
| * | `/api/proximity` | Find assets near GPS point |
|
|
| POST | `/api/upload/photo` | Upload asset photo |
|
|
| POST | `/api/upload/icon` | Upload icon |
|
|
|
|
### OCR endpoint
|
|
|
|
`POST /api/ocr` — Upload a sticker image (multipart form, field `file`). Extracts machine ID from `XXXXX-XXXXXX` Connect ID pattern, returning only the last 5 digits.
|
|
|
|
```json
|
|
{
|
|
"machine_id": "95330",
|
|
"raw_text": "CONNECT ...",
|
|
"raw_match": "05912-095330",
|
|
"confidence": "high"
|
|
}
|
|
```
|
|
|
|
### Asset fields
|
|
|
|
`machine_id` (unique, required), `name` (required), `serial_number`, `description`, `category` (Furniture/Appliances/Utensils & Serveware/Equipment/Other), `status` (active/maintenance/retired), `make`, `model`, `address`, `building_name`, `building_number`, `floor`, `room`, `trailer_number`, `walking_directions`, `map_link`, `parking_location`, `photo_path`, `customer_id`, `location_id`, `assigned_to`, `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 |
|
|
| `CANTEEN_SKIP_AUTH`| (empty) | Set to `1` for tests |
|
|
|
|
## 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, auth, OCR)
|
|
├── openapi.yaml # API contract (source of truth)
|
|
├── start.sh # One-command startup with cert gen
|
|
├── static/
|
|
│ └── index.html # SPA frontend (vanilla JS, self-contained)
|
|
├── tests/ # pytest test suite
|
|
├── docs/ # Documentation
|
|
├── uploads/ # Photo/OCR storage (gitignored)
|
|
├── cert.pem # Self-signed TLS cert (auto-generated)
|
|
├── key.pem # TLS private key (auto-generated)
|
|
├── requirements.txt # Python deps
|
|
├── PROJECT.md # Detailed project structure
|
|
└── README.md
|
|
```
|