Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/**
* State derivation for the work center displays (`/display/:workCenterId/*`).
*
* These are wall-mounted screens read from across the shop floor. Each one is a
* work center name in a full-width header band that is either green ("nothing
* needs you") or red ("something does"), over a scoreboard body. The rules that
* decide the colour and fill the scoreboard live here as pure functions: the
* routes stay thin and the thresholds are unit-testable without a database.
*/
import { SCALE } from "@carbon/utils";
import { fromDate, getLocalTimeZone } from "@internationalized/date";
/**
* Sanitize a numeric text input for a bare (non-react-aria) cell: keep digits
* and a single leading decimal point, drop everything else and any extra dots,
* and truncate the fraction to SCALE (5) places — the internal storage
* precision, so a typed value never carries more decimals than the database can
* hold. `decimalInput("1.2.3") === "1.23"`, `decimalInput("1.1234567") === "1.12345"`.
*/
export function decimalInput(value: string): string {
const cleaned = value.replace(/[^0-9.]/g, "");
const dot = cleaned.indexOf(".");
if (dot === -1) return cleaned;
const whole = cleaned.slice(0, dot);
const fraction = cleaned
.slice(dot + 1)
.replace(/\./g, "")
.slice(0, SCALE);
return `${whole}.${fraction}`;
}
export type DisplayStatus = "ok" | "alert";
export type MaintenanceAlertReason =
| "unplanned-downtime"
| "planned-downtime"
| "overdue-maintenance"
| "overdue-schedule";
export type WorkAlertReason = "blocked" | "idle";
export type DisplayState<TReason extends string> = {
status: DisplayStatus;
reasons: TReason[];
};
/** Dispatch statuses that mean the work is not finished yet. */
export const openDispatchStatuses = [
"Open",
"Assigned",
"In Progress"
] as const;
/**
* `maintenanceSource` values that were not planned for. Both a reactive
* breakdown and one raised off a non-conformance are unplanned spend, and both
* count toward the unplanned rows on the maintenance scoreboard.
*/
export const unplannedMaintenanceSources = [
"Reactive",
"Non-Conformance"
] as const;
/** How far out the "due soon" row looks. Matches the reference display. */
export const DUE_SOON_DAYS = 10;
/** Lookback windows for the two unplanned-maintenance rows. */
export const UNPLANNED_COUNT_DAYS = 30;
export const UNPLANNED_COST_DAYS = 90;
export type DisplayDispatch = {
id: string;
maintenanceDispatchId: string | null;
status: string | null;
source: string | null;
oeeImpact: string | null;
plannedStartTime: string | null;
plannedEndTime: string | null;
completedAt: string | null;
createdAt: string | null;
};
export type DisplaySchedule = {
id: string;
name: string | null;
frequency: string | null;
active: boolean | null;
nextDueAt: string | null;
};
function toTime(timestamp: string | null | undefined): number | null {
if (!timestamp) return null;
const parsed = Date.parse(timestamp);
return Number.isNaN(parsed) ? null : parsed;
}
function isPast(timestamp: string | null | undefined, now: Date): boolean {
const parsed = toTime(timestamp);
return parsed !== null && parsed < now.getTime();
}
function isOpen(status: string | null): boolean {
return openDispatchStatuses.includes(
status as (typeof openDispatchStatuses)[number]
);
}
export function isUnplanned(source: string | null): boolean {
return unplannedMaintenanceSources.includes(
source as (typeof unplannedMaintenanceSources)[number]
);
}
/**
* The moment a dispatch is expected to be finished. Dispatches with no planned
* end fall back to the planned start — one nobody started when they said they
* would is equally a problem. Unscheduled reactive work has neither and is
* surfaced by its OEE impact instead.
*/
export function getDispatchDueTime(dispatch: {
plannedEndTime: string | null;
plannedStartTime: string | null;
}): number | null {
return toTime(dispatch.plannedEndTime) ?? toTime(dispatch.plannedStartTime);
}
export function isDispatchOverdue(
dispatch: DisplayDispatch,
now: Date
): boolean {
if (!isOpen(dispatch.status)) return false;
const due = getDispatchDueTime(dispatch);
return due !== null && due < now.getTime();
}
/**
* Red when the work center is down, or when maintenance that was promised has
* not happened. "Due today" and "due soon" stay green and are reported as amber
* rows on the scoreboard — a display that cries wolf gets ignored.
*/
export function getMaintenanceDisplayState(
dispatches: DisplayDispatch[],
schedules: DisplaySchedule[],
now: Date = new Date()
): DisplayState<MaintenanceAlertReason> {
const reasons: MaintenanceAlertReason[] = [];
const inProgress = dispatches.filter((d) => d.status === "In Progress");
if (inProgress.some((d) => d.oeeImpact === "Down")) {
reasons.push("unplanned-downtime");
}
if (inProgress.some((d) => d.oeeImpact === "Planned")) {
reasons.push("planned-downtime");
}
if (dispatches.some((d) => isDispatchOverdue(d, now))) {
reasons.push("overdue-maintenance");
}
if (schedules.some((s) => s.active !== false && isPast(s.nextDueAt, now))) {
reasons.push("overdue-schedule");
}
return { status: reasons.length > 0 ? "alert" : "ok", reasons };
}
/**
* Red when nothing is running. Maintenance blocking the work center is reported
* ahead of plain idleness so the display names the actual cause rather than its
* symptom.
*/
export function getWorkDisplayState(args: {
activeEventCount: number;
isBlocked: boolean;
}): DisplayState<WorkAlertReason> {
const reasons: WorkAlertReason[] = [];
if (args.isBlocked) reasons.push("blocked");
if (args.activeEventCount === 0) reasons.push("idle");
return { status: reasons.length > 0 ? "alert" : "ok", reasons };
}
function startOfDay(now: Date, timeZone: string = getLocalTimeZone()): number {
return fromDate(now, timeZone)
.set({ hour: 0, minute: 0, second: 0, millisecond: 0 })
.toDate()
.getTime();
}
function endOfDay(now: Date, timeZone: string = getLocalTimeZone()): number {
return fromDate(now, timeZone)
.set({ hour: 23, minute: 59, second: 59, millisecond: 999 })
.toDate()
.getTime();
}
function daysAgo(now: Date, days: number): number {
return now.getTime() - days * 24 * 60 * 60 * 1000;
}
export type MaintenanceScoreboard = {
overdue: { count: number; ids: string[] };
dueToday: { count: number };
dueSoon: { count: number; days: number };
downNow: { active: boolean; dispatchId: string | null };
unplannedCount: { count: number; days: number };
unplannedCost: { total: number; days: number };
lastCompleted: { completedAt: string | null; by: string | null };
};
/**
* Everything the maintenance scoreboard renders, computed in one pass so the
* component holds no logic.
*
* Overdue and due-soon counts merge two sources: dispatches that already exist
* (someone has cut the work order) and schedules whose `nextDueAt` has come
* around without one. Counting only dispatches would let a lapsed schedule sit
* invisible; counting only schedules would miss ad-hoc planned work.
*/
export function getMaintenanceScoreboard(args: {
dispatches: DisplayDispatch[];
schedules: DisplaySchedule[];
unplannedCost: number;
lastCompleted: { completedAt: string | null; by: string | null };
now?: Date;
/**
* The work center's location timezone. Day rows ("due today" / "due soon")
* are computed from calendar days in this zone so they match the shop floor
* rather than the server (during SSR) or a mis-set display clock. Falls back
* to the runtime-local day when omitted.
*/
timeZone?: string;
}): MaintenanceScoreboard {
const { dispatches, schedules, unplannedCost, lastCompleted } = args;
const now = args.now ?? new Date();
const todayEnd = endOfDay(now, args.timeZone);
const todayStart = startOfDay(now, args.timeZone);
const soonEnd = now.getTime() + DUE_SOON_DAYS * 24 * 60 * 60 * 1000;
const openDispatches = dispatches.filter((d) => isOpen(d.status));
const activeSchedules = schedules.filter((s) => s.active !== false);
const overdueDispatches = openDispatches.filter((d) =>
isDispatchOverdue(d, now)
);
const overdueSchedules = activeSchedules.filter((s) =>
isPast(s.nextDueAt, now)
);
const dueBetween = (from: number, to: number) => {
const d = openDispatches.filter((dispatch) => {
const due = getDispatchDueTime(dispatch);
return due !== null && due >= from && due <= to;
}).length;
const s = activeSchedules.filter((schedule) => {
const due = toTime(schedule.nextDueAt);
return due !== null && due >= from && due <= to;
}).length;
return d + s;
};
const down = dispatches.find(
(d) =>
d.status === "In Progress" &&
(d.oeeImpact === "Down" || d.oeeImpact === "Planned")
);
const unplannedSince = daysAgo(now, UNPLANNED_COUNT_DAYS);
const unplannedCount = dispatches.filter((d) => {
if (!isUnplanned(d.source)) return false;
const at = toTime(d.createdAt);
return at !== null && at >= unplannedSince;
}).length;
return {
overdue: {
count: overdueDispatches.length + overdueSchedules.length,
ids: overdueDispatches
.map((d) => d.maintenanceDispatchId)
.filter((id): id is string => Boolean(id))
},
// "Due today" excludes anything already overdue — those have their own row,
// and double-counting would make the board read worse than reality.
dueToday: {
count: dueBetween(Math.max(todayStart, now.getTime()), todayEnd)
},
dueSoon: { count: dueBetween(todayEnd, soonEnd), days: DUE_SOON_DAYS },
downNow: {
active: Boolean(down),
dispatchId: down?.maintenanceDispatchId ?? null
},
unplannedCount: { count: unplannedCount, days: UNPLANNED_COUNT_DAYS },
unplannedCost: { total: unplannedCost, days: UNPLANNED_COST_DAYS },
lastCompleted
};
}
/**
* Elapsed time as zero-padded `HH:MM:SS`. Wall displays tick every second, so
* the digits must not reflow — the eye reads position, not text.
*/
export function formatElapsed(
startTime: string,
now: Date = new Date()
): string {
const started = toTime(startTime);
if (started === null) return "--:--:--";
const totalSeconds = Math.max(
0,
Math.floor((now.getTime() - started) / 1000)
);
const hours = Math.floor(totalSeconds / 3600);
const minutes = Math.floor((totalSeconds % 3600) / 60);
const seconds = totalSeconds % 60;
return [hours, minutes, seconds]
.map((part) => String(part).padStart(2, "0"))
.join(":");
}
/**
* Coarse "when" label for scheduled work. Deliberately low precision: at
* reading distance "in 3d" beats a timestamp.
*/
export function formatRelativeDue(
timestamp: string | null,
now: Date = new Date()
): string | null {
const due = toTime(timestamp);
if (due === null) return null;
const diffMs = due - now.getTime();
const overdue = diffMs < 0;
const minutes = Math.floor(Math.abs(diffMs) / 60000);
if (minutes < 1) return "now";
const value = (() => {
if (minutes < 60) return `${minutes}m`;
const hours = Math.floor(minutes / 60);
if (hours < 24) return `${hours}h`;
const days = Math.floor(hours / 24);
if (days < 14) return `${days}d`;
return `${Math.floor(days / 7)}w`;
})();
return overdue ? `${value} overdue` : `in ${value}`;
}
/** Initials for the "By?" cell — a wall display has room for two characters. */
export function getInitials(fullName: string | null): string | null {
if (!fullName) return null;
const parts = fullName.trim().split(/\s+/).filter(Boolean);
if (parts.length === 0) return null;
const first = parts[0][0];
const last = parts.length > 1 ? parts[parts.length - 1][0] : "";
return `${first}${last}`.toUpperCase();
}
/** Completion ratio clamped to 0–1, guarding the zero-quantity operation. */
export function getProgress(
quantityComplete: number | null | undefined,
operationQuantity: number | null | undefined
): number | null {
if (!operationQuantity || operationQuantity <= 0) return null;
return Math.min(1, Math.max(0, (quantityComplete ?? 0) / operationQuantity));
}