@tailor-platform/erp-kit 0.5.0 → 0.6.0

package/src/modules/manufacturing/docs/features/bill-of-material-management.md

@@ -0,0 +1,83 @@
+# Bill of Material Management
+
+## Overview
+
+Bill of Material Management defines the production recipe for a finished good or subassembly. A `BillOfMaterial` specifies which component items are required, in what quantities and units, under which version or effectivity window, with which expected scrap assumptions, and with which `bomType` explosion behavior. The feature supports multi-level manufacturing by allowing a component line to reference another manufactured item that has its own BOM.
+
+The BOM is manufacturing-owned master data, distinct from product templates and item identity. Product-management may describe the commercial definition of a product, and item-management owns the SKU that transactions reference, but manufacturing owns the recipe used to turn component stock into finished output. Production orders resolve and snapshot a BOM version at release time so future engineering changes do not silently alter in-flight work.
+
+Each `BillOfMaterial` must declare `bomType` as one of `MANUFACTURE`, `PHANTOM`, or `KIT`:
+
+- `MANUFACTURE`: The parent item is produced through the normal manufacturing path. BOM explosion preserves the parent as a make item, and released production orders may create lower-level production demand for manufactured child components according to planning policy.
+- `PHANTOM`: The parent item is a logical subassembly used for engineering structure, but manufacturing does not create a separate production order, WIP bucket, or finished-stock receipt for the phantom itself. BOM explosion flattens the phantom's child lines directly into the nearest released parent production order.
+- `KIT`: The parent item is an issue or packaging structure, not a shop-floor build recipe. BOM explosion produces component demand and picking or issue requirements only; it does not create routing-based work orders or a standalone manufacturing execution path for the kit parent.
+
+## Business Purpose
+
+- Provide a single manufacturing-owned source of truth for how a finished good or subassembly is built
+- Support multi-level production by reusing subassembly BOMs inside higher-level BOMs
+- Classify BOMs by explosion behavior so the same structural master data can support make, phantom, and kit scenarios without redesign
+- Preserve engineering change control through versions and effectivity windows rather than destructive edits
+- Enable material requirement explosion for production-order planning and inventory handoff
+- Capture expected scrap or yield assumptions used for planning and variance comparison
+- Prevent inactive, circular, or invalid component structures from entering production execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create BillOfMaterial] --> B[Select finished item and company or site scope]
+    B --> C[Set bomType: MANUFACTURE, PHANTOM, or KIT]
+    C --> D[Add component lines with quantity, UoM, and scrap factor]
+    D --> E{Subassembly component?}
+    E -->|Yes| F[Reference manufactured child item BOM]
+    E -->|No| G[Use purchased or stocked component]
+    F --> H[Validate structure, effectivity, and circular references]
+    G --> H
+    H --> I{Valid?}
+    I -->|No| J[Correct line or version data]
+    J --> D
+    I -->|Yes| K[Activate BOM version]
+    K --> L[Production order or issue flow selects BOM]
+    L --> M{bomType?}
+    M -->|MANUFACTURE| N[Keep parent make item and snapshot recipe]
+    M -->|PHANTOM| O[Flatten child components into nearest parent order]
+    M -->|KIT| P[Explode to component issue list without work orders]
+```
+
+## Scenario Patterns
+
+- **Standard assembly recipe**: A planner defines the component list and quantities for a finished good that is assembled repeatedly using the same standard recipe
+- **Multi-level subassembly reuse**: A manufactured subassembly is defined once and referenced by several parent BOMs so planning can explode common lower-level demand consistently
+- **Phantom subassembly flattening**: A logical intermediate assembly is maintained for engineering readability, but its children are exploded directly into the parent production order without generating a separate shop-floor order
+- **Kit structure definition**: A bundled item keeps a BOM-owned component list for issue or packaging purposes while explicitly bypassing routing-based manufacturing execution
+- **Engineering revision cutover**: A new BOM version becomes effective on a future date while the previous version remains valid for already released production orders
+- **Site-specific recipe difference**: The same finished item has different default component mix or yield assumptions at two sites due to local equipment or supplier differences
+- **Scrap-aware planning**: A BOM line includes expected process loss so planned component requirements better match real production behavior
+- **Change freeze at release**: A production order snapshots the active BOM at release time so later BOM edits do not mutate in-flight manufacturing instructions
+
+The `bomType` classification is part of the released BOM snapshot. A released order must preserve not only the selected component structure, but also the explosion semantics that were in force when the order was released. Later edits to convert a BOM from `PHANTOM` to `MANUFACTURE`, or from `KIT` to `MANUFACTURE`, must not retroactively rewire previously released orders.
+
+## Test Cases
+
+- Creating a BOM for an ACTIVE finished item with at least one ACTIVE component line should succeed
+- A BOM must require `bomType` to be one of `MANUFACTURE`, `PHANTOM`, or `KIT`
+- A BOM line must require a positive component quantity and a unit of measure compatible with the component item definition
+- A BOM must reject direct or indirect circular references between parent and child manufactured items
+- Overlapping active BOM effectivity windows for the same finished item and scope should be rejected unless one version is explicitly non-default
+- Inactive items must not be added as new BOM components
+- A BOM can reference both stocked raw materials and manufactured subassemblies
+- Releasing a `MANUFACTURE` BOM should preserve the parent item as a producible order output rather than flattening it away
+- Releasing a `PHANTOM` BOM should flatten its child requirements into the nearest non-phantom parent order and must not create a separate production-order requirement for the phantom parent
+- Selecting a `KIT` BOM should explode component demand without generating routing-based work orders for the kit parent
+- Editing a BOM that is already snapshotted by a released production order must not change the snapshotted order recipe
+- Editing `bomType` on an active BOM after release must not mutate the type semantics already snapshotted onto open production orders
+- Deactivating a BOM version used by open production orders may prevent new selection but must not invalidate existing snapshots
+- BOM explosion for a multi-level structure should produce the correct lower-level component requirements
+- Only authorized manufacturing users should be able to create, revise, activate, or deactivate BOM versions
+
+## Reference Links
+
+- [Odoo Manufacturing BOM configuration](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/manufacturing/basic_setup/bill_configuration.html)
+- [Oracle Manufacturing work definitions overview](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25c/faumf/how-you-create-work-definitions.html)
+- [Rootstock manufacturing ERP overview](https://www.rootstock.com/manufacturing-erp-software/)

package/src/modules/manufacturing/docs/features/manufacturing-cost-and-variance.md

@@ -0,0 +1,191 @@
+# Manufacturing Cost and Variance
+
+## Overview
+
+Manufacturing Cost and Variance captures the planned and actual cost footprint of a production order without taking ownership of accounting postings. At release time, the module snapshots expected component, labor, machine, and overhead assumptions based on the selected BOM, routing, work-center rates, and inventory-owned planned material cost resolution. During execution, it accumulates actual material consumption values sourced from the named `InventoryIssueOutcomeEvent` contract plus actual time and quantity data from work orders.
+
+The feature compares actual results against the plan and classifies manufacturing variance so downstream accounting can decide how to post it. Manufacturing owns cost visibility at the order and operation level, including WIP-oriented progress context, but it does not create journal entries, settle balances, or close accounting periods. Those responsibilities remain outside the module. Manufacturing does, however, own the operational review lifecycle that blocks order close until variance review is complete and downstream accounting has acknowledged the settlement handoff.
+
+Planned overhead is not entered ad hoc per production order. It is derived from the overhead absorption policy configured on each referenced `WorkCenter`, then snapshotted onto the production order at release alongside labor and machine assumptions. This keeps overhead calculation deterministic and aligned to the capacity resource that drives the cost.
+
+Planned material cost is also not maintained as an editable manufacturing-owned field on BOM component lines in the initial scope. Manufacturing resolves the planned unit cost for each component from inventory-owned valuation data at release time, snapshots the resolved amount onto the production order cost baseline, and preserves that baseline even if valuation settings later change.
+
+## Business Purpose
+
+- Give planners and supervisors visibility into whether production is running to expected cost
+- Preserve the standard or planned cost assumptions that were in force when work was released
+- Distinguish price, usage, rate, efficiency, scrap, and yield-related variances at a level that downstream accounting can map to separate review or posting treatment
+- Support WIP-style progress visibility without forcing manufacturing to own general-ledger behavior
+- Provide a downstream accounting handoff contract backed by operational evidence rather than manual spreadsheet reconciliation
+- Make post-order review and continuous improvement possible through cost and variance history
+- Use an explicit overhead absorption rule so planned and actual overhead can be reproduced consistently during review
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Release Production Order] --> B[Snapshot planned material, labor, machine, and overhead cost]
+    B --> C[Execute material issues through inventory]
+    C --> D[Inventory emits InventoryIssueOutcomeEvent when issue valuation is final]
+    D --> E[Collect actual time and quantity from work orders]
+    E --> F[Accumulate actual cost by production order]
+    F --> G{Order completed?}
+    G -->|No| H[Show in-progress WIP-style cost view]
+    G -->|Yes| I[Order becomes TECHNICALLY_COMPLETE]
+    I --> J[PENDING_VARIANCE_REVIEW]
+    J --> K[Compare planned vs actual]
+    K --> L[Classify price, usage, rate, efficiency, scrap, and yield variance]
+    L --> M[VARIANCE_REVIEWED]
+    M --> N[Publish reviewed manufacturing cost summary for downstream accounting]
+    N --> O[SETTLED after downstream settlement acknowledgment]
+```
+
+Each production order owns one manufacturing cost summary that moves through a named lifecycle after execution is frozen. The initial scope uses these states:
+
+- `COLLECTING`: Planned baseline is snapshotted and actual material, labor, machine, and overhead evidence is still accumulating while the order is `RELEASED`, `IN_PROGRESS`, or `COMPLETED`
+- `PENDING_VARIANCE_REVIEW`: The production order has reached `TECHNICALLY_COMPLETE`, final variance can be calculated, and review is required before administrative close
+- `VARIANCE_REVIEWED`: An authorized reviewer has approved the final planned-versus-actual comparison, variance classification, and downstream handoff payload
+- `SETTLED`: Downstream accounting or financial close processing has acknowledged the reviewed handoff and the order is now eligible for final administrative close
+
+The allowed transitions are:
+
+- `COLLECTING -> PENDING_VARIANCE_REVIEW`
+- `PENDING_VARIANCE_REVIEW -> VARIANCE_REVIEWED`
+- `VARIANCE_REVIEWED -> SETTLED`
+
+The following enforcement rules apply:
+
+- A production order entering `TECHNICALLY_COMPLETE` must move its linked cost summary to `PENDING_VARIANCE_REVIEW`
+- `VARIANCE_REVIEWED` requires final variance recalculation against the frozen order baseline and an explicit reviewer action by a manufacturing or finance-review role
+- `SETTLED` requires a named downstream acknowledgment that the reviewed variance or WIP handoff was consumed by the accounting-owned settlement process; manufacturing records the acknowledgment but does not post the settlement itself
+- A production order must not transition from `TECHNICALLY_COMPLETE` to `CLOSED` until the linked cost summary is `SETTLED`
+- If execution must resume after review begins, the production order must be reopened and the cost summary must return to `COLLECTING` or a superseded draft state through a controlled workflow
+
+## Scenario Patterns
+
+- **Standard-cost comparison**: A production order is released using standard component and work-center assumptions, then reviewed against actual execution cost after completion
+- **Labor rate change**: Actual labor is booked at a different rate than the snapped standard, and the delta is isolated from pure time-overrun effects
+- **Labor or machine overrun**: An operation takes materially longer than its standard time, and the excess resource consumption is exposed as an efficiency variance instead of being mixed into a rate variance
+- **Material price change**: Inventory issues the same planned quantity at a different actual unit valuation than the snapped standard, and the delta is tracked separately from quantity over-consumption
+- **Material loss variance**: Actual issued component quantity exceeds the BOM expectation because of setup loss, damage, or poor yield, and the excess is tracked as usage rather than price variance
+- **Scrap-heavy production run**: Scrap reported during execution inflates actual cost per good unit and is classified separately from normal usage
+- **In-progress cost visibility**: Supervisors review cost accumulation on an order that has started but not yet completed to see whether it is trending off plan
+- **Accounting handoff after review**: Manufacturing finishes variance review, publishes summarized planned-versus-actual results for downstream accounting, and waits for settlement acknowledgment before the order can close
+- **Work-center overhead absorption**: Each work center may define one active overhead absorption rule, and released orders snapshot that rule so planned and actual overhead remain reproducible even if work-center master data changes later
+
+Manufacturing resolves each component's planned material cost through inventory-owned valuation contracts at release time. The required source rules are:
+
+- Manufacturing must query inventory for the component item's active valuation context at the production order's site or company scope
+- If the item's `ValuationPolicy.costingMethod` is `STANDARD_COST`, the planned unit cost must come from inventory's `ValuationPolicy.standardCostRate`
+- If the item's costing method is `AVCO` or `FIFO`, the planned unit cost baseline must come from inventory's current `GetItemValuation.costPerUnit` at release time
+- Manufacturing must snapshot the returned unit cost, currency, valuation method, and source valuation reference onto the released production order and must not recompute the baseline from later inventory changes
+- If inventory cannot resolve planned material cost for a required component, production-order release must be rejected rather than allowing manufacturing to invent a fallback cost
+
+This makes inventory the source of truth for planned material valuation while allowing manufacturing to own the frozen release-time baseline used for later variance comparison.
+
+Manufacturing consumes actual material cost only through the named `InventoryIssueOutcomeEvent` contract emitted by inventory after a goods issue or backflush movement reaches its inventory-owned final valuation state. The minimum payload is:
+
+- `productionOrderReference`
+- `workOrderReference`: optional for issue transactions recorded at order level rather than operation level
+- `inventoryIssueReference`
+- `itemReference`
+- `issuedQuantity`
+- `unitOfMeasure`
+- `actualUnitCost`
+- `actualExtendedCost`
+- `currency`
+- `valuationMethod`
+- `postingDate`
+- `siteReference`
+
+Optional and conditional fields:
+
+- `inventoryLotReference`: optional unless the issued quantity is lot-specific and manufacturing needs lot-cost traceability
+- `costLayerReferences`: optional list of cost-layer identifiers when valuation methods such as FIFO require traceability to multiple inventory layers
+- `issueMode`: optional classification such as `MANUAL_ISSUE` or `BACKFLUSH` for cost analysis without changing the financial result
+
+Inventory emits `InventoryIssueOutcomeEvent` only after the issue transaction is accepted, executed, and valued by inventory-owned logic. Manufacturing must not infer actual material cost from the issue request itself, from open stock movements, or from duplicated valuation formulas. If inventory rejects or has not yet valued the issue, manufacturing keeps the material cost pending rather than manufacturing its own fallback amount.
+
+When a cost summary reaches `VARIANCE_REVIEWED`, manufacturing publishes the reviewed settlement handoff to downstream accounting and waits for the named `ManufacturingCostSettlementAcknowledgment` contract before allowing the summary to move to `SETTLED`. The acknowledgment contract is owned and emitted by the downstream accounting or financial-close module or service, not by manufacturing. Manufacturing may persist the received acknowledgment for auditability, but it must not fabricate, edit, or mark the acknowledgment as received through a manufacturing-only toggle.
+
+The minimum `ManufacturingCostSettlementAcknowledgment` payload is:
+
+- `productionOrderReference`
+- `costSummaryReference`
+- `settledByReference`
+- `settlementDate`
+- `currency`
+
+Optional and conditional fields:
+
+- `settlementReference`: optional downstream settlement batch, journal, or close-run identifier used to trace the accounting-side action
+- `settledAmount`: optional when accounting settles an explicit amount and required if downstream policy allows partial or currency-translated settlement evidence
+- `companyReference`: optional when company scope is derivable from the production order and required otherwise
+- `siteReference`: optional when the settlement applies at company scope rather than site scope
+- `variancePostingReference`: optional identifier for the downstream posting or variance document created from the reviewed handoff
+
+The following contract rules apply:
+
+- `ManufacturingCostSettlementAcknowledgment` must reference a cost summary already in `VARIANCE_REVIEWED`; an acknowledgment for any earlier lifecycle state is invalid
+- The payload must match the reviewed handoff's `productionOrderReference`, `costSummaryReference`, and settlement currency before manufacturing can transition the cost summary to `SETTLED`
+- If downstream accounting rejects, reverses, or supersedes the reviewed handoff, the cost summary must remain `VARIANCE_REVIEWED` until a valid replacement acknowledgment is received
+- `TECHNICALLY_COMPLETE -> CLOSED` remains blocked until manufacturing records a valid `ManufacturingCostSettlementAcknowledgment` for the linked cost summary
+
+The `CostVariance` taxonomy must be granular enough to avoid mixing price deltas with usage or efficiency deltas. The initial scope replaces the coarse `material` and `labor_machine` buckets with the following categories:
+
+- `MATERIAL_PRICE`: Actual material unit valuation differs from the snapped planned unit cost for the consumed quantity
+- `MATERIAL_USAGE`: Actual material quantity consumed differs from the BOM-based planned quantity after normalizing to the snapped planned unit cost
+- `LABOR_RATE`: Actual labor cost-per-hour differs from the snapped labor rate for the reported hours
+- `LABOR_EFFICIENCY`: Actual labor hours differ from the snapped standard hours after normalizing to the snapped labor rate
+- `MACHINE_RATE`: Actual machine rate differs from the snapped machine cost rate for the reported machine hours
+- `MACHINE_EFFICIENCY`: Actual machine hours differ from the snapped standard machine hours after normalizing to the snapped machine rate
+- `SCRAP`: Cost attributable to reported scrap transactions that should remain visible separately from normal material usage
+- `YIELD`: Cost impact caused by producing fewer good units than planned after material and resource consumption are applied
+
+Each variance category must support a distinct downstream variance-account reference from `coa-management`. Manufacturing owns the classification and reference data needed for handoff, while downstream accounting decides whether to post, aggregate, or settle those balances.
+
+Manufacturing supports a single active overhead absorption rule per `WorkCenter`. The policy is owned by manufacturing as part of `WorkCenter` master data because the rate follows the resource or line used to perform work, not the warehouse or accounting module. A work center may define:
+
+- `overheadAbsorptionMethod`: one of `PERCENT_OF_LABOR_COST`, `PERCENT_OF_MACHINE_COST`, or `FIXED_AMOUNT_PER_GOOD_UNIT`
+- `overheadAbsorptionRate`: the numeric rate or amount interpreted by the selected method
+- `overheadAbsorptionCurrency`: required when the method is `FIXED_AMOUNT_PER_GOOD_UNIT`
+
+The initial scope uses these rules:
+
+- `PERCENT_OF_LABOR_COST`: planned or actual overhead equals labor cost multiplied by the configured percentage
+- `PERCENT_OF_MACHINE_COST`: planned or actual overhead equals machine cost multiplied by the configured percentage
+- `FIXED_AMOUNT_PER_GOOD_UNIT`: planned or actual overhead equals good quantity reported multiplied by the configured amount per unit
+
+When a production order is released, manufacturing snapshots the resolved work-center overhead method, rate, and currency onto the order or operation cost baseline. Later edits to the work center must not mutate released orders. During execution, actual overhead uses the same snapped method with actual reported labor cost, machine cost, or completed good quantity as the driver. Work centers without an overhead absorption rule contribute zero planned and zero actual overhead.
+
+## Test Cases
+
+- Releasing a production order must snapshot the planned material and routing-based cost assumptions used for later variance comparison
+- Releasing a production order must resolve each component's planned unit cost from inventory-owned valuation data rather than from a manufacturing-edited BOM cost field
+- A STANDARD_COST component must snapshot inventory `ValuationPolicy.standardCostRate` as its planned unit cost at release
+- An AVCO or FIFO component must snapshot the release-time `GetItemValuation.costPerUnit` returned by inventory as its planned unit cost baseline
+- Production-order release must be rejected when inventory cannot resolve planned material cost for a required component
+- Actual material cost used by manufacturing must come from `InventoryIssueOutcomeEvent` rather than duplicated manufacturing-owned valuation logic
+- `InventoryIssueOutcomeEvent` must not be accepted as actual material cost input until the referenced inventory issue has completed inventory-owned valuation
+- Actual labor or machine cost should derive from reported time and the applicable work-center rates in force for the order snapshot
+- Moving a cost summary to `PENDING_VARIANCE_REVIEW` should require that the parent production order is `TECHNICALLY_COMPLETE`
+- Moving a cost summary to `VARIANCE_REVIEWED` should require an explicit reviewer approval and freeze the reviewed variance breakdown unless the order is reopened
+- Moving a cost summary to `SETTLED` should require a valid `ManufacturingCostSettlementAcknowledgment` rather than a manufacturing-only toggle
+- Planned overhead must derive from the released work center's snapped `overheadAbsorptionMethod` and `overheadAbsorptionRate`
+- Editing a work center's overhead absorption rule after release must not change the planned overhead baseline of an already released production order
+- Actual overhead must use the same snapped absorption method as the plan, substituting actual labor cost, machine cost, or completed good quantity as the driver
+- Planned and actual cost must be tracked independently per production order and company
+- Completing additional work after an order is marked closed should be rejected or require a controlled reopening workflow
+- Variance calculation should separate at minimum `MATERIAL_PRICE`, `MATERIAL_USAGE`, `LABOR_RATE`, `LABOR_EFFICIENCY`, and distinct scrap or yield-related causes rather than combining them into a single material or labor bucket
+- Variance handoff data must retain the variance category and its mapped variance-account reference for every published variance line
+- An in-progress production order should expose accumulated actual cost even before full completion
+- Manufacturing must not create journal entries or mutate GL balances directly as part of variance calculation
+- Downstream accounting handoff data should retain references to the production order, site, finished item, completed quantity, and variance breakdown
+- Manufacturing must not transition a reviewed cost summary to `SETTLED` until `ManufacturingCostSettlementAcknowledgment` is received from the accounting-owned settlement process with matching order and cost-summary references
+- Only authorized manufacturing or finance-review users should be able to finalize cost review, mark the summary `VARIANCE_REVIEWED`, and advance the order toward administrative close
+
+## Reference Links
+
+- [Oracle work orders overview](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25d/faumf/overview-of-work-orders.html)
+- [MRPeasy manufacturing scheduling and costing overview](https://www.mrpeasy.com/manufacturing-scheduling-software/)
+- [Rootstock manufacturing ERP overview](https://www.rootstock.com/manufacturing-erp-software/)

package/src/modules/manufacturing/docs/features/production-order-lifecycle.md

@@ -0,0 +1,103 @@
+# Production Order Lifecycle
+
+## Overview
+
+Production Order Lifecycle governs how a manufacturing request is created, planned, released, executed, and closed. A `ProductionOrder` records what item should be produced, at what quantity, for which company and site, against which BOM and routing definition, and on which planned dates. It is the manufacturing control document that turns a planning decision into executable shop-floor work.
+
+The production order tracks both control state and execution progress. Release freezes the selected BOM and routing into an order snapshot, generates operation-level work orders, and prepares material requirements for inventory coordination. Subsequent work-order reporting, material issue, scrap, and completion update production progress until the order is physically completed, marked `TECHNICALLY_COMPLETE` for cost and administrative review, and then formally closed.
+
+## Business Purpose
+
+- Turn manual planner intent or upstream demand signals into a controlled manufacturing commitment
+- Freeze recipe and process assumptions at release time so execution stays auditable
+- Provide a single source of truth for planned quantity, completed quantity, scrap quantity, and remaining open work
+- Coordinate material readiness, work-order generation, and production scheduling around one document
+- Support make-to-stock and make-to-order scenarios without moving sales or purchasing ownership into manufacturing
+- Prevent incomplete, invalid, or unauthorized production requests from reaching execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Production Order] --> B[DRAFT]
+    B --> C[Select item, quantity, site, BOM, routing, and dates]
+    C --> D{Ready to release?}
+    D -->|No| C
+    D -->|Yes| E[RELEASED]
+    E --> F[Snapshot BOM and routing]
+    F --> G[Generate work orders and material requirements]
+    G --> H{Execution started?}
+    H -->|No| I[Remain RELEASED or reschedule]
+    H -->|Yes| J[IN_PROGRESS]
+    J --> K{Completed quantity and final receipt posted?}
+    K -->|No| J
+    K -->|Yes| L[COMPLETED]
+    L --> M[Freeze execution and mark TECHNICALLY_COMPLETE]
+    M --> N[Review variances and administrative exceptions]
+    N --> O{Cost review settled?}
+    O -->|No| N
+    O -->|Yes| P[CLOSED]
+    B --> Q[CANCELLED]
+    E --> Q
+```
+
+The `ProductionOrder.status` lifecycle in the initial scope is:
+
+- `DRAFT`: Planner can create, edit, or delete the order before any execution commitment exists
+- `RELEASED`: BOM and routing are snapshotted, work orders are generated, and the order is ready for shop-floor execution
+- `IN_PROGRESS`: At least one work order has started or execution evidence exists against the order
+- `COMPLETED`: Physical production is complete because required work orders, final output reporting, and finished-goods receipt handoff have been submitted
+- `TECHNICALLY_COMPLETE`: The order is execution-frozen and no additional production activity is expected, but cost review, variance approval, and downstream accounting handoff are still pending
+- `CLOSED`: Administrative close is finished after the linked manufacturing cost summary reaches its required settled state
+- `CANCELLED`: The order is abandoned before meaningful execution and cannot accept further execution updates
+
+The allowed transitions are:
+
+- `DRAFT -> RELEASED`
+- `DRAFT -> CANCELLED`
+- `RELEASED -> IN_PROGRESS`
+- `RELEASED -> CANCELLED`
+- `RELEASED -> DRAFT` only through an explicit controlled unrelease or replan workflow if no execution evidence exists
+- `IN_PROGRESS -> COMPLETED`
+- `COMPLETED -> TECHNICALLY_COMPLETE`
+- `TECHNICALLY_COMPLETE -> CLOSED`
+
+The following gating rules apply:
+
+- `COMPLETED` requires all mandatory work orders complete plus the final output reporting and receipt handoff required by policy
+- `TECHNICALLY_COMPLETE` requires that no additional execution, rescheduling, or material issue is still expected on the order
+- `CLOSED` requires the linked manufacturing cost summary to finish variance review and reach its settled lifecycle state through a recorded `ManufacturingCostSettlementAcknowledgment`
+- Any attempt to resume execution after `TECHNICALLY_COMPLETE` must use a controlled reopen workflow rather than direct shop-floor updates
+
+## Scenario Patterns
+
+- **Make-to-stock replenishment**: A planner creates a production order to rebuild finished-goods inventory to target levels without linking ownership to a specific sales order
+- **Demand-driven production**: A production order is created in response to prioritized downstream demand while remaining a manufacturing-owned document
+- **Release after shortage review**: A planner keeps the order in draft until material availability and work-center timing are acceptable, then releases it for execution
+- **Reschedule before execution**: A released order is moved to a later date because a bottleneck work center or inbound material is not ready yet
+- **Partial completion**: A production order reports some finished quantity and scrap before the remaining balance is completed later
+- **Cancellation before execution**: A production order is cancelled because demand disappears and no meaningful execution or inventory posting has occurred yet
+- **Technical completion before close**: The order finishes physical production, then enters `TECHNICALLY_COMPLETE` so cost review and downstream settlement can occur without reopening shop-floor execution
+- **Close after review**: The order is closed only after variance review, `ManufacturingCostSettlementAcknowledgment`, and administrative checks are finished
+
+## Test Cases
+
+- Creating a production order for an ACTIVE manufactured item with positive quantity and valid company or site scope should succeed
+- A production order must not be released without an ACTIVE BOM and ACTIVE routing selection or resolvable default
+- Releasing a production order must snapshot the chosen BOM and routing definitions onto the order
+- Releasing a production order must create the expected work-order structure based on the snapshotted routing operations
+- A cancelled production order must not accept new execution updates
+- Rescheduling a production order should be allowed before execution starts and must remain auditable after release
+- Execution progress on work orders must roll up to production-order started, partial, or completed state correctly
+- Completing a production order should require final output reporting and the finished-goods receipt handoff required by policy
+- Marking a production order `TECHNICALLY_COMPLETE` should require that all planned execution is done and should block further shop-floor reporting unless the order is formally reopened
+- Closing a production order should be blocked while open work orders or unresolved execution exceptions remain
+- Closing a production order should be blocked until the linked manufacturing cost summary reaches `SETTLED` through a valid `ManufacturingCostSettlementAcknowledgment`
+- Production-order data must be isolated by company and must not reference BOMs, routings, or work centers from another company
+- Only authorized manufacturing users should be able to release, cancel, complete, technically complete, or close production 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 manufacturing features](https://www.odoo.com/app/manufacturing-features)
+- [SAP S/4HANA Cloud manufacturing overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD/2bba750d1e124e1ea2a039bb1cd9b6c5/03659e8e0c9d4f37afb3c5f3b37cabc3.html)

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.