Initial commit: Canteen Asset Geolocation Tool v2
This commit is contained in:
@@ -0,0 +1,364 @@
|
||||
# Canteen Asset Tracker — User Guide
|
||||
|
||||
> A practical guide for technicians, supervisors, and admins using the Canteen Asset Tracker.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Getting Started](#1-getting-started)
|
||||
2. [Logging In](#2-logging-in)
|
||||
3. [Adding an Asset](#3-adding-an-asset)
|
||||
4. [Checking In on an Asset](#4-checking-in-on-an-asset)
|
||||
5. [Finding Assets on the Map](#5-finding-assets-on-the-map)
|
||||
6. [Working with Geofences (Service Areas)](#6-working-with-geofences-service-areas)
|
||||
7. [Viewing Reports & Dashboard](#7-viewing-reports--dashboard)
|
||||
8. [Managing Users](#8-managing-users)
|
||||
9. [Settings & Configuration](#9-settings--configuration)
|
||||
10. [Tips & Troubleshooting](#10-tips--troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 1. Getting Started
|
||||
|
||||
### Accessing the App
|
||||
|
||||
Open your phone or desktop browser and go to:
|
||||
|
||||
```
|
||||
https://canteen.ourpad.casa:8901
|
||||
```
|
||||
|
||||
> **On your phone:** The app is designed for mobile use — it fits your screen and works with touch controls.
|
||||
|
||||
|
||||
|
||||
### Browser Requirements
|
||||
|
||||
- Any modern browser (Chrome, Firefox, Safari, Edge)
|
||||
- **Camera access** required for barcode scanning (grant when prompted)
|
||||
- **Location/GPS** required for check-in location tagging (grant when prompted)
|
||||
- Accept the self-signed certificate warning (it's safe — the cert is auto-generated)
|
||||
|
||||
---
|
||||
|
||||
## 2. Logging In
|
||||
|
||||
### Default Credentials
|
||||
|
||||
| Role | Username | Password |
|
||||
|------|----------|----------|
|
||||
| Admin | `admin` | `changeme` |
|
||||
|
||||
**⚠️ Change the default password immediately** via Settings → Users → Edit.
|
||||
|
||||
### Login Screen
|
||||
|
||||
1. Enter your **Username**
|
||||
2. Enter your **Password**
|
||||
3. Check **Remember me** to stay logged in
|
||||
4. Tap **Sign In**
|
||||
|
||||
### User Roles
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| **Admin** | Full access — create/edit/delete everything, manage users |
|
||||
| **Technician** | Add assets, check in, view maps and geofences |
|
||||
| **readonly** | Read-only — browse assets, view dashboard and reports |
|
||||
|
||||
---
|
||||
|
||||
## 3. Adding an Asset
|
||||
|
||||
Tap the **📷 Add Asset** tab (bottom nav bar or drawer menu).
|
||||
|
||||
You have three methods:
|
||||
|
||||
### Option A: Barcode Scan
|
||||
|
||||
1. Tap the **📷 Barcode** tab
|
||||
2. Point your camera at the asset's barcode
|
||||
3. If the barcode exists → asset details load
|
||||
4. If new → you're prompted to create the asset with the scanned barcode
|
||||
|
||||
### Option B: OCR (Photo of Machine ID)
|
||||
|
||||
1. Tap the **🔍 OCR** tab
|
||||
2. Take a photo of the machine ID sticker
|
||||
3. The app extracts the ID number automatically
|
||||
4. Confirm and fill in remaining details
|
||||
|
||||
### Option C: Manual Entry
|
||||
|
||||
Tap **✏️ Manual** and fill out the form:
|
||||
|
||||
**Required fields:**
|
||||
- **Machine ID** — unique identifier (often found on a sticker)
|
||||
- **Asset Name** — descriptive name (e.g., "Walk-In Cooler")
|
||||
|
||||
|
||||
|
||||
**Optional details:**
|
||||
- Serial Number, Description
|
||||
- **Category** — Equipment, Furniture, Appliances, etc.
|
||||
- **Make** — brand/manufacturer
|
||||
- **Model** — specific model
|
||||
- **Status** — Active, Maintenance, Retired
|
||||
|
||||
**📍 Directions & Access** — critical for finding the asset later:
|
||||
- Address / Trailer Number
|
||||
- Building name and number
|
||||
- Floor and Room
|
||||
- Walking directions (e.g., "Enter through loading dock, go left")
|
||||
- Map link or tap **Pin** to drop a GPS pin
|
||||
- Parking location
|
||||
|
||||
**🔑 Keys needed:**
|
||||
Tap **+ Add Key** to record which keys are required (e.g., MK300, Master Key, Padlock Key)
|
||||
|
||||
**🪪 Security Badges:**
|
||||
Check which badges are required for access (Contractor, Employee, Visitor, etc.)
|
||||
|
||||
**🏢 Customer & Location:**
|
||||
Select the customer and site location from dropdowns.
|
||||
|
||||
**📸 Photo:**
|
||||
Tap the camera area to take a photo of the asset.
|
||||
|
||||
### Save
|
||||
|
||||
- **Create Asset** — saves and stays on the form
|
||||
- **+ Add Another** — saves and clears the form for the next asset
|
||||
|
||||
---
|
||||
|
||||
## 4. Checking In on an Asset
|
||||
|
||||
### From the Asset Detail View
|
||||
|
||||
1. Tap **📦 Asset List**
|
||||
2. Search or browse to find the asset
|
||||
3. Tap on the asset row to open details
|
||||
4. Tap **Check In**
|
||||
5. Your GPS location is captured automatically
|
||||
6. Optionally add notes or a photo
|
||||
7. Tap **Submit**
|
||||
|
||||
### Via the Dashboard
|
||||
|
||||
- The **Recent Activity** feed shows the latest check-ins
|
||||
- Tap any check-in entry to see details
|
||||
|
||||
---
|
||||
|
||||
## 5. Finding Assets on the Map
|
||||
|
||||
Tap the **🗺️ Map** tab.
|
||||
|
||||
|
||||
|
||||
### Toggle Layers
|
||||
|
||||
| Button | What it does |
|
||||
|--------|-------------|
|
||||
| 📍 **Pins** | Show/hide asset location pins on the map |
|
||||
| 🔥 **Heatmap** | Show/hide a color heatmap of asset density |
|
||||
| ✏️ **Add Geofence** | Start drawing a service area polygon |
|
||||
| ◎ **My Location** | Center the map on your current GPS position |
|
||||
|
||||
### Using Asset Pins
|
||||
|
||||
- Each pin represents an asset with GPS coordinates
|
||||
- **Tap a pin** to see: asset name, machine ID, status, category
|
||||
- **Directions** — opens Google Maps navigation to that asset
|
||||
- **Details** — opens the full asset record
|
||||
|
||||
### Getting Directions
|
||||
|
||||
1. Find the asset on the map (or in Asset List → Details)
|
||||
2. Tap **Directions** or the map link
|
||||
3. Google Maps opens with the asset as the destination
|
||||
|
||||
---
|
||||
|
||||
## 6. Working with Geofences (Service Areas)
|
||||
|
||||
Geofences let you draw **service zones** on the map and assign **technicians** to cover each zone.
|
||||
|
||||
### Creating a Geofence
|
||||
|
||||
1. Tap the **🗺️ Map** tab
|
||||
2. Tap **✏️ Add Geofence**
|
||||
3. Tap points on the map to draw a polygon around your service area
|
||||
4. Tap the last point to close the shape
|
||||
5. Name the zone (e.g., "Downtown Orlando", "Building A")
|
||||
6. Choose a color
|
||||
7. Tap **Save**
|
||||
|
||||
### Viewing Geofences
|
||||
|
||||
- Saved geofences appear as colored polygons on the map
|
||||
- Tap a polygon to see the zone name and assigned users
|
||||
|
||||
### Assigning Users to a Geofence
|
||||
|
||||
Assigning a technician to a geofence means that zone is **their service area**.
|
||||
|
||||
1. Tap a geofence polygon on the map
|
||||
2. In the popup, tap **👤 Assign**
|
||||
3. A dialog shows all users with checkboxes
|
||||
4. Check the technicians who cover this zone
|
||||
5. Tap **Save**
|
||||
|
||||
Or from the geofence list (below the map):
|
||||
- Each zone shows an 👤 badge with the number of assigned users
|
||||
- Tap **Assign** to open the same dialog
|
||||
|
||||
### Removing User Assignment
|
||||
|
||||
Same process — uncheck a user and save. The user is removed from that service area.
|
||||
|
||||
### Listing a User's Service Areas
|
||||
|
||||
To see all zones a technician is assigned to:
|
||||
|
||||
```
|
||||
GET /api/users/{user_id}/geofences
|
||||
```
|
||||
|
||||
This returns every geofence the user is assigned to — useful for filtering work orders by territory.
|
||||
|
||||
---
|
||||
|
||||
## 7. Viewing Reports & Dashboard
|
||||
|
||||
### Dashboard
|
||||
|
||||
Tap the **📊 Dash** tab to see:
|
||||
- **Total Assets** count
|
||||
- **Total Check-ins** count
|
||||
- **Active Technicians** count
|
||||
|
||||
|
||||
|
||||
- Breakdowns by category, status, and manufacturer
|
||||
- **Most Visited Assets** ranking
|
||||
- **Recent Activity** feed
|
||||
- **Quick Actions** for CSV exports
|
||||
|
||||
### Exporting Reports
|
||||
|
||||
From the Dashboard, tap:
|
||||
|
||||
| Button | What you get |
|
||||
|--------|-------------|
|
||||
| 📋 **Assets CSV** | All assets with location, status, keys, badges |
|
||||
| 📍 **Check-ins CSV** | Check-in history with GPS, timestamps, notes |
|
||||
| 📊 **Service Summary** | Report grouped by customer/location |
|
||||
|
||||
CSV files download to your device and can be opened in Excel, Google Sheets, or any spreadsheet app.
|
||||
|
||||
### Reports Tab
|
||||
|
||||
The **📋 Reports** tab has additional export options and filterable reports.
|
||||
|
||||
---
|
||||
|
||||
## 8. Managing Users
|
||||
|
||||
### Adding a User
|
||||
|
||||
1. Tap **⚙️ Settings** (from drawer menu)
|
||||
2. Scroll to the **Users** section
|
||||
3. Tap **+ Add**
|
||||
4. Enter: Username, Password, Display Name, Role
|
||||
5. Tap **Save**
|
||||
|
||||
### Editing a User
|
||||
|
||||
1. Tap the **✏️** (edit) button next to the user
|
||||
2. Update fields
|
||||
3. Tap **Save**
|
||||
|
||||
### Deleting a User
|
||||
|
||||
1. Tap the **🗑️** (delete) button next to the user
|
||||
2. Confirm deletion
|
||||
3. The user is removed from the system and all geofence assignments are cleaned up automatically
|
||||
|
||||
> **Note:** Deleting a user also removes their geofence assignments (cascade delete). It does NOT delete assets or check-ins created by that user.
|
||||
|
||||
---
|
||||
|
||||
## 9. Settings & Configuration
|
||||
|
||||
### Managing Dropdown Lists
|
||||
|
||||
In **⚙️ Settings** you can add, edit, or delete values for:
|
||||
|
||||
|
||||
|
||||
| List | Example Values |
|
||||
|------|---------------|
|
||||
| **Categories** | Equipment, Furniture, Appliances, Utensils & Serveware, Other |
|
||||
| **Makes** | Cambro, Hobart, Metro, Rubbermaid, Vollrath |
|
||||
| **Models** | Specific models under each make |
|
||||
| **Key Names** | MK300, Master Key, Padlock Key, Red Key, Green Dot |
|
||||
| **Key Types** | Barrel, Flat, Standard, Tubular, Round Short |
|
||||
| **Security Badges** | Employee Badge, Contractor Badge, Visitor Badge |
|
||||
|
||||
### Changing Theme
|
||||
|
||||
Tap the **Theme** dropdown in Settings to switch between:
|
||||
- **Dark** (default) — easier on the eyes in low-light
|
||||
- **Light** — better in bright environments
|
||||
|
||||
### Resetting the Database
|
||||
|
||||
> ⚠️ **Warning:** This permanently deletes ALL data — assets, check-ins, geofences, users, everything.
|
||||
|
||||
1. Go to **⚙️ Settings**
|
||||
2. Scroll to the bottom
|
||||
3. Tap **🗑 Reset Database** (red button)
|
||||
4. Confirm by typing "DELETE" in the prompt
|
||||
5. Tap **Confirm**
|
||||
|
||||
The app will restart with fresh default data (admin account and example settings).
|
||||
|
||||
---
|
||||
|
||||
## 10. Tips & Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| **Can't log in** | Check caps lock. Passwords are case-sensitive. Ask an admin to reset your password. |
|
||||
| **Camera not working** | Grant camera permission when prompted. On iPhone, check Settings → Safari → Camera. |
|
||||
| **GPS not working** | Grant location permission. On Android, use "While using the app" not "Deny". |
|
||||
| **Map tiles not loading** | Check your internet connection. OpenStreetMap tiles require internet access. |
|
||||
| **"User denied Geolocation"** | Refresh the page and allow location when prompted. |
|
||||
| **Barcode won't scan** | Ensure good lighting. Hold the phone 4-8 inches from the barcode. Try the manual entry instead. |
|
||||
| **502 Bad Gateway** | The server may be restarting. Wait 30 seconds and refresh. |
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Add photos** — a picture of the asset saves time for the next technician
|
||||
- **Be specific with directions** — "Behind the walk-in cooler, third shelf from the top" is better than "In the back"
|
||||
- **Record key info** — note which keys and badges are needed before you go
|
||||
- **Check in every visit** — this builds the service history and helps with billing
|
||||
- **Assign geofences** — when a technician joins, assign their service areas so route planning is clear
|
||||
|
||||
### Keyboard Shortcuts (Desktop)
|
||||
|
||||
- **Esc** — Close modals / dialogs
|
||||
- **Enter** — Submit forms
|
||||
- **Menu** → click away — Close drawer
|
||||
|
||||
### Offline / Low Connectivity
|
||||
|
||||
The app requires an internet connection to load data. If connectivity is poor:
|
||||
1. Load the page while connected
|
||||
2. Navigate to the data you need (it stays in browser memory)
|
||||
3. Don't refresh until you're back online
|
||||
|
||||
For full offline support, use the **Android app** which caches data locally.
|
||||
Reference in New Issue
Block a user