canteen-asset-tracker/docs/USER_GUIDE.md

Canteen Asset Tracker — User Guide

A practical guide for technicians, supervisors, and admins using the Canteen Asset Tracker.

Table of Contents

1. Getting Started
2. Logging In
3. Adding an Asset
4. Checking In on an Asset
5. Finding Assets on the Map
6. Working with Geofences (Service Areas)
7. Viewing Reports & Dashboard
8. Managing Users
9. Settings & Configuration
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.