107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
# 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
|
|
```
|