@7365admin1/layer-common 4.52.0 → 4.54.0

package/utils/robot-display.ts

@@ -286,8 +286,10 @@ const COMMAND_NEEDS: Readonly<Record<string, string>> = {
   area: "startProcess",
   spot: "spotClean",
   return: "sendToDock",
-  pause: "pauseProcess",
-  resume: "pauseProcess",
+  // Pause / resume = pausing a robot mid-way; cancel = stopping the job. Split
+  // so a brand that can stop but not pause (PadBot) shows Cancel with no Pause.
+  pause: "pauseResume",
+  resume: "pauseResume",
   cancel: "pauseProcess",
   navigate: "navigateToPoint",
   relocalize: "relocalize",
@@ -383,7 +385,8 @@ export type TRobotCommandKind =
   | "resume"
   | "cancel"
   | "navigate"
-  | "relocalize";
+  | "relocalize"
+  | "patrol-resume";
 
 /**
  * The command bar's buttons, in bar order; each needs `COMMAND_NEEDS[kind]`.
@@ -398,6 +401,7 @@ const COMMANDS: ReadonlyArray<{ kind: TRobotCommandKind; label: string }> = [
   { kind: "cancel", label: "Cancel" },
   { kind: "navigate", label: "Go to point" },
   { kind: "relocalize", label: "Set position" },
+  { kind: "patrol-resume", label: "Resume patrol" },
 ];
 
 export type TRobotCommand = { kind: TRobotCommandKind; label: string; primary: boolean };
@@ -409,7 +413,9 @@ export type TRobotCommand = { kind: TRobotCommandKind; label: string; primary: b
  *  - role: only a Manager (`canCommand`, i.e. the app's command permission);
  *  - online: only a robot confirmed online (`online === true`);
  *  - context: Pause only while working, Resume only while paused;
- *  - type: a security robot has no cleaning jobs, so no Clean all / Clean area.
+ *  - type: a security robot has no cleaning jobs, so no Clean all / Clean area -
+ *    but a brand with `patrolControl` gets Start patrol (the default route) and
+ *    Resume patrol (while it is not already patrolling).
  *
  * Returns [] whenever the bar should not render at all.
  */
@@ -422,13 +428,20 @@ export function visibleCommands(input: {
 } | null | undefined): TRobotCommand[] {
   if (!input || input.canCommand !== true || input.online !== true) return [];
   const caps = input.capabilities ?? {};
+  const patrol = input.type === "security" && caps.patrolControl === true;
   return COMMANDS.filter((c) => {
+    if (c.kind === "patrol-resume") return patrol && input.mode !== "WORKING" && input.mode !== "IN_TRANSIT";
     if (caps[COMMAND_NEEDS[c.kind]!] !== true) return false;
     if (c.kind === "pause" && input.mode !== "WORKING") return false;
     if (c.kind === "resume" && input.mode !== "PAUSED") return false;
-    if ((c.kind === "full" || c.kind === "area") && input.type === "security") return false;
+    if (c.kind === "full" && input.type === "security") return patrol;
+    if (c.kind === "area" && input.type === "security") return false;
     return true;
-  }).map((c) => ({ kind: c.kind, label: c.label, primary: c.kind === "full" }));
+  }).map((c) => ({
+    kind: c.kind,
+    label: c.kind === "full" && input.type === "security" ? "Start patrol" : c.label,
+    primary: c.kind === "full",
+  }));
 }
 
 /**
@@ -596,28 +609,79 @@ export type TLiveRobotState = {
   /** The brand's own status words ("CLEANING_AUTO"), quoted as "Brand status". */
   statusName?: string;
   model?: string;
-  fault?: { code: string; message?: string; since?: number } | null;
+  fault?: { code: string; message?: string; since?: number; imageUrl?: string | null; thermalImageUrl?: string | null } | null;
   capabilities?: Record<string, unknown>;
   lastSeenAt?: string | null;
+  /** Epoch ms of the last answer that was read (set by `mergeLiveStates`). */
+  readAt?: number;
+  /** Epoch ms when the shown position was reported. */
+  positionAt?: number;
+  /** true = what is shown is the last reading, kept through a short gap - drawn faded with "last seen". */
+  stale?: boolean;
 };
 
+/** A gap shorter than this keeps the last reading (faded, "last seen N s ago"); longer reads "Reconnecting". */
+export const LIVE_GRACE_MS = 15_000;
+
+const hasPos = (s: Partial<TLiveRobotState> | null | undefined) =>
+  (!!s?.position && finite(s.position.x) && finite(s.position.y)) || (!!s?.planPosition && finite(s.planPosition.x) && finite(s.planPosition.y));
+
 /**
- * Fold one poll's answer into the live map. A robot that did not answer
- * REPLACES its old state with `{ ok: false }`: a stale battery or position
- * must never stay on screen as if live. Robots not in this answer keep theirs.
+ * Fold one poll's answer into the live map. Robots not in this answer keep theirs.
+ *
+ * One missed or failed update must not make a robot vanish from the map
+ * (owner, 2026-09-26: it disappeared and came back while moving). So:
+ *  - no answer (`ok: false`): the last reading is kept, marked `stale`, for
+ *    up to `LIVE_GRACE_MS` after it was read; past that it is REPLACED by
+ *    `{ ok: false }` ("Reconnecting") - a stale battery or position is never
+ *    kept as if live;
+ *  - an answer without a position: the last position is kept (stale) within
+ *    the same window, unless the robot now says it is offline or that its
+ *    floor is unknown (`floorKnown: false`);
+ *  - an answer without floor fields keeps the last floor.
  */
 export function mergeLiveStates(
   prev: Record<string, TLiveRobotState>,
   items: Array<Partial<TLiveRobotState> & { id?: unknown }> | null | undefined,
+  now: number = Date.now(),
 ): Record<string, TLiveRobotState> {
   const next = { ...prev };
   for (const item of items ?? []) {
     if (!item || typeof item.id !== "string") continue;
-    next[item.id] = item.ok === true ? ({ ...item, ok: true } as TLiveRobotState) : { id: item.id, ok: false, monitorable: item.monitorable !== false };
+    const p = prev[item.id];
+    const recent = (at: number | undefined) => finite(at) && now - at <= LIVE_GRACE_MS;
+    if (item.ok !== true) {
+      next[item.id] =
+        item.monitorable !== false && p?.ok && recent(p.readAt)
+          ? { ...p, stale: true }
+          : { id: item.id, ok: false, monitorable: item.monitorable !== false };
+      continue;
+    }
+    const s = { ...item, ok: true, readAt: now, stale: false } as TLiveRobotState;
+    if (!("floorKnown" in item) && !("floorNo" in item) && p?.ok) {
+      s.floorNo = p.floorNo;
+      s.floorKnown = p.floorKnown;
+    }
+    if (hasPos(item)) s.positionAt = now;
+    else if (p?.ok && hasPos(p) && recent(p.positionAt) && item.online !== false && item.floorKnown !== false) {
+      s.position = p.position ?? null;
+      s.planPosition = p.planPosition ?? null;
+      s.positionAt = p.positionAt;
+      s.stale = true;
+    }
+    next[item.id] = s;
   }
   return next;
 }
 
+/** "last seen 8 s ago" for a kept (stale) reading, "" when it is fresh. */
+export function staleText(live: TLiveRobotState | null | undefined, now: number = Date.now()): string {
+  if (!live?.stale) return "";
+  const at = finite(live.positionAt) ? live.positionAt : live.readAt;
+  if (!finite(at)) return "last reading";
+  return `last seen ${Math.max(0, Math.round((now - at) / 1000))} s ago`;
+}
+
 /**
  * What the Status cell says for a row: the live mode when read; "Reconnecting"
  * when the last poll got no answer; "Offline" from the stored record while no
@@ -718,7 +782,7 @@ export function brandName(brand: unknown, brands?: Array<{ brand?: unknown; disp
 
 /* ------------------------------------------------------------- mini-map */
 
-export type TMapRobot = { id: string; name: string; mode?: string; type?: string; left: string; top: string; rot: string };
+export type TMapRobot = { id: string; name: string; mode?: string; type?: string; left: string; top: string; rot: string; stale?: boolean; seen?: string };
 
 const finite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
 
@@ -787,7 +851,8 @@ export function mapRobots(
     const live = states[id];
     if (!placeable(live) || live!.floorNo !== floor) return [];
     const at = planPoint(live as any)!;
-    return [{ id, name: String(r.name ?? ""), mode: live!.mode, type: r.type as string, ...at, rot: `rotate(${headingDeg(live)}deg)` }];
+    // A kept (stale) reading is drawn faded with "last seen N s ago" - never as live.
+    return [{ id, name: String(r.name ?? ""), mode: live!.mode, type: r.type as string, ...at, rot: `rotate(${headingDeg(live)}deg)`, stale: live!.stale === true, seen: staleText(live) }];
   });
 }
 
@@ -815,33 +880,47 @@ export type TPatrolRouteView = {
   floorNo: number | null;
   checkpoints: Array<{ name: string; x: number; y: number }>;
   currentCheckpoint: number | null;
+  /** Every stop's name in order, placed on the plan or not (PadBot); a route with none placed is listed, never drawn. */
+  stops?: string[];
 };
 
+const placed = (c: { x?: unknown; y?: unknown }) => finite(c?.x) && finite(c?.y);
+
+/** "Gate → Lobby → Car park" for a route whose stops cannot be placed on the plan; "" when it can be drawn. */
+export function unplacedStopsText(route: Pick<TPatrolRouteView, "checkpoints" | "stops"> | null | undefined): string {
+  if (!route || (route.checkpoints ?? []).filter(placed).length >= 2 || !route.stops?.length) return "";
+  return route.stops.join(" → ");
+}
+
 /** The SVG path of a closed route on a `w` x `h` viewBox (checkpoints are 0-100 shares of the plan). */
 export function routePathD(checkpoints: Array<{ x: number; y: number }>, w = 400, h = 300): string {
-  if (!checkpoints?.length) return "";
+  checkpoints = (checkpoints ?? []).filter(placed);
+  if (checkpoints.length < 2) return "";
   return checkpoints.map((p, i) => `${i ? "L" : "M"}${((p.x / 100) * w).toFixed(1)} ${((p.y / 100) * h).toFixed(1)}`).join(" ") + " Z";
 }
 
 /** Numbered checkpoint markers for every route; `current` = the one the robot is heading for. */
 export function routeMarks(routes: TPatrolRouteView[]) {
   return routes.flatMap((r) =>
-    r.checkpoints.map((c, i) => ({
+    r.checkpoints.flatMap((c, i) => (!placed(c) ? [] : [{
       key: `${r.id}-${i}`,
       n: i + 1,
       left: `${c.x}%`,
       top: `${c.y}%`,
       label: c.name,
       current: r.currentCheckpoint === i,
-    })),
+    }])),
   );
 }
 
 /** A route-name tag at each route's first checkpoint. */
 export function routeTags(routes: TPatrolRouteView[]) {
   return routes
-    .filter((r) => r.checkpoints.length)
-    .map((r) => ({ key: r.id, name: r.name, count: r.checkpoints.length, left: `${r.checkpoints[0]!.x}%`, top: `${r.checkpoints[0]!.y}%` }));
+    .filter((r) => r.checkpoints.some(placed))
+    .map((r) => {
+      const first = r.checkpoints.find(placed)!;
+      return { key: r.id, name: r.name, count: r.checkpoints.length, left: `${first.x}%`, top: `${first.y}%` };
+    });
 }
 
 /**
@@ -947,6 +1026,7 @@ export function optimisticMode(kind: unknown, mode: unknown): string {
     case "area":
     case "spot":
     case "resume":
+    case "patrol-resume":
       return "WORKING";
     case "return":
       return "CHARGING_CYCLE";
@@ -981,6 +1061,84 @@ export function commandBody(kind: TRobotCommandKind, live: TLiveRobotState | nul
   return finite(live?.floorNo) ? { kind, floorNo: live!.floorNo, x: p.x, y: p.y, theta: p.theta } : null;
 }
 
+/* ------------------------------------------ saved points (Go to point / Set position) */
+
+/** §5.1 target point types, in words. */
+export const POINT_TYPE_TEXT: Readonly<Record<number, string>> = { 0: "Point", 3: "Lift", 4: "Loading", 6: "Access door", 10: "Charging" };
+
+export type TSavedPoint = { mapId: string; targetPointId: string; name: string; type: string; floorNo: number | null; x: number; y: number; yaw: number };
+export type TSavedPointGroup = { mapId: string; title: string; floorNo: number | null; points: TSavedPoint[] };
+
+/**
+ * The robot's own saved points, per map ("Lobby map · L3"), from `/robots/:id/maps`
+ * items that carry `targetPoints` (PadBot). [] for brands without them - they
+ * keep the current-pose behaviour of `commandBody`.
+ */
+export function savedPointGroups(maps: Array<Record<string, any>> | null | undefined): TSavedPointGroup[] {
+  return (Array.isArray(maps) ? maps : []).flatMap((m) => {
+    const floorNo = Number.isInteger(m?.floor) ? (m.floor as number) : null;
+    const points = (Array.isArray(m?.targetPoints) ? m.targetPoints : [])
+      .filter((t: any) => typeof t?.targetPointId === "string" && t.targetPointId && finite(t.worldX) && finite(t.worldY))
+      .map((t: any) => ({
+        mapId: String(m.mapId ?? t.mapId ?? ""),
+        targetPointId: t.targetPointId,
+        name: String(t.name || "Unnamed point"),
+        type: POINT_TYPE_TEXT[t.targetPointType] ?? "Point",
+        floorNo,
+        x: t.worldX,
+        y: t.worldY,
+        yaw: finite(t.yaw) ? t.yaw : 0,
+      }));
+    if (!points.length || !m?.mapId) return [];
+    const name = String(m.mapDisplayName || m.mapName || "Map");
+    return [{ mapId: String(m.mapId), title: floorNo === null ? name : `${name} · ${levelText(floorNo)}`, floorNo, points }];
+  });
+}
+
+/**
+ * The command for a picked saved point. Go to point names the point
+ * (`go-to-point`); Set position tells the robot it stands there now - only on
+ * the floor the robot reports (null otherwise).
+ */
+export function pointCommandBody(kind: "navigate" | "relocalize", point: TSavedPoint, live: TLiveRobotState | null | undefined): Record<string, unknown> | null {
+  if (kind === "navigate") return { kind: "go-to-point", mapId: point.mapId, targetPointId: point.targetPointId };
+  if (point.floorNo === null || !finite(live?.floorNo) || live!.floorNo !== point.floorNo) return null;
+  return { kind: "relocalize", floorNo: point.floorNo, x: point.x, y: point.y, theta: (point.yaw * Math.PI) / 180 };
+}
+
+/* ------------------------------------------ recent patrol runs (no schedule API) */
+
+/**
+ * A HINT, never a schedule: when the same route started on at least 3 of the
+ * last 7 days inside one 60-minute window, "Looks like "Night round" runs
+ * daily around 20:00 (based on the last 7 days)". Local clock. "" otherwise.
+ */
+export function patrolRunHint(records: Array<{ routeName?: unknown; startedAt?: unknown }> | null | undefined, now: number = Date.now()): string {
+  const since = now - 7 * 86_400_000;
+  const byRoute = new Map<string, Array<{ day: string; min: number }>>();
+  for (const r of records ?? []) {
+    const t = typeof r?.startedAt === "string" ? Date.parse(r.startedAt) : NaN;
+    const name = typeof r?.routeName === "string" ? r.routeName.trim() : "";
+    if (!name || !finite(t) || t < since || t > now) continue;
+    const d = new Date(t);
+    byRoute.set(name, [...(byRoute.get(name) ?? []), { day: d.toDateString(), min: d.getHours() * 60 + d.getMinutes() }]);
+  }
+  let best: { name: string; days: number; min: number } | null = null;
+  for (const [name, runs] of byRoute) {
+    for (const start of runs) {
+      const inWin = runs.filter((x) => x.min >= start.min && x.min < start.min + 60);
+      const days = new Set(inWin.map((x) => x.day)).size;
+      if (days >= 3 && (!best || days > best.days)) {
+        best = { name, days, min: Math.round(inWin.reduce((s, x) => s + x.min, 0) / inWin.length / 5) * 5 };
+      }
+    }
+  }
+  if (!best) return "";
+  const hhmm = `${String(Math.floor(best.min / 60) % 24).padStart(2, "0")}:${String(best.min % 60).padStart(2, "0")}`;
+  const how = best.days >= 6 ? "daily" : `on ${best.days} of the last 7 days`;
+  return `Looks like "${best.name}" runs ${how} around ${hhmm} (based on the last 7 days)`;
+}
+
 /**
  * May the plan take spot-clean clicks? A Manager, a cleaning robot, a brand
  * that declares `spotClean`, and a robot confirmed online. (A busy robot keeps
@@ -1025,12 +1183,15 @@ export function speedText(
 }
 
 /** "x 17.9 · y 34.1 · 53°" (metres, the robot's map frame) - or "Reconnecting", or "Not reported". */
-export function positionText(live: TLiveRobotState | null | undefined, capabilities: Record<string, unknown> | null | undefined): string {
+export function positionText(live: TLiveRobotState | null | undefined, capabilities: Record<string, unknown> | null | undefined, now: number = Date.now()): string {
   if (capabilities?.readLocation !== true) return "Not reported";
   const p = live?.position;
-  if (!live?.ok || live.online === false || !p || !finite(p.x) || !finite(p.y)) return "Reconnecting";
+  if (!live?.ok || live.online === false) return "Reconnecting";
+  // Answering, but it has no position right now (e.g. not relocalised) - said, not guessed.
+  if (!p || !finite(p.x) || !finite(p.y)) return "Position not reported right now";
   const deg = finite(p.theta) ? Math.round(((((p.theta * 180) / Math.PI) % 360) + 360) % 360) : 0;
-  return `x ${p.x.toFixed(1)} · y ${p.y.toFixed(1)} · ${deg}°`;
+  const seen = staleText(live, now);
+  return `x ${p.x.toFixed(1)} · y ${p.y.toFixed(1)} · ${deg}°${seen ? ` · ${seen}` : ""}`;
 }
 
 export type TRobotFact = { label: string; value: string; dim: boolean };
@@ -1091,6 +1252,8 @@ export function mergePose(
   const plan = event.planPosition as { x?: unknown; y?: unknown } | null | undefined;
   return {
     ...live,
+    stale: false,
+    positionAt: Date.now(),
     position: { x, y, theta: finite(theta) ? theta : live.position?.theta ?? 0 },
     ...(plan && finite(plan.x) && finite(plan.y) ? { planPosition: { x: plan.x, y: plan.y } } : {}),
     ...(typeof mode === "string" && mode ? { mode } : {}),
@@ -1184,6 +1347,28 @@ export function activityRow(entry: Record<string, any> | null | undefined, now:
  * type; option shows capability"): only brands that make that class (a brand
  * declaring no `types` makes cleaning robots), as "Ounitech · Basic control".
  */
+/** "Open alarm" / "Machine fault" badge for the fault bar: a security robot's alarm is something it SAW. */
+export function faultBadge(fault: { code?: unknown; alarm?: unknown } | null | undefined): "ALARM" | "FAULT" {
+  return fault?.alarm === true || (typeof fault?.code === "string" && fault.code.startsWith("ALARM-")) ? "ALARM" : "FAULT";
+}
+
+/** One past patrol as a row: "Completed · 1 min 41 s · 19.9 m · 1 alert". */
+export function patrolRecordRow(r: Record<string, any> | null | undefined, now: number = Date.now()) {
+  const RESULT: Record<string, string> = { completed: "Completed", partial: "Partly completed", failed: "Failed", "in-progress": "In progress" };
+  const secs = typeof r?.durationS === "number" && Number.isFinite(r.durationS) ? Math.max(0, Math.round(r.durationS)) : null;
+  const dur = secs === null ? "—" : secs >= 60 ? `${Math.floor(secs / 60)} min ${secs % 60} s` : `${secs} s`;
+  const dist = typeof r?.distanceM === "number" && Number.isFinite(r.distanceM) ? `${Math.round(r.distanceM * 10) / 10} m` : "—";
+  const alerts = Number(r?.alarmCount) || 0;
+  return {
+    key: String(r?.id ?? ""),
+    when: activityWhen(r?.startedAt, now),
+    route: String(r?.routeName || "Patrol"),
+    result: RESULT[String(r?.result)] ?? "Unknown",
+    tone: (r?.result === "completed" ? "success" : r?.result === "in-progress" ? "info" : "warning") as THeroTone,
+    detail: `${dur} · ${dist} · ${alerts === 1 ? "1 alert" : `${alerts} alerts`}`,
+  };
+}
+
 export function brandOptions(
   brands: Array<Record<string, any>> | null | undefined,
   type: unknown,