Update user guides with Pixel 9a screenshots
- Updated USER_GUIDE.md with Pixel 9a mobile screenshots (login, dashboard, manual form, assets list, map, drawer) - Added ADMIN_GUIDE.md with admin panel screenshots (login, dashboard, customers, sync page) - 10 screenshots captured at 412x892 viewport @2.625 DPR - Removed stale old image references, replaced with new p9a_* images
This commit is contained in:
+102
-265
@@ -1,6 +1,6 @@
|
||||
# Canteen Asset Tracker — User Guide
|
||||
|
||||
> A practical guide for technicians, supervisors, and admins using the Canteen Asset Tracker.
|
||||
> A practical guide for technicians, supervisors, and admins using the Canteen Asset Tracker on mobile (Pixel 9a shown).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
@@ -11,9 +11,7 @@
|
||||
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)
|
||||
8. [Tips & Troubleshooting](#8-tips--troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
@@ -24,19 +22,18 @@
|
||||
Open your phone or desktop browser and go to:
|
||||
|
||||
```
|
||||
https://canteen.ourpad.casa:8901
|
||||
https://canteen.ourpad.casa
|
||||
```
|
||||
|
||||
> **On your phone:** The app is designed for mobile use — it fits your screen and works with touch controls.
|
||||
> **On your phone:** The app is designed for mobile use — it fits your screen and works with touch controls. Pixel 9a viewport shown in screenshots.
|
||||
|
||||
|
||||
|
||||
|
||||
### 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)
|
||||
|
||||
---
|
||||
|
||||
@@ -48,317 +45,157 @@ https://canteen.ourpad.casa:8901
|
||||
|------|----------|----------|
|
||||
| Admin | `admin` | `changeme` |
|
||||
|
||||
**⚠️ Change the default password immediately** via Settings → Users → Edit.
|
||||
### Steps
|
||||
|
||||
### Login Screen
|
||||
1. Open https://canteen.ourpad.casa in your browser
|
||||
2. Tap **Username** and enter your username
|
||||
3. Tap **Password** and enter your password
|
||||
4. Check **Remember me** if you want to stay logged in for 30 days
|
||||
5. Tap **Sign In**
|
||||
|
||||
1. Enter your **Username**
|
||||
2. Enter your **Password**
|
||||
3. Check **Remember me** to stay logged in
|
||||
4. Tap **Sign In**
|
||||
|
||||
|
||||
### User Roles
|
||||
### After Login
|
||||
|
||||
| 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 |
|
||||
Once logged in, you'll see the main dashboard. The default view shows the **Add Asset** tab with options for barcode scanning, OCR, or manual entry.
|
||||
|
||||
|
||||
|
||||
### Navigation
|
||||
|
||||
The bottom tab bar gives you quick access to:
|
||||
- **➕ Add** — Add a new asset via barcode, OCR, or manual form
|
||||
- **📋 Assets** — Browse and search all assets
|
||||
- **🗺️ Map** — View assets on the map with geofences and heatmap
|
||||
- **🧭 Nav** — Navigation tools
|
||||
- **⋯ More** — Open the drawer for Settings, Reports, and Logout
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3. Adding an Asset
|
||||
|
||||
Tap the **📷 Add Asset** tab (bottom nav bar or drawer menu).
|
||||
The app offers three ways to add an asset:
|
||||
|
||||
You have three methods:
|
||||
### Option A: Barcode Scan (fastest)
|
||||
|
||||
### Option A: Barcode Scan
|
||||
1. Tap the **Barcode** toggle on the Add Asset tab
|
||||
2. Tap **Tap to start camera** and grant camera permission
|
||||
3. Point the camera at the asset's barcode sticker
|
||||
4. The scanner auto-detects the barcode and fills in the machine ID
|
||||
5. Confirm the details and tap **Create Asset**
|
||||
|
||||
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 label)
|
||||
|
||||
### 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
|
||||
1. Tap the **OCR** toggle
|
||||
2. Tap **Take Photo** or **Pick Photo** to capture the asset's label
|
||||
3. The app extracts the machine ID using text recognition
|
||||
4. Review and correct if needed, then tap **Create Asset**
|
||||
|
||||
### Option C: Manual Entry
|
||||
|
||||
Tap **✏️ Manual** and fill out the form:
|
||||
Tap **Manual** to fill in all fields by hand:
|
||||
|
||||
**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
|
||||
Fields:
|
||||
- **Machine ID** — The asset's unique ID (required)
|
||||
- **Name** — A descriptive name (required)
|
||||
- **Category** — e.g. Appliances, Furniture, Electronics
|
||||
- **Status** — active, maintenance, retired
|
||||
- **Serial Number** — Optional
|
||||
- **Make / Model** — Optional
|
||||
- **Address / Location Info** — Where the asset is located
|
||||
- **GPS Coordinates** — Tap the 📍 button to auto-fill your current location
|
||||
- **Photo** — Optional, upload an image of the asset
|
||||
- **Notes** — Any additional information
|
||||
|
||||
---
|
||||
|
||||
## 4. Checking In on an Asset
|
||||
|
||||
### From the Asset Detail View
|
||||
1. From the **Assets** list, tap an asset to open its detail view
|
||||
2. Tap **Check In**
|
||||
3. The app captures your GPS location automatically
|
||||
4. Add any notes about the visit
|
||||
5. Tap **Submit Check-in**
|
||||
|
||||
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
|
||||
Each check-in creates a **Visit** record, which is used for service tracking and reporting.
|
||||
|
||||
---
|
||||
|
||||
## 5. Finding Assets on the Map
|
||||
|
||||
Tap the **🗺️ Map** tab.
|
||||
Tap the **🗺️ Map** tab to view all assets plotted on an interactive map.
|
||||
|
||||
|
||||
|
||||
|
||||
### Toggle Layers
|
||||
Features:
|
||||
- **Blue pins** mark asset locations
|
||||
- **Toggle Pins** button shows/hides asset markers
|
||||
- **Heatmap** view shows asset density
|
||||
- **🎯 My GPS** button centers the map on your location (requires GPS permission)
|
||||
- Tap a pin to see asset details and get directions
|
||||
|
||||
| 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
|
||||
The map is powered by **Leaflet** with **OpenStreetMap** tiles — no API key needed.
|
||||
|
||||
---
|
||||
|
||||
## 6. Working with Geofences (Service Areas)
|
||||
|
||||
Geofences let you draw **service zones** on the map and assign **technicians** to cover each zone.
|
||||
Geofences are managed from the **admin panel** (see Admin Guide). Once created, they appear on the main app's map as colored polygons:
|
||||
|
||||
### 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.
|
||||
- Tap a geofence polygon to see its name and details
|
||||
- Geofences help organize assets by service area or route
|
||||
|
||||
---
|
||||
|
||||
## 7. Viewing Reports & Dashboard
|
||||
|
||||
### Dashboard
|
||||
The Dashboard tab shows:
|
||||
- **Total assets** and **total check-ins** counts
|
||||
- **Recent activity** feed showing who did what
|
||||
- **Category and status breakdowns**
|
||||
|
||||
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.
|
||||
Access the drawer menu (**⋯ More**) → **Dashboard** for a full view.
|
||||
|
||||
---
|
||||
|
||||
## 8. Managing Users
|
||||
## 8. Tips & Troubleshooting
|
||||
|
||||
### Adding a User
|
||||
### GPS Not Working
|
||||
|
||||
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**
|
||||
- Tap the **📍 Tap for GPS** badge in the top header (it prompts the permission)
|
||||
- If prompted, tap **Allow** on the browser's location permission dialog
|
||||
- On Pixel 9a / Android: ensure Location is enabled in Quick Settings
|
||||
- If GPS still doesn't work, open browser settings → Site Settings → Location → Allow
|
||||
|
||||
### Editing a User
|
||||
### Camera Not Working
|
||||
|
||||
1. Tap the **✏️** (edit) button next to the user
|
||||
2. Update fields
|
||||
3. Tap **Save**
|
||||
- Ensure you're on **HTTPS** (camera requires a secure connection)
|
||||
- Grant camera permission when prompted by the browser
|
||||
- Try the **Pick Photo** option instead — it uses the gallery and may work better on some browsers
|
||||
|
||||
### Deleting a User
|
||||
### Barcode Not Scanning
|
||||
|
||||
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
|
||||
- Ensure good lighting on the barcode
|
||||
- Hold the camera steady about 4-6 inches from the label
|
||||
- Try **OCR** mode if the barcode is damaged or smudged
|
||||
|
||||
> **Note:** Deleting a user also removes their geofence assignments (cascade delete). It does NOT delete assets or check-ins created by that user.
|
||||
### Login Issues
|
||||
|
||||
- Check your username and password
|
||||
- Use the **admin / changeme** default credentials if they haven't been changed
|
||||
- Contact your supervisor for password resets
|
||||
|
||||
### App Not Loading / Blank Page
|
||||
|
||||
- Hard refresh: long-press the browser refresh icon → **Bypass Cache**
|
||||
- Clear site data: browser settings → Site Settings → Clear data
|
||||
- If the problem persists, the server may be down — contact IT support
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
> **Pro tip:** For the best mobile experience, add the app to your home screen:
|
||||
> Chrome → Menu → **Add to Home Screen**. It opens like a native app!
|
||||
|
||||
Reference in New Issue
Block a user