@naisys/erp 3.0.0-beta.3

package/dist/routes/step-runs.d.ts

@@ -0,0 +1,332 @@
+import type { FastifyInstance } from "fastify";
+import type { ErpUser } from "../auth-middleware.js";
+import { validateFieldValue } from "../services/field-value-service.js";
+import { type StepRunWithStepAndFields } from "../services/step-run-service.js";
+export declare function stepRunResource(orderKey: string, runNo: number, seqNo: number): string;
+export declare function buildStepRunActionTemplates(stepRunHref: string, canUpdate: boolean, multiSet: boolean, hasAttachmentFields: boolean, hasArrayFields: boolean): ({
+    rel: string;
+    hrefTemplate: string;
+    method: "PUT";
+    title: string;
+    schema: string;
+    body: {
+        value: string | string[];
+        fieldValues?: undefined;
+    };
+    alternateEncoding?: undefined;
+} | {
+    rel: string;
+    hrefTemplate: string;
+    method: "PUT";
+    title: string;
+    schema: string;
+    body: {
+        fieldValues: ({
+            fieldSeqNo: number;
+            value: string;
+        } | {
+            fieldSeqNo: number;
+            value: string[];
+        })[];
+        value?: undefined;
+    };
+    alternateEncoding?: undefined;
+} | {
+    rel: string;
+    hrefTemplate: string;
+    method: "DELETE";
+    title: string;
+    schema?: undefined;
+    body?: undefined;
+    alternateEncoding?: undefined;
+} | {
+    rel: string;
+    hrefTemplate: string;
+    method: "POST";
+    title: string;
+    alternateEncoding: {
+        contentType: string;
+        description: string;
+        fileFields: string[];
+    };
+    schema?: undefined;
+    body?: undefined;
+} | {
+    rel: string;
+    hrefTemplate: string;
+    method: "GET";
+    title: string;
+    schema?: undefined;
+    body?: undefined;
+    alternateEncoding?: undefined;
+})[];
+/** Compute just the HATEOAS actions + action templates for a step run */
+export declare function computeStepRunHateoas(orderKey: string, runNo: number, seqNo: number, stepSeqNo: number, opRunId: number, operationId: number, opRunStatus: string, completed: boolean, stepRunId: number, multiSet: boolean, hasAttachmentFields: boolean, hasArrayFields: boolean, user: ErpUser | undefined): Promise<{
+    _actions: {
+        rel: string;
+        href: string;
+        method: string;
+        title?: string | undefined;
+        schema?: string | undefined;
+        body?: Record<string, unknown> | undefined;
+        alternateEncoding?: {
+            contentType: string;
+            fileFields: string[];
+            description?: string | undefined;
+        } | undefined;
+        disabled?: boolean | undefined;
+        disabledReason?: string | string[] | undefined;
+    }[];
+    _actionTemplates: ({
+        rel: string;
+        hrefTemplate: string;
+        method: "PUT";
+        title: string;
+        schema: string;
+        body: {
+            value: string | string[];
+            fieldValues?: undefined;
+        };
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "PUT";
+        title: string;
+        schema: string;
+        body: {
+            fieldValues: ({
+                fieldSeqNo: number;
+                value: string;
+            } | {
+                fieldSeqNo: number;
+                value: string[];
+            })[];
+            value?: undefined;
+        };
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "DELETE";
+        title: string;
+        schema?: undefined;
+        body?: undefined;
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "POST";
+        title: string;
+        alternateEncoding: {
+            contentType: string;
+            description: string;
+            fileFields: string[];
+        };
+        schema?: undefined;
+        body?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "GET";
+        title: string;
+        schema?: undefined;
+        body?: undefined;
+        alternateEncoding?: undefined;
+    })[];
+}>;
+export declare function formatStepRunTransition(orderKey: string, runNo: number, seqNo: number, opRunId: number, operationId: number, opRunStatus: string, user: ErpUser | undefined, stepRun: StepRunWithStepAndFields): Promise<{
+    _actions: {
+        rel: string;
+        href: string;
+        method: string;
+        title?: string | undefined;
+        schema?: string | undefined;
+        body?: Record<string, unknown> | undefined;
+        alternateEncoding?: {
+            contentType: string;
+            fileFields: string[];
+            description?: string | undefined;
+        } | undefined;
+        disabled?: boolean | undefined;
+        disabledReason?: string | string[] | undefined;
+    }[];
+    _actionTemplates: ({
+        rel: string;
+        hrefTemplate: string;
+        method: "PUT";
+        title: string;
+        schema: string;
+        body: {
+            value: string | string[];
+            fieldValues?: undefined;
+        };
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "PUT";
+        title: string;
+        schema: string;
+        body: {
+            fieldValues: ({
+                fieldSeqNo: number;
+                value: string;
+            } | {
+                fieldSeqNo: number;
+                value: string[];
+            })[];
+            value?: undefined;
+        };
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "DELETE";
+        title: string;
+        schema?: undefined;
+        body?: undefined;
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "POST";
+        title: string;
+        alternateEncoding: {
+            contentType: string;
+            description: string;
+            fileFields: string[];
+        };
+        schema?: undefined;
+        body?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "GET";
+        title: string;
+        schema?: undefined;
+        body?: undefined;
+        alternateEncoding?: undefined;
+    })[];
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+    id: number;
+    completed: boolean;
+    note: string | null;
+}>;
+export declare function formatStepRunWithFields(orderKey: string, runNo: number, seqNo: number, opRunId: number, operationId: number, opRunStatus: string, user: ErpUser | undefined, stepRun: StepRunWithStepAndFields): Promise<{
+    _actions: {
+        rel: string;
+        href: string;
+        method: string;
+        title?: string | undefined;
+        schema?: string | undefined;
+        body?: Record<string, unknown> | undefined;
+        alternateEncoding?: {
+            contentType: string;
+            fileFields: string[];
+            description?: string | undefined;
+        } | undefined;
+        disabled?: boolean | undefined;
+        disabledReason?: string | string[] | undefined;
+    }[];
+    _actionTemplates: ({
+        rel: string;
+        hrefTemplate: string;
+        method: "PUT";
+        title: string;
+        schema: string;
+        body: {
+            value: string | string[];
+            fieldValues?: undefined;
+        };
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "PUT";
+        title: string;
+        schema: string;
+        body: {
+            fieldValues: ({
+                fieldSeqNo: number;
+                value: string;
+            } | {
+                fieldSeqNo: number;
+                value: string[];
+            })[];
+            value?: undefined;
+        };
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "DELETE";
+        title: string;
+        schema?: undefined;
+        body?: undefined;
+        alternateEncoding?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "POST";
+        title: string;
+        alternateEncoding: {
+            contentType: string;
+            description: string;
+            fileFields: string[];
+        };
+        schema?: undefined;
+        body?: undefined;
+    } | {
+        rel: string;
+        hrefTemplate: string;
+        method: "GET";
+        title: string;
+        schema?: undefined;
+        body?: undefined;
+        alternateEncoding?: undefined;
+    })[];
+    _links: {
+        rel: string;
+        href: string;
+        method?: string | undefined;
+        title?: string | undefined;
+        schema?: string | undefined;
+    }[];
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+    id: number;
+    operationRunId: number;
+    stepId: number;
+    seqNo: number;
+    title: string;
+    instructions: string;
+    multiSet: boolean;
+    completed: boolean;
+    note: string | null;
+    fieldCount: number;
+    fieldValues: {
+        fieldId: number;
+        fieldSeqNo: number;
+        label: string;
+        type: string;
+        valueFormat: string;
+        required: boolean;
+        setIndex: number;
+        value: string | string[];
+        attachments?: {
+            id: string;
+            filename: string;
+            fileSize: number;
+            downloadHref?: string;
+        }[];
+        validation: ReturnType<typeof validateFieldValue>;
+    }[];
+}>;
+export default function stepRunRoutes(fastify: FastifyInstance): void;
+//# sourceMappingURL=step-runs.d.ts.map

package/dist/routes/step-runs.js

@@ -0,0 +1,324 @@
+import { ErrorResponseSchema, fieldTypeString, getValueFormatHint, OperationRunStatus, StepRunListQuerySchema, StepRunListResponseSchema, StepRunSchema, } from "@naisys/erp-shared";
+import { z } from "zod/v4";
+import { hasPermission } from "../auth-middleware.js";
+import { notFound } from "../error-handler.js";
+import { API_PREFIX, selfLink } from "../hateoas.js";
+import { checkWorkCenterAccess, childItemLinks, formatAuditFields, resolveActions, resolveOpRun, resolveStepRun, } from "../route-helpers.js";
+import { deserializeFieldValue, validateCompletionFields, validateFieldValue, } from "../services/field-value-service.js";
+import { isUserClockedIn } from "../services/labor-ticket-service.js";
+import { getStepRunWithFields, listStepRuns, listStepRunsWithFields, } from "../services/step-run-service.js";
+export function stepRunResource(orderKey, runNo, seqNo) {
+    return `orders/${orderKey}/runs/${runNo}/ops/${seqNo}/steps`;
+}
+async function stepRunItemActions(orderKey, runNo, seqNo, stepSeqNo, opRunId, operationId, opRunStatus, completed, stepRunId, user) {
+    const href = `${API_PREFIX}/${stepRunResource(orderKey, runNo, seqNo)}/${stepSeqNo}`;
+    const isExecutor = hasPermission(user, "order_executor");
+    const isInProgress = opRunStatus === OperationRunStatus.in_progress;
+    // Pre-compute disabled reasons for complete action
+    const wcErr = user ? await checkWorkCenterAccess(operationId, user) : null;
+    const clockedInErr = isExecutor && isInProgress && !completed
+        ? (await isUserClockedIn(opRunId, user.id))
+            ? null
+            : "You must be clocked in to complete steps"
+        : null;
+    const fieldsErr = isExecutor && isInProgress && !completed
+        ? await (async () => {
+            const existing = await getStepRunWithFields(stepRunId);
+            return existing ? validateCompletionFields(existing) : null;
+        })()
+        : null;
+    return resolveActions([
+        {
+            rel: "complete",
+            path: "/complete",
+            method: "POST",
+            title: "Complete",
+            schema: `${API_PREFIX}/schemas/CompleteStepRun`,
+            body: { note: "" },
+            permission: "order_executor",
+            visibleWhen: () => !completed,
+            disabledWhen: () => !isInProgress
+                ? "Parent operation must be in progress"
+                : (wcErr ?? clockedInErr ?? fieldsErr),
+        },
+        {
+            rel: "reopen",
+            path: "/reopen",
+            method: "POST",
+            title: "Reopen",
+            permission: "order_executor",
+            visibleWhen: () => completed,
+            disabledWhen: () => !isInProgress ? "Parent operation must be in progress" : wcErr,
+        },
+    ], href, { status: opRunStatus, user });
+}
+export function buildStepRunActionTemplates(stepRunHref, canUpdate, multiSet, hasAttachmentFields, hasArrayFields) {
+    if (!canUpdate)
+        return [];
+    // Show array example in body hints when there are array fields
+    const valueHint = hasArrayFields ? [""] : "";
+    const batchValueHint = hasArrayFields
+        ? [
+            { fieldSeqNo: 0, value: "" },
+            { fieldSeqNo: 0, value: [""] },
+        ]
+        : [{ fieldSeqNo: 0, value: "" }];
+    return [
+        {
+            rel: "updateField",
+            hrefTemplate: multiSet
+                ? `${stepRunHref}/sets/{setIndex}/fields/{fieldSeqNo}`
+                : `${stepRunHref}/fields/{fieldSeqNo}`,
+            method: "PUT",
+            title: "Update Field Value",
+            schema: `${API_PREFIX}/schemas/UpdateFieldValue`,
+            body: { value: valueHint },
+        },
+        {
+            rel: "batchUpdateFields",
+            hrefTemplate: multiSet
+                ? `${stepRunHref}/sets/{setIndex}/fields`
+                : `${stepRunHref}/fields`,
+            method: "PUT",
+            title: "Batch Update Field Values",
+            schema: `${API_PREFIX}/schemas/BatchUpdateFieldValues`,
+            body: { fieldValues: batchValueHint },
+        },
+        ...(multiSet
+            ? [
+                {
+                    rel: "deleteSet",
+                    hrefTemplate: `${stepRunHref}/sets/{setIndex}`,
+                    method: "DELETE",
+                    title: "Delete Set",
+                },
+            ]
+            : []),
+        ...(hasAttachmentFields
+            ? [
+                {
+                    rel: "uploadAttachment",
+                    hrefTemplate: multiSet
+                        ? `${stepRunHref}/sets/{setIndex}/fields/{fieldSeqNo}/attachments`
+                        : `${stepRunHref}/fields/{fieldSeqNo}/attachments`,
+                    method: "POST",
+                    title: "Upload Attachment",
+                    alternateEncoding: {
+                        contentType: "multipart/form-data",
+                        description: "Upload file as multipart/form-data with field 'file'",
+                        fileFields: ["file"],
+                    },
+                },
+                {
+                    rel: "downloadAttachment",
+                    hrefTemplate: multiSet
+                        ? `${stepRunHref}/sets/{setIndex}/fields/{fieldSeqNo}/attachments/{attachmentId}`
+                        : `${stepRunHref}/fields/{fieldSeqNo}/attachments/{attachmentId}`,
+                    method: "GET",
+                    title: "Download Attachment",
+                },
+                {
+                    rel: "deleteAttachment",
+                    hrefTemplate: multiSet
+                        ? `${stepRunHref}/sets/{setIndex}/fields/{fieldSeqNo}/attachments/{attachmentId}`
+                        : `${stepRunHref}/fields/{fieldSeqNo}/attachments/{attachmentId}`,
+                    method: "DELETE",
+                    title: "Delete Attachment",
+                },
+            ]
+            : []),
+    ];
+}
+/** Compute just the HATEOAS actions + action templates for a step run */
+export async function computeStepRunHateoas(orderKey, runNo, seqNo, stepSeqNo, opRunId, operationId, opRunStatus, completed, stepRunId, multiSet, hasAttachmentFields, hasArrayFields, user) {
+    const canUpdate = hasPermission(user, "order_executor") &&
+        opRunStatus === OperationRunStatus.in_progress;
+    const stepRunHref = `${API_PREFIX}/${stepRunResource(orderKey, runNo, seqNo)}/${stepSeqNo}`;
+    return {
+        _actions: await stepRunItemActions(orderKey, runNo, seqNo, stepSeqNo, opRunId, operationId, opRunStatus, completed, stepRunId, user),
+        _actionTemplates: buildStepRunActionTemplates(stepRunHref, canUpdate, multiSet, hasAttachmentFields, hasArrayFields),
+    };
+}
+const OpSeqNoParamsSchema = z.object({
+    orderKey: z.string(),
+    runNo: z.coerce.number().int(),
+    seqNo: z.coerce.number().int(),
+});
+const StepSeqNoParamsSchema = z.object({
+    orderKey: z.string(),
+    runNo: z.coerce.number().int(),
+    seqNo: z.coerce.number().int(),
+    stepSeqNo: z.coerce.number().int(),
+});
+export async function formatStepRunTransition(orderKey, runNo, seqNo, opRunId, operationId, opRunStatus, user, stepRun) {
+    const stepSeqNo = stepRun.step.seqNo;
+    const multiSet = stepRun.step.multiSet;
+    const fields = stepRun.step.fieldSet?.fields ?? [];
+    const hasAttachmentFields = fields.some((f) => f.type === "attachment");
+    const hasArrayFields = fields.some((f) => f.isArray);
+    const hateoas = await computeStepRunHateoas(orderKey, runNo, seqNo, stepSeqNo, opRunId, operationId, opRunStatus, stepRun.completed, stepRun.id, multiSet, hasAttachmentFields, hasArrayFields, user);
+    return {
+        id: stepRun.id,
+        completed: stepRun.completed,
+        note: stepRun.statusNote ?? null,
+        ...formatAuditFields(stepRun),
+        ...hateoas,
+    };
+}
+export async function formatStepRunWithFields(orderKey, runNo, seqNo, opRunId, operationId, opRunStatus, user, stepRun) {
+    const stepSeqNo = stepRun.step.seqNo;
+    const multiSet = stepRun.step.multiSet;
+    // Determine how many sets exist
+    const storedFieldValues = stepRun.fieldRecord?.fieldValues ?? [];
+    const maxSetIndex = storedFieldValues.reduce((max, fv) => Math.max(max, fv.setIndex), -1);
+    const setCount = Math.max(1, maxSetIndex + 1);
+    // Merge field definitions with stored values + validation + attachments
+    const fieldValues = [];
+    const stepRunHref = `${API_PREFIX}/${stepRunResource(orderKey, runNo, seqNo)}/${stepSeqNo}`;
+    for (let si = 0; si < setCount; si++) {
+        for (const field of stepRun.step.fieldSet?.fields ?? []) {
+            const stored = storedFieldValues.find((fv) => fv.fieldId === field.id && fv.setIndex === si);
+            const value = deserializeFieldValue(stored?.value ?? "", field.isArray);
+            const setPath = multiSet
+                ? `/sets/${si}/fields/${field.seqNo}`
+                : `/fields/${field.seqNo}`;
+            const attachments = field.type === "attachment" && stored
+                ? stored.fieldAttachments.map((sfa) => ({
+                    id: sfa.attachment.publicId,
+                    filename: sfa.attachment.filename,
+                    fileSize: sfa.attachment.fileSize,
+                    downloadHref: `${stepRunHref}${setPath}/attachments/${sfa.attachment.publicId}`,
+                }))
+                : undefined;
+            const fieldType = fieldTypeString(field.type, field.isArray);
+            fieldValues.push({
+                fieldId: field.id,
+                fieldSeqNo: field.seqNo,
+                label: field.label,
+                type: fieldType,
+                valueFormat: getValueFormatHint(fieldType),
+                required: field.required,
+                setIndex: si,
+                value,
+                attachments,
+                validation: validateFieldValue(field.type, field.isArray, field.required, value),
+            });
+        }
+    }
+    const allFields = stepRun.step.fieldSet?.fields ?? [];
+    const hasAttachmentFields = allFields.some((f) => f.type === "attachment");
+    const hasArrayFields = allFields.some((f) => f.isArray);
+    const hateoas = await computeStepRunHateoas(orderKey, runNo, seqNo, stepSeqNo, opRunId, operationId, opRunStatus, stepRun.completed, stepRun.id, multiSet, hasAttachmentFields, hasArrayFields, user);
+    return {
+        id: stepRun.id,
+        operationRunId: stepRun.operationRunId,
+        stepId: stepRun.stepId,
+        seqNo: stepSeqNo,
+        title: stepRun.step.title,
+        instructions: stepRun.step.instructions,
+        multiSet,
+        completed: stepRun.completed,
+        note: stepRun.statusNote ?? null,
+        fieldCount: stepRun.step.fieldSet?.fields.length ?? 0,
+        fieldValues,
+        ...formatAuditFields(stepRun),
+        _links: childItemLinks("/" + stepRunResource(orderKey, runNo, seqNo), stepSeqNo, "Step Runs", "/orders/" + orderKey + "/runs/" + runNo + "/ops/" + seqNo, "Operation Run", "StepRun", "operationRun"),
+        ...hateoas,
+    };
+}
+function formatListStepRun(stepRun) {
+    const stepSeqNo = stepRun.step.seqNo;
+    const fieldCount = stepRun.step.fieldSet?._count.fields ?? 0;
+    return {
+        id: stepRun.id,
+        operationRunId: stepRun.operationRunId,
+        stepId: stepRun.stepId,
+        seqNo: stepSeqNo,
+        title: stepRun.step.title,
+        instructions: stepRun.step.instructions,
+        multiSet: stepRun.step.multiSet,
+        completed: stepRun.completed,
+        note: stepRun.statusNote ?? null,
+        fieldCount,
+        ...formatAuditFields(stepRun),
+    };
+}
+export default function stepRunRoutes(fastify) {
+    const app = fastify.withTypeProvider();
+    // LIST
+    app.get("/", {
+        schema: {
+            description: "List step runs for an operation run",
+            tags: ["Step Runs"],
+            params: OpSeqNoParamsSchema,
+            querystring: StepRunListQuerySchema,
+            response: {
+                200: StepRunListResponseSchema,
+                404: ErrorResponseSchema,
+            },
+        },
+        handler: async (request, reply) => {
+            const { orderKey, runNo, seqNo } = request.params;
+            const { includeFields } = request.query;
+            const resolved = await resolveOpRun(orderKey, runNo, seqNo);
+            if (!resolved) {
+                return notFound(reply, `Operation run not found`);
+            }
+            if (includeFields) {
+                const items = await listStepRunsWithFields(resolved.opRun.id);
+                const formatted = await Promise.all(items.map(async (stepRun) => {
+                    const { _links, ...rest } = await formatStepRunWithFields(orderKey, runNo, seqNo, resolved.opRun.id, resolved.opRun.operationId, resolved.opRun.status, request.erpUser, stepRun);
+                    return rest;
+                }));
+                return {
+                    items: formatted,
+                    total: items.length,
+                    _links: [selfLink(`/${stepRunResource(orderKey, runNo, seqNo)}`)],
+                    _linkTemplates: [
+                        {
+                            rel: "item",
+                            hrefTemplate: `${API_PREFIX}/${stepRunResource(orderKey, runNo, seqNo)}/{seqNo}`,
+                        },
+                    ],
+                };
+            }
+            const items = await listStepRuns(resolved.opRun.id);
+            return {
+                items: items.map((stepRun) => formatListStepRun(stepRun)),
+                total: items.length,
+                _links: [selfLink(`/${stepRunResource(orderKey, runNo, seqNo)}`)],
+                _linkTemplates: [
+                    {
+                        rel: "item",
+                        hrefTemplate: `${API_PREFIX}/${stepRunResource(orderKey, runNo, seqNo)}/{seqNo}`,
+                    },
+                ],
+            };
+        },
+    });
+    // GET by stepSeqNo
+    app.get("/:stepSeqNo", {
+        schema: {
+            description: "Get a single step run by step sequence number",
+            tags: ["Step Runs"],
+            params: StepSeqNoParamsSchema,
+            response: {
+                200: StepRunSchema,
+                404: ErrorResponseSchema,
+            },
+        },
+        handler: async (request, reply) => {
+            const { orderKey, runNo, seqNo, stepSeqNo } = request.params;
+            const resolved = await resolveStepRun(orderKey, runNo, seqNo, stepSeqNo);
+            if (!resolved) {
+                return notFound(reply, `Step run not found`);
+            }
+            const stepRun = await getStepRunWithFields(resolved.stepRun.id);
+            if (!stepRun) {
+                return notFound(reply, `Step run not found`);
+            }
+            return formatStepRunWithFields(orderKey, runNo, seqNo, resolved.opRun.id, resolved.opRun.operationId, resolved.opRun.status, request.erpUser, stepRun);
+        },
+    });
+}
+//# sourceMappingURL=step-runs.js.map

package/dist/routes/steps.d.ts

@@ -0,0 +1,3 @@
+import type { FastifyInstance } from "fastify";
+export default function stepRoutes(fastify: FastifyInstance): void;
+//# sourceMappingURL=steps.d.ts.map