@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/inventory/docs/commands/UpdateStorageLocation.md

@@ -0,0 +1,41 @@
+# UpdateStorageLocation
+
+## Overview
+
+updateStorageLocation modifies the mutable fields of a storage location, including name, code, storageCondition, and capacity. The warehouseId, parentId, and locationType are immutable after creation.
+
+## Business Rules
+
+- Storage location must exist
+- Name and code must remain unique within the warehouse if changed
+- warehouseId, parentId, and locationType are immutable after creation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Location exists?}
+    B -->|No| C[Return error: STORAGE_LOCATION_NOT_FOUND]
+    B -->|Yes| D{Name or code changed?}
+    D -->|Yes| E{New name/code unique in warehouse?}
+    E -->|No| F[Return error: DUPLICATE_LOCATION_NAME]
+    E -->|Yes| G[Update location record]
+    D -->|No| G
+    G --> H[Return updated location]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **DUPLICATE_LOCATION_NAME**: A location with the new name or code already exists in the warehouse
+
+## Test Cases
+
+- returns error when location not found
+- returns error when new name conflicts
+- updates location name
+- updates storage condition

package/src/modules/inventory/docs/commands/UpdateValuationPolicy.md

@@ -0,0 +1,44 @@
+# UpdateValuationPolicy
+
+## Overview
+
+updateValuationPolicy updates an existing valuation policy. When the standardCostRate is changed for a STANDARD_COST policy, a revaluation event is emitted to trigger recalculation of inventory values for all items using this policy.
+
+## Business Rules
+
+- Valuation policy must exist
+- standardCostRate is required if costingMethod is STANDARD_COST
+- Updating the standard cost rate emits a revaluation event
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Policy exists?}
+    B -->|No| C[Return error: VALUATION_POLICY_NOT_FOUND]
+    B -->|Yes| D{costingMethod is STANDARD_COST?}
+    D -->|Yes| E{standardCostRate provided?}
+    E -->|No| F[Return error: STANDARD_COST_RATE_REQUIRED]
+    E -->|Yes| G[Update policy]
+    D -->|No| G
+    G --> H{Standard cost rate changed?}
+    H -->|Yes| I[Emit revaluation event]
+    I --> J[Return updated policy]
+    H -->|No| J
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **VALUATION_POLICY_NOT_FOUND**: Referenced valuation policy does not exist
+- **STANDARD_COST_RATE_REQUIRED**: costingMethod is STANDARD_COST but no standardCostRate was provided
+
+## Test Cases
+
+- returns error when not found
+- returns error when standard cost rate required
+- updates policy name
+- updates standard cost rate and emits revaluation event

package/src/modules/inventory/docs/commands/UpdateWarehouse.md

@@ -0,0 +1,42 @@
+# UpdateWarehouse
+
+## Overview
+
+updateWarehouse modifies the mutable fields of an existing warehouse, including name, storageCondition, and capacity. The siteId is immutable and cannot be changed after creation.
+
+## Business Rules
+
+- Warehouse must exist
+- Name must remain unique within the same site if changed
+- siteId is immutable after creation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Warehouse exists?}
+    B -->|No| C[Return error: WAREHOUSE_NOT_FOUND]
+    B -->|Yes| D{Name changed?}
+    D -->|Yes| E{New name unique within site?}
+    E -->|No| F[Return error: DUPLICATE_WAREHOUSE_NAME]
+    E -->|Yes| G[Update warehouse record]
+    D -->|No| G
+    G --> H[Return updated warehouse]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: Referenced warehouse does not exist
+- **DUPLICATE_WAREHOUSE_NAME**: A warehouse with the new name already exists at the same site
+
+## Test Cases
+
+- returns error when warehouse not found
+- returns error when new name conflicts
+- updates warehouse name
+- updates storage condition
+- updates capacity

package/src/modules/inventory/docs/features/inventory-adjustment.md

@@ -0,0 +1,64 @@
+# Inventory Adjustment
+
+## Overview
+
+Inventory adjustments are manual corrections to on-hand stock quantities that reconcile system records with physical reality. Discrepancies arise from damage, theft, counting errors, receiving mistakes, or production variances. Each adjustment specifies a reason code, the affected item and location, and the quantity delta (positive or negative). When confirmed, the adjustment generates a stock movement to or from a virtual "adjustment" location, updating the on-hand balance and impacting inventory valuation.
+
+Adjustments may originate from a standalone correction (e.g., a warehouse worker discovers damaged goods) or as a follow-up to an inventory count that reveals a variance. Organizations can optionally enforce an approval workflow for adjustments that exceed a configurable quantity or value threshold.
+
+## Business Purpose
+
+- **Accuracy**: Corrects system stock levels to match actual physical inventory, preventing downstream issues in order fulfillment and purchasing
+- **Traceability**: Every adjustment records a reason code and creates an auditable stock movement, satisfying regulatory and internal audit requirements
+- **Valuation integrity**: Adjustments flow through to inventory valuation so that financial reports reflect the true cost of goods on hand
+- **Loss visibility**: Categorizing adjustments by reason code (damage, shrinkage, counting error) enables analysis of inventory loss patterns and root-cause investigation
+- **Integration with inventory counts**: Provides the mechanism to act on count variances discovered during cycle counts or full physical inventories
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Identify Discrepancy] --> B[Create Adjustment Record]
+    B --> C[Select Item, Location, Quantity Delta]
+    C --> D[Assign Reason Code]
+    D --> E{Approval Required?}
+    E -- No --> G[Confirm Adjustment]
+    E -- Yes --> F[Submit for Approval]
+    F --> F1{Approved?}
+    F1 -- Yes --> G
+    F1 -- No --> H[Reject Adjustment]
+    H --> I[Return to Draft / Cancel]
+    G --> J[Generate Stock Movement]
+    J --> K[Update On-Hand Quantity]
+    K --> L[Update Inventory Valuation]
+```
+
+## Scenario Patterns
+
+- **Damage write-down**: A warehouse inspection reveals physically damaged units. A negative adjustment with reason code "Damage" removes the affected quantity from on-hand stock.
+- **Shrinkage / theft**: Periodic checks or count results show missing inventory with no corresponding shipment. A negative adjustment with reason code "Shrinkage" records the loss.
+- **Counting error correction**: A cycle count reveals more units on the shelf than the system shows. A positive adjustment with reason code "Counting Error" increases the on-hand balance.
+- **Receiving error correction**: Goods receipt recorded the wrong quantity. A positive or negative adjustment with reason code "Receiving Error" corrects the discrepancy.
+- **Production variance**: Actual yield differs from the expected output of a manufacturing process. An adjustment with reason code "Production Variance" reconciles the difference.
+- **Threshold-based approval**: An adjustment exceeding a configured quantity or value limit is routed to a supervisor for approval before confirmation.
+- **Bulk post-count adjustment**: After a full physical inventory count, the system generates one adjustment record per variance line, allowing batch review, reason-code assignment, and confirmation.
+
+## Test Cases
+
+- A positive adjustment increases on-hand quantity by the specified amount at the given location
+- A negative adjustment decreases on-hand quantity by the specified amount at the given location
+- A negative adjustment cannot reduce on-hand quantity below zero (unless the organization permits negative stock)
+- Every confirmed adjustment creates exactly one stock movement record with the correct source/destination (virtual adjustment location)
+- A reason code is required on every adjustment; confirmation without a reason code is rejected
+- Adjustments in draft status do not affect on-hand quantity or valuation until confirmed
+- When approval workflow is enabled, adjustments above the threshold remain pending until approved
+- A rejected adjustment does not generate a stock movement or change on-hand quantity
+- Adjustments originating from an inventory count link back to the count session for traceability
+- Confirmed adjustments update inventory valuation consistent with the organization's costing method
+- Adjustments are immutable after confirmation; corrections require a new, offsetting adjustment
+
+## Reference Links
+
+- [SAP Goods Movement - Adjustment Posting (Movement Types 501/502)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f42e93de3a7c4de2abb5ffb817785bef/4023cff7ddba1d65e10000000a174cb4.html)
+- [Oracle Inventory Adjustments](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/famoh/inventory-adjustments.html)
+- [NetSuite Inventory Adjustment](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1624498.html)

package/src/modules/inventory/docs/features/inventory-count.md

@@ -0,0 +1,78 @@
+# Inventory Count
+
+## Overview
+
+Inventory Count manages the process of verifying physical stock against system records through full physical inventories and cycle counts. A full physical inventory counts every item at a location, while a cycle count targets a subset of items on a rolling schedule — typically driven by ABC classification, location zone, or product group.
+
+The count workflow follows a structured lifecycle: plan the count, optionally freeze stock movements, execute the physical count, review variances (counted quantity minus system quantity), approve results, and automatically generate inventory adjustments for approved variances. Cycle counts can be scheduled to run continuously, ensuring stock accuracy is maintained without the disruption of a full physical inventory.
+
+## Business Purpose
+
+- **Regulatory compliance**: Periodic physical verification is required by accounting standards and auditors to validate inventory balances on the balance sheet
+- **Stock accuracy**: Identifies and corrects discrepancies between system records and actual physical quantities, improving fulfillment reliability
+- **Loss detection**: Surfaces shrinkage, damage, misplacement, and theft through systematic variance analysis
+- **Continuous improvement**: Cycle counts enable rolling accuracy checks without halting warehouse operations, unlike full physical inventories that may require a stock freeze
+- **Downstream reliability**: Accurate inventory feeds into purchasing (reorder points), sales (available-to-promise), and finance (inventory valuation)
+- **Root cause analysis**: Variance data collected over time reveals patterns in stock discrepancies, enabling process improvements
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Count Document] --> B[Select Location / Warehouse]
+    B --> C{Freeze Stock?}
+    C -- Yes --> D[Block Inbound/Outbound Movements]
+    C -- No --> E[Snapshot System Quantities]
+    D --> E
+    E --> F[Distribute Count Sheets]
+    F --> G[Execute Physical Count]
+    G --> H[Enter Counted Quantities]
+    H --> I[Calculate Variances]
+    I --> J{Variances Within Tolerance?}
+    J -- Yes --> K[Auto-Approve]
+    J -- No --> L[Manager Reviews Variances]
+    L --> M{Recount Required?}
+    M -- Yes --> G
+    M -- No --> N[Approve / Reject Line Items]
+    K --> O[Generate Inventory Adjustments]
+    N --> O
+    O --> P[Post Adjustments]
+    P --> Q{Stock Frozen?}
+    Q -- Yes --> R[Unfreeze Stock Movements]
+    Q -- No --> S[Count Completed]
+    R --> S
+```
+
+## Scenario Patterns
+
+- **Annual full physical inventory**: All items at a warehouse are counted at fiscal year-end with stock movements frozen to ensure an accurate snapshot for financial reporting
+- **ABC cycle count**: High-value A-items are counted weekly, B-items monthly, and C-items quarterly, distributing count workload evenly across the year
+- **Location-based cycle count**: A specific warehouse zone or bin range is counted on a rotating schedule, ensuring every location is verified within a defined period
+- **Blind count**: Counters are not shown system quantities during counting to prevent bias; variances are calculated only after all counts are entered
+- **Recount on high variance**: When a counted quantity deviates beyond a configured tolerance threshold, a mandatory recount is triggered before the variance can be approved
+- **Multi-counter reconciliation**: Two independent counters verify the same items; discrepancies between their counts trigger a third-party recount before variance approval
+- **Post-count adjustment**: Approved variances automatically generate inventory adjustment records that update on-hand quantities and post corresponding financial entries
+
+## Test Cases
+
+- Creating a count document captures the target location, count type (full or cycle), and planned date
+- Snapshot records the system on-hand quantity for each item at the moment the count is initiated
+- Variance is calculated as counted quantity minus system quantity for each count line
+- Variances within the configured tolerance are auto-approved without manager review
+- Variances exceeding tolerance require explicit approval or rejection by an authorized user
+- Rejecting a variance line triggers a recount for that item without affecting other approved lines
+- Approved variances generate corresponding inventory adjustment records with reason code "inventory-count"
+- Generated adjustments update on-hand stock quantities and post to the inventory valuation ledger
+- Freezing stock blocks new inbound and outbound movements for the counted location until the count is completed
+- Unfreezing stock resumes normal movement processing after count completion
+- Cycle count policies can be configured by ABC classification, location, or product group with independent frequencies
+- Scheduled cycle counts automatically generate count documents on their configured frequency
+- A count document cannot be finalized until all lines are either approved, rejected, or marked for recount
+- Blind count mode hides system quantities from the count entry interface
+- Count documents maintain a complete audit trail of who counted, when, and what values were entered
+
+## Reference Links
+
+- [SAP Physical Inventory (MI01/MI04/MI07)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f42e4a8abfc34ed6b11ab15478b79e78/4e2dd7c6b24e3857e10000000a174cb4.html)
+- [Oracle Cycle Counting](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/famie/cycle-counting.html)
+- [Odoo Inventory Adjustments](https://www.odoo.com/documentation/17.0/applications/inventory_and_mrp/inventory/warehouses_storage/inventory_management/count_products.html)

package/src/modules/inventory/docs/features/inventory-valuation.md

@@ -0,0 +1,77 @@
+# Inventory Valuation
+
+## Overview
+
+Inventory Valuation calculates and tracks the monetary value of on-hand stock using configurable costing methods: FIFO (First In, First Out), Weighted Average Cost (AVCO), and Standard Cost. Each stock movement — goods receipt, goods issue, transfer, or adjustment — triggers a recalculation of cost-per-unit and total inventory value for the affected item.
+
+The valuation method is configured through ValuationPolicy — an entity owned by the inventory module that defines the costing strategy (FIFO, AVCO, or Standard Cost) and related parameters such as standard cost rate. Each item is associated with a ValuationPolicy, allowing operators to assign different costing strategies per item or group items under a shared policy by convention. When a valuation change occurs, the module emits events that downstream systems (such as accounting) can consume to create journal entries. The inventory module owns cost tracking, valuation configuration, and valuation calculation; general ledger posting is explicitly out of scope.
+
+## Business Purpose
+
+- **Financial reporting accuracy**: Maintain up-to-date inventory asset values for balance sheet reporting
+- **Cost of Goods Sold (COGS) calculation**: Determine the cost assigned to goods issued or sold, using the configured costing method
+- **Costing method flexibility**: Support multiple valuation strategies (FIFO, AVCO, Standard Cost) to meet different industry and regulatory requirements
+- **Movement-driven updates**: Automatically recalculate valuations on every stock movement, eliminating manual revaluation effort
+- **Audit trail**: Record cost-per-unit at the time of each movement for traceability and variance analysis
+- **Downstream integration**: Emit valuation events so accounting or other modules can create corresponding financial entries without tight coupling
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Stock Movement Occurs] --> B{Movement Type?}
+    B -->|Goods Receipt| C[Record unit cost from receipt]
+    B -->|Goods Issue| D[Calculate issue cost using costing method]
+    B -->|Adjustment| E[Apply cost impact based on adjustment type]
+    B -->|Transfer| F[Carry existing cost-per-unit to destination]
+
+    C --> G{Costing Method?}
+    G -->|FIFO| H[Add receipt as new cost layer]
+    G -->|AVCO| I[Recalculate weighted average cost]
+    G -->|Standard Cost| J[Record at standard rate, capture variance]
+
+    D --> K{Costing Method?}
+    K -->|FIFO| L[Consume oldest cost layer first]
+    K -->|AVCO| M[Issue at current average cost]
+    K -->|Standard Cost| N[Issue at standard rate]
+
+    H --> O[Update total valuation]
+    I --> O
+    J --> O
+    L --> O
+    M --> O
+    N --> O
+    E --> O
+    F --> O
+
+    O --> P[Emit valuation change event]
+    P --> Q[Downstream systems consume event]
+```
+
+## Scenario Patterns
+
+- **FIFO receipt and issue**: A goods receipt creates a new cost layer with the purchase unit cost and quantity. A subsequent goods issue consumes the oldest cost layer first; if that layer is exhausted, the next layer is used. This produces accurate COGS that reflects actual purchase prices in chronological order.
+- **Weighted average receipt**: A goods receipt recalculates the average cost by combining the existing on-hand value with the new receipt value, then dividing by the total quantity. All subsequent issues use this updated average cost until the next receipt.
+- **Standard cost with variance capture**: Goods are received and issued at a predefined standard cost. Any difference between the actual purchase price and the standard cost is recorded as a purchase price variance. Periodic revaluation can update the standard rate, producing a revaluation variance.
+- **Inventory adjustment impact**: A positive adjustment (e.g., found stock) increases on-hand quantity at the current cost-per-unit. A negative adjustment (e.g., shrinkage) removes quantity and reduces total valuation, using the current costing method to determine the cost removed.
+- **Internal transfer**: Transfers between warehouses or storage locations carry the existing cost-per-unit to the destination. No valuation change occurs at the item level; only the location-level valuation splits are updated.
+- **Scrap disposal**: Scrapped items are issued at their current cost-per-unit, reducing total inventory valuation. The valuation event includes the scrapped cost for downstream write-off accounting.
+
+## Test Cases
+
+- Given an item configured with FIFO costing, when 10 units are received at 100 currency and then 5 units at 120 currency, then issuing 12 units should consume all 10 units at 100 and 2 units at 120, producing a COGS of 1240
+- Given an item configured with AVCO costing, when 10 units are received at 100 currency (total value 1000) and then 10 units are received at 200 currency, the average cost-per-unit should be 150
+- Given an item configured with AVCO costing with an average cost of 150 per unit and 20 units on hand, when 5 units are issued, the issue cost should be 750 and remaining valuation should be 2250
+- Given an item configured with standard cost of 50 per unit, when 10 units are received at an actual cost of 55 per unit, the inventory should be valued at 500 and a purchase price variance of 50 should be recorded
+- Given a standard cost item, when the standard cost is updated from 50 to 60 with 100 units on hand, a revaluation event should be emitted with a variance of 1000
+- Given any costing method, when a stock movement updates the valuation, a valuation change event should be emitted containing the item identifier, old and new cost-per-unit, old and new total valuation, and the originating movement reference
+- Given an internal transfer of 10 units with a cost-per-unit of 80, the total item-level valuation should remain unchanged after the transfer completes
+- Given a negative inventory adjustment of 3 units for an AVCO item with a current average cost of 120, the total valuation should decrease by 360
+- Given a FIFO item with two cost layers (5 units at 100, 5 units at 110), when all 10 units are scrapped, the total valuation removal should be 1050
+
+## Reference Links
+
+- [Inventory Module README](../../README.md) — module scope and dependency overview
+- [Stock Movement](./stock-movement.md) — movement types that trigger valuation updates
+- [Inventory Adjustment](./inventory-adjustment.md) — adjustment scenarios with valuation impact
+- [Scrap Management](./scrap-management.md) — scrap disposal and valuation write-off

package/src/modules/inventory/docs/features/lot-and-batch-tracking.md

@@ -0,0 +1,81 @@
+# Lot and Batch Tracking
+
+## Overview
+
+Lot and Batch Tracking assigns lot or batch identifiers to groups of identical products that were produced or received together, enabling full traceability through the supply chain. Each lot carries key attributes such as lot number, manufacture date, expiration date, and supplier lot reference, allowing organizations to trace products forward (from lot to which customers received it) and backward (from lot to which supplier provided it).
+
+Stock quantities are tracked at the lot level per storage location, providing granular visibility into which specific batches are on hand, where they are stored, and when they expire. This lot-level granularity supports expiration alerting, First Expired First Out (FEFO) picking strategies, and regulatory compliance for industries such as food, pharmaceuticals, and chemicals.
+
+## Business Purpose
+
+- Enable forward traceability — given a lot, determine which customers, orders, or locations received stock from that lot
+- Enable backward traceability — given a lot, determine which supplier, purchase order, or production run produced it
+- Track expiration dates to prevent shipping or consuming expired stock
+- Support FEFO (First Expired, First Out) strategies by providing expiration-date-sorted lot lists for operator-driven picking decisions
+- Maintain compliance with regulatory requirements including FDA regulations, EU food safety directives, and FSMA Section 204
+- Provide lot-level stock visibility per warehouse and storage location for precise inventory management
+- Record supplier lot references to correlate internal lot numbers with supplier-provided identifiers
+- Support recall workflows by quickly identifying all locations and recipients of an affected lot
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Goods Receipt] --> B{Lot-Tracked Item?}
+    B -->|No| C[Standard Stock Update]
+    B -->|Yes| D[Create or Select Lot]
+    D --> E[Record Lot Attributes]
+    E --> F[Assign Lot to Received Quantity]
+    F --> G[Update Lot-Level Stock per Location]
+    G --> H[Lot In Stock]
+    H --> I{Stock Movement?}
+    I -->|Transfer| J[Move Lot Quantity Between Locations]
+    I -->|Issue / Ship| K[Deduct Lot Quantity]
+    I -->|Adjustment| L[Adjust Lot Quantity with Reason]
+    J & K & L --> M[Record Movement Against Lot]
+    M --> H
+    H --> N{Expiration Check}
+    N -->|Approaching Expiry| O[Trigger Expiration Alert]
+    N -->|Expired| P[Block or Flag Lot]
+    O --> Q[Prioritize for FEFO Picking]
+    H --> R{Recall or Inquiry?}
+    R -->|Forward Trace| S[Lot -> Movements -> Recipients]
+    R -->|Backward Trace| T[Lot -> Receipt -> Supplier / PO]
+```
+
+## Scenario Patterns
+
+- **Goods Receipt with Lot Assignment**: A shipment of 500 units arrives from a supplier. The receiver creates lot "LOT-2026-0312" with manufacture date 2026-03-01, expiration date 2027-03-01, and supplier lot reference "SUP-A-8834". All 500 units are recorded against this lot at the receiving location.
+- **Multi-Lot Receipt**: A single purchase order delivery contains items from two different production runs. The receiver creates two lots, each with distinct manufacture and expiration dates, and splits the received quantity accordingly.
+- **FEFO Picking**: Warehouse has lot A (expires 2026-06-01) and lot B (expires 2026-09-01) for the same item. When a goods issue is requested, the operator refers to the expiration-date-sorted lot list and manually selects lot A first because it expires sooner. Automated FEFO picking assignment is not in scope.
+- **Expiration Alert**: A nightly or periodic check identifies lots expiring within a configurable threshold (e.g., 30 days). Alerts are generated so warehouse staff can prioritize these lots for outbound orders or mark them for review.
+- **Forward Traceability (Recall)**: A quality issue is discovered in lot "LOT-2026-0312". The system traces all outbound movements for that lot, identifying every sales order, customer, and destination location that received units from the affected lot.
+- **Backward Traceability (Root Cause)**: A customer reports a defect. The shipped lot is identified, and the system traces backward to the originating supplier, purchase order, and supplier lot reference to isolate the source.
+- **Lot Transfer Between Locations**: 100 units of lot "LOT-2026-0312" are transferred from Warehouse A, Bin 01 to Warehouse B, Bin 05. Both the source deduction and destination addition are recorded against the same lot.
+- **Lot-Level Inventory Adjustment**: During a physical count, 10 units of a specific lot are found missing. An inventory adjustment is recorded against that lot with a reason code, updating the lot-level stock balance.
+- **Expired Lot Handling**: A lot passes its expiration date. The system flags the lot as expired, preventing it from being selected for outbound shipments. The lot quantity may be routed to scrap management for disposal.
+
+## Test Cases
+
+- Creating a lot requires a unique lot number within the scope of the item
+- Lot number is immutable after creation
+- Manufacture date, expiration date, and supplier lot reference are recorded at lot creation and can be updated before the lot is fully consumed
+- Goods receipt for a lot-tracked item must specify a lot; receipts without lot assignment should be rejected
+- Stock quantities are tracked per lot per storage location; on-hand balances reflect lot-level granularity
+- A goods issue against a specific lot reduces that lot's quantity at the specified location
+- Issuing more quantity than a lot's on-hand balance at a location should be rejected
+- Internal transfers preserve the lot association — the destination stock record references the same lot
+- Inventory adjustments are recorded at the lot level with a mandatory reason code
+- Forward traceability query for a lot returns all outbound stock movements and their destinations
+- Backward traceability query for a lot returns the originating receipt, supplier, and purchase order reference
+- Expiration alert is triggered when a lot's expiration date is within the configured threshold
+- Expired lots are excluded from FEFO picking recommendations
+- Lots with no remaining on-hand quantity across all locations are marked as fully consumed
+- A single item can have multiple active lots simultaneously at the same storage location
+
+## Reference Links
+
+- [SAP Batch Management](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f47f7a5b49084709aac9f60498bab8cd/4517edda2c8c7744e10000000a174cb4.html)
+- [Odoo Lot and Serial Number Tracking](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/product_management/product_tracking.html)
+- [FDA FSMA Section 204 Traceability Rule](https://www.fda.gov/food/food-safety-modernization-act-fsma/fsma-final-rule-requirements-additional-traceability-records-certain-foods)
+- [Oracle Lot Control](https://docs.oracle.com/en/cloud/saas/supply-chain-management/24d/faims/lot-and-serial-control.html)

package/src/modules/inventory/docs/features/scrap-management.md

@@ -0,0 +1,63 @@
+# Scrap Management
+
+## Overview
+
+Scrap management handles the controlled removal of damaged, expired, defective, or obsolete stock from usable inventory. Scrap is modeled as an InventoryAdjustment with `adjustmentType = SCRAP`. When confirmed, the adjustment moves stock from the source storage location to a virtual "scrap" location, effectively removing it from available stock and reducing inventory valuation.
+
+Organizations may enforce approval workflows for scrap adjustments that exceed a defined value threshold, ensuring proper oversight of material losses. Scrap adjustments follow the same approval workflow as correction adjustments (DRAFT → PENDING_APPROVAL → CONFIRMED). Once confirmed, the adjustment is immutable — if scrap was created in error, a new CORRECTION adjustment with a positive quantityDelta can restore the stock.
+
+## Business Purpose
+
+- Remove physically damaged, expired, or quality-rejected stock from available inventory so it is not accidentally picked, sold, or consumed
+- Maintain accurate inventory valuation by writing off the cost of scrapped items at the time of disposal
+- Provide an auditable trail of why, when, and by whom stock was disposed, supporting regulatory and internal compliance requirements
+- Enable approval controls for high-value scrap events, preventing unauthorized write-offs
+- Support root-cause analysis by categorizing scrap reasons (damage, expiration, quality failure, obsolescence), feeding continuous improvement initiatives
+- Preserve lot and serial traceability through the scrap process for recall and warranty tracking
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Identify unusable stock] --> B[Create inventory adjustment with type=SCRAP]
+    B --> C{Approval required?}
+    C -- Yes --> D[Submit for approval]
+    D --> E{Approved?}
+    E -- Yes --> F[Confirm adjustment]
+    E -- No --> G[Reject / return to draft]
+    C -- No --> F
+    F --> H[Move stock to virtual scrap location]
+    H --> I[Adjust inventory valuation]
+    I --> J[Scrap completed]
+```
+
+## Scenario Patterns
+
+- **Damaged goods scrap**: Warehouse staff discover physically damaged items during handling or counting and create a SCRAP adjustment referencing the damage reason and source location
+- **Expired stock disposal**: Items that have passed their expiration date are identified (often via lot tracking) and scrapped to clear them from available inventory
+- **Quality failure scrap**: Items that fail incoming or in-process quality inspection are immediately scrapped, with the quality rejection linked as the scrap reason
+- **Obsolescence write-off**: Slow-moving or discontinued items are scrapped as part of a periodic inventory review to reflect their true recoverable value
+- **High-value approval scrap**: A scrap adjustment exceeds the organization's value threshold, triggering a manager approval step before the stock movement is executed
+- **Scrap error correction**: A scrap adjustment is found to have been created in error; a new CORRECTION adjustment with positive quantityDelta restores the stock to the source location
+- **Lot/serial-tracked scrap**: Specific lots or serial numbers are scrapped, maintaining full traceability from receipt through disposal. Serial numbers transition to SCRAPPED state on confirmation.
+
+## Test Cases
+
+- Creating a SCRAP adjustment with positive quantityDelta is rejected
+- Confirming a SCRAP adjustment removes the specified quantity from the source location's available stock
+- Scrapped stock appears in the virtual scrap location and is excluded from available-to-promise calculations
+- Inventory valuation decreases by the cost of the scrapped items upon confirmation
+- SCRAP adjustments record the item, quantity, source location, reason, date, and responsible user
+- When lot tracking is enabled, the scrap adjustment must reference a valid lot number with sufficient quantity
+- When serial tracking is enabled, the scrap adjustment must reference specific serial numbers in the source location; serial transitions to SCRAPPED on confirmation
+- SCRAP adjustments exceeding the configured value threshold require approval before confirmation
+- Rejected SCRAP adjustments remain in draft and do not affect stock or valuation
+- Scrapped items cannot re-enter available stock without a new CORRECTION adjustment
+- Scrap reason is mandatory and must be one of the defined reason categories
+- Listing adjustments filtered by `adjustmentType = SCRAP` returns only scrap records
+
+## Reference Links
+
+- [Odoo Scrap Management](https://www.odoo.com/documentation/17.0/applications/inventory_and_mrp/inventory/warehouses_storage/removal_strategies.html)
+- [SAP Movement Types 551/552 for Scrapping](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f7fddfe4caca43b4a511ab5e99f65567/e457ae2bbbf71014bfc0e6eee74504ce.html)
+- [Oracle Inventory Scrap Transactions](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/fammi/inventory-transactions.html)

package/src/modules/inventory/docs/features/serial-number-tracking.md

@@ -0,0 +1,68 @@
+# Serial Number Tracking
+
+## Overview
+
+Serial number tracking enables individual unit-level traceability within the inventory module. Each serialized item is assigned a unique serial number that follows it through its inventory lifecycle — from goods receipt or production through to goods issue, return, or disposal. A serialized item always represents exactly one unit of stock, distinguishing it from lot/batch tracking where a single identifier covers multiple units.
+
+Serial numbers are unique per item type: the same serial number cannot exist twice for the same item, ensuring unambiguous identification of every individual unit. The item-management module defers all serial number management to the inventory module, which owns assignment, state transitions, and history.
+
+The inventory module tracks serial numbers only through inventory-relevant states (AVAILABLE, ISSUED, RETURNED, SCRAPPED). Reservation for sales orders and shipment tracking are the responsibility of the sales module, which references serial numbers but does not own their state. This separation aligns with SAP/Oracle approaches and avoids coupling inventory to sales lifecycle concerns.
+
+## Business Purpose
+
+- **Individual unit traceability**: Know exactly which specific unit was shipped to which customer, enabling precise after-sales support
+- **Warranty tracking**: Link warranty claims to the exact unit by serial number, with full visibility into manufacture date, shipment date, and transaction history
+- **Recall management**: Identify and locate every affected unit by serial number when a product recall is issued
+- **Regulatory compliance**: Meet traceability requirements such as DSCSA (Drug Supply Chain Security Act) for pharmaceuticals and similar regulations in electronics, medical devices, and aerospace
+- **Return and repair tracking**: Match returned units to their original shipment and trace repair history across service events
+- **Fraud prevention**: Detect duplicate or counterfeit serial numbers entering the supply chain
+
+## Process Flow
+
+The following diagram shows the lifecycle states of a serialized item from initial assignment through terminal states.
+
+```mermaid
+flowchart TD
+    A[Goods Receipt / Production] -->|Assign serial number| B(AVAILABLE)
+    B -->|Goods issue| C(ISSUED)
+    C -->|Customer returns unit| D(RETURNED)
+    D -->|Inspect and restock| B
+    D -->|Unit is defective| E(SCRAPPED)
+    B -->|Unit damaged in warehouse| E(SCRAPPED)
+```
+
+Serial numbers are assigned at the point of goods receipt (for purchased items) or at the end of production (for manufactured items). Once assigned, a serial number is immutable and permanently associated with that specific physical unit. A serial number is always associated with a StorageLocation — its location changes through stock movements.
+
+## Scenario Patterns
+
+- **Goods receipt serialization**: A purchase order is received and each individual unit is assigned a unique serial number during the inbound inspection or put-away process
+- **Production serialization**: A manufacturing work order completes and each finished unit is assigned a serial number before being admitted to inventory
+- **Goods issue**: A stock movement issues a serialized unit from inventory, transitioning it from AVAILABLE to ISSUED. The sales module may reference the serial number for shipment and customer tracking
+- **Customer return**: An issued unit is returned by the customer, transitioning to RETURNED for inspection and disposition
+- **Restock after return**: An inspected returned unit passes quality checks and is restocked as AVAILABLE at a StorageLocation
+- **Scrap disposition**: A returned or warehouse-damaged unit is deemed unfit for sale and transitioned to SCRAPPED, removing it from inventory
+- **Warranty lookup**: A customer contacts support with a serial number; the system retrieves the full transaction history including receipt date, issue date, and any prior returns
+- **Recall execution**: A product recall is initiated; the system queries all serial numbers for the affected item and identifies their current state and location (warehouse or issued)
+
+## Test Cases
+
+- Each serialized item has a quantity of exactly 1; the system rejects any transaction that would result in a fractional or multi-unit quantity for a serial number
+- Serial numbers are unique per item type; assigning a duplicate serial number for the same item is rejected
+- Serial numbers for different item types may overlap (e.g., item A serial "001" and item B serial "001" can coexist)
+- A serial number can only be assigned during goods receipt or production completion
+- Once assigned, a serial number cannot be changed or reassigned to a different physical unit
+- State transitions follow the defined lifecycle: AVAILABLE -> ISSUED, ISSUED -> RETURNED, RETURNED -> AVAILABLE or SCRAPPED, AVAILABLE -> SCRAPPED
+- An AVAILABLE serial can transition directly to SCRAPPED (e.g., warehouse damage)
+- An ISSUED serial cannot transition directly to AVAILABLE; it must pass through RETURNED first
+- A SCRAPPED serial is terminal and cannot transition to any other state
+- The full transaction history for a serial number is queryable, including all state transitions with timestamps, related stock movements, and StorageLocation changes
+- Inventory counts for serialized items reconcile as the sum of individual serial numbers in AVAILABLE state at the counted StorageLocation
+
+## Reference Links
+
+- [Stock Tracking](./stock-tracking.md) — serial numbers are associated with a StorageLocation; for serialized items, on-hand count equals the number of serials in AVAILABLE state
+- [Stock Movement](./stock-movement.md) — serial state transitions are driven by stock movements (goods receipt assigns, goods issue transitions to ISSUED)
+- [Warehouse Management](./warehouse-management.md) — StorageLocation provides the spatial axis for serial number location
+- [Oracle Serial Number Management](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/fammi/manage-serial-numbers.html)
+- [SAP Serial Number Management](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f42e19a0e7404ebdbf6ec38ca93c1498/e54d9e616e2b1014b3fc9daa49709e5e.html)
+- [DSCSA — FDA Drug Supply Chain Security Act](https://www.fda.gov/drugs/drug-supply-chain-integrity/drug-supply-chain-security-act-dscsa)