fix(web): refresh admin operations realtime

Author: JasonTM17

CHANGELOG.md

@@ -4,6 +4,16 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · SemVer.
 
 ## [Unreleased]
 
+## [2.1.1] – 2026-06-20
+
+### Added
+- Authenticated Admin realtime event cursor and map refresh for bin fullness,
+  alerts, devices, and reports.
+
+### Fixed
+- Admin and User dashboards now receive the same hardware fullness changes
+  without requiring a manual map refresh.
+
 ## [2.1.0] – 2026-06-20
 
 ### Added

README.md

@@ -54,6 +54,7 @@ Trash Sorter Pro là một hệ sinh thái AI phân loại rác end-to-end:
 - [Checklist tích hợp phần cứng](docs/hardware_integration_checklist.md)
 - [Operations map local-first](docs/operations-map-local-first.md)
 - [Release v2.1.0: cloud map and hardware bridge](docs/releases/v2.1.0.md)
+- [Release v2.1.1: Admin and User realtime](docs/releases/v2.1.1.md)
 
 Hướng dẫn chạy web app cho đồng nghiệp: [docs/huong-dan-chay-web-app.md](docs/huong-dan-chay-web-app.md).
 
@@ -249,9 +250,9 @@ Local operations map:
 - Admin APIs manage roles, devices, bin map, alerts, collection schedules, model,
   audio, and reports. User APIs are scoped to map, alerts, schedule, mark-collected,
   device issue reporting, own history, and own account.
-- Supabase bin/alert triggers write scoped `realtime_events`. User dashboard/map
-  consumes an authenticated event cursor every 1.2 seconds and refreshes after a
-  hardware fullness event; the six-second map poll remains a connection fallback.
+- Supabase bin/alert triggers write scoped `realtime_events`. Admin and User
+  dashboard maps consume authenticated event cursors every 1.2 seconds and refresh
+  after a hardware fullness event; the six-second map poll remains a connection fallback.
 
 Public Admin hardware bridge:
 

docs/releases/v2.1.1.md

@@ -0,0 +1,64 @@
+# Trash Sorter Pro v2.1.1 — Admin & User Realtime
+
+**Released:** 2026-06-20  
+**Production:** <https://trash-sorter-v2.vercel.app>
+
+## Purpose
+
+This patch makes the realtime behavior identical for both dashboard roles.
+When the hardware bridge records a fullness change such as `BIN:3:96`, the
+relevant Admin and User screens refresh automatically. Neither person needs to
+close the popup or press the map refresh button.
+
+## Realtime behavior
+
+```mermaid
+sequenceDiagram
+    participant Sensor as Hardware sensor
+    participant Bridge as Supabase synchronizer
+    participant DB as Supabase
+    participant Admin as Admin dashboard
+    participant User as Assigned User dashboard
+
+    Sensor->>Bridge: BIN:3:96
+    Bridge->>DB: update selected bin + alert
+    DB->>DB: write realtime_events row
+    Admin->>DB: event cursor every 1.2 s
+    User->>DB: scoped event cursor every 1.2 s
+    DB-->>Admin: changed event
+    DB-->>User: changed event for assigned station
+    Admin->>DB: refresh map + alerts + schedules
+    User->>DB: refresh scoped map + alerts + schedules
+```
+
+- **Admin:** sees every active station, its bin fullness, and alerts.
+- **User:** sees only stations assigned to that account.
+- **Cursor interval:** 1.2 seconds while a supported operations screen is
+  visible and the tab is not hidden.
+- **Fallback:** a six-second background refresh protects against a temporary
+  event-cursor failure.
+- **No data leakage:** Admin endpoint requires Admin session; User endpoint
+  applies station-owner filtering server-side.
+
+## Screens covered
+
+| Role | Screens refreshed automatically |
+| --- | --- |
+| Admin | Bản đồ thùng, Cảnh báo, Thiết bị, Báo cáo |
+| User | Tổng quan, Bản đồ, Cảnh báo, Lịch, Thu gom, Báo lỗi thiết bị |
+
+## Verification
+
+1. Open Admin **Bản đồ thùng** and an assigned User **Bản đồ** in separate
+   browser sessions.
+2. Admin assigns the physical sensor to a bin.
+3. Send a firmware reading, for example `BIN:3:65`, then `BIN:3:96`.
+4. Both maps should update within roughly 1.2 seconds. At 96%, both should show
+   the full state and the relevant alert.
+5. Confirm the User cannot access the Admin event endpoint or unassigned bins.
+
+## Validation completed
+
+- Unit tests cover the Admin event cursor’s unscoped query and existing User
+  owner-scoped query.
+- Production build passes before deployment.

web/src/app/api/admin/operation-events/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+
+import { authenticateSession, CloudAuthConfigError, extractBearerToken } from "@/lib/server/cloud-auth";
+import { cloudOperationEvents } from "@/lib/server/cloud-operations";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET(request: NextRequest) {
+  try {
+    const identity = await authenticateSession(extractBearerToken(request.headers.get("authorization")));
+    if (!identity) return NextResponse.json({ detail: "Invalid or missing agent token" }, { status: 401 });
+    if (identity.role !== "admin") return NextResponse.json({ detail: "Admin role is required" }, { status: 403 });
+    const after = Number(request.nextUrl.searchParams.get("after") ?? 0);
+    return NextResponse.json(await cloudOperationEvents(identity, Number.isFinite(after) ? after : 0));
+  } catch (error) {
+    if (error instanceof CloudAuthConfigError) {
+      return NextResponse.json({ detail: "Cloud database is not configured" }, { status: 503 });
+    }
+    return NextResponse.json({ detail: "Cloud Admin realtime events failed" }, { status: 500 });
+  }
+}

web/src/components/dashboard-client.tsx

@@ -357,6 +357,8 @@ export function DashboardClient() {
   const userOperationsRefreshInFlightRef = useRef(false);
   const userOperationsEventCursorRef = useRef(0);
   const userOperationsInteractionUntilRef = useRef(0);
+  const adminOperationsRefreshInFlightRef = useRef(false);
+  const adminOperationsEventCursorRef = useRef(0);
   const shownBinFullAlertRanksRef = useRef<Map<string, number>>(new Map());
 
   const cameraStream = useMemo(() => {
@@ -909,6 +911,29 @@ export function DashboardClient() {
     setOperationsHealth(healthData);
   }
 
+  async function refreshAdminRealtimeOperations() {
+    if (adminOperationsRefreshInFlightRef.current) {
+      return;
+    }
+    adminOperationsRefreshInFlightRef.current = true;
+    try {
+      const [binMapData, alertsData, schedulesData] = await Promise.all([
+        cloudFetch<BinMapResponse>("/api/admin/bin-map", { timeoutMs: 45_000 }, agentToken),
+        cloudFetch<AlertsResponse>("/api/admin/alerts?include_resolved=false", { timeoutMs: 45_000 }, agentToken),
+        cloudFetch<CollectionSchedulesResponse>("/api/admin/collection-schedules", { timeoutMs: 45_000 }, agentToken)
+      ]);
+      setAdminBinMap(binMapData);
+      setAdminAlerts(alertsData);
+      showNewBinFullnessPopup(alertsData, "admin");
+      setAdminSchedules(schedulesData);
+    } catch {
+      // The full Admin refresh remains available from the map button if a
+      // transient realtime request fails.
+    } finally {
+      adminOperationsRefreshInFlightRef.current = false;
+    }
+  }
+
   async function refreshUserOperations(options?: { background?: boolean }) {
     if (userOperationsRefreshInFlightRef.current) {
       return;
@@ -1777,6 +1802,58 @@ export function DashboardClient() {
     };
   }, [agentToken, auth?.role, auth?.password_default, userView]);
 
+  useEffect(() => {
+    const refreshableAdminTabs: TabId[] = ["bin-map", "alerts", "devices", "reports"];
+    if (auth?.role !== "admin" || auth.password_default || !agentToken || !refreshableAdminTabs.includes(active)) {
+      return;
+    }
+    let cancelled = false;
+    let eventRequestInFlight = false;
+    adminOperationsEventCursorRef.current = 0;
+    const pollOperationEvents = async () => {
+      if (cancelled || eventRequestInFlight || document.visibilityState === "hidden") {
+        return;
+      }
+      eventRequestInFlight = true;
+      try {
+        const payload = await cloudFetch<OperationEventsResponse>(
+          `/api/admin/operation-events?after=${adminOperationsEventCursorRef.current}`,
+          { timeoutMs: 8000 },
+          agentToken
+        );
+        if (cancelled) return;
+        adminOperationsEventCursorRef.current = payload.cursor;
+        if (payload.changed) {
+          void refreshAdminRealtimeOperations();
+        }
+      } catch {
+        // The six-second fallback below keeps the Admin map current when the
+        // event cursor is briefly unavailable.
+      } finally {
+        eventRequestInFlight = false;
+      }
+    };
+    void pollOperationEvents();
+    const eventTimer = window.setInterval(() => void pollOperationEvents(), 1200);
+    return () => {
+      cancelled = true;
+      window.clearInterval(eventTimer);
+    };
+  }, [active, agentToken, auth?.role, auth?.password_default]);
+
+  useEffect(() => {
+    const refreshableAdminTabs: TabId[] = ["bin-map", "alerts", "devices", "reports"];
+    if (auth?.role !== "admin" || auth.password_default || !agentToken || !refreshableAdminTabs.includes(active)) {
+      return;
+    }
+    const timer = window.setInterval(() => {
+      if (document.visibilityState !== "hidden") {
+        void refreshAdminRealtimeOperations();
+      }
+    }, 6000);
+    return () => window.clearInterval(timer);
+  }, [active, agentToken, auth?.role, auth?.password_default]);
+
   useEffect(() => {
     const refreshableUserViews: UserView[] = ["dashboard", "map", "alerts", "schedule", "collect", "report-issue"];
     if (auth?.role !== "user" || auth.password_default || !agentToken || !refreshableUserViews.includes(userView)) {

web/src/lib/agent.ts

@@ -1066,6 +1066,7 @@ const CLOUD_DASHBOARD_API_PREFIXES = [
   "/api/admin/collection-schedules",
   "/api/admin/demo-bin-target",
   "/api/admin/devices",
+  "/api/admin/operation-events",
   "/api/admin/operations/health",
   "/api/admin/roles",
   "/api/user/"

web/tests/unit/operation-events.test.ts

@@ -12,6 +12,12 @@ const USER: CloudAuthIdentity = {
   password_default: false
 };
 
+const ADMIN: CloudAuthIdentity = {
+  ...USER,
+  role: "admin",
+  username: "admin"
+};
+
 describe("operation realtime event cursor", () => {
   const query = vi.fn();
 
@@ -52,4 +58,13 @@ describe("operation realtime event cursor", () => {
     expect(result.events[0]).toMatchObject({ event_name: "bin_status_changed" });
     expect(query.mock.calls[0][1]).toEqual([42, "nguyen-son"]);
   });
+
+  it("lets Admin consume the unscoped operations event cursor", async () => {
+    query.mockResolvedValueOnce({ rows: [{ cursor: "57" }] });
+
+    const result = await cloudOperationEvents(ADMIN, 0);
+
+    expect(result).toEqual({ cursor: 57, changed: true, events: [] });
+    expect(query.mock.calls[0][1]).toEqual([""]);
+  });
 });