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.
import type { PostgrestError } from "@supabase/supabase-js";
import { z } from "zod";
import { zfd } from "zod-form-data";
import { nonConformancePriority } from "../quality/quality.models";
import {
methodItemType,
methodOperationOrders,
methodType,
operationTypes,
sourcingType,
standardFactorType
} from "../shared/shared.models";
export const batchPropertyDataTypes = [
"text",
"numeric",
"boolean",
"list",
"date"
] as const;
export const configurationParameterDataTypes = [
"text",
"numeric",
"boolean",
"list",
"material"
] as const;
export const itemTrackingTypes = [
"Inventory",
"Non-Inventory",
"Serial",
"Batch"
] as const;
export const ItemTrackingType = {
Inventory: "Inventory",
NonInventory: "Non-Inventory",
Serial: "Serial",
Batch: "Batch"
} as const satisfies Record<string, (typeof itemTrackingTypes)[number]>;
export const itemCostingMethods = [
"Standard",
"Average",
"FIFO",
"LIFO"
] as const;
export const itemReorderingPolicies = [
"Manual Reorder",
"Demand-Based Reorder",
"Fixed Reorder Quantity",
"Maximum Quantity"
] as const;
export const itemReplenishmentSystems = [
"Buy",
"Make",
"Buy and Make"
] as const;
/** The fields the item tables' bulk Update sets on many items at once. */
export const itemBulkUpdateFields = [
"itemPostingGroupId",
"replenishmentSystem",
"defaultMethodType",
"sourcingType",
"itemTrackingType"
] as const;
export type ItemBulkUpdateField = (typeof itemBulkUpdateFields)[number];
export function isItemBulkUpdateField(
field: unknown
): field is ItemBulkUpdateField {
return itemBulkUpdateFields.some((allowed) => allowed === field);
}
/** One field set on many items (the items tables' Update): the field and a
* value it takes. Any item group id, or none, is a value. */
export const itemBulkUpdateValidator = z.discriminatedUnion("field", [
z.object({
field: z.literal("itemTrackingType"),
value: z.enum(itemTrackingTypes)
}),
z.object({
field: z.literal("replenishmentSystem"),
value: z.enum(itemReplenishmentSystems)
}),
z.object({
field: z.literal("defaultMethodType"),
value: z.enum(methodType)
}),
z.object({ field: z.literal("sourcingType"), value: z.enum(sourcingType) }),
z.object({ field: z.literal("itemPostingGroupId"), value: z.string() })
]);
export type ItemBulkUpdate = z.infer<typeof itemBulkUpdateValidator>;
// Maps an edit of ONE of the three interlocked item-level fields
// (replenishmentSystem, defaultMethodType, sourcingType) to the columns that must
// change together on the item, plus the values to mirror down to method materials.
// Pure — no DB access — so the interlock rule lives in ONE place, shared by the
// inline item-update route (x+/items+/update.tsx) and the change-order attributes
// editor. Keeping them in sync via a hand-copied mapping is exactly the drift this
// avoids.
export function deriveItemMethodUpdate(
field: "replenishmentSystem" | "defaultMethodType" | "sourcingType",
value: string
): {
itemUpdate: {
replenishmentSystem?: (typeof itemReplenishmentSystems)[number];
defaultMethodType?: (typeof methodType)[number];
sourcingType?: (typeof sourcingType)[number];
};
cascade: {
sourcingType?: (typeof sourcingType)[number];
methodType?: (typeof methodType)[number];
};
} {
switch (field) {
case "replenishmentSystem": {
const replenishmentSystem =
value as (typeof itemReplenishmentSystems)[number];
// Picking a concrete replenishment system pins the default method type.
if (value !== "Buy and Make") {
const defaultMethodType: (typeof methodType)[number] =
value === "Make"
? "Make to Order"
: value === "Buy"
? "Purchase to Order"
: "Pull from Inventory";
return {
itemUpdate: { replenishmentSystem, defaultMethodType },
cascade: { methodType: defaultMethodType }
};
}
return { itemUpdate: { replenishmentSystem }, cascade: {} };
}
case "defaultMethodType": {
const defaultMethodType = value as (typeof methodType)[number];
// A concrete method type pins the replenishment system to match.
if (value !== "Pull from Inventory") {
const replenishmentSystem: (typeof itemReplenishmentSystems)[number] =
value === "Make to Order"
? "Make"
: value === "Purchase to Order"
? "Buy"
: "Buy and Make";
return {
itemUpdate: { defaultMethodType, replenishmentSystem },
cascade: { methodType: defaultMethodType }
};
}
return {
itemUpdate: { defaultMethodType },
cascade: { methodType: defaultMethodType }
};
}
case "sourcingType": {
const sourcingTypeValue = value as (typeof sourcingType)[number];
// Sourcing drives method type: Drop Ship → Purchase to Order, Ship from
// Inventory → Pull from Inventory, Specified → leave method type as-is.
const derivedMethodType: (typeof methodType)[number] | undefined =
value === "Drop Ship"
? "Purchase to Order"
: value === "Ship from Inventory"
? "Pull from Inventory"
: undefined;
return {
itemUpdate: {
sourcingType: sourcingTypeValue,
...(derivedMethodType ? { defaultMethodType: derivedMethodType } : {})
},
cascade: {
sourcingType: sourcingTypeValue,
methodType: derivedMethodType
}
};
}
}
}
export const shelfLifeModes = [
"NotManaged",
"Fixed Duration",
"Calculated",
"Set on Receipt"
] as const;
export const shelfLifeTriggerTimings = ["Before", "After"] as const;
export const partManufacturingPolicies = [
"Make to Stock",
"Make to Order"
] as const;
// Services are Buy or Make only — never "Buy and Make", and never stocked
// ("Pull from Inventory" is not a valid method for a Non-Inventory item).
export const serviceReplenishmentSystems = ["Buy", "Make"] as const;
export const supplierPartPriceSourceTypes = [
"Quote",
"Purchase Order",
"Manual Entry"
] as const;
export const itemValidator = z.object({
id: z.string().min(1, { message: "Item ID is required" }).max(255),
readableId: zfd.text(z.string().optional()),
name: z
.string()
.min(1, { message: "Short description is required" })
.max(255),
description: zfd.text(z.string().optional()),
// Manufacturer Part Number — the manufacturer's catalog number for a
// purchased item. Only surfaced/edited for Buy items in the Properties panel.
mpn: zfd.text(z.string().optional()),
replenishmentSystem: z.enum(itemReplenishmentSystems, {
error: "Replenishment system is required"
}),
defaultMethodType: z.enum(methodType, {
error: "Default method is required"
}),
itemTrackingType: z.enum(itemTrackingTypes, {
error: "Part type is required"
}),
postingGroupId: zfd.text(z.string().optional()),
unitOfMeasureCode: z
.string()
.min(1, { message: "Unit of Measure is required" }),
unitCost: zfd.numeric(z.number().nonnegative().optional()),
// Default storage unit (form-only; persisted to pickMethod via
// upsertItemDefaultPickMethod). Can point at any level of the
// storageUnit hierarchy since storageUnit nests via parentId. The
// locationId is derived server-side from storageUnit.locationId -
// the form itself does not capture a location.
defaultStorageUnitId: zfd.text(z.string().optional()),
// Shelf life. The UI Select only surfaces "Fixed Duration" / "Calculated";
// clearing it (X button) submits an empty string, which we preprocess to
// the sentinel "NotManaged" so the server deletes any existing
// itemShelfLife row. Truly absent fields (non-form callers like MCP that
// don't set shelfLifeMode at all) remain undefined, which the upsert
// helper treats as a no-op.
shelfLifeMode: z
.union([z.literal(""), z.enum(shelfLifeModes)])
.transform((v) => (v === "" ? "NotManaged" : v))
.optional(),
shelfLifeDays: zfd.numeric(z.number().positive().optional()),
shelfLifeTriggerProcessId: zfd.text(z.string().optional()),
// Whether the clock starts when the trigger process begins ('Before') or
// completes ('After'). Only meaningful with Fixed Duration + a trigger
// process; ignored otherwise. Defaults to 'After' to preserve legacy
// behavior on items that pre-date this column.
shelfLifeTriggerTiming: z.enum(shelfLifeTriggerTimings).optional(),
// Fixed Duration + Make items only: when true, the produced expiry is
// capped by the earliest input expiry — the output cannot outlast its
// raw materials. Falls back to today + days when no input has a date.
// Mirrors the inventory-settings "Calculate from BOM" copy.
shelfLifeCalculateFromBom: zfd.checkbox()
});
// Common storage / shelf-life refines. Shared across all item-type
// validators. Default Storage Unit is optional for every type - users can
// set it later via the pickMethod UI once they know where the item lives.
export const applyStorageAndShelfLifeRefines = <T extends z.ZodObject>(
schema: T
) => {
const refined: z.ZodType<z.infer<T>, z.input<T>> = schema
.refine(
(data: z.infer<T>) =>
data.shelfLifeDays === undefined ||
data.shelfLifeMode === "Fixed Duration",
{
message:
"Shelf-life days can only be set when shelf-life management is Fixed Duration",
path: ["shelfLifeDays"]
}
)
.refine(
(data: z.infer<T>) =>
data.shelfLifeMode !== "Fixed Duration" ||
data.shelfLifeDays !== undefined,
{
message:
"Shelf-life days is required when shelf-life management is Fixed Duration",
path: ["shelfLifeDays"]
}
)
.refine(
(data: z.infer<T>) =>
!data.shelfLifeTriggerProcessId ||
data.shelfLifeMode === "Fixed Duration",
{
message:
"Trigger process can only be set when shelf-life management is Fixed Duration",
path: ["shelfLifeTriggerProcessId"]
}
)
.refine(
(data: z.infer<T>) =>
!data.shelfLifeMode ||
data.shelfLifeMode === "NotManaged" ||
data.itemTrackingType === "Serial" ||
data.itemTrackingType === "Batch",
{
message:
"Shelf-life can only be managed on items tracked by Serial or Batch - there's no per-unit record to set the expiry on otherwise",
path: ["shelfLifeMode"]
}
)
.refine(
(data: z.infer<T>) =>
data.shelfLifeMode !== "Calculated" ||
data.replenishmentSystem !== "Buy",
{
message:
"Component minimum shelf-life requires a BoM - only Make or Buy and Make items qualify",
path: ["shelfLifeMode"]
}
)
.refine(
(data: z.infer<T>) =>
data.shelfLifeMode !== "Set on Receipt" ||
data.replenishmentSystem !== "Make",
{
message:
"Set on receipt applies at goods-in - only Buy or Buy and Make items qualify",
path: ["shelfLifeMode"]
}
)
.refine(
(data: z.infer<T>) =>
!data.shelfLifeCalculateFromBom ||
data.shelfLifeMode === "Fixed Duration",
{
message: "Calculate from BOM only applies to Fixed Duration shelf life",
path: ["shelfLifeCalculateFromBom"]
}
)
.refine(
(data: z.infer<T>) =>
!data.shelfLifeCalculateFromBom || data.replenishmentSystem !== "Buy",
{
message:
"Calculate from BOM requires a BoM - only Make or Buy and Make items qualify",
path: ["shelfLifeCalculateFromBom"]
}
) as unknown as z.ZodType<z.infer<T>, z.input<T>>;
return refined;
};
export const configurationParameterGroupValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" })
});
export const configurationParameterGroupOrderValidator = z.object({
id: z.string().min(1, { message: "ID is required" }),
sortOrder: zfd.numeric(z.number().min(0))
});
export const configurationParameterOrderValidator = z.object({
id: z.string().min(1, { message: "ID is required" }),
sortOrder: zfd.numeric(z.number().min(0)),
configurationParameterGroupId: zfd.text(z.string().nullable())
});
export const configurationParameterValidator = z
.object({
id: zfd.text(z.string().optional()),
itemId: z.string().min(1, { message: "Item ID is required" }),
key: zfd.text(z.string().optional()),
label: z.string().min(1, { message: "Label is required" }),
dataType: z.enum([...configurationParameterDataTypes, "date"]),
listOptions: z.string().min(1).array().optional(),
configurationParameterGroupId: z.string().optional(),
materialFormFilterId: zfd.text(z.string().optional())
})
.refine(
(data) => {
if (data.dataType === "list") {
return !!data.listOptions;
}
return true;
},
{ message: "List options are required", path: ["listOptions"] }
)
.refine(
(data) => {
return data.key?.match(/^[a-zA-Z0-9]+(_[a-zA-Z0-9]+)*$/);
},
{ message: "Key must be lowercase and underscore separated" }
);
export const configurationRuleValidator = z.object({
field: z.string().min(1, { message: "Field is required" }),
code: z.string().min(1, { message: "Code is required" })
});
export const consumableValidator = applyStorageAndShelfLifeRefines(
itemValidator.merge(
z.object({
id: z.string().min(1, { message: "Consumable ID is required" }).max(255),
unitOfMeasureCode: z
.string()
.min(1, { message: "Unit of Measure is required" })
})
)
);
export const customerPartValidator = z.object({
id: zfd.text(z.string().optional()),
itemId: z.string().min(1, { message: "Item ID is required" }),
customerId: z.string().min(1, { message: "Customer is required" }),
customerPartId: z.string(),
customerPartRevision: zfd.text(z.string().optional())
});
export const getMethodValidator = z.object({
targetId: z.string().min(1, { message: "Please select a target method" }),
sourceId: z.string().min(1, { message: "Please select a source method" }),
billOfMaterial: zfd.checkbox(),
billOfProcess: zfd.checkbox(),
parameters: zfd.checkbox(),
tools: zfd.checkbox(),
steps: zfd.checkbox(),
workInstructions: zfd.checkbox()
});
export const makeMethodVersionValidator = z.object({
copyFromId: z.string().min(1, { message: "Please select a source method" }),
activeVersionId: zfd.text(z.string().optional()),
version: zfd.numeric(z.number().min(0, { message: "Please enter a version" }))
});
export const materialValidator = applyStorageAndShelfLifeRefines(
itemValidator.merge(
z.object({
id: z.string().min(1, { message: "Material ID is required" }).max(255),
materialSubstanceId: zfd.text(z.string().optional()),
materialFormId: zfd.text(z.string().optional()),
materialTypeId: zfd.text(z.string().optional()),
finishId: zfd.text(z.string().optional()),
gradeId: zfd.text(z.string().optional()),
dimensionId: zfd.text(z.string().optional()),
sizes: z.array(z.string()).optional()
})
)
);
export const materialValidatorWithGeneratedIds = z.object({
id: z.string().min(1, { message: "" }),
materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
materialFormId: z.string().min(1, { message: "Shape is required" }),
materialTypeId: zfd.text(z.string().optional()),
finishId: zfd.text(z.string().optional()),
gradeId: zfd.text(z.string().optional()),
dimensionId: zfd.text(z.string().optional()),
sizes: z.array(z.string()).optional()
});
export const methodMaterialValidator = z.object({
id: z.string().trim().min(1, { message: "Material ID is required" }),
makeMethodId: z.string().min(1, { message: "Make method is required" }),
order: zfd.numeric(z.number().min(0)),
itemType: z.enum(methodItemType, {
error: "Item type is required"
}),
kit: zfd.text(z.string().optional()).transform((value) => value === "true"),
methodType: z.enum(methodType, {
error: "Method type is required"
}),
sourcingType: z.enum(sourcingType, {
error: "Sourcing type is required"
}),
itemId: z.string().optional(),
methodOperationId: zfd.text(z.string().optional()),
// description: z.string().min(1, { message: "Description is required" }),
quantity: zfd.numeric(z.number().min(0)),
unitOfMeasureCode: z
.string()
.min(1, { message: "Unit of Measure is required" }),
// A location → storageUnitId map. The BoM web form submits it as a JSON string
// (`<Hidden value={JSON.stringify(...)} />`); the MCP/API layer sends the object
// map directly. `preprocess` accepts both — a string is JSON-parsed (a malformed
// string stays a string and is REJECTED by the record below, never silently
// stored) — and the input JSON Schema published to MCP is a clean object map.
// `nullish` lets a caller omit it or send `null` to clear (the service applies
// the create/update semantics: omitted → preserve on update / {} on create,
// explicit null/{} → clear).
storageUnitIds: z
.preprocess(
(val) => {
if (typeof val !== "string") return val;
try {
return JSON.parse(val);
} catch {
return val;
}
},
z.record(z.string(), z.string())
)
.nullish()
});
export const methodOperationValidator = z
.object({
id: z.string().min(1, { message: "Operation ID is required" }),
makeMethodId: z.string().min(0, { message: "Make method is required" }),
order: zfd.numeric(z.number().min(0)),
operationOrder: z.enum(methodOperationOrders, {
error: "Operation order is required"
}),
operationType: z.enum(operationTypes, {
error: "Operation type is required"
}),
processId: z.string().min(1, { message: "Process is required" }),
workCenterId: zfd.text(z.string().optional()),
procedureId: zfd.text(z.string().optional()),
assemblyInstructionId: zfd.text(z.string().optional()),
inspectionDocumentId: zfd.text(z.string().optional()),
description: zfd.text(
z.string().min(0, { message: "Description is required" })
),
setupUnit: z
.enum(standardFactorType, {
error: "Setup unit is required"
})
.optional(),
setupTime: zfd.numeric(z.number().min(0).optional()),
laborUnit: z
.enum(standardFactorType, {
error: "Labor unit is required"
})
.optional(),
laborTime: zfd.numeric(z.number().min(0).optional()),
machineUnit: z
.enum(standardFactorType, {
error: "Machine unit is required"
})
.optional(),
machineTime: zfd.numeric(z.number().min(0).optional()),
operationSupplierProcessId: zfd.text(z.string().optional()),
operationMinimumCost: zfd.numeric(z.number().min(0).optional()),
operationUnitCost: zfd.numeric(z.number().min(0).optional()),
operationLeadTime: zfd.numeric(z.number().min(0).optional())
})
.refine(
(data) => {
if (data.operationType !== "Outside Processing") {
return !!data.setupUnit;
}
return true;
},
{
message: "Setup unit is required",
path: ["setupUnit"]
}
)
.refine(
(data) => {
if (data.operationType !== "Outside Processing") {
return !!data.laborUnit;
}
return true;
},
{
message: "Labor unit is required",
path: ["laborUnit"]
}
)
.refine(
(data) => {
// Machine only applies to Process operations — Assembly and Inspection
// are setup + labor work.
if (data.operationType === "Process") {
return !!data.machineUnit;
}
return true;
},
{
message: "Machine unit is required",
path: ["machineUnit"]
}
)
.refine(
(data) => {
if (data.operationType !== "Outside Processing") {
return Number.isFinite(data.setupTime);
}
return true;
},
{
message: "Setup time is required",
path: ["setupTime"]
}
)
.refine(
(data) => {
if (data.operationType !== "Outside Processing") {
return Number.isFinite(data.laborTime);
}
return true;
},
{
message: "Labor time is required",
path: ["laborTime"]
}
)
.refine(
(data) => {
if (data.operationType === "Process") {
return Number.isFinite(data.machineTime);
}
return true;
},
{
message: "Machine time is required",
path: ["machineTime"]
}
)
.refine(
(data) => {
if (data.operationType === "Inspection") {
return !!data.inspectionDocumentId;
}
return true;
},
{
message: "Inspection Plan is required",
path: ["inspectionDocumentId"]
}
);
export const itemCostValidator = z.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
itemPostingGroupId: zfd.text(z.string().optional()),
costingMethod: z.enum(itemCostingMethods, {
error: "Costing method is required"
}),
// standardCost: zfd.numeric(z.number().min(0)),
unitCost: zfd.numeric(z.number().min(0))
// costIsAdjusted: zfd.checkbox(),
});
export const itemManufacturingValidator = z.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
// manufacturingBlocked: zfd.checkbox(),
requiresConfiguration: zfd.checkbox().optional(),
lotSize: zfd.numeric(z.number().min(0)),
scrapPercentage: zfd.numeric(z.number().min(0)),
leadTime: zfd.numeric(z.number().min(0))
});
export const itemPostingGroupValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }).max(255),
description: z.string().optional()
});
export const itemPlanningValidator = z
.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
locationId: z.string().min(1, { message: "Location is required" }),
reorderingPolicy: z.enum(itemReorderingPolicies, {
error: "Reordering policy is required"
}),
demandAccumulationPeriod: zfd.numeric(z.number().min(1).optional()),
demandAccumulationSafetyStock: zfd.numeric(z.number().min(0).optional()),
reorderPoint: zfd.numeric(z.number().min(0).optional()).optional(),
reorderQuantity: zfd.numeric(z.number().min(0)).optional(),
maximumInventoryQuantity: zfd.numeric(z.number().min(0)).optional(),
minimumOrderQuantity: zfd.numeric(z.number().min(0)).optional(),
maximumOrderQuantity: zfd.numeric(z.number().min(0)).optional(),
orderMultiple: zfd.numeric(z.number().min(1)).optional(),
// The planning horizon (time fence) in days from today: the planning grids
// surface only the actions and suggested orders that fall inside it. Empty
// = inherit the company default, else no fence; 0 = no fence for this item
// even when the company has a default.
planningHorizonDays: zfd.numeric(z.number().int().min(0).optional()),
// the ownership ladder's leaf override (spec §P1.3): this item at this
// location; empty = inherit item group → location → company default
responsibleEmployee: zfd.text(z.string().optional())
// critical: zfd.checkbox(),
})
.refine(
(data) => {
if (data.reorderingPolicy === "Maximum Quantity") {
return (
data.maximumInventoryQuantity &&
data.reorderPoint &&
data.maximumInventoryQuantity > data.reorderPoint
);
}
return true;
},
{
message: "Maximum inventory quantity must be greater than reorder point",
path: ["maximumInventoryQuantity"]
}
)
.refine(
(data) => {
if (data.reorderingPolicy === "Fixed Reorder Quantity") {
return data.reorderQuantity && data.reorderQuantity > 0;
}
return true;
},
{
message: "Reorder quantity must be greater than 0",
path: ["reorderQuantity"]
}
);
export const supersessionModes = [
"Consume First",
"Prefer New",
"Stock Only",
"No Stock"
] as const;
export type SupersessionMode = (typeof supersessionModes)[number];
// Single source of truth for how each supersession mode is presented — the same
// color + description is reused everywhere the mode shows up (the item
// supersession picker, the item lifecycle badge, and the change-order cutover),
// so they never drift.
export const supersessionModeMeta: Record<
SupersessionMode,
{ color: "green" | "blue" | "orange" | "red"; description: string }
> = {
"Consume First": {
color: "green",
description: "Use remaining stock before switching to the successor"
},
"Prefer New": {
color: "blue",
description:
"Plan and build with the successor; picking falls back to the old part only while the successor is out of stock"
},
"Stock Only": {
color: "orange",
description: "Hold a minimum reserve for service; no production use"
},
"No Stock": {
color: "red",
description: "Fully obsolete — do not plan or stock"
}
};
export const itemSupersessionValidator = z
.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
// Absent mode = no supersession; saving without a mode clears it.
supersessionMode: zfd.text(z.enum(supersessionModes).optional()),
successorItemId: zfd.text(z.string().optional()),
discontinuationDate: zfd.text(z.string().optional()),
successorEffectivityDate: zfd.text(z.string().optional()),
// How many of the successor replace one old part (1 old = N new).
conversionFactor: zfd.numeric(z.number().positive().optional()),
// The minimum service-stock floor is per-location (stored on itemPlanning).
locationId: zfd.text(z.string().optional()),
minimumReserveQuantity: zfd.numeric(z.number().min(0).optional())
})
.refine(
(data) =>
data.supersessionMode && data.supersessionMode !== "Consume First"
? !!data.discontinuationDate
: true,
{
message: "Discontinuation date is required",
path: ["discontinuationDate"]
}
)
.refine(
(data) =>
data.supersessionMode && data.supersessionMode !== "No Stock"
? !!data.successorItemId
: true,
{
message: "Successor part is required",
path: ["successorItemId"]
}
)
.refine((data) => data.successorItemId !== data.itemId, {
message: "A part cannot be its own successor",
path: ["successorItemId"]
})
.refine(
(data) =>
data.successorEffectivityDate && data.discontinuationDate
? data.successorEffectivityDate >= data.discontinuationDate
: true,
{
message:
"Successor effectivity date must be on or after the discontinuation date",
path: ["successorEffectivityDate"]
}
);
export const predecessorSupersessionValidator = z
.object({
predecessorItemId: z.string().min(1, { message: "Part is required" }),
supersessionMode: z.enum(supersessionModes),
discontinuationDate: zfd.text(z.string().optional()),
successorEffectivityDate: zfd.text(z.string().optional()),
conversionFactor: zfd.numeric(z.number().positive().optional())
})
.refine((data) => data.supersessionMode !== "No Stock", {
message: "No Stock has no successor; set it on the part itself",
path: ["supersessionMode"]
})
.refine(
(data) =>
data.supersessionMode !== "Consume First"
? !!data.discontinuationDate
: true,
{
message: "Discontinuation date is required",
path: ["discontinuationDate"]
}
)
.refine(
(data) =>
data.successorEffectivityDate && data.discontinuationDate
? data.successorEffectivityDate >= data.discontinuationDate
: true,
{
message:
"Successor effectivity date must be on or after the discontinuation date",
path: ["successorEffectivityDate"]
}
);
export const itemPurchasingValidator = z.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
preferredSupplierId: zfd.text(z.string().optional()),
conversionFactor: zfd.numeric(z.number().min(0)),
leadTime: zfd.numeric(z.number().min(0)),
purchasingUnitOfMeasureCode: zfd.text(z.string().optional())
// purchasingBlocked: zfd.checkbox(),
});
export const itemUnitSalePriceValidator = z.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
unitSalePrice: zfd.numeric(z.number().min(0))
// currencyCode: z.string().min(1, { message: "Currency is required" }),
// salesUnitOfMeasureCode: z
// .string()
// .min(1, { message: "Unit of Measure is required" }),
// salesBlocked: zfd.checkbox(),
// priceIncludesTax: zfd.checkbox(),
// allowInvoiceDiscount: zfd.checkbox(),
});
export const materialDimensionValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }).max(255),
materialFormId: z.string().min(1, { message: "Shape is required" })
});
export const materialFinishValidator = z.object({
id: zfd.text(z.string().optional()),
materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
name: z.string().trim().min(1, { message: "Name is required" }).max(255)
});
export const materialFormValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }).max(255),
code: z.string().trim().min(1, { message: "Code is required" }).max(10)
});
export const materialGradeValidator = z.object({
id: zfd.text(z.string().optional()),
materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
name: z.string().trim().min(1, { message: "Name is required" }).max(255)
});
export const materialSubstanceValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }).max(255),
code: z.string().trim().min(1, { message: "Code is required" }).max(10)
});
export const materialTypeValidator = z.object({
id: zfd.text(z.string().optional()),
materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
materialFormId: z.string().min(1, { message: "Shape is required" }),
name: z.string().trim().min(1, { message: "Name is required" }).max(255),
code: z.string().trim().min(1, { message: "Code is required" }).max(10)
});
/** A part's fields before the storage and shelf-life rules (`partValidator`). */
export const partFields = itemValidator.merge(
z.object({
id: z.string().min(1, { message: "Part ID is required" }).max(255),
revision: z.string().min(1, { message: "Revision is required" }),
modelUploadId: zfd.text(z.string().optional()),
lotSize: zfd.numeric(z.number().min(0).optional())
})
);
export const partValidator = applyStorageAndShelfLifeRefines(partFields);
// Tracked-entity pick order surfaced on the item's per-location Inventory
// card. 'Default' = the picker's smart order (expiring soonest, then oldest).
// Mirrors "pickMethodSortMethod" Postgres enum.
export const pickMethodSortMethods = [
"Default",
"FEFO",
"FIFO",
"LIFO"
] as const;
export const pickMethodValidator = z.object({
itemId: z.string().min(1, { message: "Item ID is required" }),
locationId: z.string().min(1, { message: "Location is required" }),
defaultStorageUnitId: zfd.text(z.string().optional()),
sortMethod: z.enum(pickMethodSortMethods).optional()
});
// pickMethod form + shelf-life policy in one submit. Shelf-life itself is
// item-level (stored on itemShelfLife keyed by itemId), not per-location,
// but we surface the controls on the per-location "Inventory" card so
// users editing the item's stocking defaults can also manage its shelf-
// life policy without navigating elsewhere. The server-side action is
// responsible for routing each subset of fields to its own upsert helper.
//
// Note: this validator does NOT reference itemTrackingType (pickMethod
// doesn't carry it). The UI gates visibility of the shelf-life fields on
// tracking type via a prop, and the itemValidator chain already enforces
// the Serial-or-Batch prerequisite at item creation. If a caller somehow
// posts shelfLifeMode on an item without Serial/Batch tracking, the
// itemShelfLife table's CHECK constraints still stand - but it's easier
// UX to not render the fields at all in that case.
export const pickMethodWithShelfLifeValidator = pickMethodValidator
.merge(
z.object({
shelfLifeMode: z.preprocess(
(v) => (v === "" ? "NotManaged" : v),
z.enum(shelfLifeModes).optional()
),
shelfLifeDays: zfd.numeric(z.number().positive().optional()),
shelfLifeTriggerProcessId: zfd.text(z.string().optional()),
shelfLifeTriggerTiming: z.enum(shelfLifeTriggerTimings).optional(),
shelfLifeCalculateFromBom: zfd.checkbox()
})
)
.refine(
(data) =>
data.shelfLifeDays === undefined ||
data.shelfLifeMode === "Fixed Duration",
{
message:
"Shelf-life days can only be set when shelf-life management is Fixed Duration",
path: ["shelfLifeDays"]
}
)
.refine(
(data) =>
data.shelfLifeMode !== "Fixed Duration" ||
data.shelfLifeDays !== undefined,
{
message:
"Shelf-life days is required when shelf-life management is Fixed Duration",
path: ["shelfLifeDays"]
}
)
.refine(
(data) =>
!data.shelfLifeTriggerProcessId ||
data.shelfLifeMode === "Fixed Duration",
{
message:
"Trigger process can only be set when shelf-life management is Fixed Duration",
path: ["shelfLifeTriggerProcessId"]
}
)
.refine(
(data) =>
!data.shelfLifeCalculateFromBom ||
data.shelfLifeMode === "Fixed Duration",
{
message: "Calculate from BOM only applies to Fixed Duration shelf life",
path: ["shelfLifeCalculateFromBom"]
}
);
export const revisionValidator = z
.object({
id: zfd.text(z.string().optional()),
type: z.enum(["Part", "Material", "Tool", "Consumable", "Service"]),
copyFromId: zfd.text(z.string().optional()),
revision: z.string().min(1, { message: "Revision is required" })
})
.refine(
(data) => {
return data.id || data.copyFromId;
},
{ message: "Revision or copy from is required" }
);
export const SERVICE_NAME_MAX_LENGTH = 100;
/**
* The built-in "Each" unit of measure. Every company has it and the database
* refuses to rename, deactivate or delete it; a service is always counted in it.
*/
export const EACH_UNIT_OF_MEASURE_CODE = "EA";
export const serviceValidator = applyStorageAndShelfLifeRefines(
itemValidator.merge(
z.object({
// A service is identified by its name: it is the readable id, so
// neither an id nor a revision is asked for. `id` is only the key of the
// service to update.
id: zfd.text(z.string().max(255).optional()),
name: z
.string()
.trim()
.min(1, { message: "Name is required" })
.max(SERVICE_NAME_MAX_LENGTH),
revision: zfd.text(z.string().optional()),
// Ignored: a service is always counted in Each (EA).
unitOfMeasureCode: zfd.text(z.string().optional()),
replenishmentSystem: z.enum(serviceReplenishmentSystems, {
error: "Replenishment system is required"
}),
// Services can never be shipped, received, or stocked
itemTrackingType: z.literal("Non-Inventory")
})
)
);
export const supplierPartValidator = z.object({
id: zfd.text(z.string().optional()),
itemId: z.string().min(1, { message: "Item ID is required" }),
supplierId: z.string().min(1, { message: "Supplier ID is required" }),
supplierPartId: z.string().optional(),
supplierUnitOfMeasureCode: zfd.text(z.string().optional()),
minimumOrderQuantity: zfd.numeric(z.number().min(0)),
orderMultiple: zfd.numeric(z.number().min(1)).optional(),
conversionFactor: zfd.numeric(z.number().min(0)),
// Per purchase unit, in currencyCode — the price as the supplier quoted it.
currencyCode: zfd.text(z.string().optional()),
supplierUnitPrice: zfd.numeric(z.number().min(0).optional())
});
/** A supplier part's price breaks, per purchase unit in its currency. */
export const supplierPartPriceBreaksValidator = z.array(
z.object({
quantity: z.number(),
supplierUnitPrice: z.number(),
leadTime: z.number().optional()
})
);
/** The supplier part drawer's post: the part, and its price breaks as JSON. */
export const supplierPartFormValidator = supplierPartValidator.extend({
priceBreaks: zfd.json(supplierPartPriceBreaksValidator.optional())
});
/** A tool's fields before the storage and shelf-life rules (`toolValidator`). */
export const toolFields = itemValidator.merge(
z.object({
id: z.string().min(1, { message: "Tool ID is required" }).max(255),
revision: z.string().min(1, { message: "Revision is required" }),
modelUploadId: zfd.text(z.string().optional()),
unitOfMeasureCode: z
.string()
.min(1, { message: "Unit of Measure is required" }),
lotSize: zfd.numeric(z.number().min(0).optional())
})
);
export const toolValidator = applyStorageAndShelfLifeRefines(toolFields);
export const unitOfMeasureValidator = z.object({
id: zfd.text(z.string().optional()),
code: z.string().trim().min(1, { message: "Code is required" }).max(10),
name: z.string().trim().min(1, { message: "Name is required" }).max(50)
});
export const itemRevisionStatus = [
"Design",
"Prototype",
"Production",
"Obsolete"
] as const;
// companySettings.plmReleaseControl
export const plmReleaseControl = ["off", "warn", "enforce"] as const;
// Error shape returned by the change notice service functions: either a real
// Supabase PostgrestError or a hand-built message (sequence/lookup failures that
// don't originate from a query). One alias so callers get a consistent contract.
export type ChangeNoticeError = PostgrestError | { message: string };
// =============================================================================
// Change Notices — validators, enums, and the stage state machine.
//
// A sub-area of the Items module, modeled on Quality. The header evolves the
// existing `changeOrder` table. v2: a CO's per-affected-item edits live on a
// REAL CO-owned Draft make method (no staged mirror tables); the change type
// drives the release action. Validators here cover the header, affected items +
// change type, cutover, manual supersession, and freeform actions.
// =============================================================================
// changeOrder.type — the legacy category enum on the header. Retained (the
// column still exists); the primary "Category" is `changeOrderTypeId` (a row in
// the changeNoticeType lookup, reseeded to Design improvement / Obsolescence /
// Cost reduction).
export const changeNoticeType = [
"Engineering",
"Manufacturing",
"Documentation"
] as const;
// V1 stage flow (forward, one step at a time). Notifies on Start /
// Implementation / Done; silent on Draft / Engineering Complete. "Cancelled" is
// the off-ramp: a CO can be closed from any open stage and reopened to Draft.
export const changeNoticeStatus = [
"Draft",
"Start",
"Engineering Complete",
"Implementation",
"Done",
"Cancelled"
] as const;
// The forward progress stages only (excludes the "Cancelled" off-ramp). Drives
// the read-only status-flow progress bar so a cancelled CO doesn't render as a
// sixth step.
export const changeNoticeStageFlow: (typeof changeNoticeStatus)[number][] = [
"Draft",
"Start",
"Engineering Complete",
"Implementation",
"Done"
];
export const changeNoticeTaskStatus = [
"Pending",
"In Progress",
"Completed",
"Skipped"
] as const;
// v2 per-affected-item change type. Drives the release action + which editing
// surface is shown. Two axes — is there a predecessor, and same part number?
// Version = new method version on the SAME item (BoM/BoP, no supersession)
// Revision = new revision item, same #, new rev (BoM/BoP + attrs, auto
// old-rev→new-rev supersession)
// Replacement Part = new P/N derived from + auto-superseding the affected part
// (BoM/BoP + attrs) — the 1:1 replacement, renamed from the old
// "New Part"
// New Part = net-new part, NO predecessor, NO supersession — introduced by
// the CO (Make or Buy). Used to introduce a part under change
// control, incl. the consolidated "1" in an N→1 assembly BOM
// change.
// BoM/BoP is editable on ANY change type for a manufactured (non-Buy) draft; only
// Version's extra editing scope differs (no attributes/docs/cutover surface).
export const changeNoticeChangeTypes = [
"Version",
"Revision",
"Replacement Part",
"New Part"
] as const;
export type ChangeNoticeChangeType = (typeof changeNoticeChangeTypes)[number];
// changeOrder.priority reuses quality's nonConformancePriority DB enum.
export const changeNoticePriority = nonConformancePriority;
// -----------------------------------------------------------------------------
// Stage state machine (G8 — one place). Forward, single step, plus the Cancel /
// Reopen off-ramp. This map only encodes the allowed shape of a transition.
// IMPORTANT: the forward stage is always index 0 — the header's "Advance" action
// reads `transitions[status][0]`, so "Cancelled" must never be first.
// -----------------------------------------------------------------------------
export const changeNoticeStatusTransitions: Record<
(typeof changeNoticeStatus)[number],
(typeof changeNoticeStatus)[number][]
> = {
Draft: ["Start", "Cancelled"],
Start: ["Engineering Complete", "Cancelled"],
"Engineering Complete": ["Implementation", "Cancelled"],
// Last entry is the reopen edge — "Done" stays first so the header still advances/releases.
Implementation: ["Done", "Cancelled", "Engineering Complete"],
Done: [],
// Reopen a closed CO back to Draft (fully editable). Done stays terminal.
Cancelled: ["Draft"]
};
export function isAllowedChangeNoticeTransition(
from: string | null | undefined,
to: string | null | undefined
): boolean {
if (!from || !to || from === to) return false;
const allowed =
changeNoticeStatusTransitions[from as (typeof changeNoticeStatus)[number]];
if (!allowed) return false;
return (allowed as readonly string[]).includes(to);
}
// The stages that notify the CO assignee + action-task assignees on entry.
export const changeNoticeNotifyStages: (typeof changeNoticeStatus)[number][] = [
"Start",
"Implementation",
"Done"
];
// "Open" = every stage before the record is closed at Done. Used by the item
// open-CO alert and the single-open-CO guard.
export const changeNoticeOpenStatuses: (typeof changeNoticeStatus)[number][] = [
"Draft",
"Start",
"Engineering Complete",
"Implementation"
];
export function isChangeNoticeOpen(status: string | null | undefined): boolean {
return changeNoticeOpenStatuses.some((s) => s === status);
}
// Locked once closed — Done (released, part of the audit trail) or Cancelled
// (abandoned). Reopen a Cancelled CO to Draft to edit it again.
export function isChangeNoticeLocked(
status: string | null | undefined
): boolean {
return status === "Done" || status === "Cancelled";
}
// Engineering content — affected items, BOM/BOP drafts, cutover, reason/description.
// Frozen from Implementation onward: what is being implemented must not shift underneath.
export function canEditChangeNoticeEngineering(
status: string | null | undefined
): boolean {
return !isChangeNoticeLocked(status) && status !== "Implementation";
}
// Why a change notice is locked, for whichever surface is asking: server guards
// flash it, the affected-item UI shows it in the read-only tooltip. One wording,
// so the two never drift.
export function changeNoticeLockedMessage(status: string | null | undefined) {
return status === "Implementation"
? "This change notice is being implemented, so its changes are locked. Reopen it to make changes."
: "This change notice is closed, so its changes are read-only.";
}
// Engineering content is also frozen while an approval request is pending: the
// approver signs off on exactly what they reviewed.
export const changeNoticeAwaitingApprovalMessage =
"This change notice is waiting for approval. Engineering changes are locked until it is approved or rejected.";
// Workflow content — action tasks, assignee, dates, priority. Editable until closed.
export function canEditChangeNoticeWorkflow(
status: string | null | undefined
): boolean {
return !isChangeNoticeLocked(status);
}
// -----------------------------------------------------------------------------
// Header
// -----------------------------------------------------------------------------
export const changeNoticeValidator = z.object({
id: zfd.text(z.string().optional()),
changeOrderId: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
reasonForChange: zfd.text(z.string().optional()),
description: zfd.text(z.string().optional()),
type: z.enum(changeNoticeType).optional(),
priority: z.enum(nonConformancePriority).optional(),
changeOrderTypeId: zfd.text(z.string().optional()),
nonConformanceId: zfd.text(z.string().optional()),
openDate: z.string().min(1, { message: "Open date is required" }),
dueDate: zfd.text(z.string().optional()),
assignee: zfd.text(z.string().optional()),
// Optional affected Parts/Tools to attach at create time — each is added as a
// Version affected item (Buy items coerced to Revision service-side). More can
// be added later on the CO detail. Only consumed by the create action.
affectedItemIds: zfd.repeatableOfType(z.string()).optional()
});
// Status transition (used by the $id.status route). fromStatus drives a
// compare-and-swap so a stale/concurrent transition is rejected.
export const changeNoticeStatusValidator = z.object({
id: z.string().min(1, { message: "Id is required" }),
fromStatus: z.enum(changeNoticeStatus),
status: z.enum(changeNoticeStatus),
assignee: zfd.text(z.string().optional())
});
// =============================================================================
// Top-to-bottom change content (v2) — affected items + per-item change type +
// cutover + manual supersession. The user selects affected parts first; each
// part's edits live on a REAL CO-owned Draft make method edited via the normal
// BillOfMaterial/BillOfProcess/PartProperties editors (no staged mirror tables).
// All validators are flat objects (no discriminated unions / heavy generics) to
// stay clear of TS2589 when threaded through @carbon/form's `validator()`.
// =============================================================================
// Affected item — the part the user selects to change. Adding one creates a
// CO-owned Draft make method per the change type (service side).
export const changeNoticeAffectedItemValidator = z.object({
id: zfd.text(z.string().optional()),
changeOrderId: z.string().min(1, { message: "Change notice is required" }),
itemId: z.string().min(1, { message: "Item is required" }),
changeType: z.enum(changeNoticeChangeTypes).default("Version"),
// Optional revision label for a Revision change (e.g. "A"). Blank → the next
// revision is auto-computed server-side (createChangeNoticeDraftMethod).
revision: zfd.text(z.string().optional())
});
// Add-affected-item path for a net-new "New Part" (no existing itemId): the CO
// mints a brand-new inactive Part and adds it as a New Part affected item. Always
// a Part (no Part/Tool choice in the modal).
export const changeNoticeNewPartValidator = z.object({
changeOrderId: z.string().min(1, { message: "Change notice is required" }),
// The route branches on this raw FormData value; also seeds the change-type
// Select so it reads "New Part" after the form remounts (see AffectedItemForm).
changeType: z.enum(changeNoticeChangeTypes).default("New Part"),
readableId: z.string().min(1, { message: "Part number is required" }),
name: z.string().trim().min(1, { message: "Name is required" }),
replenishmentSystem: z.enum(["Buy", "Make", "Buy and Make"]).default("Make"),
itemTrackingType: z.enum(itemTrackingTypes).default("Inventory")
});
// Switch the change type on an existing affected item (rebuilds its CO-owned
// Draft make method for the new type — see updateChangeNoticeAffectedItemChangeType).
export const changeNoticeAffectedItemChangeTypeValidator = z.object({
id: z.string().min(1, { message: "Id is required" }),
changeType: z.enum(changeNoticeChangeTypes)
});
// Per-item revision cutover config (Q3): existence of the oldRev→newRev
// supersession is automatic at release; the user only tunes mode + dates here.
export const changeNoticeAffectedItemCutoverValidator = z.object({
id: z.string().min(1, { message: "Id is required" }),
supersessionMode: z.enum(supersessionModes),
discontinuationDate: zfd.text(z.string().optional()),
successorEffectivityDate: zfd.text(z.string().optional())
});
// Action task status transition (Start / Complete / Reopen). Actions are
// instantiated from templates (see changeOrderRequiredAction); there's no
// freeform-create validator.
export const changeNoticeActionStatusValidator = z.object({
id: z.string().min(1, { message: "Id is required" }),
status: z.enum(changeNoticeTaskStatus)
});
// Configurable default actions (changeOrderRequiredAction templates) — the
// per-company set a new change notice is seeded from. Configured like Issue Types.
export const changeNoticeRequiredActionValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
active: zfd.checkbox()
});
// -----------------------------------------------------------------------------
// Diff types (Q5 git-style) — one shape reused for the pre-release "tips"
// (staged-vs-live) and the post-release revision redline (oldRev-vs-newRev).
// -----------------------------------------------------------------------------
export type MethodDiffStatus = "added" | "removed" | "modified" | "unchanged";
export type MethodDiffEntry<T> = {
status: MethodDiffStatus;
before: T | null;
after: T | null;
// Field-level changes for a "modified" entry: { field: { before, after } }.
changedFields?: Record<string, { before: unknown; after: unknown }>;
};
// One operation's child-level diff (steps / parameters / tools), each bucket
// classified added/removed/modified/unchanged. Defined here (not in
// items.service.ts) so ChangeNoticeItemDiff can carry the operation tree
// without a circular import; items.service.ts re-exports these for its own
// callers.
export type OperationChildrenDiff = {
steps: MethodDiffEntry<Record<string, unknown>>[];
parameters: MethodDiffEntry<Record<string, unknown>>[];
tools: MethodDiffEntry<Record<string, unknown>>[];
};
// An operation diff entry, optionally carrying its child-level diff. A superset
// of MethodDiffEntry, so consumers typed against the base entry keep working.
export type OperationDiffEntry = MethodDiffEntry<Record<string, unknown>> & {
children?: OperationChildrenDiff;
};
export type ChangeNoticeItemDiff = {
affectedItemId: string;
itemId: string;
materials: MethodDiffEntry<Record<string, unknown>>[];
// Operations carry the optional child (steps/parameters/tools) diff so the
// read-only diff viewer can render the BOP as a tree.
operations: OperationDiffEntry[];
attributes: MethodDiffEntry<Record<string, unknown>>[];
// Supplier parts on a draft item. A Revision draft starts with a copy of its
// source revision's, so its entries are a real diff against the source; a
// Replacement Part / New Part draft starts with none, so its are all `added`.
supplierParts: MethodDiffEntry<Record<string, unknown>>[];
};
// -----------------------------------------------------------------------------
// Change Notice Types (the "Category" lookup — configured like Issue Types)
// -----------------------------------------------------------------------------
export const changeNoticeTypeValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" })
});