feat(dashboard): add upcoming EOL + admin operations widgets

Surface operational signal alongside inventory: upcoming-EOL banner and
KPI for everyone; admin-only repairs tempo, FM close time, open FMs by
host, and custody backlog. Service shapes payload by role.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

apps/api/src/services/analytics.test.ts

@@ -2,9 +2,15 @@ import { describe, expect, it } from 'vitest';
 import type { Tx } from './types.js';
 import { dashboard } from './analytics.js';
 
-// Minimal in-memory tx double exercising the dashboard() aggregator.
-// We only stub the calls dashboard() actually makes; other Prisma methods remain unimplemented.
-function makeTx(args: {
+type EolPartModel = {
+  id: string;
+  mpn: string;
+  eolDate: Date | null;
+  manufacturerId: string;
+  manufacturer: { name: string };
+};
+
+type FakeArgs = {
   partCount: number;
   stateRows: { state: string; count: number; totalPrice: number }[];
   parts: {
@@ -15,57 +21,110 @@ function makeTx(args: {
     partModelId: string;
   }[];
   openFms: number;
-  eolPartModels: {
-    id: string;
-    mpn: string;
-    eolDate: Date | null;
-    manufacturerId: string;
-    manufacturer: { name: string };
-  }[];
+  pastEolModels: EolPartModel[];
+  upcomingEolModels: EolPartModel[];
   bins: { id: string; name: string; room: { name: string; site: { name: string } } }[];
-}): Tx {
+  // Admin-only inputs. Ignored when isAdmin=false path is exercised.
+  repairs?: { performedAt: Date }[];
+  fmsClosed?: { openedAt: Date; closedAt: Date | null }[];
+  newFms7d?: number;
+  openFmGroups?: { hostId: string; count: number }[];
+  custodyGroups?: { custodianId: string | null; count: number }[];
+  hosts?: { id: string; name: string }[];
+  users?: { id: string; username: string }[];
+};
+
+function makeTx(args: FakeArgs): Tx {
   const tx = {
     part: {
       count: async () => args.partCount,
-      groupBy: async () =>
-        args.stateRows.map((s) => ({
+      groupBy: async (q: { by: string[]; where?: { custodianId?: unknown } }) => {
+        if (q.by.includes('custodianId')) {
+          return (args.custodyGroups ?? []).map((g) => ({
+            custodianId: g.custodianId,
+            _count: { _all: g.count },
+          }));
+        }
+        return args.stateRows.map((s) => ({
           state: s.state,
           _count: { _all: s.count },
           _sum: { price: s.totalPrice },
-        })),
+        }));
+      },
       findMany: async () => args.parts,
     },
     fm: {
-      count: async () => args.openFms,
+      count: async (q: { where?: { status?: string; openedAt?: { gte: Date } } }) => {
+        if (q.where?.openedAt) return args.newFms7d ?? 0;
+        return args.openFms;
+      },
+      findMany: async () => args.fmsClosed ?? [],
+      groupBy: async () =>
+        (args.openFmGroups ?? []).map((g) => ({
+          hostId: g.hostId,
+          _count: { _all: g.count },
+        })),
     },
     partModel: {
-      findMany: async () => args.eolPartModels,
+      findMany: async (q: { where?: { eolDate?: { gt?: Date; lte?: Date; not?: unknown } } }) => {
+        const gt = q.where?.eolDate?.gt;
+        if (gt !== undefined) return args.upcomingEolModels;
+        return args.pastEolModels;
+      },
     },
     bin: {
       findMany: async () => args.bins,
     },
+    repair: {
+      count: async (q: { where?: { performedAt?: { gte: Date } } }) => {
+        const gte = q.where?.performedAt?.gte;
+        if (!gte) return 0;
+        return (args.repairs ?? []).filter((r) => r.performedAt >= gte).length;
+      },
+      findMany: async (q: { where?: { performedAt?: { gte: Date } } }) => {
+        const gte = q.where?.performedAt?.gte;
+        if (!gte) return args.repairs ?? [];
+        return (args.repairs ?? []).filter((r) => r.performedAt >= gte);
+      },
+    },
+    host: {
+      findMany: async () => args.hosts ?? [],
+    },
+    user: {
+      findMany: async () => args.users ?? [],
+    },
   };
   return tx as unknown as Tx;
 }
 
 const now = new Date('2026-04-16T00:00:00.000Z');
 const daysAgo = (n: number) => new Date(now.getTime() - n * 24 * 60 * 60 * 1000);
+const daysAhead = (n: number) => new Date(now.getTime() + n * 24 * 60 * 60 * 1000);
+const HOUR_MS = 60 * 60 * 1000;
 
-describe('analytics.dashboard', () => {
+const EMPTY: FakeArgs = {
+  partCount: 0,
+  stateRows: [],
+  parts: [],
+  openFms: 0,
+  pastEolModels: [],
+  upcomingEolModels: [],
+  bins: [],
+};
+
+describe('analytics.dashboard — base fields', () => {
   it('aggregates totals, state counts and open FMs', async () => {
     const tx = makeTx({
+      ...EMPTY,
       partCount: 5,
       stateRows: [
         { state: 'SPARE', count: 3, totalPrice: 1500 },
         { state: 'DEPLOYED', count: 2, totalPrice: 8000 },
       ],
-      parts: [],
       openFms: 4,
-      eolPartModels: [],
-      bins: [],
     });
 
-    const r = await dashboard(tx);
+    const r = await dashboard(tx, { isAdmin: false });
     expect(r.totalParts).toBe(5);
     expect(r.openFms).toBe(4);
     expect(r.byState).toEqual([
@@ -76,48 +135,42 @@ describe('analytics.dashboard', () => {
 
   it('buckets parts by age correctly', async () => {
     const tx = makeTx({
+      ...EMPTY,
       partCount: 4,
-      stateRows: [],
       parts: [
         { id: 'p1', state: 'SPARE', binId: null, createdAt: daysAgo(10), partModelId: 'pm' },
         { id: 'p2', state: 'SPARE', binId: null, createdAt: daysAgo(60), partModelId: 'pm' },
         { id: 'p3', state: 'SPARE', binId: null, createdAt: daysAgo(400), partModelId: 'pm' },
         { id: 'p4', state: 'SPARE', binId: null, createdAt: daysAgo(900), partModelId: 'pm' },
       ],
-      openFms: 0,
-      eolPartModels: [],
-      bins: [],
     });
 
-    const r = await dashboard(tx);
+    const r = await dashboard(tx, { isAdmin: false });
     const byLabel = Object.fromEntries(r.ageBuckets.map((b) => [b.label, b.count]));
     expect(byLabel['0–30d']).toBe(1);
     expect(byLabel['31–90d']).toBe(1);
     expect(byLabel['1–2y']).toBe(1);
     expect(byLabel['2y+']).toBe(1);
-    // totals should match
     expect(r.ageBuckets.reduce((s, b) => s + b.count, 0)).toBe(4);
   });
 
   it('ranks top bins and labels them site/room/bin', async () => {
     const tx = makeTx({
+      ...EMPTY,
       partCount: 4,
-      stateRows: [],
       parts: [
         { id: '1', state: 'SPARE', binId: 'b1', createdAt: daysAgo(1), partModelId: 'pm' },
         { id: '2', state: 'SPARE', binId: 'b1', createdAt: daysAgo(1), partModelId: 'pm' },
         { id: '3', state: 'SPARE', binId: 'b2', createdAt: daysAgo(1), partModelId: 'pm' },
         { id: '4', state: 'SPARE', binId: null, createdAt: daysAgo(1), partModelId: 'pm' },
       ],
-      openFms: 0,
-      eolPartModels: [],
       bins: [
         { id: 'b1', name: 'A1', room: { name: 'Lab', site: { name: 'HQ' } } },
         { id: 'b2', name: 'B2', room: { name: 'Lab', site: { name: 'HQ' } } },
       ],
     });
 
-    const r = await dashboard(tx);
+    const r = await dashboard(tx, { isAdmin: false });
     expect(r.topBins).toEqual([
       { binId: 'b1', label: 'HQ / Lab / A1', count: 2 },
       { binId: 'b2', label: 'HQ / Lab / B2', count: 1 },
@@ -126,15 +179,14 @@ describe('analytics.dashboard', () => {
 
   it('flags part models whose EOL has passed and have deployed parts', async () => {
     const tx = makeTx({
+      ...EMPTY,
       partCount: 3,
-      stateRows: [],
       parts: [
         { id: '1', state: 'DEPLOYED', binId: null, createdAt: daysAgo(1), partModelId: 'pm1' },
         { id: '2', state: 'DEPLOYED', binId: null, createdAt: daysAgo(1), partModelId: 'pm1' },
         { id: '3', state: 'DEPLOYED', binId: null, createdAt: daysAgo(1), partModelId: 'pm2' },
       ],
-      openFms: 0,
-      eolPartModels: [
+      pastEolModels: [
         {
           id: 'pm1',
           mpn: 'ACM-100',
@@ -157,10 +209,9 @@ describe('analytics.dashboard', () => {
           manufacturer: { name: 'Gamma' },
         },
       ],
-      bins: [],
     });
 
-    const r = await dashboard(tx);
+    const r = await dashboard(tx, { isAdmin: false });
     expect(r.deployedPastEol.map((m) => m.mpn)).toEqual(['ACM-100', 'BET-200']);
     expect(r.deployedPastEol[0]).toMatchObject({
       partModelId: 'pm1',
@@ -174,3 +225,122 @@ describe('analytics.dashboard', () => {
     });
   });
 });
+
+describe('analytics.dashboard — upcomingEol', () => {
+  it('lists models with upcoming EOL sorted by date, filters zero-deployed', async () => {
+    const tx = makeTx({
+      ...EMPTY,
+      partCount: 3,
+      parts: [
+        { id: '1', state: 'DEPLOYED', binId: null, createdAt: daysAgo(1), partModelId: 'pm1' },
+        { id: '2', state: 'DEPLOYED', binId: null, createdAt: daysAgo(1), partModelId: 'pm2' },
+        { id: '3', state: 'DEPLOYED', binId: null, createdAt: daysAgo(1), partModelId: 'pm2' },
+      ],
+      upcomingEolModels: [
+        {
+          id: 'pm2',
+          mpn: 'LATER',
+          eolDate: daysAhead(150),
+          manufacturerId: 'm1',
+          manufacturer: { name: 'Acme' },
+        },
+        {
+          id: 'pm1',
+          mpn: 'SOONER',
+          eolDate: daysAhead(45),
+          manufacturerId: 'm1',
+          manufacturer: { name: 'Acme' },
+        },
+        {
+          id: 'pm3',
+          mpn: 'NODEP',
+          eolDate: daysAhead(30),
+          manufacturerId: 'm1',
+          manufacturer: { name: 'Acme' },
+        },
+      ],
+    });
+
+    const r = await dashboard(tx, { isAdmin: false });
+    expect(r.upcomingEol.map((m) => m.mpn)).toEqual(['SOONER', 'LATER']);
+    expect(r.upcomingEol[0]).toMatchObject({ partModelId: 'pm1', deployedCount: 1 });
+    expect(r.upcomingEol[1]).toMatchObject({ partModelId: 'pm2', deployedCount: 2 });
+  });
+});
+
+describe('analytics.dashboard — isAdmin gating', () => {
+  it('omits operations when isAdmin is false', async () => {
+    const tx = makeTx(EMPTY);
+    const r = await dashboard(tx, { isAdmin: false });
+    expect(r.operations).toBeUndefined();
+  });
+
+  it('returns operations with expected shape when isAdmin is true', async () => {
+    const tx = makeTx({
+      ...EMPTY,
+      repairs: [{ performedAt: daysAgo(1) }],
+      fmsClosed: [{ openedAt: daysAgo(2), closedAt: daysAgo(1) }],
+      newFms7d: 3,
+      openFmGroups: [{ hostId: 'h1', count: 2 }],
+      custodyGroups: [{ custodianId: 'u1', count: 1 }],
+      hosts: [{ id: 'h1', name: 'host-1' }],
+      users: [{ id: 'u1', username: 'alice' }],
+    });
+
+    const r = await dashboard(tx, { isAdmin: true });
+    expect(r.operations).toBeDefined();
+    expect(r.operations).toMatchObject({
+      repairs7d: 1,
+      repairs30d: 1,
+      newFms7d: 3,
+    });
+    expect(r.operations!.repairsTrend30d).toHaveLength(30);
+    expect(r.operations!.openFmsByHost).toEqual([{ hostId: 'h1', hostName: 'host-1', count: 2 }]);
+    expect(r.operations!.custodyBacklog).toEqual([
+      { userId: 'u1', username: 'alice', count: 1 },
+    ]);
+  });
+});
+
+describe('analytics.dashboard — operations fields', () => {
+  it('repairsTrend30d has 30 entries and zero-fills empty days', async () => {
+    const tx = makeTx({
+      ...EMPTY,
+      repairs: [{ performedAt: daysAgo(5) }, { performedAt: daysAgo(28) }],
+    });
+
+    const r = await dashboard(tx, { isAdmin: true });
+    const trend = r.operations!.repairsTrend30d;
+    expect(trend).toHaveLength(30);
+    expect(trend.filter((d) => d.count === 0)).toHaveLength(28);
+    expect(trend.filter((d) => d.count === 1)).toHaveLength(2);
+    // Chronological order: earliest first, today last
+    for (let i = 1; i < trend.length; i++) {
+      expect(trend[i]!.date >= trend[i - 1]!.date).toBe(true);
+    }
+  });
+
+  it('avgFmCloseHours30d is null when no FMs closed in window', async () => {
+    const tx = makeTx({ ...EMPTY, fmsClosed: [] });
+    const r = await dashboard(tx, { isAdmin: true });
+    expect(r.operations!.avgFmCloseHours30d).toBeNull();
+  });
+
+  it('avgFmCloseHours30d averages close durations in hours', async () => {
+    const tx = makeTx({
+      ...EMPTY,
+      fmsClosed: [
+        {
+          openedAt: new Date(now.getTime() - 4 * HOUR_MS),
+          closedAt: new Date(now.getTime() - 2 * HOUR_MS),
+        },
+        {
+          openedAt: new Date(now.getTime() - 10 * HOUR_MS),
+          closedAt: new Date(now.getTime() - 4 * HOUR_MS),
+        },
+      ],
+    });
+    const r = await dashboard(tx, { isAdmin: true });
+    expect(r.operations!.avgFmCloseHours30d).toBe(4);
+  });
+});