Skip to content

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.

fix(production): show batch notes where operators load and start a batch

Raul2832150b77ee
diff --git a/apps/erp/app/modules/production/production.service.ts b/apps/erp/app/modules/production/production.service.ts
index 73d35bab04..31ab930ed2 100644
--- a/apps/erp/app/modules/production/production.service.ts
+++ b/apps/erp/app/modules/production/production.service.ts
@@ -2062,7 +2062,7 @@ export async function getJobOperationsList(
}
const JOB_OPERATION_DETAIL_COLUMNS =
- "*, jobOperationBatch(id, readableId, status), jobOperationTool(*, jobOperationToolStep(jobOperationStepId)), jobOperationParameter(*), jobOperationStep(*, jobOperationStepRecord(*), jobOperationStepSlide(*))" as const;
+ "*, jobOperationBatch(id, readableId, status, notes), jobOperationTool(*, jobOperationToolStep(jobOperationStepId)), jobOperationParameter(*), jobOperationStep(*, jobOperationStepRecord(*), jobOperationStepSlide(*))" as const;
export async function getJobOperationsByMethodId(
client: SupabaseClient<Database>,
diff --git a/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json b/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
index 5cdaa1e35f..07c76ee7d3 100644
--- a/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
+++ b/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
@@ -753,7 +753,7 @@
{"name":"production_getJobOperationBatchWithMembers","classification":"READ","schema":"1a62d6c430a5","response":"520bac578dba","permission":"production:view","paginates":false},
{"name":"production_getJobOperationDependencies","classification":"READ","schema":"ca49bc65b712","response":"9214ed6d51dd","permission":"production:view","paginates":false},
{"name":"production_getJobOperations","classification":"READ","schema":"f67274205e12","response":"7f24f7881568","permission":"production:view","paginates":true},
- {"name":"production_getJobOperationsByMethodId","classification":"READ","schema":"7679db37b5f9","response":"db1f7927f373","permission":"production:view","paginates":false},
+ {"name":"production_getJobOperationsByMethodId","classification":"READ","schema":"7679db37b5f9","response":"02e990581d5b","permission":"production:view","paginates":false},
{"name":"production_getJobOperationsList","classification":"READ","schema":"ca49bc65b712","response":"4e5425835530","permission":"production:view","paginates":false},
{"name":"production_getJobOperationStepRecords","classification":"READ","schema":"f67274205e12","response":"7bd4e5876d03","permission":"production:view","paginates":true},
{"name":"production_getJobOrderStatusMap","classification":"READ","schema":"cc93d4900988","response":"5a380f81ad00","permission":"production:view","paginates":false},
diff --git a/apps/mes/app/components/JobOperation/JobOperation.tsx b/apps/mes/app/components/JobOperation/JobOperation.tsx
index 2f29acf090..4bcea38409 100644
--- a/apps/mes/app/components/JobOperation/JobOperation.tsx
+++ b/apps/mes/app/components/JobOperation/JobOperation.tsx
@@ -1259,6 +1259,18 @@ export const JobOperation = ({
<Trans>Back to batch</Trans>
</Button>
</div>
+ {/* Member links land here, so the planner's notes
+ follow the operator out of the batch view. */}
+ {batch.notes?.trim() && (
+ <div className="mt-3 border-t pt-3">
+ <p className="font-medium text-foreground">
+ <Trans>Batch notes</Trans>
+ </p>
+ <p className="whitespace-pre-wrap break-words">
+ {batch.notes}
+ </p>
+ </div>
+ )}
</AlertDescription>
</Alert>
</div>
diff --git a/apps/mes/app/components/JobOperation/components/BatchOverview.tsx b/apps/mes/app/components/JobOperation/components/BatchOverview.tsx
index 1e184ad7fc..f61f44b0d4 100644
--- a/apps/mes/app/components/JobOperation/components/BatchOverview.tsx
+++ b/apps/mes/app/components/JobOperation/components/BatchOverview.tsx
@@ -151,20 +151,23 @@ export function BatchOverview({
return next;
});
- // The planner's notes from the batch builder: plain text, shown first so the
- // operator reads them before the steps.
+ // The planner's notes from the batch builder: plain text, shown before the
+ // steps on Instructions, and before the load list on Details, the tab the
+ // batch opens on, so an operator who loads and starts from Details reads them.
const notes = batch.notes?.trim() ? batch.notes : null;
+ const notesSection = (divider: boolean) =>
+ notes && (
+ <Section divider={divider} title={t`Batch notes`}>
+ <div className="prose dark:prose-invert whitespace-pre-wrap break-words">
+ {notes}
+ </div>
+ </Section>
+ );
if (view === "instructions") {
return (
<>
- {notes && (
- <Section divider={false} title={t`Batch notes`}>
- <div className="prose dark:prose-invert whitespace-pre-wrap break-words">
- {notes}
- </div>
- </Section>
- )}
+ {notesSection(false)}
{workInstructions && (
<Suspense fallback={<TableSkeleton />}>
<Await resolve={workInstructions}>
@@ -471,6 +474,8 @@ export function BatchOverview({
</div>
</div>
+ {notesSection(true)}
+
{/* Always shown in batch mode so the operator can see the jobs, parts
and quantities that belong in the run — a laser nest or an oven load
is the same item across many jobs, and needs the per-job list even
diff --git a/apps/mes/app/components/Kanban/components/ItemCard.tsx b/apps/mes/app/components/Kanban/components/ItemCard.tsx
index 462dfe3059..85981a97e3 100644
--- a/apps/mes/app/components/Kanban/components/ItemCard.tsx
+++ b/apps/mes/app/components/Kanban/components/ItemCard.tsx
@@ -26,6 +26,7 @@ import {
LuCirclePlay,
LuClipboardCheck,
LuSquareUser,
+ LuStickyNote,
LuTimer,
LuTrash,
LuTriangleAlert
@@ -255,6 +256,13 @@ export function ItemCard({
{item.reworkId && <Badge variant="red">Rework</Badge>}
</HStack>
+ {isBatch && item.batchNotes && (
+ <HStack className="items-start justify-start space-x-2 max-md:col-span-2">
+ <LuStickyNote className="mt-0.5 shrink-0 text-muted-foreground" />
+ <span className="text-sm line-clamp-2">{item.batchNotes}</span>
+ </HStack>
+ )}
+
{showDescription && item.description && (
<HStack className="justify-start space-x-2 max-md:col-span-2">
<LuClipboardCheck className="text-muted-foreground" />
diff --git a/apps/mes/app/components/Kanban/types.ts b/apps/mes/app/components/Kanban/types.ts
index 19df3e6c4d..62e20aaeea 100644
--- a/apps/mes/app/components/Kanban/types.ts
+++ b/apps/mes/app/components/Kanban/types.ts
@@ -78,6 +78,9 @@ const itemValidator = z.object({
// The member jobs' readable ids, in collapse order — shown on the collapsed
// batch card so it names every job in the batch, not just the first member.
batchJobReadableIds: z.array(z.string()).optional(),
+ // The planner's notes from the batch builder, shown on the collapsed card so
+ // the operator choosing the next run sees there is something to read.
+ batchNotes: z.string().nullable().optional(),
hasConflict: z.boolean().optional(),
conflictReason: z.string().optional()
});
diff --git a/apps/mes/app/routes/x+/operations.tsx b/apps/mes/app/routes/x+/operations.tsx
index bd7a9f0f48..86c2adbcf4 100644
--- a/apps/mes/app/routes/x+/operations.tsx
+++ b/apps/mes/app/routes/x+/operations.tsx
@@ -74,6 +74,7 @@ type BatchTotals = {
quantity: number;
targetQuantity: number;
jobReadableIds: string[];
+ notes: string | null;
};
function getBatchTotals(
@@ -88,7 +89,10 @@ function getBatchTotals(
size: 0,
quantity: 0,
targetQuantity: 0,
- jobReadableIds: []
+ jobReadableIds: [],
+ notes: member.jobOperationBatch?.notes?.trim()
+ ? member.jobOperationBatch.notes
+ : null
};
total.size += 1;
total.quantity += member.operationQuantity ?? 0;
@@ -152,6 +156,7 @@ function collapseBatches(
batchSize: total?.size ?? members.length,
batchJobReadableIds:
total?.jobReadableIds ?? members.map((m) => m.title).filter(Boolean),
+ batchNotes: total?.notes ?? null,
quantity:
total?.quantity ??
members.reduce((sum, m) => sum + (m.quantity ?? 0), 0),
diff --git a/apps/mes/app/services/operations.service.ts b/apps/mes/app/services/operations.service.ts
index 52b09c6112..86f3ce0ff0 100644
--- a/apps/mes/app/services/operations.service.ts
+++ b/apps/mes/app/services/operations.service.ts
@@ -498,7 +498,7 @@ export async function getJobOperationBatchMembers(
return client
.from("jobOperation")
.select(
- "jobOperationBatchId, operationQuantity, targetQuantity, job(jobId)"
+ "jobOperationBatchId, operationQuantity, targetQuantity, job(jobId), jobOperationBatch(notes)"
)
.in("jobOperationBatchId", batchIds)
.eq("companyId", companyId);
diff --git a/packages/documents/src/pdf/BatchListPDF.test.ts b/packages/documents/src/pdf/BatchListPDF.test.ts
index 32e643c582..9693243cb1 100644
--- a/packages/documents/src/pdf/BatchListPDF.test.ts
+++ b/packages/documents/src/pdf/BatchListPDF.test.ts
@@ -5,8 +5,9 @@
import type { ReactElement, ReactNode } from "react";
import { Children, isValidElement } from "react";
import { describe, expect, it } from "vitest";
-import { BatchListPDF, breakLongNotesWord } from "./BatchListPDF";
+import { BatchListPDF } from "./BatchListPDF";
import { SAMPLE_JOB_TRAVELER } from "./jobTraveler.samples";
+import { breakLongNotesWord } from "./notesText";
// Every string the batch list prints, read off its element tree.
function printedText(notes: string | null | undefined): string[] {
diff --git a/packages/documents/src/pdf/BatchListPDF.tsx b/packages/documents/src/pdf/BatchListPDF.tsx
index 825a396cf4..1b89db5012 100644
--- a/packages/documents/src/pdf/BatchListPDF.tsx
+++ b/packages/documents/src/pdf/BatchListPDF.tsx
@@ -8,6 +8,7 @@ import { DEFAULT_THEME } from "../template";
import type { Company } from "../types";
import { tw } from "./blocks/jobTraveler/tw";
import { Header, Template } from "./components";
+import { breakLongNotesWord } from "./notesText";
// Shared column widths so the header and body rows can never drift out of
// alignment (the MaterialsBlock convention: widths sum to 12/12; spacing via
@@ -23,21 +24,6 @@ const COL_QUANTITY = "w-2/12 text-right";
const NOTES_TITLE = `flex flex-row items-center mt-[20px] mb-[10px] py-[6px] px-[3px] border-t border-b border-[#CCCCCC] text-[9px] font-bold uppercase text-[${DEFAULT_THEME.heading}]`;
const NOTES_BODY = `text-[9px] text-[${DEFAULT_THEME.text}]`;
-// react-pdf breaks a line only between words or at the English hyphenation
-// points it finds, so an unbroken string wider than the page (a URL, a file
-// path) printed past the margin. Notes break at spaces, and a longer word
-// every NOTES_WORD_CHUNK characters.
-const NOTES_WORD_CHUNK = 40;
-
-export function breakLongNotesWord(word: string): string[] {
- if (word.length <= NOTES_WORD_CHUNK) return [word];
- const parts: string[] = [];
- for (let start = 0; start < word.length; start += NOTES_WORD_CHUNK) {
- parts.push(word.slice(start, start + NOTES_WORD_CHUNK));
- }
- return parts;
-}
-
export interface BatchListMember {
id: string;
jobReadableId: string | null;
diff --git a/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.test.ts b/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.test.ts
new file mode 100644
index 0000000000..9c687fc862
--- /dev/null
+++ b/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.test.ts
@@ -0,0 +1,81 @@
+// 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 { ReactElement, ReactNode } from "react";
+import { Children, isValidElement } from "react";
+import { describe, expect, it } from "vitest";
+import { SAMPLE_JOB_TRAVELER } from "../../jobTraveler.samples";
+import { OperationsBlock } from "./OperationsBlock";
+
+type Rendered = { texts: string[]; images: number };
+
+// Every text and image the block draws for one operation.
+function render(operation: Record<string, unknown>): Rendered {
+ const tree = OperationsBlock({
+ block: { type: "operations", showWorkInstructions: false },
+ data: {
+ ...SAMPLE_JOB_TRAVELER,
+ jobOperations: [{ ...SAMPLE_JOB_TRAVELER.jobOperations[0], ...operation }]
+ }
+ } as never) as ReactElement;
+ const rendered: Rendered = { texts: [], images: 0 };
+ const walk = (node: ReactNode) =>
+ Children.forEach(node, (child) => {
+ if (typeof child === "string" || typeof child === "number") {
+ rendered.texts.push(String(child));
+ return;
+ }
+ if (!isValidElement(child)) return;
+ const props = child.props as { src?: string; children?: ReactNode };
+ if (props.src) rendered.images += 1;
+ walk(props.children);
+ });
+ walk(tree);
+ return rendered;
+}
+
+describe("Job traveler operations", () => {
+ it("print start and complete codes on an operation in no batch", () => {
+ const { texts, images } = render({ jobOperationBatch: null });
+ expect(texts).toEqual(
+ expect.arrayContaining([
+ "Actions",
+ "Setup",
+ "Labor",
+ "Machine",
+ "Complete"
+ ])
+ );
+ expect(images).toBe(4);
+ });
+
+ it("print the batch, its notes and one open code on a batched operation", () => {
+ const { texts, images } = render({
+ jobOperationBatch: {
+ readableId: "BAT000012",
+ notes: "Furnace 2, program 7.\nTop rack first."
+ }
+ });
+ expect(texts).toEqual(
+ expect.arrayContaining([
+ "Batch BAT000012",
+ "Open in MES",
+ "Batch Notes",
+ "Furnace 2, program 7.\nTop rack first."
+ ])
+ );
+ expect(texts).not.toContain("Actions");
+ expect(texts).not.toContain("Complete");
+ expect(texts).not.toContain("Labor");
+ expect(images).toBe(1);
+ });
+
+ it("leave out an empty notes block", () => {
+ const { texts } = render({
+ jobOperationBatch: { readableId: "BAT000012", notes: " " }
+ });
+ expect(texts).toContain("Batch BAT000012");
+ expect(texts).not.toContain("Batch Notes");
+ });
+});
diff --git a/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.tsx b/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.tsx
index 2a068963d0..42f8e1113a 100644
--- a/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.tsx
+++ b/packages/documents/src/pdf/blocks/jobTraveler/OperationsBlock.tsx
@@ -9,6 +9,7 @@ import { Image, Text, View } from "@react-pdf/renderer";
import { generateQRCode } from "../../../qr/qr-code";
import type { OperationsBlock as OperationsBlockType } from "../../../template";
import { Note } from "../../components";
+import { breakLongNotesWord } from "../../notesText";
import { tw } from "./tw";
import type { JobOperationWithSteps, JobTravelerData } from "./types";
@@ -20,6 +21,27 @@ function getEndPath(operationId: string) {
return `${getMESUrl()}/x/end/${operationId}`;
}
+// Opens the operation without starting anything. The MES decides from the
+// live membership whether it runs in a batch, so the code stays right when
+// the job leaves the batch after this page is printed.
+function getOperationPath(operationId: string) {
+ return `${getMESUrl()}/x/operation/${operationId}`;
+}
+
+// The ruled uppercase title over a sub-section of an operation row.
+const SUB_SECTION_TITLE = {
+ marginBottom: 8,
+ borderTopWidth: 1,
+ borderTopColor: "#d1d5db",
+ borderBottomWidth: 1,
+ borderColor: "#d1d5db",
+ paddingTop: 4,
+ paddingBottom: 4,
+ fontSize: 9,
+ fontWeight: 700,
+ textTransform: "uppercase"
+} as const;
+
function getParallelizedOrder(
index: number,
item: JobOperationWithSteps,
@@ -62,21 +84,32 @@ export function OperationsBlock({
.sort((a, b) => a.order - b.order)
.map((operation, index) => {
const isInside = operation.operationType !== "Outside Processing";
+ // A batched operation runs on the batch's shared timer and is
+ // completed with the whole batch, so its row gets no start or
+ // complete codes: those would time and complete this job alone.
+ const batch = operation.jobOperationBatch ?? null;
+ const batchNotes = batch?.notes?.trim() ? batch.notes : null;
+ const openQrCode = batch
+ ? generateQRCode(getOperationPath(operation.id), 10)
+ : null;
const setupQrCode =
- operation.setupTime > 0
+ !batch && operation.setupTime > 0
? generateQRCode(`${getStartPath(operation.id)}?type=Setup`, 10)
: null;
let laborQrCode =
- operation.laborTime > 0
+ !batch && operation.laborTime > 0
? generateQRCode(`${getStartPath(operation.id)}?type=Labor`, 10)
: null;
const machiningQrCode =
- operation.machineTime > 0
+ !batch && operation.machineTime > 0
? generateQRCode(`${getStartPath(operation.id)}?type=Machine`, 10)
: null;
- const completeQrCode = generateQRCode(getEndPath(operation.id), 10);
+ const completeQrCode = batch
+ ? null
+ : generateQRCode(getEndPath(operation.id), 10);
if (
+ !batch &&
setupQrCode === null &&
laborQrCode === null &&
machiningQrCode === null
@@ -123,7 +156,7 @@ export function OperationsBlock({
"flex flex-col border-b border-gray-300 py-4 px-[6px] page-break-inside-avoid"
)}
key={operation.id}
- wrap={includeWorkInstructions ? true : false}
+ wrap={includeWorkInstructions || Boolean(batchNotes)}
>
<View style={tw("flex flex-col gap-y-4")} wrap={false}>
<View
@@ -166,10 +199,24 @@ export function OperationsBlock({
"flex flex-row justify-between items-center py-3 px-[6px] border-gray-300 font-bold uppercase page-break-inside-avoid"
)}
>
- <Text style={tw("text-left pr-4")}>Actions</Text>
+ <Text style={tw("text-left pr-4")}>
+ {batch ? `Batch ${batch.readableId}` : "Actions"}
+ </Text>
</View>
<View style={tw("w-full flex flex-row justify-start gap-2")}>
+ {openQrCode ? (
+ <View style={tw("flex flex-col items-center w-1/4")}>
+ <Image src={openQrCode} style={tw("w-16 h-16")} />
+ <Text style={tw("text-[10px] mt-1")}>Open in MES</Text>
+ </View>
+ ) : null}
+ {batch ? (
+ <Text style={tw("w-3/4 self-center text-[10px]")}>
+ This operation runs with other jobs as one batch. Start
+ and complete it from the batch in MES.
+ </Text>
+ ) : null}
{isInside && setupQrCode ? (
<View style={tw("flex flex-col items-center w-1/4")}>
<>
@@ -195,33 +242,33 @@ export function OperationsBlock({
</>
</View>
) : null}
- <View style={tw("flex flex-col items-center w-1/4")}>
- <Image src={completeQrCode} style={tw("w-16 h-16")} />
- <Text style={tw("text-[10px] mt-1")}>Complete</Text>
- </View>
+ {completeQrCode ? (
+ <View style={tw("flex flex-col items-center w-1/4")}>
+ <Image src={completeQrCode} style={tw("w-16 h-16")} />
+ <Text style={tw("text-[10px] mt-1")}>Complete</Text>
+ </View>
+ ) : null}
</View>
</View>
- {hasWorkInstruction || hasProcedureSteps ? (
+ {batchNotes || hasWorkInstruction || hasProcedureSteps ? (
<View style={tw("mt-2 ml-8")}>
- {hasProcedureSteps ? (
+ {/* The planner's notes from the batch builder: plain text,
+ so line breaks print as typed. First, as in the MES. */}
+ {batchNotes ? (
<View style={tw("mb-2")}>
+ <Text style={SUB_SECTION_TITLE}>Batch Notes</Text>
<Text
- style={{
- marginBottom: 8,
- borderTopWidth: 1,
- borderTopColor: "#d1d5db",
- borderBottomWidth: 1,
- borderColor: "#d1d5db",
- paddingTop: 4,
- paddingBottom: 4,
- fontSize: 9,
- fontWeight: 700,
- textTransform: "uppercase"
- }}
+ style={tw("text-[9px]")}
+ hyphenationCallback={breakLongNotesWord}
>
- Procedure Steps
+ {batchNotes}
</Text>
+ </View>
+ ) : null}
+ {hasProcedureSteps ? (
+ <View style={tw("mb-2")}>
+ <Text style={SUB_SECTION_TITLE}>Procedure Steps</Text>
{operation
.jobOperationStep!.sort(
(a, b) => a.sortOrder - b.sortOrder
diff --git a/packages/documents/src/pdf/blocks/jobTraveler/types.ts b/packages/documents/src/pdf/blocks/jobTraveler/types.ts
index b0796f7c1d..155cc1aff0 100644
--- a/packages/documents/src/pdf/blocks/jobTraveler/types.ts
+++ b/packages/documents/src/pdf/blocks/jobTraveler/types.ts
@@ -17,6 +17,8 @@ type JobOperationStep = Database["public"]["Tables"]["jobOperationStep"]["Row"];
export type JobOperationWithSteps =
Database["public"]["Tables"]["jobOperation"]["Row"] & {
jobOperationStep?: JobOperationStep[];
+ // The operation batch it runs in, when it has one.
+ jobOperationBatch?: { readableId: string; notes?: string | null } | null;
};
/** One BOM line rendered in the opt-in Materials section. */
diff --git a/packages/documents/src/pdf/notesText.ts b/packages/documents/src/pdf/notesText.ts
new file mode 100644
index 0000000000..c6aeb09d4e
--- /dev/null
+++ b/packages/documents/src/pdf/notesText.ts
@@ -0,0 +1,19 @@
+// 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.
+
+// react-pdf breaks a line only between words or at the English hyphenation
+// points it finds, so an unbroken string wider than the page (a URL, a file
+// path) printed past the margin. Plain-text notes break at spaces, and a
+// longer word every NOTES_WORD_CHUNK characters.
+const NOTES_WORD_CHUNK = 40;
+
+/** The `hyphenationCallback` for a `<Text>` of plain-text notes. */
+export function breakLongNotesWord(word: string): string[] {
+ if (word.length <= NOTES_WORD_CHUNK) return [word];
+ const parts: string[] = [];
+ for (let start = 0; start < word.length; start += NOTES_WORD_CHUNK) {
+ parts.push(word.slice(start, start + NOTES_WORD_CHUNK));
+ }
+ return parts;
+}