filtering tenants

README.md

@@ -6,7 +6,11 @@ badge holders to real names, and displays a unified live attendance table with
 first/latest badge times, source controller, and ON TIME / LATE status.
 
 **Multi-controller:** add as many UniFi Access controllers as the host can reach.
-Webhooks are auto-registered when you add a controller from the UI. (05/28/26)
+Webhooks are auto-registered when you add a controller from the UI.
+
+**Tenant filtering:** hide building tenants (or any non-staff actor) from the
+attendance table with one click — events are still recorded so unfiltering
+restores their full history. (05/28/26)
 
 ---
 
@@ -169,8 +173,10 @@ Per-controller actions in the modal:
 | **Date picker** | Choose which day to view |
 | **Badged in by** | Set your on-time cutoff (HH:MM) |
 | **Controller** | Filter the table to one controller, or show All |
+| **Show filtered** | Include filtered tenants in the table (dimmed and tagged) |
 | **Refresh** | Reload the table |
 | **Sync Users** | Pull latest users from every enabled controller |
+| **🚫 Filtered** | Open the filtered-tenants modal to review and unhide |
 | **⚙ Controllers** | Add / manage controllers |
 | **Reset Day** | Delete all badge records for the selected date (respects the Controller filter — testing only) |
 
@@ -185,6 +191,7 @@ Per-controller actions in the modal:
 | **Latest Badge In** | Most recent entry — shows *"— same"* if only one badge event |
 | **Actor ID** | First 8 characters of the UniFi user UUID |
 | **Status** | ON TIME (green) or LATE (red) based on first badge vs cutoff |
+| **Actions** | **Hide** filters this tenant out of future views; **Unhide** restores them |
 
 > The same physical person on two different controllers will appear as two rows
 > (different controllers issue different user UUIDs). They're distinguishable
@@ -192,6 +199,25 @@ Per-controller actions in the modal:
 
 ---
 
+## Filtering tenants
+
+Use this when an actor (typically a building tenant, vendor, or contractor)
+badges into the same doors as your staff but you don't want them counted on
+the attendance table.
+
+- Click **Hide** on any row to filter that actor out. They're removed from the
+  table immediately and stay hidden on future days.
+- Toggle **Show filtered** in the controls bar to see them again — filtered
+  rows render dimmed with a FILTERED tag and an **Unhide** action.
+- Click the **🚫 Filtered** button in the header for a bulk-management view
+  across all controllers, with one-click unhide per actor.
+
+The filter is per `(controller, actor)`, so the same person on two controllers
+must be hidden on each one. Badge events are still recorded while an actor is
+filtered — unhiding restores their full history with no gaps.
+
+---
+
 ## Updating from GitHub
 
 ```bash
@@ -217,7 +243,9 @@ reverse proxy with auth in front of it.
 |---|---|---|---|
 | `POST` | `/api/unifi-access/<controller_id>` | webhook body | Receives UniFi Access webhook for that controller |
 | `POST` | `/api/unifi-access` | webhook body | Legacy alias — routes to the oldest controller |
-| `GET` | `/api/first-badge-status` | `date`, `cutoff`, `controller_id?` | Returns first + latest badge per user |
+| `GET` | `/api/first-badge-status` | `date`, `cutoff`, `controller_id?`, `include_filtered?` | Returns first + latest badge per user (filtered tenants hidden unless `include_filtered=1`) |
+| `GET` | `/api/users` | `controller_id?`, `filtered?` | List cached actors with their filtered flag |
+| `PATCH` | `/api/users/<controller_id>/<actor_id>` | `filtered` (bool) | Hide / unhide an actor from the attendance table |
 | `GET` | `/api/controllers` | — | List configured controllers |
 | `POST` | `/api/controllers` | `name`, `host`, `port`, `api_token` | Add a controller (also registers webhook) |
 | `PATCH` | `/api/controllers/<id>` | `name?`, `enabled?` | Rename or enable/disable a controller |
@@ -241,6 +269,8 @@ reverse proxy with auth in front of it.
 | Webhook URL stored in controller points to the wrong address | Browser's origin isn't reachable from the controller | Set `DASHBOARD_BASE_URL` in `.env`, remove + re-add the controller |
 | `Port 12445 connection refused` | Firewall blocking port | Add LAN IN firewall rule in UniFi Network (Step 1) |
 | Dashboard shows stale names after a user rename | Cache not refreshed | Click **Sync Users** or wait for the hourly auto-sync |
+| A tenant I hid is still showing up | Same person exists on a second controller | Hide them on each controller — the filter is per `(controller, actor)` |
+| Filtered tenant doesn't appear when I tick "Show filtered" | They've never badged in on the selected date | Open the **🚫 Filtered** modal to confirm they're filtered |
 
 ---