docs: add Category Icon System documentation

2026-05-31 00:32:22 -04:00
parent 191642ff52
commit c4580b6fd1
1 changed files with 54 additions and 0 deletions
@@ -0,0 +1,54 @@
+# Category Icon System
+
+The Canteen Asset Tracker uses a category-based icon system to visually identify asset types at a glance.
+
+## Category Map (main app `static/index.html`)
+
+| Category   | Icon | Color    |
+|------------|------|----------|
+| Bev        | 🥤   | #0a7ab5 |
+| Snack      | 🍿   | #c97d0e |
+| Food       | 🍔   | #e67e22 |
+| Equipment  | 🔧   | #2c3e50 |
+| Appliances | 🔌   | #3b82f6 |
+| Other      | 📦   | #6b7280 |
+
+## Fallback Logic (`categoryInfo()`)
+
+- Category in map → uses that entry's icon + color
+- Category exists but NOT in map (unmapped) → ❓ with red background (#b91c1c) — visible signal to admin
+- Null/missing category → 📦 (generic)
+
+This means any new category imported from Cantaloupe that isn't in the lookup table will immediately be visible as ❓ on the technician's phone, prompting the admin to add it.
+
+## Admin Server Category Health
+
+The `/api/stats` endpoint includes `category_health`:
+```json
+{
+  "unmapped": [{"name": "Snack/Bev", "count": 18}],
+  "total_categories": 6,
+  "unmapped_count": 1
+}
+```
+
+The admin dashboard shows a red **⚠️ Category Health** card when `unmapped_count > 0`, linking to Settings → Categories to fix.
+
+## DB Schema
+
+Table `categories`:
+- `id` INTEGER PRIMARY KEY
+- `name` TEXT UNIQUE NOT NULL
+- `icon` TEXT (emoji or image path)
+
+Seed data (both `server.py` and `admin_server.py`):
+```python
+("Bev", "🥤"), ("Snack", "🍿"),
+("Food", "🍔"), ("Equipment", "🔧"),
+("Appliances", "🔌"), ("Other", "📦"),
+```
+
+## History
+
+- **2026-05-29 (f1a3bb9):** Cleaned CATEGORY_MAP (removed dead entries, fixed duplicates). Added `categoryInfo()` helper with proper unmapped fallback. Added detail view icons. Synced DB categories with real asset data.
+- **Admin d58834b:** Added Category Health dashboard widget.