@tailor-platform/erp-kit 0.5.0 → 0.6.0

package/src/modules/manufacturing/db/productionOrderRoutingSnapshot.ts

@@ -0,0 +1,43 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { productionOrder } from "./productionOrder";
+
+export interface CreateProductionOrderRoutingSnapshotTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+  productionOrderType: TailorAnyDBType;
+}
+
+export function createProductionOrderRoutingSnapshotType<
+  const F extends Record<string, TailorAnyDBField>,
+>(params: CreateProductionOrderRoutingSnapshotTypeParams<F>) {
+  return db
+    .type("ProductionOrderRoutingSnapshot", {
+      productionOrderId: db
+        .uuid()
+        .relation({
+          type: "1-1",
+          toward: { type: params.productionOrderType },
+          backward: "routingSnapshot",
+        })
+        .description("Foreign key to ProductionOrder (one snapshot per order)"),
+      routingId: db.uuid().description("Routing ID reference for the snapshot"),
+      snapshotData: db
+        .string({ optional: true })
+        .description("JSON blob containing the full routing snapshot"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productionOrderRoutingSnapshot = createProductionOrderRoutingSnapshotType({
+  productionOrderType: productionOrder,
+});

package/src/modules/manufacturing/db/routing.ts

@@ -0,0 +1,63 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub, site as siteStub, item as itemStub } from "../lib/_db_deps";
+
+export const BASE_ROUTING_STATUSES = ["DRAFT", "ACTIVE", "INACTIVE"] as const;
+
+export interface CreateRoutingTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType: TailorAnyDBType;
+  siteType: TailorAnyDBType;
+  itemType: TailorAnyDBType;
+}
+
+export function createRoutingType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateRoutingTypeParams<F>,
+) {
+  return db
+    .type("Routing", {
+      parentItemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.itemType },
+          backward: "routings",
+        })
+        .description("Foreign key to Item – the manufactured item"),
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType },
+          backward: "routings",
+        })
+        .description("Foreign key to Company"),
+      siteId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.siteType },
+          backward: "routings",
+        })
+        .description("Foreign key to Site – optional site scope"),
+      revisionNumber: db.string({ optional: true }).description("Version identity of the routing"),
+      status: db
+        .enum([...BASE_ROUTING_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: DRAFT, ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const routing = createRoutingType({
+  companyType: companyStub,
+  siteType: siteStub,
+  itemType: itemStub,
+});

package/src/modules/manufacturing/db/routingOperation.ts

@@ -0,0 +1,57 @@
+import {
+  db,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { routing } from "./routing";
+import { workCenter } from "./workCenter";
+
+export interface CreateRoutingOperationTypeParams {
+  routingType: TailorAnyDBType;
+  workCenterType: TailorAnyDBType;
+}
+
+export function createRoutingOperationType(params: CreateRoutingOperationTypeParams) {
+  return db
+    .type("RoutingOperation", {
+      routingId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.routingType },
+          backward: "routingOperations",
+        })
+        .description("Foreign key to Routing"),
+      sequenceNumber: db.int().description("Step order within the routing"),
+      operationDescription: db
+        .string({ optional: true })
+        .description("Human-readable description of the operation"),
+      workCenterId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.workCenterType },
+          backward: "routingOperations",
+        })
+        .description("Foreign key to WorkCenter"),
+      standardSetupTime: db.float().description("Standard setup time (>= 0)"),
+      standardRunTime: db.float().description("Standard run time per unit (>= 0)"),
+      operatorInstructions: db
+        .string({ optional: true })
+        .description("Free-text instructions for the operator"),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["routingId", "sequenceNumber"],
+      unique: true,
+      name: "routing_operation_routing_seq_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const routingOperation = createRoutingOperationType({
+  routingType: routing,
+  workCenterType: workCenter,
+});

package/src/modules/manufacturing/db/workCenter.ts

@@ -0,0 +1,87 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub, site as siteStub } from "../lib/_db_deps";
+
+export const BASE_WORK_CENTER_STATUSES = ["DRAFT", "ACTIVE", "INACTIVE"] as const;
+
+export const OVERHEAD_ABSORPTION_METHODS = [
+  "PERCENT_OF_LABOR_COST",
+  "PERCENT_OF_MACHINE_COST",
+  "FIXED_AMOUNT_PER_GOOD_UNIT",
+] as const;
+
+export interface CreateWorkCenterTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType: TailorAnyDBType;
+  siteType: TailorAnyDBType;
+}
+
+export function createWorkCenterType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateWorkCenterTypeParams<F>,
+) {
+  return db
+    .type("WorkCenter", {
+      code: db.string().description("Work-center code, unique within company and site scope"),
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType },
+          backward: "workCenters",
+        })
+        .description("Foreign key to Company"),
+      siteId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.siteType },
+          backward: "workCenters",
+        })
+        .description("Foreign key to Site; required when company uses site-level work centers"),
+      status: db
+        .enum([...BASE_WORK_CENTER_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: DRAFT, ACTIVE, INACTIVE"),
+      capacityAssumptions: db
+        .float()
+        .description(
+          "Capacity assumption expressed in a consistent planning unit; must be positive",
+        ),
+      laborRate: db
+        .float({ optional: true })
+        .description("Standard labor rate per planning unit; must be zero or greater"),
+      machineRate: db
+        .float({ optional: true })
+        .description("Standard machine rate per planning unit; must be zero or greater"),
+      calendarReference: db
+        .string({ optional: true })
+        .description("Calendar identifier; required when activating the work center"),
+      overheadAbsorptionMethod: db
+        .enum([...OVERHEAD_ABSORPTION_METHODS] as [string, ...string[]], {
+          optional: true,
+        })
+        .description(
+          "Method for absorbing overhead: PERCENT_OF_LABOR_COST, PERCENT_OF_MACHINE_COST, or FIXED_AMOUNT_PER_GOOD_UNIT",
+        ),
+      overheadAbsorptionCurrency: db
+        .string({ optional: true })
+        .description(
+          "ISO 4217 currency code for overhead absorption; required when method is FIXED_AMOUNT_PER_GOOD_UNIT",
+        ),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["code", "companyId", "siteId"],
+      unique: true,
+      name: "work_center_code_company_site_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const workCenter = createWorkCenterType({ companyType: companyStub, siteType: siteStub });

package/src/modules/manufacturing/db/workOrder.ts

@@ -0,0 +1,65 @@
+import {
+  db,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { productionOrder } from "./productionOrder";
+import { workCenter } from "./workCenter";
+
+export const BASE_WORK_ORDER_STATUSES = [
+  "PENDING",
+  "IN_PROGRESS",
+  "PAUSED",
+  "COMPLETE",
+  "CANCELLED",
+] as const;
+
+export interface CreateWorkOrderTypeParams {
+  productionOrderType: TailorAnyDBType;
+  workCenterType: TailorAnyDBType;
+}
+
+export function createWorkOrderType(params: CreateWorkOrderTypeParams) {
+  return db
+    .type("WorkOrder", {
+      productionOrderId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.productionOrderType },
+          backward: "workOrders",
+        })
+        .description("Foreign key to ProductionOrder"),
+      routingOperationSequenceNumber: db
+        .int()
+        .description("Sequence number of the routing operation"),
+      workCenterId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.workCenterType },
+          backward: "workOrders",
+        })
+        .description("Foreign key to WorkCenter"),
+      plannedQuantity: db.float().description("Planned quantity to produce, must be >= 0"),
+      completedQuantity: db.float().description("Completed quantity, must be >= 0"),
+      scrapQuantity: db.float().description("Scrap quantity, must be >= 0"),
+      actualSetupTime: db.float().description("Actual setup time in minutes, must be >= 0"),
+      actualRunTime: db.float().description("Actual run time in minutes, must be >= 0"),
+      actualStartDate: db.datetime({ optional: true }).description("Actual start date and time"),
+      pauseReason: db.string({ optional: true }).description("Reason for pausing the work order"),
+      executionNotes: db.string({ optional: true }).description("Free-form notes about execution"),
+      status: db
+        .enum([...BASE_WORK_ORDER_STATUSES] as [string, ...string[]])
+        .description("Lifecycle status: PENDING, IN_PROGRESS, PAUSED, COMPLETE, CANCELLED"),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const workOrder = createWorkOrderType({
+  productionOrderType: productionOrder,
+  workCenterType: workCenter,
+});

package/src/modules/manufacturing/db/workOrderExecutionEvent.ts

@@ -0,0 +1,54 @@
+import {
+  db,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { workOrder } from "./workOrder";
+
+export const EXECUTION_EVENT_TYPES = [
+  "STARTED",
+  "PAUSED",
+  "RESUMED",
+  "PROGRESS_REPORTED",
+  "COMPLETED",
+] as const;
+
+export interface CreateWorkOrderExecutionEventTypeParams {
+  workOrderType: TailorAnyDBType;
+}
+
+export function createWorkOrderExecutionEventType(params: CreateWorkOrderExecutionEventTypeParams) {
+  return db
+    .type("WorkOrderExecutionEvent", {
+      workOrderId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.workOrderType },
+          backward: "executionEvents",
+        })
+        .description("Foreign key to WorkOrder"),
+      eventType: db
+        .enum([...EXECUTION_EVENT_TYPES] as [string, ...string[]])
+        .description("Event type: STARTED, PAUSED, RESUMED, PROGRESS_REPORTED, COMPLETED"),
+      timestamp: db.datetime().description("When the event occurred"),
+      quantity: db
+        .float({ optional: true })
+        .description("Quantity associated with the event, must be >= 0"),
+      timeValue: db
+        .float({ optional: true })
+        .description("Time value associated with the event, must be >= 0"),
+      scrapValue: db
+        .float({ optional: true })
+        .description("Scrap value associated with the event, must be >= 0"),
+      notes: db.string({ optional: true }).description("Optional notes about the event"),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const workOrderExecutionEvent = createWorkOrderExecutionEventType({
+  workOrderType: workOrder,
+});

package/src/modules/manufacturing/docs/commands/ActivateBillOfMaterial.md

@@ -0,0 +1,50 @@
+# ActivateBillOfMaterial
+
+## Overview
+
+ActivateBillOfMaterial validates a draft BOM version and makes it selectable for production-order release. Activation is where circular-reference checks, effectivity conflicts, and component readiness are enforced.
+
+## Business Rules
+
+- Target BOM must exist and be in `DRAFT`.
+- The BOM must contain at least one valid component line.
+- All referenced items must be active in the required scope.
+- Manufactured-child references must not create a direct or indirect circular structure.
+- Overlapping active effectivity windows for the same parent item and scope are rejected unless selection remains unambiguous.
+- Activation preserves any already released production-order snapshots from other versions.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{BOM exists and is DRAFT?}
+    B -->|No| C[Return BOM_NOT_ACTIVATABLE]
+    B -->|Yes| D[Validate component readiness]
+    D --> E[Check circular references]
+    E --> F[Check effectivity conflicts]
+    F --> G[Set status to ACTIVE]
+    G --> H[Return active BOM]
+```
+
+## External Dependencies
+
+- [detectBillOfMaterialCircularReference](../queries/DetectBillOfMaterialCircularReference.md) - Prevent cyclical manufactured-item structures.
+
+## Error Scenarios
+
+- **BOM_NOT_FOUND**: Target BOM does not exist.
+- **BOM_NOT_ACTIVATABLE**: The BOM is not in `DRAFT`.
+- **COMPONENT_LINE_REQUIRED**: The BOM has no component lines.
+- **COMPONENT_ITEM_INACTIVE**: A referenced component is inactive.
+- **CIRCULAR_BOM_REFERENCE**: A direct or indirect manufactured-item loop was detected.
+- **EFFECTIVITY_CONFLICT**: Activation would create conflicting active effectivity windows.
+
+## Test Cases
+
+- activates a valid draft BOM
+- returns error when the BOM does not exist
+- returns error when the BOM is not in `DRAFT`
+- returns error when the BOM has no component lines
+- returns error when a component item is inactive
+- returns error when a circular manufactured-item structure is detected
+- returns error when activation would create an effectivity conflict

package/src/modules/manufacturing/docs/commands/ActivateRouting.md

@@ -0,0 +1,48 @@
+# ActivateRouting
+
+## Overview
+
+ActivateRouting validates a draft routing and makes it eligible for production-order release. Activation enforces operation completeness, sequence integrity, and active work-center readiness.
+
+## Business Rules
+
+- Target routing must exist and be in `DRAFT`.
+- The routing must contain at least one operation.
+- Operation sequence numbers must be unique and ordered.
+- Every referenced work center must be active and within the same company.
+- Activation preserves existing operation snapshots already frozen on released orders.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Routing exists and is DRAFT?}
+    B -->|No| C[Return ROUTING_NOT_ACTIVATABLE]
+    B -->|Yes| D[Validate operations]
+    D --> E[Validate work-center readiness]
+    E --> F[Set status to ACTIVE]
+    F --> G[Return active routing]
+```
+
+## External Dependencies
+
+- [WorkCenter](../models/WorkCenter.md) - Referenced work centers must already be active.
+
+## Error Scenarios
+
+- **ROUTING_NOT_FOUND**: Target routing does not exist.
+- **ROUTING_NOT_ACTIVATABLE**: The routing is not in `DRAFT`.
+- **OPERATION_REQUIRED**: The routing has no operations.
+- **DUPLICATE_OPERATION_SEQUENCE**: Two operations use the same sequence number.
+- **WORK_CENTER_NOT_ACTIVE**: A referenced work center is inactive.
+- **CROSS_COMPANY_WORK_CENTER**: A work center belongs to a different company scope.
+
+## Test Cases
+
+- activates a valid draft routing
+- returns error when the routing does not exist
+- returns error when the routing is not in DRAFT
+- returns error when the routing has no operations
+- returns error when operation sequence numbers are duplicated
+- returns error when a referenced work center is inactive
+- returns error when a referenced work center is outside the routing company

package/src/modules/manufacturing/docs/commands/ActivateWorkCenter.md

@@ -0,0 +1,49 @@
+# ActivateWorkCenter
+
+## Overview
+
+ActivateWorkCenter validates that a draft or inactive work center has the execution data required by planning and costing, then marks it available for routing and work-order use.
+
+## Business Rules
+
+- Target work center must exist.
+- Only `DRAFT` or `INACTIVE` work centers can be activated.
+- Required calendar or availability context must be present.
+- Capacity must be positive.
+- Any configured rates and overhead settings must be internally valid.
+- Activation makes the work center eligible for active routing operations.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Work center exists?}
+    B -->|No| C[Return WORK_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status activatable?}
+    D -->|No| E[Return WORK_CENTER_NOT_ACTIVATABLE]
+    D -->|Yes| F[Validate calendar, capacity, and rates]
+    F --> G[Set status to ACTIVE]
+    G --> H[Return active work center]
+```
+
+## External Dependencies
+
+- [Site](../../../organization/docs/models/Site.md) - Site-scoped activation requires a valid site context.
+
+## Error Scenarios
+
+- **WORK_CENTER_NOT_FOUND**: Target work center does not exist.
+- **WORK_CENTER_NOT_ACTIVATABLE**: The current status does not allow activation.
+- **MISSING_CALENDAR_CONTEXT**: Required calendar or availability data is missing.
+- **INVALID_CAPACITY**: Capacity is zero or negative.
+- **INVALID_RATE**: Labor or machine rate is negative.
+- **OVERHEAD_CURRENCY_REQUIRED**: Fixed-amount overhead requires a currency.
+
+## Test Cases
+
+- activates a valid draft work center
+- reactivates a valid inactive work center
+- returns error when the work center does not exist
+- returns error when the status does not allow activation
+- returns error when required calendar context is missing
+- returns error when capacity is not positive

package/src/modules/manufacturing/docs/commands/CancelProductionOrder.md

@@ -0,0 +1,48 @@
+# CancelProductionOrder
+
+## Overview
+
+CancelProductionOrder abandons a draft or not-yet-started released order. It preserves audit history while blocking further execution updates and cascading cancellation to pending work orders.
+
+## Business Rules
+
+- Target order must exist.
+- Only `DRAFT` or `RELEASED` orders may be cancelled.
+- Released orders cannot be cancelled once meaningful execution or inventory evidence exists.
+- Cancelling a released order cascades cancellation to pending work orders.
+- Cancelled orders reject all further execution, completion, and closeout commands.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Order exists?}
+    B -->|No| C[Return PRODUCTION_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status cancellable?}
+    D -->|No| E[Return PRODUCTION_ORDER_NOT_CANCELLABLE]
+    D -->|Yes| F{Execution or inventory evidence exists?}
+    F -->|Yes| G[Return EXECUTION_ALREADY_STARTED]
+    F -->|No| H[Cancel order and pending work orders]
+    H --> I[Return cancelled order]
+```
+
+## External Dependencies
+
+- [WorkOrder](../models/WorkOrder.md) - Pending child work orders are cancelled with the parent order.
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_NOT_FOUND**: Target order does not exist.
+- **PRODUCTION_ORDER_NOT_CANCELLABLE**: The current status does not allow cancellation.
+- **EXECUTION_ALREADY_STARTED**: Work-order execution evidence already exists.
+- **INVENTORY_HANDOFF_EXISTS**: Inventory issue or receipt evidence already exists.
+
+## Test Cases
+
+- cancels a draft production order
+- cancels a released order before execution starts
+- returns error when the order does not exist
+- returns error when the status does not allow cancellation
+- returns error when execution evidence already exists
+- returns error when inventory handoff evidence already exists
+- cascades cancellation to pending work orders

package/src/modules/manufacturing/docs/commands/CloseProductionOrder.md

@@ -0,0 +1,46 @@
+# CloseProductionOrder
+
+## Overview
+
+CloseProductionOrder performs the final administrative close after technical completion and downstream cost settlement are done. The command is the last lifecycle step for the production order.
+
+## Business Rules
+
+- Target order must exist and be in `TECHNICALLY_COMPLETE`.
+- All open work orders and execution exceptions must already be resolved.
+- The linked manufacturing cost summary must be in `SETTLED`.
+- Closed orders reject further execution, reopen, or rescheduling commands.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close request] --> B{Order exists and is TECHNICALLY_COMPLETE?}
+    B -->|No| C[Return PRODUCTION_ORDER_NOT_CLOSABLE]
+    B -->|Yes| D{Open work or exceptions remain?}
+    D -->|Yes| E[Return OPEN_WORK_REMAINS]
+    D -->|No| F{Cost summary settled?}
+    F -->|No| G[Return COST_SUMMARY_NOT_SETTLED]
+    F -->|Yes| H[Set order status to CLOSED]
+    H --> I[Return closed order]
+```
+
+## External Dependencies
+
+- [ManufacturingCostSummary](../models/ManufacturingCostSummary.md) - Administrative close depends on settled variance review.
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_NOT_FOUND**: Target order does not exist.
+- **PRODUCTION_ORDER_NOT_CLOSABLE**: The order is not in `TECHNICALLY_COMPLETE`.
+- **OPEN_WORK_REMAINS**: Open work orders or execution exceptions still exist.
+- **COST_SUMMARY_NOT_SETTLED**: The linked cost summary is not in `SETTLED`.
+
+## Test Cases
+
+- closes a technically complete order with a settled cost summary
+- returns error when the order does not exist
+- returns error when the order is not technically complete
+- returns error when open work or execution exceptions remain
+- returns error when the linked cost summary is not settled
+- blocks further execution commands after close

package/src/modules/manufacturing/docs/commands/CompleteProductionOrder.md

@@ -0,0 +1,48 @@
+# CompleteProductionOrder
+
+## Overview
+
+CompleteProductionOrder marks physical production complete once required work orders are finished and final receipt obligations are satisfied. The command freezes production execution while still allowing later technical completion and review.
+
+## Business Rules
+
+- Target order must exist and be in `IN_PROGRESS`.
+- All mandatory work orders must be completed.
+- Final output reporting must exist for the required good quantity.
+- Finished-goods or intermediate receipt handoff required by policy must already be submitted.
+- Completing the order blocks additional operational production work except through controlled reopen.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive complete request] --> B{Order exists and is IN_PROGRESS?}
+    B -->|No| C[Return PRODUCTION_ORDER_NOT_COMPLETABLE]
+    B -->|Yes| D{All required work orders complete?}
+    D -->|No| E[Return OPEN_WORK_ORDER_REMAINS]
+    D -->|Yes| F{Final reporting and receipt handoff complete?}
+    F -->|No| G[Return FINAL_RECEIPT_REQUIRED]
+    F -->|Yes| H[Set status to COMPLETED]
+    H --> I[Return completed order]
+```
+
+## External Dependencies
+
+- [WorkOrder](../models/WorkOrder.md) - Completion requires the operation-level plan to be done.
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_NOT_FOUND**: Target order does not exist.
+- **PRODUCTION_ORDER_NOT_COMPLETABLE**: The order is not in `IN_PROGRESS`.
+- **OPEN_WORK_ORDER_REMAINS**: One or more required work orders are still open.
+- **FINAL_OUTPUT_REQUIRED**: Final output reporting is incomplete.
+- **FINAL_RECEIPT_REQUIRED**: Required receipt handoff evidence is missing.
+
+## Test Cases
+
+- completes an in-progress order after all required work orders finish
+- returns error when the order does not exist
+- returns error when the order is not in `IN_PROGRESS`
+- returns error when required work orders remain open
+- returns error when final output reporting is incomplete
+- returns error when required receipt handoff evidence is missing