diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md new file mode 100644 index 0000000..9ea9910 --- /dev/null +++ b/docs/ADMIN_GUIDE.md @@ -0,0 +1,195 @@ +# Canteen Admin Panel β€” User Guide + +> Administrative interface for managing customers, locations, users, geofences, settings, and Cantaloupe data sync. Designed for desktop but mobile-responsive (screenshots from Pixel 9a). + +## Table of Contents + +1. [Accessing the Admin Panel](#1-accessing-the-admin-panel) +2. [Dashboard Overview](#2-dashboard-overview) +3. [Managing Customers & Locations](#3-managing-customers--locations) +4. [Managing Users](#4-managing-users) +5. [Geofences (Service Areas)](#5-geofences-service-areas) +6. [Settings & Configuration](#6-settings--configuration) +7. [Cantaloupe Data Sync](#7-cantaloupe-data-sync) +8. [Activity Log & Reports](#8-activity-log--reports) +9. [Tips & Troubleshooting](#9-tips--troubleshooting) + +--- + +## 1. Accessing the Admin Panel + +Open your browser and go to: + +``` +https://admin.canteen.ourpad.casa +``` + +### Logging In + +Use the same credentials as the main app: + +| Role | Username | Password | +|------|----------|----------| +| Admin | `admin` | `changeme` | + +![Admin Login](images/p9a_admin_login.png) + +--- + +## 2. Dashboard Overview + +After logging in, the dashboard shows: + +- **Total Assets** count +- **Total Check-ins** count +- **Active Users** count +- **Recent Activity** feed +- Quick access to all management sections via the sidebar + +![Admin Dashboard](images/p9a_admin_dashboard.png) + +### Sidebar Navigation + +The sidebar on the left provides access to: +- **πŸ“Š Dashboard** β€” Stats overview and activity feed +- **🏒 Customers** β€” Customer and location management +- **πŸ‘₯ Users** β€” User account management +- **πŸ“ Geofences** β€” Service area polygon management +- **πŸ”„ Sync** β€” Cantaloupe data import +- **βš™οΈ Settings** β€” Categories, makes, models, key types, badge types +- **πŸ“‹ Activity** β€” Full activity log with filters +- **πŸ“€ Exports** β€” CSV data export + +--- + +## 3. Managing Customers & Locations + +### Customers + +The Customers page shows a searchable list of all customers. + +![Customers](images/p9a_admin_customers.png) + +**Add a Customer:** +1. Click **+ Add Customer** +2. Enter the customer's name +3. Optionally add contacts (name, phone, email) +4. Click **Save** + +**Edit/Delete:** Use the ✏️ and πŸ—‘ buttons next to each customer. + +### Locations + +Within each customer's detail view, you can add locations: + +- Click on a customer to expand their details +- **+ Add Location** β€” Add a new site/building +- Location fields: name, address, building name, floor, site hours, trailer number, access notes, walking directions, GPS coordinates + +--- + +## 4. Managing Users + +Navigate to **πŸ‘₯ Users** in the sidebar. + +**Add a User:** +- Click **+ Add User** +- Enter username, password, and select a role (admin / technician / readonly) +- Techs can create assets and check-ins; readonly users can only view + +--- + +## 5. Geofences (Service Areas) + +Navigate to **πŸ“ Geofences** in the sidebar. + +- **+ Add Geofence** β€” Draw a polygon on the map to define a service area +- Assign geofences to specific users/technicians +- Edit or delete existing geofences + +Geofences appear as colored polygons on the main app's map for visual reference. + +--- + +## 6. Settings & Configuration + +Navigate to **βš™οΈ Settings** in the sidebar. + +Manage these lookup tables: +- **Categories** β€” Asset categories (Appliances, Furniture, etc.) +- **Makes** β€” Manufacturer names (Canteen, Hobart, Vollrath, etc.) + - Expand each make to manage its **Models** +- **Key Names** β€” Field service key names +- **Key Types** β€” Field service key types +- **Badge Types** β€” Asset badge types + +--- + +## 7. Cantaloupe Data Sync + +Navigate to **πŸ”„ Sync** in the sidebar. + +![Cantaloupe Sync](images/p9a_admin_sync.png) + +The Cantaloupe Sync page lets you import asset data from the Cantaloupe vending management system. + +### How it Works + +1. **Sync Now** button β€” Downloads the latest Excel export from Cantaloupe and creates a pending import batch +2. **Upload Excel File** β€” Manually upload a Cantaloupe Excel export file +3. **Review Changes** β€” Each batch shows new, changed, and removed assets with field-level diffs +4. **Approve** β€” Apply the changes to live data +5. **Reject** β€” Discard the batch + +### Import History + +The bottom section shows all past import batches with their status (PENDING / APPROVED / REJECTED / ERROR) and change summaries. + +--- + +## 8. Activity Log & Reports + +### Activity Log + +Navigate to **πŸ“‹ Activity** in the sidebar. + +- Full chronological log of all actions (creates, updates, deletes, check-ins, logins) +- Filters: by user, action type, date range +- Uses pagination for large logs + +### CSV Exports + +Available at the bottom of the sidebar: +- **Export Assets** β€” Download all assets as CSV +- **Export Check-ins** β€” Download check-ins filtered by asset + +### Database Reset + +> ⚠️ **Danger zone:** The **Reset Database** button in the sidebar footer deletes ALL data and reinitializes with defaults. Requires confirmation. + +--- + +## 9. Tips & Troubleshooting + +### Cantaloupe Sync Fails + +1. Check the credentials in the Cantaloupe downloader config +2. The server must have network access to mycantaloupe.com +3. Check the error message in the sync batch detail view +4. Try the **Upload Excel File** option as a fallback + +### Admin Panel Not Loading + +- Hard refresh (Ctrl+Shift+R on desktop, long-press refresh on mobile) +- Clear site data +- Check that both services are running (`canteen-main.service` and `canteen-admin.service`) + +### Permissions + +- You must be logged in as an **admin** role user to access the admin panel +- Technicians and readonly users cannot access the admin panel +- Session tokens expire after **1 day** (or **30 days** with "Remember me") + +--- + +> **Note:** The admin panel shares the same database as the main app, so changes made here (customers, locations, geofences, settings) are immediately visible in the field app. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 10df8d6..b136e6f 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -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. -![Login Screen](images/login.png) +![Login Screen](images/p9a_main_login.png) ### 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** +![Login Screen](images/p9a_main_login.png) -### 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. + +![Dashboard](images/p9a_main_dashboard.png) + +### 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 + +![Drawer Menu](images/p9a_main_drawer.png) --- ## 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") +![Manual Entry Form](images/p9a_main_manual_form.png) -![Manual Entry Form](images/manual-entry.png) - -**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. -![Map with Geofence](images/map-geofence.png) +![Map View](images/p9a_main_map.png) -### 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 - -![Dashboard](images/dashboard.png) - -- 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: - -![Settings](images/settings.png) - -| 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! diff --git a/docs/images/p9a_admin_customers.png b/docs/images/p9a_admin_customers.png new file mode 100644 index 0000000..a9ca546 Binary files /dev/null and b/docs/images/p9a_admin_customers.png differ diff --git a/docs/images/p9a_admin_dashboard.png b/docs/images/p9a_admin_dashboard.png new file mode 100644 index 0000000..5efcc36 Binary files /dev/null and b/docs/images/p9a_admin_dashboard.png differ diff --git a/docs/images/p9a_admin_login.png b/docs/images/p9a_admin_login.png new file mode 100644 index 0000000..6a59ab9 Binary files /dev/null and b/docs/images/p9a_admin_login.png differ diff --git a/docs/images/p9a_admin_sync.png b/docs/images/p9a_admin_sync.png new file mode 100644 index 0000000..f555e3c Binary files /dev/null and b/docs/images/p9a_admin_sync.png differ diff --git a/docs/images/p9a_main_assets.png b/docs/images/p9a_main_assets.png new file mode 100644 index 0000000..c8fee78 Binary files /dev/null and b/docs/images/p9a_main_assets.png differ diff --git a/docs/images/p9a_main_dashboard.png b/docs/images/p9a_main_dashboard.png new file mode 100644 index 0000000..840aac9 Binary files /dev/null and b/docs/images/p9a_main_dashboard.png differ diff --git a/docs/images/p9a_main_drawer.png b/docs/images/p9a_main_drawer.png new file mode 100644 index 0000000..82928be Binary files /dev/null and b/docs/images/p9a_main_drawer.png differ diff --git a/docs/images/p9a_main_login.png b/docs/images/p9a_main_login.png new file mode 100644 index 0000000..2fb510b Binary files /dev/null and b/docs/images/p9a_main_login.png differ diff --git a/docs/images/p9a_main_manual_form.png b/docs/images/p9a_main_manual_form.png new file mode 100644 index 0000000..d472e9d Binary files /dev/null and b/docs/images/p9a_main_manual_form.png differ diff --git a/docs/images/p9a_main_map.png b/docs/images/p9a_main_map.png new file mode 100644 index 0000000..d50f10c Binary files /dev/null and b/docs/images/p9a_main_map.png differ