@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/manufacturing/docs/models/RoutingOperation.md

@@ -0,0 +1,40 @@
+# RoutingOperation
+
+## Description
+
+RoutingOperation defines one ordered step within a Routing. It owns the sequence number, work-center assignment, standard setup and run time assumptions, optional operation description, and operator instructions that production-order release later snapshots into executable work orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createRouting](../commands/CreateRouting.md) - Create draft routings including initial ordered operations.
+- [updateRouting](../commands/UpdateRouting.md) - Revise operation sequence, times, and work-center assignments while the routing is draft.
+- [activateRouting](../commands/ActivateRouting.md) - Validate ordered operations and make the routing eligible for production-order release.
+- [deactivateRouting](../commands/DeactivateRouting.md) - Retire the routing revision without mutating operations already snapshotted onto released orders.
+
+### Query Definitions
+
+- [getRouting](../queries/GetRouting.md) - Retrieve one routing revision with ordered operations.
+- [listRoutingsByItem](../queries/ListRoutingsByItem.md) - List routing revisions and operations for one parent item and scope.
+
+### Models
+
+- RoutingOperation
+
+### Invariants
+
+- Every RoutingOperation belongs to exactly one Routing.
+- `sequenceNumber` must be unique within its parent Routing.
+- `standardSetupTime` and `standardRunTime` must be zero or greater.
+- Each operation must reference an active work center valid for the same company and effective scope.
+- An active Routing must not reference an inactive work center through any of its operations.
+
+### Relationships
+
+- **Belongs To Routing**: each operation is subordinate to one [Routing](./Routing.md).
+- **References WorkCenter**: `workCenterId` points to the [WorkCenter](./WorkCenter.md) where the step executes.

package/src/modules/manufacturing/docs/models/WorkOrderExecutionEvent.md

@@ -0,0 +1,38 @@
+# WorkOrderExecutionEvent
+
+## Description
+
+WorkOrderExecutionEvent records one discrete execution action taken on a WorkOrder. It owns the event type, timestamp, and optional quantity, time, scrap, and notes values that together form the immutable audit trail for shop-floor progress, pauses, resumes, and completion.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [startWorkOrder](../commands/StartWorkOrder.md) - Append STARTED execution events when shop-floor work begins.
+- [reportWorkOrderProgress](../commands/ReportWorkOrderProgress.md) - Append PROGRESS_REPORTED events with quantities, time, scrap, and notes.
+- [pauseWorkOrder](../commands/PauseWorkOrder.md) - Append PAUSED execution events when work is interrupted.
+- [resumeWorkOrder](../commands/ResumeWorkOrder.md) - Append RESUMED execution events when work continues after a pause.
+- [completeWorkOrder](../commands/CompleteWorkOrder.md) - Append COMPLETED execution events when the operation finishes.
+
+### Query Definitions
+
+- [getWorkOrder](../queries/GetWorkOrder.md) - Retrieve execution events as part of one work order.
+
+### Models
+
+- WorkOrderExecutionEvent
+
+### Invariants
+
+- Every WorkOrderExecutionEvent belongs to exactly one WorkOrder.
+- `eventType` must be one of `STARTED`, `PAUSED`, `RESUMED`, `PROGRESS_REPORTED`, or `COMPLETED`.
+- `quantity`, `timeValue`, and `scrapValue`, when provided, must be zero or greater.
+- Events are append-only; existing events are never mutated after creation.
+
+### Relationships
+
+- **Belongs To WorkOrder**: each event is subordinate to one [WorkOrder](./WorkOrder.md).

package/src/modules/manufacturing/docs/queries/ExplodeBillOfMaterial.md

@@ -54,3 +54,4 @@ flowchart TD
 - returns error when the root BOM is not effective on the requested date
 - returns error when a required lower-level child BOM cannot be resolved
 - returns error when the explosion detects a circular BOM reference
+- resolves lower-level child BOMs using the applicable site scope

package/src/modules/manufacturing/docs/queries/ListWorkCentersBySite.md

@@ -36,3 +36,4 @@ flowchart TD
 - returns an empty list when the site has no work centers
 - returns error when company scope is missing
 - returns error when site scope is missing
+- filters work centers by work-center type and accepts name ordering

package/src/modules/organization/command/updateCompany.test.ts

@@ -89,7 +89,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when company does not exist", async () => {
+  it("returns error when company does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(undefined);
 
@@ -109,7 +109,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when legal name is empty", async () => {
+  it("returns error when legal name is empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(draftCompany);
 
@@ -129,7 +129,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when changing base currency on ACTIVE company", async () => {
+  it("returns error when changing base currency on ACTIVE company", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeCompany);
 
@@ -149,7 +149,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when changing base currency on INACTIVE company", async () => {
+  it("returns error when changing base currency on INACTIVE company", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(inactiveCompany);
 
@@ -169,7 +169,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when new base currency does not exist", async () => {
+  it("returns error when new base currency does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(draftCompany) // company lookup
@@ -191,7 +191,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when new base currency is inactive", async () => {
+  it("returns error when new base currency is inactive", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(draftCompany) // company lookup

package/src/modules/organization/command/updateCompany.ts

@@ -8,7 +8,7 @@ import {
 import type { PrimitivesQueries } from "../module";
 import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
 
-export interface UpdateCompanyInput {
+export type UpdateCompanyInput = {
   companyId: string;
   legalName?: string;
   taxId?: string;
@@ -19,8 +19,7 @@ export interface UpdateCompanyInput {
   state?: string;
   postalCode?: string;
   country?: string;
-}
-
+};
 /**
  * Function: updateCompany
  *
@@ -29,7 +28,7 @@ export interface UpdateCompanyInput {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateCompanyInput & CF,
+  input: UpdateCompanyInput & Omit<Partial<CF>, "status">,
   ctx: CommandContext,
   primitivesQueries?: Pick<PrimitivesQueries, "getCurrency">,
 ) {

package/src/modules/organization/command/updateDepartment.test.ts

@@ -88,7 +88,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when department does not exist", async () => {
+  it("returns error when department does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(undefined);
 
@@ -103,7 +103,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when name is empty", async () => {
+  it("returns error when name is empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeDepartment);
 
@@ -118,7 +118,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when name is whitespace-only", async () => {
+  it("returns error when name is whitespace-only", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeDepartment);
 
@@ -133,7 +133,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when setting self as parent", async () => {
+  it("returns error when setting self as parent", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeDepartment);
 
@@ -148,7 +148,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when parent does not exist", async () => {
+  it("returns error when parent does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(activeDepartment) // find department
@@ -165,7 +165,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when parent belongs to different company", async () => {
+  it("returns error when parent belongs to different company", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(activeDepartment) // find department
@@ -182,7 +182,7 @@ describe("updateDepartment", () => {
     }
   });
 
-  it("throws when reparenting creates circular reference", async () => {
+  it("returns error when reparenting creates circular reference", async () => {
     const { db, spies } = createMockDb<Transaction>();
     // activeDepartment -> childDepartment -> grandchildDepartment
     // Try to set activeDepartment's parent to grandchildDepartment

package/src/modules/organization/command/updateDepartment.ts

@@ -9,12 +9,11 @@ import {
 import { run as detectCircularReference } from "../query/detectDepartmentCircularReference";
 import { ok, err } from "@tailor-platform/erp-kit/module";
 
-export interface UpdateDepartmentInput {
+export type UpdateDepartmentInput = {
   departmentId: string;
   name?: string;
   parentDepartmentId?: string | null;
-}
-
+};
 /**
  * Function: updateDepartment
  *
@@ -23,20 +22,22 @@ export interface UpdateDepartmentInput {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateDepartmentInput & CF,
+  input: UpdateDepartmentInput & Omit<Partial<CF>, "status">,
 ) {
-  const { departmentId, name, parentDepartmentId, ...customFields } = input;
+  const { name, parentDepartmentId, ...rest } = input;
+  const customFields = { ...rest } as Record<string, unknown>;
+  delete customFields.departmentId;
 
   // 1. Find department
   const existing = await db
     .selectFrom("Department")
     .selectAll()
-    .where("id", "=", departmentId)
+    .where("id", "=", input.departmentId)
     .forUpdate()
     .executeTakeFirst();
 
   if (!existing) {
-    return err(new DepartmentNotFoundError(departmentId));
+    return err(new DepartmentNotFoundError(input.departmentId));
   }
 
   // 2. Validate name if provided
@@ -47,8 +48,8 @@ export async function run<CF extends Record<string, unknown>>(
   // 3. Validate parentDepartmentId if provided
   if (parentDepartmentId !== undefined && parentDepartmentId !== null) {
     // Self-reference check
-    if (parentDepartmentId === departmentId) {
-      return err(new SelfReferenceError(departmentId));
+    if (parentDepartmentId === existing.id) {
+      return err(new SelfReferenceError(existing.id));
     }
 
     // Find parent department
@@ -69,11 +70,11 @@ export async function run<CF extends Record<string, unknown>>(
 
     // Circular reference detection via shared query
     const circularResult = await detectCircularReference(db, {
-      departmentId,
+      departmentId: existing.id,
       newParentId: parentDepartmentId,
     });
     if (circularResult.ok && circularResult.value.isCircular) {
-      return err(new CircularReferenceError(departmentId));
+      return err(new CircularReferenceError(existing.id));
     }
   }
 
@@ -112,7 +113,7 @@ export async function run<CF extends Record<string, unknown>>(
   const department = await db
     .updateTable("Department")
     .set(updateSet)
-    .where("id", "=", departmentId)
+    .where("id", "=", existing.id)
     .returningAll()
     .executeTakeFirst();
 

package/src/modules/organization/command/updateSite.test.ts

@@ -88,7 +88,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when site does not exist", async () => {
+  it("returns error when site does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(undefined);
 
@@ -100,7 +100,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when name is empty", async () => {
+  it("returns error when name is empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -112,7 +112,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when name already exists in same company", async () => {
+  it("returns error when name already exists in same company", async () => {
     const { db, spies } = createMockDb<Transaction>();
     const otherSite = { ...activeSite, id: "site-other", name: "Existing Name" };
 
@@ -128,7 +128,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when type is invalid", async () => {
+  it("returns error when type is invalid", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -140,7 +140,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when country code is invalid", async () => {
+  it("returns error when country code is invalid", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -152,7 +152,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when timezone is invalid", async () => {
+  it("returns error when timezone is invalid", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -179,7 +179,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when street is set to empty", async () => {
+  it("returns error when street is set to empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -191,7 +191,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when city is set to empty", async () => {
+  it("returns error when city is set to empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -203,7 +203,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when postalCode is set to empty", async () => {
+  it("returns error when postalCode is set to empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 
@@ -215,7 +215,7 @@ describe("updateSite", () => {
     }
   });
 
-  it("throws when country is set to empty", async () => {
+  it("returns error when country is set to empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeSite);
 

package/src/modules/organization/command/updateSite.ts

@@ -10,7 +10,7 @@ import {
 } from "../lib/errors.generated";
 import { ok, err } from "@tailor-platform/erp-kit/module";
 
-export interface UpdateSiteInput {
+export type UpdateSiteInput = {
   siteId: string;
   name?: string;
   type?: string;
@@ -20,7 +20,7 @@ export interface UpdateSiteInput {
   postalCode?: string;
   country?: string;
   timezone?: string;
-}
+};
 
 const VALID_SITE_TYPES = ["OFFICE", "WAREHOUSE", "STORE", "FACTORY", "DISTRIBUTION_CENTER"];
 
@@ -42,7 +42,6 @@ function isValidTimezone(tz: string): boolean {
     return false;
   }
 }
-
 /**
  * Function: updateSite
  *
@@ -51,7 +50,7 @@ function isValidTimezone(tz: string): boolean {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateSiteInput & CF,
+  input: UpdateSiteInput & Omit<Partial<CF>, "status">,
 ) {
   const {
     siteId,

package/src/modules/organization/docs/commands/UpdateCompany.md

@@ -49,10 +49,10 @@ flowchart TD
 - updates legal name on DRAFT company
 - updates address fields on ACTIVE company
 - updates tax ID and registration number
-- throws when company does not exist
-- throws when legal name is empty
-- throws when changing base currency on ACTIVE company
-- throws when changing base currency on INACTIVE company
-- throws when new base currency does not exist
-- throws when new base currency is inactive
+- returns error when company does not exist
+- returns error when legal name is empty
+- returns error when changing base currency on ACTIVE company
+- returns error when changing base currency on INACTIVE company
+- returns error when new base currency does not exist
+- returns error when new base currency is inactive
 - updates base currency on DRAFT company

package/src/modules/organization/docs/commands/UpdateDepartment.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-UpdateDepartment modifies the name or parent department of an existing department. The department code and company are immutable. Parent department changes are validated to prevent self-references and circular hierarchies. Updating is allowed on both ACTIVE and INACTIVE departments.
+UpdateDepartment modifies the name or parent department of an existing department. Department code and company ownership are fixed by the existing record and are not part of the update input. Parent department changes are validated to prevent self-references and circular hierarchies. Updating is allowed on both ACTIVE and INACTIVE departments.
 
 This command supports organizational restructuring and department renaming.
 
@@ -10,8 +10,7 @@ This command supports organizational restructuring and department renaming.
 
 - Department must exist
 - Name, if provided, must be non-empty
-- Department code cannot be changed
-- companyId cannot be changed
+- Department code and company ownership are not part of the update input
 - Parent department, if provided, must exist and belong to the same company
 - A department cannot reference itself as its own parent
 - Circular parent references are rejected
@@ -54,11 +53,11 @@ flowchart TD
 - updates department name
 - updates parent department
 - removes parent department (promotes to top-level)
-- throws when department does not exist
-- throws when name is empty
-- throws when name is whitespace-only
-- throws when setting self as parent
-- throws when parent does not exist
-- throws when parent belongs to different company
-- throws when reparenting creates circular reference
+- returns error when department does not exist
+- returns error when name is empty
+- returns error when name is whitespace-only
+- returns error when setting self as parent
+- returns error when parent does not exist
+- returns error when parent belongs to different company
+- returns error when reparenting creates circular reference
 - updates parent on INACTIVE department

package/src/modules/organization/docs/commands/UpdateSite.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-UpdateSite modifies fields on an existing site. Updatable fields include name, type, address fields, country, and timezone. The companyId is immutable after creation. Updating is permitted on both ACTIVE and INACTIVE sites.
+UpdateSite modifies fields on an existing site. Updatable fields include name, type, address fields, country, and timezone. Company ownership is fixed by the existing record and is not part of the update input. Updating is permitted on both ACTIVE and INACTIVE sites.
 
 This command supports address corrections, type reclassification, and timezone updates.
 
@@ -12,7 +12,7 @@ This command supports address corrections, type reclassification, and timezone u
 - Name, if provided, must be non-empty
 - Name, if changed, must remain unique within the same company
 - Type, if provided, must be one of the allowed classifications
-- companyId cannot be changed
+- companyId is not part of the update input
 - Timezone, if provided, must be a valid IANA timezone identifier
 - Country, if provided, must reference a valid country code
 - Address fields can be individually updated
@@ -64,17 +64,17 @@ flowchart TD
 - updates site address fields
 - updates site type
 - updates site timezone
-- throws when site does not exist
-- throws when name is empty
-- throws when name already exists in same company
-- throws when type is invalid
-- throws when country code is invalid
-- throws when timezone is invalid
+- returns error when site does not exist
+- returns error when name is empty
+- returns error when name already exists in same company
+- returns error when type is invalid
+- returns error when country code is invalid
+- returns error when timezone is invalid
 - updates site country
-- throws when street is set to empty
-- throws when city is set to empty
-- throws when postalCode is set to empty
-- throws when country is set to empty
+- returns error when street is set to empty
+- returns error when city is set to empty
+- returns error when postalCode is set to empty
+- returns error when country is set to empty
 - updates state/province field
 - clears state/province field
 - updates address fields on INACTIVE site

package/src/modules/product-management/command/updateProduct.test.ts

@@ -3,7 +3,6 @@ import { createMockDb } from "../../../testing/index";
 import type { GetUnitInput } from "../../primitives/query/getUnit";
 import type { Transaction } from "../generated/kysely-tailordb";
 import {
-  CodeImmutableError,
   InvalidUomError,
   MissingRequiredFieldError,
   NoFieldsToUpdateError,
@@ -51,16 +50,6 @@ describe("updateProduct", () => {
     }
   });
 
-  it("returns error when code change attempted", async () => {
-    const { db, spies } = createMockDb<Transaction>();
-    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
-    const result = await run(db, { id: "product-1", code: "NEW-CODE" }, ctx, primitivesQueries);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBeInstanceOf(CodeImmutableError);
-    }
-  });
-
   it("returns error when no fields provided", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce({ ...baseDraftProduct });
@@ -147,6 +136,23 @@ describe("updateProduct", () => {
     }
   });
 
+  it("looks up product by code and updates name", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseDraftProduct, name: "Updated Name" };
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    spies.update.mockReturnValueOnce(updated);
+    const result = await run(
+      db,
+      { code: baseDraftProduct.code, name: "Updated Name" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.product.name).toBe("Updated Name");
+    }
+  });
+
   it("passes custom fields through", async () => {
     const { db, spies } = createMockDb<Transaction>();
     const updated = { ...baseDraftProduct, customField1: "value1" };