@tailor-platform/erp-kit 0.5.1 → 0.6.0

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

@@ -0,0 +1,48 @@
+# UpdateBillOfMaterial
+
+## Overview
+
+UpdateBillOfMaterial revises mutable draft BOM content before activation. It supports changes to effectivity, default flags, `bomType`, and component lines while preserving released production-order snapshots.
+
+## Business Rules
+
+- Target BOM must exist.
+- Only `DRAFT` BOM versions are mutable through this command.
+- Updated component lines must still satisfy positive quantity and unit compatibility rules.
+- Inactive items cannot be introduced as new components.
+- Changing effectivity or default selection must not create an ambiguous active-selection plan once activated.
+- Updating a draft BOM must not alter any production-order snapshot already taken from another version.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{BOM exists?}
+    B -->|No| C[Return BOM_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return BOM_NOT_MUTABLE]
+    D -->|Yes| F[Validate revised fields and lines]
+    F --> G[Persist updated draft]
+    G --> H[Return updated BOM]
+```
+
+## External Dependencies
+
+- [Item](../../../item-management/docs/models/Item.md) - Any newly referenced component item must remain valid.
+
+## Error Scenarios
+
+- **BOM_NOT_FOUND**: Target BOM does not exist.
+- **BOM_NOT_MUTABLE**: The BOM is not in `DRAFT`.
+- **INVALID_COMPONENT_QUANTITY**: A revised component quantity is zero or negative.
+- **COMPONENT_ITEM_INACTIVE**: A new component references an inactive item.
+- **AMBIGUOUS_EFFECTIVITY_RULE**: Revised effectivity or default flags would create ambiguous selection behavior.
+
+## Test Cases
+
+- updates draft BOM metadata and component lines
+- returns error when the BOM does not exist
+- returns error when the BOM is not in `DRAFT`
+- returns error when a revised component quantity is invalid
+- returns error when a newly referenced component is inactive
+- returns error when effectivity changes would create ambiguous selection

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

@@ -0,0 +1,48 @@
+# UpdateProductionOrder
+
+## Overview
+
+UpdateProductionOrder revises mutable draft planning fields such as dates, quantity, and preferred BOM or routing before release freezes execution assumptions.
+
+## Business Rules
+
+- Target production order must exist.
+- Only `DRAFT` orders are mutable through this command.
+- Planned quantity must remain greater than zero.
+- Produced item, company, and site identity are immutable after creation.
+- Optional BOM or routing references must remain within the same company and site scope.
+- Updating a draft order does not create work orders or cost baselines.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Order exists?}
+    B -->|No| C[Return PRODUCTION_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return PRODUCTION_ORDER_NOT_MUTABLE]
+    D -->|Yes| F[Validate revised planning fields]
+    F --> G[Persist draft changes]
+    G --> H[Return updated order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_NOT_FOUND**: Target order does not exist.
+- **PRODUCTION_ORDER_NOT_MUTABLE**: The order is not in `DRAFT`.
+- **INVALID_PLANNED_QUANTITY**: Planned quantity is zero or negative.
+- **IMMUTABLE_SCOPE_FIELD**: The request attempts to change produced item or company or site identity.
+- **CROSS_SCOPE_MASTER_REFERENCE**: BOM or routing reference belongs to another company or site.
+
+## Test Cases
+
+- updates draft planning fields on a production order
+- returns error when the order does not exist
+- returns error when the order is not in `DRAFT`
+- returns error when planned quantity is not positive
+- returns error when immutable scope identity is changed
+- returns error when BOM or routing references are out of scope

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

@@ -0,0 +1,52 @@
+# UpdateRouting
+
+## Overview
+
+UpdateRouting revises mutable draft routing content before activation. It supports operation resequencing, instruction changes, and work-center reassignment while preserving snapshots already frozen on released production orders.
+
+## Business Rules
+
+- Target routing must exist.
+- Only `DRAFT` routings are mutable through this command.
+- Revised operation sequence numbers must remain unique.
+- Revised standard times must be zero or greater.
+- Every referenced work center must exist in the same company scope.
+- Updating a routing never mutates operation snapshots already copied onto released work orders.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Routing exists?}
+    B -->|No| C[Return ROUTING_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return ROUTING_NOT_MUTABLE]
+    D -->|Yes| F[Validate revised operations]
+    F --> G[Persist draft changes]
+    G --> H[Return updated routing]
+```
+
+## External Dependencies
+
+- [Item](../../../item-management/docs/models/Item.md) - The routing remains scoped to one manufactured parent item.
+- [WorkCenter](../models/WorkCenter.md) - Revised operations must continue to reference valid work centers.
+
+## Error Scenarios
+
+- **ROUTING_NOT_FOUND**: Target routing does not exist.
+- **ROUTING_NOT_MUTABLE**: The routing is not in `DRAFT`.
+- **DUPLICATE_OPERATION_SEQUENCE**: Two operations use the same sequence number.
+- **INVALID_STANDARD_TIME**: Setup or run time is negative.
+- **WORK_CENTER_NOT_FOUND**: A referenced work center does not exist.
+- **CROSS_COMPANY_WORK_CENTER**: A work center belongs to a different company scope.
+
+## Test Cases
+
+- updates draft routing operations
+- returns error when the routing does not exist
+- returns error when the routing is not in DRAFT
+- returns error when revised sequence numbers conflict
+- returns error when a revised standard time is negative
+- returns error when a referenced work center does not exist
+- returns error when a referenced work center is outside the routing company
+- preserves released routing snapshots after update

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

@@ -0,0 +1,48 @@
+# UpdateWorkCenter
+
+## Overview
+
+UpdateWorkCenter revises mutable work-center master data such as capacity, calendar, rate assumptions, and overhead policy. The command keeps existing production-order cost snapshots immutable even when active master data changes.
+
+## Business Rules
+
+- Target work center must exist.
+- Draft and active work centers may be updated.
+- Scope identity and unique code remain immutable after creation.
+- Capacity must remain positive.
+- Labor and machine rates must be zero or greater.
+- Fixed-amount overhead requires a currency.
+- Updates do not retroactively change released production-order baselines.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Work center exists?}
+    B -->|No| C[Return WORK_CENTER_NOT_FOUND]
+    B -->|Yes| D[Validate mutable fields]
+    D --> E[Persist work center changes]
+    E --> F[Return updated work center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WORK_CENTER_NOT_FOUND**: Target work center does not exist.
+- **IMMUTABLE_SCOPE_FIELD**: The request attempts to change immutable scope or code fields.
+- **INVALID_CAPACITY**: Capacity is zero or negative.
+- **INVALID_RATE**: Labor or machine rate is negative.
+- **INVALID_OVERHEAD_METHOD**: Overhead method is not supported.
+- **OVERHEAD_CURRENCY_REQUIRED**: Fixed-amount overhead requires a currency.
+
+## Test Cases
+
+- updates an active work center without changing scope identity
+- returns error when the work center does not exist
+- returns error when immutable scope fields are changed
+- returns error when capacity is not positive
+- returns error when a rate is negative
+- preserves released cost baselines after update

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)