fix(web): persist hardware sensor assignment

Author: JasonTM17

CHANGELOG.md

@@ -4,6 +4,30 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · SemVer.
 
 ## [Unreleased]
 
+## [2.1.0] – 2026-06-20
+
+### Added
+- Production cloud map, scoped realtime bin fullness, collection alerts, and the
+  Admin-only hardware bridge for camera/live operations.
+- DeepSeek-backed EcoPet chat with Vietnamese quality safeguards, role-scoped
+  context, User monthly quota, and a safe Vietnamese fallback.
+- A persistent hardware-sensor assignment on the map: Admin maps one physical
+  `BIN:1`, `BIN:2`, or `BIN:3` sensor reading to one cloud bin; Users can view
+  the live result but cannot change the shared hardware mapping.
+- Detailed operator guide for the map-to-hardware sensor flow and release notes.
+
+### Changed
+- Map sensor controls now explain their purpose, state that they never reset a
+  fullness percentage, and keep the action on a separate row to avoid overlap.
+- The persisted sensor assignment is reloaded after a page refresh, so the map
+  continues to show the bin currently receiving hardware data.
+
+### Fixed
+- Removed the misleading generic “Chọn” map control and restored a visible
+  success message on the User map.
+- Hardened bridge restart/reconnection and reduced the demo-target database
+  write to one scoped upsert.
+
 ### Fixed
 - Stabilized Live labels and servo dispatch by tracking route consensus across
   class-name changes for the same physical object.

README.md

@@ -53,6 +53,7 @@ Trash Sorter Pro là một hệ sinh thái AI phân loại rác end-to-end:
 - [Supabase/cloud readiness](docs/supabase-full-cloud-readiness.md)
 - [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)
 
 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).
 

docs/releases/v2.1.0.md

@@ -0,0 +1,129 @@
+# Trash Sorter Pro v2.1.0 — Cloud Map & Hardware Bridge
+
+**Released:** 2026-06-20  
+**Production:** <https://trash-sorter-v2.vercel.app>  
+**Scope:** desktop recognition, cloud dashboard, realtime bin map, EcoPet AI,
+and the secure Admin hardware bridge.
+
+## What people can understand at a glance
+
+Trash Sorter Pro has two connected applications:
+
+| Application | Who uses it | Main job |
+| --- | --- | --- |
+| Desktop app | Operator/Admin at the machine | Runs the USB camera, YOLO detection, UART/Arduino commands, sound, and reads physical fullness sensors. |
+| Web dashboard | Admin and User | Shows cloud data: bins, alerts, collection schedules, Eco Score, reports, and EcoPet AI. |
+
+The web dashboard does **not** drive a User’s camera or machine. Admin camera
+and training actions travel through the protected hardware bridge; ordinary map
+and chat data use the cloud database directly.
+
+## Map sensor button: exact meaning
+
+The map control is intentionally **not a reset button**.
+
+`Gán cảm biến` means: *choose which cloud bin receives a physical fullness
+reading from the hardware machine.* For example, choosing the recyclable bin
+with index `3` maps the next `BIN:3:87` UART reading to that selected bin. The
+web map then updates to `87%`, creates/updates the appropriate alert, and User
+views receive the realtime update.
+
+```mermaid
+flowchart LR
+    A[HC-SR04 / firmware] -->|BIN:3:87| B[Desktop agent]
+    B --> C[Supabase hardware synchronizer]
+    C -->|looks up current Admin assignment| D[demo_hardware_targets]
+    D --> E[Selected bin in bins table]
+    E --> F[Realtime event and alert]
+    F --> G[Admin and assigned User map]
+```
+
+### What Admin sees
+
+1. Open **Bản đồ thùng**.
+2. Open a station marker.
+3. Read the green explanation block: it says the action assigns a physical
+   sensor and does not reset the current fill percentage.
+4. Press **Gán cảm biến** on the intended O/R/I bin.
+5. The action changes to **Đang nhận dữ liệu cảm biến** and a success message
+   confirms the `BIN:<index>` mapping, station, and non-reset behavior.
+6. Refreshing the page keeps the selected state because the assignment is read
+   back from Supabase.
+
+Only one physical demo target is active at once. Selecting a different bin
+changes the destination for future hardware readings; it does not modify old
+history, erase alerts, or set a percentage to zero.
+
+### What User sees
+
+Users can see the assigned station, current fullness, and the label
+**Cảm biến phần cứng đang đồng bộ**. They cannot change the mapping. This avoids
+one User accidentally rerouting the shared physical sensor away from another
+station.
+
+### What happens when the bin is full
+
+- Under `80%`: normal state.
+- From `80%` to `94%`: warning / near full.
+- From `95%`: full state and an alert is created or refreshed.
+- Map refresh: authenticated User map checks realtime events every 1.2 seconds;
+  the regular refresh remains as a fallback.
+
+## Security and role boundaries
+
+| Action | Admin | User |
+| --- | --- | --- |
+| Assign the shared physical sensor target | Yes | No |
+| View assigned bins and realtime fullness | Yes | Yes, only assigned stations |
+| Use camera/live/training through bridge | Yes | No |
+| Read another account’s map/history | No special restriction for operations | No |
+
+The assignment is validated server-side against an active station and active
+bin. A User cannot forge an owner name. The bridge exports neither images,
+tokens, raw logs, passwords, nor arbitrary local endpoints.
+
+## Operating the bridge
+
+On the hardware computer, run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/start_public_hardware_bridge.ps1
+```
+
+The script starts or reuses the local agent, Supabase state synchronizer, and
+Cloudflare tunnel. Copy its HTTPS URL into Vercel Production as
+`TRASH_SORTER_HARDWARE_BRIDGE_URL`; the bridge secret must match
+`TRASH_SORTER_HARDWARE_BRIDGE_SECRET` on both sides.
+
+For a real deployment, use a named Cloudflare Tunnel or service manager. A
+Quick Tunnel URL changes whenever `cloudflared` restarts, so Vercel must be
+updated and redeployed after a URL change.
+
+## EcoPet AI in this release
+
+- Runs server-side with DeepSeek; no API key is exposed to the browser.
+- Answers in Vietnamese with diacritics, short practical guidance, and
+  role-scoped context.
+- User quota is 36 requests per month.
+- If AI is unavailable or returns poor Vietnamese text, EcoPet uses a safe
+  Vietnamese fallback and does not invent machine status.
+
+## Verification completed
+
+- Web build completed successfully.
+- Unit suite: **89/89 passed**.
+- Production alias and external bridge health endpoint were verified before
+  this release candidate.
+
+## Upgrade checklist
+
+1. Apply the Supabase migrations, including
+   `202606180004_demo_hardware_targets.sql`.
+2. Set `NEXT_PUBLIC_DEMO_HARDWARE_TARGET=1` on Vercel only when the demo sensor
+   control is intentionally enabled.
+3. Set `TRASH_SORTER_DEMO_HARDWARE_TARGET=1` only on the hardware bridge.
+4. Confirm a bridge health response before enabling Admin camera controls.
+5. Sign in as Admin, assign one sensor target, then send a safe test reading
+   such as `BIN:3:65` from the hardware firmware.
+6. Sign in as the assigned User and confirm the map updates without exposing
+   Admin controls.

web/src/app/api/user/demo-bin-target/route.ts

@@ -1,22 +1,15 @@
 import { NextRequest, NextResponse } from "next/server";
 
-import { cloudSetDemoHardwareTarget } from "@/lib/server/cloud-operations";
 import { handleCloudUserRequest } from "@/lib/server/cloud-user-route";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 export async function POST(request: NextRequest) {
-  let payload: Record<string, unknown>;
-  try {
-    payload = await request.json();
-  } catch {
-    return NextResponse.json({ detail: "Invalid JSON body" }, { status: 400 });
-  }
-  return handleCloudUserRequest(request, async (identity) => {
-    const result = await cloudSetDemoHardwareTarget(identity, payload);
-    if (!result) return NextResponse.json({ detail: "Station or bin is outside this User scope" }, { status: 404 });
-    if ("disabled" in result && result.disabled) return NextResponse.json(result, { status: 404 });
-    return result;
-  });
+  return handleCloudUserRequest(request, async () =>
+    NextResponse.json(
+      { detail: "Only an Admin can assign the shared hardware sensor to a map bin." },
+      { status: 403 }
+    )
+  );
 }

web/src/app/globals.css

@@ -1424,6 +1424,18 @@ input[type="file"] {
   opacity: 1;
 }
 
+.popup-sensor-target-status {
+  background: rgba(5, 150, 105, 0.1);
+  border: 1px solid rgba(5, 150, 105, 0.3);
+  border-radius: 7px;
+  color: #047857;
+  font-size: 11px;
+  font-weight: 800;
+  grid-column: 2 / -1;
+  line-height: 18px;
+  padding: 5px 8px;
+}
+
 .popup-bin-row > span,
 .popup-bin-row > strong {
   font-size: 12px;

web/src/components/dashboard-client.tsx

@@ -1059,7 +1059,7 @@ export function DashboardClient() {
       return;
     }
     const role = auth?.role;
-    if (role !== "admin" && role !== "user") {
+    if (role !== "admin") {
       setAgentError("Bạn cần đăng nhập để chọn thùng demo.");
       return;
     }
@@ -1076,7 +1076,7 @@ export function DashboardClient() {
     setAgentError("");
     try {
       const result = await cloudFetch<DemoHardwareTargetResponse>(
-        role === "admin" ? "/api/admin/demo-bin-target" : "/api/user/demo-bin-target",
+        "/api/admin/demo-bin-target",
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -1116,6 +1116,14 @@ export function DashboardClient() {
     }
   }, [agentToken, auth?.role]);
 
+  useEffect(() => {
+    const map = auth?.role === "admin" ? adminBinMap : auth?.role === "user" ? userBinMap : null;
+    const target = map?.sensor_target;
+    const targetKey = target ? `${target.station_id}:${target.bin_id}` : "";
+    setSelectedDemoBinKey(targetKey);
+    selectedDemoBinKeyRef.current = targetKey;
+  }, [adminBinMap, auth?.role, userBinMap]);
+
   async function reportDeviceIssue(payload: DeviceIssueCreatePayload) {
     setBusy(true);
     try {

web/src/components/operations-bin-map.tsx

@@ -765,6 +765,9 @@ function BinFillRow({
           {selected ? (pending ? "Đang kích hoạt cảm biến..." : "Đang nhận dữ liệu cảm biến") : pending ? "Đang kích hoạt..." : "Gán cảm biến"}
         </button>
       ) : null}
+      {selected && !demoTargetEnabled ? (
+        <span className="popup-sensor-target-status">Cảm biến phần cứng đang đồng bộ</span>
+      ) : null}
     </div>
   );
 }

web/src/components/user-dashboard/user-route-content.tsx

@@ -42,7 +42,7 @@ export function UserRouteContent(props: UserDashboardPanelProps) {
         selectedDemoBinKey={props.selectedDemoBinKey}
         onMapInteraction={props.onUserMapInteraction}
         onRefresh={props.onRefreshOperations}
-        demoTargetEnabled={process.env.NEXT_PUBLIC_DEMO_HARDWARE_TARGET === "1"}
+        demoTargetEnabled={false}
         onSelectDemoBin={props.onSelectDemoBin}
       />
     );

web/src/lib/agent.ts

@@ -623,6 +623,12 @@ export type BinMapResponse = {
   };
   stations: BinStation[];
   total: number;
+  sensor_target?: {
+    station_id: string;
+    bin_id: string;
+    bin_index: number;
+    selected_at: string;
+  } | null;
 };
 
 export type BinStationCreatePayload = {

web/src/lib/server/cloud-operations.ts

@@ -185,12 +185,40 @@ export async function cloudBinMap(identity: CloudAuthIdentity, includeInactive =
   const childBinsByStation = await binsByStation(stationIds);
   const alertsByStation = await openAlertCountsByStation(stationIds, owner);
   const stations = stationRows.map((row) => stationDto(row, childBinsByStation.get(row.station_id) ?? [], alertsByStation));
+  const sensorTarget = await cloudDemoHardwareTarget(identity);
   return {
     generated_at: new Date().toISOString(),
     center: DEFAULT_CENTER,
     stations,
     total: stations.length,
-    seed_source: SEED_SOURCE
+    seed_source: SEED_SOURCE,
+    sensor_target: sensorTarget
+  };
+}
+
+async function cloudDemoHardwareTarget(identity: CloudAuthIdentity) {
+  if (!demoHardwareTargetEnabled()) {
+    return null;
+  }
+  const owner = identity.role === "user" ? identity.username : "";
+  const result = await pool().query<DemoHardwareTargetRow>(
+    `select owner_username, station_id, bin_id, bin_index, selected_by, selected_at, active
+       from public.demo_hardware_targets
+      where active = true
+        and ($1::text = '' or owner_username = $1)
+      order by selected_at desc
+      limit 1`,
+    [owner]
+  );
+  const target = result.rows[0];
+  if (!target) {
+    return null;
+  }
+  return {
+    station_id: target.station_id,
+    bin_id: target.bin_id,
+    bin_index: Number(target.bin_index),
+    selected_at: iso(target.selected_at)
   };
 }