205 lines
6.1 KiB
Markdown
205 lines
6.1 KiB
Markdown
# 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 |
|