Initial commit: Canteen Asset Geolocation Tool v2
This commit is contained in:
@@ -0,0 +1,204 @@
|
||||
# Canteen Asset Tracker — Features Walkthrough
|
||||
|
||||
> A mobile-friendly web app for tracking physical assets with barcode scanning, GPS check-ins, geofenced service areas, and technician assignment.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 1. 🔐 Authentication
|
||||
|
||||
- **Login** with username/password
|
||||
- **Remember Me** persists session
|
||||
- Three roles: **Admin**, **Technician**, **readonly**
|
||||
- Default admin account: `admin` / `changeme`
|
||||
|
||||
---
|
||||
|
||||
## 2. 📷 Add Asset
|
||||
|
||||
Three ways to add an asset:
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| **Barcode** | Scan barcodes via device camera (ZXing library). Auto-lookup or prompt to create new. |
|
||||
| **OCR** | Upload a photo of a machine ID sticker; text is extracted via Tesseract OCR. |
|
||||
| **Manual** | Full form with all fields. |
|
||||
|
||||
|
||||
|
||||
### Asset Fields
|
||||
|
||||
- **Required:** Machine ID, Asset Name
|
||||
- **General:** Serial Number, Description, Category, Make, Model, Status
|
||||
- **Directions & Access:** Address/Trailer, Building name/number, Floor, Room, Walking directions, Map link (GPS pin), Parking location
|
||||
- **Keys:** Add named keys (MK300, Master Key, Padlock Key, etc.)
|
||||
- **Security Badges:** Checkboxes for badge types (Contractor, Employee, Visitor, etc.)
|
||||
- **Customer & Location:** Dropdowns for linked customer and location
|
||||
- **Photo:** Take or upload a photo of the asset
|
||||
|
||||
---
|
||||
|
||||
## 3. 📦 Asset List
|
||||
|
||||
- Search by keyword or **Machine ID**
|
||||
- Filter by category, status, make
|
||||
- Sort by date, name, status
|
||||
- Tap any asset for full detail view, edit, or delete
|
||||
- **CSV Import** for bulk asset creation
|
||||
|
||||
### Check-In History
|
||||
|
||||
Each asset has a check-in timeline showing:
|
||||
- GPS coordinates (with map link)
|
||||
- Photo attachments
|
||||
- Notes from the technician
|
||||
- Timestamp
|
||||
|
||||
---
|
||||
|
||||
## 4. 🗺️ Map
|
||||
|
||||
Interactive map powered by **Leaflet** + **OpenStreetMap** (free, no API key).
|
||||
|
||||
|
||||
|
||||
### Map Controls
|
||||
|
||||
| Button | Action |
|
||||
|--------|--------|
|
||||
| 📍 **Pins** | Toggle asset location pins on/off |
|
||||
| 🔥 **Heatmap** | Toggle density heatmap of assets |
|
||||
| ✏️ **Add Geofence** | Enter draw mode to create polygons |
|
||||
| ◎ **My Location** | Center map on your GPS position |
|
||||
|
||||
### Asset Pins
|
||||
|
||||
- Each pin shows the asset name, machine ID, status, category
|
||||
- **Directions** link opens Google Maps navigation
|
||||
- **Details** button opens the full asset view
|
||||
- GPS blue dot shows your current location
|
||||
|
||||
### Geofences (Service Areas)
|
||||
|
||||
Draw polygons on the map to define service territories:
|
||||
|
||||
- Custom colors per zone
|
||||
- **Point-in-polygon check** determines which zone contains a given GPS point
|
||||
- Each geofence can be assigned to one or more **technicians** (see §7)
|
||||
- Edit or delete existing geofences from the popup
|
||||
|
||||
---
|
||||
|
||||
## 5. 📊 Dashboard
|
||||
|
||||
|
||||
|
||||
### Key Metrics
|
||||
- Total assets, total check-ins, active technicians
|
||||
|
||||
### Breakdowns
|
||||
- **By Category** — Equipment, Furniture, Appliances, Utensils & Serveware, Other
|
||||
- **By Status** — Active, Maintenance, Retired
|
||||
- **By Make / Manufacturer** — see which brands you have most of
|
||||
- **Most Visited Assets** — top assets by check-in count
|
||||
|
||||
### Quick Actions
|
||||
- **Assets CSV** — download full asset spreadsheet
|
||||
- **Check-ins CSV** — download check-in log
|
||||
- **Service Summary** — CSV report grouped by location/geofence
|
||||
- **Refresh** — reload dashboard data
|
||||
|
||||
### Recent Activity Feed
|
||||
Live feed of creates, updates, and deletes across the system. Tap **View All** for the full activity log.
|
||||
|
||||
---
|
||||
|
||||
## 6. 📋 Reports
|
||||
|
||||
- **Assets CSV Export** — all asset data with location, status, keys, badges
|
||||
- **Check-ins CSV Export** — history with GPS coordinates, timestamps, notes
|
||||
- **Service Summary** — company/location-based summary for billing or service records
|
||||
|
||||
---
|
||||
|
||||
## 7. 👤 Users & Service Areas
|
||||
|
||||
### User Management (Settings → Users)
|
||||
- Create, edit, delete users
|
||||
- Set role: Admin, Technician, readonly
|
||||
- Each technician can be assigned to multiple geofence service areas
|
||||
|
||||
### Assigning Users to Geofences
|
||||
|
||||
From the **Map** tab:
|
||||
|
||||
1. Tap an existing geofence polygon on the map
|
||||
2. Tap **👤 Assign** in the popup
|
||||
3. Check the technicians that cover this zone
|
||||
4. Save
|
||||
|
||||
Or from the **Geofence List** (below the map):
|
||||
|
||||
- Each zone shows an 👤 icon with user count
|
||||
- Tap **Assign** to open the same dialog
|
||||
|
||||
### API Endpoint
|
||||
|
||||
```
|
||||
GET /api/users/{user_id}/geofences
|
||||
```
|
||||
|
||||
Returns all geofence service areas assigned to a specific user — useful for filtering assets or visits by a technician's territory.
|
||||
|
||||
---
|
||||
|
||||
## 8. ⚙️ Settings
|
||||
|
||||
|
||||
|
||||
| Section | Description |
|
||||
|---------|-------------|
|
||||
| **Categories** | Manage asset categories (Appliances, Equipment, Furniture, etc.) |
|
||||
| **Makes & Models** | Manage manufacturers and their models |
|
||||
| **Key Names** | Key types for access (MK300, Master Key, Padlock Key, etc.) |
|
||||
| **Key Types** | Physical key types (Barrel, Flat, Standard, Tubular, etc.) |
|
||||
| **Security Badges** | Badge requirements (Contractor, Employee, Visitor, etc.) |
|
||||
| **Users** | Account management with role assignment |
|
||||
| **Theme** | Toggle between Dark and Light mode |
|
||||
| **Reset Database** | Wipe all data (admin only, requires confirmation) |
|
||||
|
||||
---
|
||||
|
||||
## 9. 🏢 Customers & Locations
|
||||
|
||||
- **Customers** — company records with contact info
|
||||
- **Locations** — sites under each customer
|
||||
- **Rooms** — specific rooms/areas within locations
|
||||
- Hierarchical: Customer → Location → Room
|
||||
- Each asset can be linked to a customer and location
|
||||
|
||||
---
|
||||
|
||||
## 10. 📱 Mobile Features
|
||||
|
||||
- **Responsive design** works on phones, tablets, and desktops
|
||||
- **Bottom navigation bar** for one-handed use
|
||||
- **Camera integration** for barcode scanning and OCR
|
||||
- **GPS auto-acquisition** for location-tagged check-ins
|
||||
- **Touch-friendly** form fields and buttons
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|-----------|
|
||||
| **Backend** | FastAPI + SQLite (WAL mode) |
|
||||
| **Frontend** | Vanilla HTML/CSS/JS (single file, no build step) |
|
||||
| **Maps** | Leaflet 1.9.4 + OpenStreetMap |
|
||||
| **Geofences** | Leaflet Draw + point-in-polygon (Turf.js) |
|
||||
| **Scanner** | ZXing (CDN) |
|
||||
| **OCR** | Tesseract via pytesseract |
|
||||
| **TLS** | Self-signed cert on port 8901 |
|
||||
| **Reverse Proxy** | Nginx Proxy Manager Plus |
|
||||
Reference in New Issue
Block a user