@tailor-platform/erp-kit 0.5.1 → 0.6.0

package/src/modules/manufacturing/docs/features/routing-and-work-center-definition.md

@@ -0,0 +1,63 @@
+# Routing and Work Center Definition
+
+## Overview
+
+Routing and Work Center Definition captures how manufacturing work is performed and where capacity exists to perform it. A `Routing` defines the ordered set of operations required to produce an item, including sequence, standard setup or run times, instructions, and the work center expected to execute each step. A `WorkCenter` represents the machine, line, cell, or labor pool where operations are scheduled and reported.
+
+This feature establishes the execution structure used by production orders and work orders. Routing and work-center data drive planned lead time, operation sequencing, standard labor or machine cost, optional overhead absorption policy, and the work-order breakdown created when a production order is released. The initial scope supports deterministic step sequencing and capacity context, while deferring advanced optimization, parallel routing logic, and outsourced operations.
+
+## Business Purpose
+
+- Define a repeatable manufacturing process for each produced item or family of items
+- Associate each operation with the capacity and cost context required for planning and execution
+- Support realistic planned duration and standard-cost estimation before work begins
+- Provide operators and supervisors with step-level instructions and expected execution order
+- Create the basis for work-order generation and progress tracking at operation level
+- Prevent production from being released against incomplete or inactive process definitions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create WorkCenter] --> B[Set company or site scope, calendar, capacity, and rates]
+    B --> C[Activate WorkCenter]
+    C --> D[Create Routing]
+    D --> E[Add ordered operations with standard times and instructions]
+    E --> F[Assign each operation to a WorkCenter]
+    F --> G{Valid sequence and active centers?}
+    G -->|No| H[Correct routing or work-center data]
+    H --> E
+    G -->|Yes| I[Activate Routing]
+    I --> J[Production order selects routing]
+    J --> K[Release creates work orders by operation]
+```
+
+## Scenario Patterns
+
+- **Single-line assembly flow**: A finished item uses a simple routing with cut, assemble, inspect, and pack operations assigned to distinct work centers
+- **Shared bottleneck center**: Several routings reference the same constrained work center, allowing planners to see where capacity pressure will accumulate
+- **Site-specific process**: The same manufactured item uses different routings at different sites because local equipment or labor specialization differs
+- **Instruction-driven operation**: An operation stores setup notes, drawings, or SOP-style instructions so execution users know the expected method
+- **Standard-time planning**: Standard setup and run time on routing operations provide the planned duration used for release and variance comparison
+- **Resource-based overhead policy**: A work center defines the overhead absorption method and rate used by manufacturing cost snapshots for orders executed on that resource
+- **Controlled process revision**: A routing is revised for future orders while open production orders continue using the snapshotted process they were released with
+
+## Test Cases
+
+- Creating a work center with a unique code within its company or site scope should succeed
+- A work center must require positive capacity assumptions and must not be activated while missing required calendar or status data
+- Creating a routing with at least one operation assigned to an ACTIVE work center should succeed
+- Routing operation sequence numbers must be unique within the routing
+- An ACTIVE routing must reject references to inactive or cross-company work centers
+- Standard setup and run times on an operation must be zero or greater
+- A work center may define one overhead absorption method and rate, which released production orders snapshot for later cost comparison
+- Releasing a production order should snapshot the selected routing and operation definitions onto generated work orders
+- Editing a routing after a production order is released must not mutate the released order's operation plan
+- Deactivating a work center that is referenced by future routings or open released work should be blocked or require controlled replacement
+- Only authorized manufacturing users should be able to activate, revise, or deactivate work centers and routings
+
+## Reference Links
+
+- [Odoo work centers and operations](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/manufacturing/advanced_configuration/using_work_centers.html)
+- [Oracle Manufacturing work definitions](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25c/faumf/how-you-create-work-definitions.html)
+- [SAP Digital Manufacturing routing documentation](https://help.sap.com/docs/sap-digital-manufacturing/execution/routing)

package/src/modules/manufacturing/docs/features/work-order-execution.md

@@ -0,0 +1,115 @@
+# Work Order Execution
+
+## Overview
+
+Work Order Execution tracks the operation-level progress of manufacturing work after a production order is released. A `WorkOrder` represents one executable routing step with assigned work-center context, planned quantity, status, actual start or finish data, and the execution evidence needed to move the parent production order forward. Work orders provide the operational unit for supervisors and operators to start, pause, report, and complete shop-floor activity.
+
+This feature also defines how manufacturing coordinates with inventory during execution. Material issue may occur explicitly before work starts or implicitly through backflush on completion, while final or intermediate output completion triggers receipt handoff to inventory. Scrap reported during execution can also trigger an inventory scrap handoff. Manufacturing owns the operational intent and recorded progress; inventory owns stock movement persistence, lot or serial state, and valuation consequences.
+
+## Business Purpose
+
+- Break a released production order into operation-level executable steps with clear status and ownership
+- Provide auditable tracking of actual start, stop, completion, quantity, time, and scrap at each operation
+- Support both manual material issue and backflush-style material consumption
+- Coordinate finished-goods or intermediate receipt with inventory without embedding warehouse ownership in manufacturing
+- Expose operation-level exceptions that explain why production is late, paused, or under-yielding
+- Roll execution progress into parent production-order status and cost collection
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Production Order Released] --> B[Open Work Orders by Operation]
+    B --> C[Start Work Order]
+    C --> D{Manual issue required?}
+    D -->|Yes| E[Send material issue request to inventory]
+    D -->|No| F[Continue execution]
+    E --> F
+    F --> G[Report time, completed qty, and scrap]
+    G --> H{Backflush at completion?}
+    H -->|Yes| I[Send backflush issue request to inventory]
+    H -->|No| J[Keep manual issue basis]
+    I --> J
+    J --> K{Final or intermediate output complete?}
+    K -->|Yes| L[Send production receipt handoff to inventory]
+    K -->|No| M[Move to next operation]
+    L --> M
+    M --> N{All required operations complete?}
+    N -->|No| C
+    N -->|Yes| O[Parent Production Order progresses toward completion]
+```
+
+## Scenario Patterns
+
+- **Pre-issued materials**: Components are issued to the line before the first operation starts, and the work order records execution without backflushing those same quantities again
+- **Backflush assembly**: Standard components are consumed automatically when an operation or order reports completion, reducing operator transaction burden
+- **Partial operation reporting**: An operator reports some completed quantity and some scrap, leaving the work order open for the remaining balance
+- **Paused bottleneck operation**: A work order is started, paused due to machine or staffing constraints, and later resumed with the pause history preserved
+- **Intermediate output step**: A routing produces an intermediate quantity at one operation that must be receipted before the next step continues
+- **Final receipt handoff**: The final operation completes and sends finished-goods receipt intent to inventory while keeping manufacturing as the owner of execution evidence
+- **Manufacturing scrap handoff**: A work order reports nonrecoverable scrap and sends a named scrap contract to inventory so stock and valuation can be reduced through the inventory-owned adjustment flow
+- **Exception note capture**: A supervisor records an exception reason on a delayed or abnormal work order to explain variance and schedule slippage
+
+Manufacturing uses two named handoff contracts during execution. `ManufacturingReceiptHandoff` is sent when a work order reports intermediate or finished output that must be receipted into inventory. The minimum payload is:
+
+- `productionOrderReference`
+- `workOrderReference`
+- `itemReference`
+- `quantity`
+- `unitOfMeasure`
+- `siteReference`
+- `postingDate`
+
+Optional and conditional fields:
+
+- `finishedGoodLotReference`: optional for non-lot-tracked items and required when the receipted item is lot-tracked
+- `storageLocationReference`: optional when inventory can derive the receiving location from site or production policy; otherwise required
+- `serialReferences`: required when the receipted item is serial-tracked and serial numbers are assigned before inventory confirmation
+
+Inventory owns final lot, serial, and storage persistence. Manufacturing owns only the execution evidence and the handoff intent. The same receipt handoff contract is used for both intermediate and final receipts.
+
+`ManufacturingScrapHandoff` is sent when a work order reports scrap that must reduce usable stock in inventory. The minimum payload is:
+
+- `productionOrderReference`
+- `workOrderReference`
+- `itemReference`
+- `scrapQuantity`
+- `unitOfMeasure`
+- `scrapReasonCode`
+- `siteReference`
+- `postingDate`
+
+Optional and conditional fields:
+
+- `sourceStorageLocationReference`: optional when inventory can derive the source location from prior issue or backflush context, or from a site-level manufacturing scrap policy; otherwise required
+- `inventoryLotReference`: required when the scrapped item is lot-tracked
+- `serialReferences`: required when the scrapped item is serial-tracked
+- `scrapDispositionCode`: optional classification used by downstream inventory or accounting policies
+
+Manufacturing creates the handoff once per submitted scrap transaction. Inventory is responsible for translating the handoff into an inventory-owned `InventoryAdjustment` approval flow and for rejecting the handoff if location, lot, or serial resolution is incomplete.
+
+For any stock-loss event that originates from manufacturing execution and can be traced to a `productionOrderReference` or `workOrderReference`, `ManufacturingScrapHandoff` is the only valid inventory path in the initial scope. A direct inventory `InventoryAdjustment` with reason code `Production Variance` is reserved for fallback situations where the manufacturing module is not deployed or the discrepancy is discovered after the fact with no resolvable manufacturing source document. This rule prevents the same physical production loss from being posted through two asymmetric flows and preserves work-order traceability.
+
+## Test Cases
+
+- Starting a work order should succeed only when its parent production order is in a releasable execution state
+- A work order must not be completed before it is started unless an explicit bypass policy exists
+- Reported completed quantity and scrap quantity must be zero or greater, and at least one must be positive for a completion transaction
+- Completing a work order must update parent production-order progress correctly
+- Material issue requested manually from manufacturing must call the downstream inventory contract exactly once per submitted issue transaction
+- Backflush consumption must not duplicate quantities already issued manually
+- Final or intermediate receipt handoff payloads must include production-order reference, work-order reference, item reference, quantity, unit of measure, site, and posting date at minimum
+- Receipt handoff must include `finishedGoodLotReference` whenever the receipted item is lot-tracked
+- Reporting positive scrap quantity must emit `ManufacturingScrapHandoff` exactly once per submitted scrap transaction
+- Scrap handoff payloads must include production-order reference, work-order reference, item reference, scrap quantity, unit of measure, scrap reason code, site, and posting date at minimum
+- Manufacturing-originated stock loss with a resolvable production-order or work-order reference must not bypass `ManufacturingScrapHandoff` through a direct inventory adjustment
+- A paused work order must be resumable without losing prior execution history
+- Completing a later sequential operation before a required earlier operation should be rejected unless the routing policy explicitly allows it
+- Work-order execution must remain isolated by company and site context
+- Only authorized manufacturing users should be able to start, pause, resume, report, or complete work orders
+
+## Reference Links
+
+- [Oracle work orders overview](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25d/faumf/overview-of-work-orders.html)
+- [Odoo work centers and manufacturing execution concepts](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/manufacturing/advanced_configuration/using_work_centers.html)
+- [SAP Digital Manufacturing execution routing](https://help.sap.com/docs/sap-digital-manufacturing/execution/routing)

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

@@ -0,0 +1,60 @@
+# BillOfMaterial
+
+## Description
+
+BillOfMaterial stores the manufacturing-owned recipe used to build one finished item or subassembly at company or site scope. It owns version identity, effectivity, `bomType`, default-selection behavior, and the component-line structure that production orders later snapshot at release time.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createBillOfMaterial
+    Draft --> Draft: updateBillOfMaterial
+    Draft --> Active: activateBillOfMaterial
+    Active --> Inactive: deactivateBillOfMaterial
+```
+
+### Command Definitions
+
+- [createBillOfMaterial](../commands/CreateBillOfMaterial.md) - Create a draft BOM version for one manufactured parent item.
+- [updateBillOfMaterial](../commands/UpdateBillOfMaterial.md) - Revise mutable draft metadata, effectivity, and component lines.
+- [activateBillOfMaterial](../commands/ActivateBillOfMaterial.md) - Validate the draft structure and make the version selectable for release.
+- [deactivateBillOfMaterial](../commands/DeactivateBillOfMaterial.md) - Prevent future selection while preserving existing production-order snapshots.
+
+### Query Definitions
+
+- [getBillOfMaterial](../queries/GetBillOfMaterial.md) - Retrieve one BOM version with component lines and effectivity details.
+- [explodeBillOfMaterial](../queries/ExplodeBillOfMaterial.md) - Expand one BOM version into multi-level component requirements on a specific effectivity date.
+- [listBillOfMaterialsByItem](../queries/ListBillOfMaterialsByItem.md) - List BOM versions for one parent item and scope.
+- [detectBillOfMaterialCircularReference](../queries/DetectBillOfMaterialCircularReference.md) - Detect direct or indirect loops across manufactured child items.
+
+### Models
+
+- BillOfMaterial
+- BillOfMaterialLine
+
+### Invariants
+
+- Every BOM version belongs to exactly one manufactured parent item and one company, with optional site-specific scope.
+- The parent item must be ACTIVE and manufacturable when the BOM is created or activated.
+- `bomType` must always be one of `MANUFACTURE`, `PHANTOM`, or `KIT`.
+- A draft or active BOM contains at least one component line with positive required quantity.
+- Component lines may reference stocked items or manufactured subassemblies, but inactive items cannot appear as newly added components.
+- Active BOM versions may only reference ACTIVE component items.
+- An active BOM must not introduce a direct or indirect circular manufactured-item reference.
+- Overlapping active effectivity windows for the same parent item and scope are allowed only when default-selection rules keep the active version unambiguous.
+- Production-order release snapshots the selected BOM version, lines, and `bomType` semantics so later BOM edits never mutate released work.
+
+### Relationships
+
+- **References Item (cross-module)**: `parentItemId` and component `itemId` point to [Item](../../../item-management/docs/models/Item.md).
+- **Belongs To Company and optional Site**: scope is constrained by [Company](../../../organization/docs/models/Company.md) and optionally [Site](../../../organization/docs/models/Site.md).
+- **Has Many BillOfMaterialLines**: component structure, scrap assumptions, and subassembly references live under the parent BOM version.
+- **Referenced By ProductionOrder**: [ProductionOrder](./ProductionOrder.md) resolves and snapshots one active BOM version at release.
+- **Depends On primitives**: component and parent quantities use primitives-owned unit-of-measure compatibility.

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

@@ -0,0 +1,66 @@
+# ManufacturingCostSummary
+
+## Description
+
+ManufacturingCostSummary stores the planned-versus-actual cost view for one production order without taking ownership of journal posting. It owns the frozen release-time baseline, accumulated actual material or resource evidence, variance-line classification, review lifecycle, and downstream settlement-acknowledgment traceability that gates final administrative close.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> COLLECTING: releaseProductionOrder
+    COLLECTING --> COLLECTING: recordInventoryIssueOutcome
+    COLLECTING --> PENDING_VARIANCE_REVIEW: technicallyCompleteProductionOrder
+    PENDING_VARIANCE_REVIEW --> VARIANCE_REVIEWED: reviewManufacturingCostSummary
+    PENDING_VARIANCE_REVIEW --> COLLECTING: reopenProductionOrder
+    VARIANCE_REVIEWED --> COLLECTING: reopenProductionOrder
+    VARIANCE_REVIEWED --> SETTLED: recordManufacturingCostSettlementAcknowledgment
+```
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Create the frozen planned baseline when the order is released.
+- [recordInventoryIssueOutcome](../commands/RecordInventoryIssueOutcome.md) - Apply inventory-valued material issue outcomes to actual cost accumulation.
+- [technicallyCompleteProductionOrder](../commands/TechnicallyCompleteProductionOrder.md) - Move the summary into variance-review status when execution is frozen.
+- [reviewManufacturingCostSummary](../commands/ReviewManufacturingCostSummary.md) - Recalculate and approve the final variance breakdown.
+- [reopenProductionOrder](../commands/ReopenProductionOrder.md) - Return the summary to active collection when execution is resumed.
+- [recordManufacturingCostSettlementAcknowledgment](../commands/RecordManufacturingCostSettlementAcknowledgment.md) - Persist downstream settlement evidence and unlock order close.
+
+### Query Definitions
+
+- [getManufacturingCostSummary](../queries/GetManufacturingCostSummary.md) - Retrieve one production order cost summary with planned, actual, and variance data.
+- [listManufacturingCostSummariesByStatus](../queries/ListManufacturingCostSummariesByStatus.md) - List summaries waiting for review or settlement queues.
+
+### Models
+
+- ManufacturingCostSummary
+- ManufacturingCostLine
+- CostVarianceLine
+- ManufacturingCostSettlementRecord
+
+### Invariants
+
+- Every production order owns exactly one manufacturing cost summary.
+- The planned material, labor, machine, and overhead baseline is frozen at release and never recomputed from later master-data changes.
+- Actual material cost enters the summary only through the named inventory-owned outcome contract after inventory valuation is final.
+- `PENDING_VARIANCE_REVIEW` and `VARIANCE_REVIEWED` summaries belong only to production orders that have already reached `TECHNICALLY_COMPLETE`.
+- `VARIANCE_REVIEWED` requires an explicit reviewer action and a frozen variance breakdown.
+- `SETTLED` requires a valid downstream acknowledgment whose order, summary, and currency match the reviewed handoff.
+- `COLLECTING` is the only state that accepts new actual cost accumulation from execution evidence.
+- If execution is reopened after review, the summary must return to `COLLECTING` rather than accumulating against a settled baseline.
+- Variance classification must keep at least `MATERIAL_PRICE`, `MATERIAL_USAGE`, `LABOR_RATE`, `LABOR_EFFICIENCY`, `MACHINE_RATE`, `MACHINE_EFFICIENCY`, `SCRAP`, and `YIELD` distinct.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: summary lifecycle is subordinate to one [ProductionOrder](./ProductionOrder.md).
+- **Consumes WorkOrder evidence**: actual labor, machine, quantity, and scrap signals originate from [WorkOrder](./WorkOrder.md) execution.
+- **Consumes InventoryIssueOutcomeEvent**: actual material cost arrives from the named inventory-owned issue valuation contract.
+- **Consumes settlement acknowledgment**: the reviewed handoff is settled through the named `ManufacturingCostSettlementAcknowledgment` contract from downstream accounting or financial close.
+- **References WorkCenter and BOM snapshots**: planned baseline uses released [WorkCenter](./WorkCenter.md) rates and [BillOfMaterial](./BillOfMaterial.md) component assumptions.
+- **References coa-management**: reviewed variance lines carry downstream account references from coa-management for settlement handoff.

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

@@ -0,0 +1,76 @@
+# ProductionOrder
+
+## Description
+
+ProductionOrder is the manufacturing control document that turns one planning decision into executable shop-floor work. It owns the produced item, planned quantity and dates, company or site scope, released snapshots of BOM and routing content, execution rollup from work orders, and the lifecycle that governs release, completion, technical completion, reopening, and administrative close.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> DRAFT: createProductionOrder
+    DRAFT --> DRAFT: updateProductionOrder
+    DRAFT --> RELEASED: releaseProductionOrder
+    DRAFT --> CANCELLED: cancelProductionOrder
+    RELEASED --> DRAFT: unreleaseProductionOrder
+    RELEASED --> RELEASED: rescheduleProductionOrder
+    RELEASED --> IN_PROGRESS: startWorkOrder
+    RELEASED --> CANCELLED: cancelProductionOrder
+    IN_PROGRESS --> IN_PROGRESS: reportWorkOrderProgress
+    IN_PROGRESS --> COMPLETED: completeProductionOrder
+    COMPLETED --> TECHNICALLY_COMPLETE: technicallyCompleteProductionOrder
+    TECHNICALLY_COMPLETE --> IN_PROGRESS: reopenProductionOrder
+    TECHNICALLY_COMPLETE --> CLOSED: closeProductionOrder
+```
+
+### Command Definitions
+
+- [createProductionOrder](../commands/CreateProductionOrder.md) - Create a draft production request with planning data.
+- [updateProductionOrder](../commands/UpdateProductionOrder.md) - Revise mutable draft planning fields before release.
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Freeze BOM and routing, create work orders, and open execution.
+- [unreleaseProductionOrder](../commands/UnreleaseProductionOrder.md) - Return a released order to draft when no execution evidence exists.
+- [rescheduleProductionOrder](../commands/RescheduleProductionOrder.md) - Move planned dates on a released order before execution starts.
+- [cancelProductionOrder](../commands/CancelProductionOrder.md) - Abandon the order before meaningful execution makes cancellation invalid.
+- [completeProductionOrder](../commands/CompleteProductionOrder.md) - Mark physical production complete after final reporting and receipt handoff.
+- [technicallyCompleteProductionOrder](../commands/TechnicallyCompleteProductionOrder.md) - Freeze execution and move the linked cost summary into review.
+- [reopenProductionOrder](../commands/ReopenProductionOrder.md) - Re-enable controlled execution after a technically complete or reviewed state.
+- [closeProductionOrder](../commands/CloseProductionOrder.md) - Perform final administrative close once the linked cost summary is settled.
+
+### Query Definitions
+
+- [getProductionOrder](../queries/GetProductionOrder.md) - Retrieve one production order with snapshots, progress, and closeout status.
+- [listProductionOrdersByStatus](../queries/ListProductionOrdersByStatus.md) - List production orders for planning, execution, or closeout queues.
+
+### Models
+
+- ProductionOrder
+- ProductionOrderMaterialRequirement
+- ProductionOrderBomSnapshot
+- ProductionOrderRoutingSnapshot
+- ProductionOrderCostBaseline
+
+### Invariants
+
+- Every production order belongs to exactly one company and one execution site.
+- The ordered item must be an ACTIVE manufacturable item and planned quantity must remain greater than zero.
+- BOM and routing references selected at release must belong to the same company and site scope as the production order.
+- Orders in `RELEASED`, `IN_PROGRESS`, `COMPLETED`, `TECHNICALLY_COMPLETE`, or `CLOSED` always carry immutable BOM and routing snapshots.
+- `CANCELLED` and `CLOSED` orders reject further shop-floor execution updates.
+- Entering `COMPLETED` requires the final output-reporting and receipt-handoff evidence required by policy.
+- Entering `TECHNICALLY_COMPLETE` requires that no additional execution, rescheduling, or material issue is still expected.
+- Entering `CLOSED` requires the linked [ManufacturingCostSummary](./ManufacturingCostSummary.md) to be in `SETTLED`.
+
+### Relationships
+
+- **References Item (cross-module)**: the produced item is an [Item](../../../item-management/docs/models/Item.md).
+- **Belongs To Company and Site**: execution scope is defined by [Company](../../../organization/docs/models/Company.md) and [Site](../../../organization/docs/models/Site.md).
+- **Snapshots BillOfMaterial**: release freezes one [BillOfMaterial](./BillOfMaterial.md) version and exploded component requirements.
+- **Snapshots Routing**: release freezes one [Routing](./Routing.md) revision and operation plan.
+- **Has Many WorkOrders**: released routing operations materialize into [WorkOrder](./WorkOrder.md) records.
+- **Owns One ManufacturingCostSummary**: cost collection and variance review are tracked in [ManufacturingCostSummary](./ManufacturingCostSummary.md).

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

@@ -0,0 +1,58 @@
+# Routing
+
+## Description
+
+Routing defines the ordered manufacturing process used to build one produced item or item family. It owns operation sequencing, standard setup and run assumptions, work-center assignment, operator instructions, and the revision that production orders later freeze into executable work orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createRouting
+    Draft --> Draft: updateRouting
+    Draft --> Active: activateRouting
+    Active --> Inactive: deactivateRouting
+```
+
+### Command Definitions
+
+- [createRouting](../commands/CreateRouting.md) - Create a draft routing for one manufactured item or scope.
+- [updateRouting](../commands/UpdateRouting.md) - Revise operation order, instructions, and work-center assignments while mutable.
+- [activateRouting](../commands/ActivateRouting.md) - Validate ordered operations and make the routing eligible for production-order release.
+- [deactivateRouting](../commands/DeactivateRouting.md) - Remove the routing from future selection without mutating released snapshots.
+
+### Query Definitions
+
+- [getRouting](../queries/GetRouting.md) - Retrieve one routing revision with ordered operations.
+- [listRoutingsByItem](../queries/ListRoutingsByItem.md) - List routing revisions available for one parent item and scope.
+
+### Models
+
+- Routing
+- RoutingOperation
+
+### Invariants
+
+- Every routing belongs to one company and targets one manufactured item or item family within an optional site scope.
+- The produced item must be ACTIVE and manufacturable when the routing is activated.
+- A draft or active routing contains at least one operation with a unique sequence number inside the routing.
+- Standard setup and run time values are always zero or greater.
+- Each operation references a work center that is valid for the same company and effective scope.
+- An active routing must not reference an inactive work center.
+- Active routing operations may only reference ACTIVE work centers.
+- Revisions for future orders may be created or activated without mutating any routing snapshot already frozen onto released production orders.
+- Deterministic sequencing is part of the routing definition in the initial scope, so operations execute in one ordered path rather than parallel branches.
+
+### Relationships
+
+- **References Item (cross-module)**: the produced parent item is an [Item](../../../item-management/docs/models/Item.md).
+- **Has Many RoutingOperations**: ordered step definitions live under the routing aggregate.
+- **References WorkCenter**: each operation is assigned to one [WorkCenter](./WorkCenter.md).
+- **Referenced By ProductionOrder**: [ProductionOrder](./ProductionOrder.md) snapshots one routing revision at release.
+- **Materializes Into WorkOrder**: released operation snapshots become [WorkOrder](./WorkOrder.md) records.

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

@@ -0,0 +1,56 @@
+# WorkCenter
+
+## Description
+
+WorkCenter represents the machine, line, cell, or labor pool where routing operations are planned and executed. It owns scope, capacity assumptions, calendar reference, standard labor or machine rates, and the optional overhead-absorption rule that manufacturing snapshots onto released orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createWorkCenter
+    Draft --> Draft: updateWorkCenter
+    Draft --> Active: activateWorkCenter
+    Active --> Active: updateWorkCenter
+    Active --> Inactive: deactivateWorkCenter
+    Inactive --> Active: activateWorkCenter
+```
+
+### Command Definitions
+
+- [createWorkCenter](../commands/CreateWorkCenter.md) - Create a draft work center with scope, capacity, and rate definitions.
+- [updateWorkCenter](../commands/UpdateWorkCenter.md) - Revise mutable master data, capacity assumptions, and overhead policy.
+- [activateWorkCenter](../commands/ActivateWorkCenter.md) - Validate readiness and move the work center into executable use.
+- [deactivateWorkCenter](../commands/DeactivateWorkCenter.md) - Prevent future routing or execution use while preserving history.
+
+### Query Definitions
+
+- [getWorkCenter](../queries/GetWorkCenter.md) - Retrieve one work center with cost and capacity context.
+- [listWorkCentersBySite](../queries/ListWorkCentersBySite.md) - List work centers available at one site or scoped facility.
+
+### Models
+
+- WorkCenter
+
+### Invariants
+
+- Work-center code is unique inside its company and effective site scope.
+- Capacity assumptions are always positive and expressed in one consistent planning unit.
+- An active work center must have the calendar, status, and cost fields required by release and execution flows.
+- Labor and machine rate assumptions are always zero or greater.
+- `overheadAbsorptionMethod` may be unset, but when set it must be one of `PERCENT_OF_LABOR_COST`, `PERCENT_OF_MACHINE_COST`, or `FIXED_AMOUNT_PER_GOOD_UNIT`.
+- `overheadAbsorptionCurrency` is required whenever the overhead method is `FIXED_AMOUNT_PER_GOOD_UNIT`.
+- Changes to work-center rates or overhead rules never mutate cost baselines already snapshotted on released production orders.
+
+### Relationships
+
+- **Belongs To Company and Site**: execution scope is constrained by [Company](../../../organization/docs/models/Company.md) and [Site](../../../organization/docs/models/Site.md).
+- **Referenced By Routing**: [Routing](./Routing.md) operations assign work to one work center.
+- **Referenced By WorkOrder**: released operation snapshots preserve work-center context on [WorkOrder](./WorkOrder.md).
+- **Feeds ManufacturingCostSummary**: labor, machine, and overhead assumptions roll into [ManufacturingCostSummary](./ManufacturingCostSummary.md).

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

@@ -0,0 +1,63 @@
+# WorkOrder
+
+## Description
+
+WorkOrder is the operation-level execution record created from a released production-order routing snapshot. It owns one executable step, its work-center context, planned and actual quantities, actual time, pause or exception history, and the execution lifecycle that drives progress rollup, inventory handoff, and cost accumulation.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: releaseProductionOrder
+    PENDING --> IN_PROGRESS: startWorkOrder
+    IN_PROGRESS --> IN_PROGRESS: reportWorkOrderProgress
+    IN_PROGRESS --> PAUSED: pauseWorkOrder
+    PAUSED --> IN_PROGRESS: resumeWorkOrder
+    IN_PROGRESS --> COMPLETE: completeWorkOrder
+    PENDING --> CANCELLED: cancelProductionOrder
+```
+
+### Command Definitions
+
+- [startWorkOrder](../commands/StartWorkOrder.md) - Start execution on one released work order.
+- [pauseWorkOrder](../commands/PauseWorkOrder.md) - Pause an in-progress work order with an exception reason.
+- [resumeWorkOrder](../commands/ResumeWorkOrder.md) - Resume a paused work order without losing prior history.
+- [reportWorkOrderProgress](../commands/ReportWorkOrderProgress.md) - Record partial quantities, time, scrap, and execution notes.
+- [completeWorkOrder](../commands/CompleteWorkOrder.md) - Finish the operation and emit required completion handoffs.
+- [cancelProductionOrder](../commands/CancelProductionOrder.md) - Cascade cancellation to pending work orders when the parent order is cancelled before execution.
+
+### Query Definitions
+
+- [getWorkOrder](../queries/GetWorkOrder.md) - Retrieve one work order with execution evidence and handoff status.
+- [listWorkOrdersByProductionOrder](../queries/ListWorkOrdersByProductionOrder.md) - List work orders under one production order in sequence order.
+- [listWorkOrdersByWorkCenter](../queries/ListWorkOrdersByWorkCenter.md) - List work orders assigned to one work center across production orders for bottleneck review.
+
+### Models
+
+- WorkOrder
+- WorkOrderExecutionEvent
+
+### Invariants
+
+- Every work order belongs to exactly one production order and one released routing-operation snapshot.
+- Every work order is created from a single sequential routing operation within the parent production order.
+- `plannedQuantity`, `completedQuantity`, `scrapQuantity`, and captured time values are always zero or greater.
+- A work order may move to `IN_PROGRESS` only while its parent production order is in an execution-capable state.
+- A work order in `PAUSED` preserves prior execution evidence and can resume without resetting accumulated quantities or time.
+- Completing a later sequential work order before its required predecessor is done is invalid unless the routing snapshot explicitly allows it.
+- Receipt and scrap handoffs must carry the production-order and work-order references that preserve manufacturing traceability.
+- `COMPLETE` and `CANCELLED` work orders reject further execution reporting.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: each work order is created under one [ProductionOrder](./ProductionOrder.md).
+- **References Routing and WorkCenter snapshots**: executable operation context comes from released [Routing](./Routing.md) and [WorkCenter](./WorkCenter.md) data.
+- **Emits ManufacturingReceiptHandoff**: completion reporting sends the named receipt contract to inventory.
+- **Emits ManufacturingScrapHandoff**: scrap reporting sends the named scrap contract to inventory.
+- **Feeds ManufacturingCostSummary**: actual time, quantity, and scrap roll up into [ManufacturingCostSummary](./ManufacturingCostSummary.md).

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

@@ -0,0 +1,39 @@
+# DetectBillOfMaterialCircularReference
+
+## Overview
+
+DetectBillOfMaterialCircularReference checks whether adding or activating a manufactured-child component would introduce a direct or indirect loop in the BOM graph.
+
+## Business Rules
+
+- Company scope and both item references are required.
+- The query traverses only manufactured-child BOM references.
+- The result returns whether a loop exists and the detected item path when one is found.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive company and item references] --> B[Traverse manufactured-child BOM graph]
+    B --> C{Loop found?}
+    C -->|Yes| D[Return loop path]
+    C -->|No| E[Return no circular reference]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided.
+- **ITEM_REFERENCE_REQUIRED**: Parent or child item reference is missing.
+
+## Test Cases
+
+- detects a direct BOM loop
+- detects an indirect BOM loop across multiple subassemblies
+- returns no loop when the graph is acyclic
+- scopes detection to the requested company
+- returns error when parent or child reference is missing
+- returns error when company scope is missing