# stock-adjustment-processing

## Overview

Reconciles physical stock against the system when the two diverge — a miscount, damage, or blocking stock for QA. An Inventory Manager captures a DRAFT stock adjustment with the appropriate `adjustmentType` and lines, then submits it for approval; an Approver confirms it (which applies the stock movement) or rejects it back. A DRAFT can be cancelled.

The `adjustmentType` on the header determines the effect, and all line quantities are always positive:

- **CORRECTION** — a count correction; each line carries an `adjustmentDirection` (INCREASE or DECREASE) applied to AVAILABLE stock.
- **SCRAP** — writes off stock; each line's `fromStockCategory` selects AVAILABLE (default) or BLOCKED stock to scrap.
- **BLOCK** — moves stock AVAILABLE → BLOCKED.
- **UNBLOCK** — moves stock BLOCKED → AVAILABLE.

Nothing touches real stock until the adjustment is **CONFIRMED**. Confirmation posts inventory ledger entries and updates the affected `StockLevel` rows; it can fail when there is not enough stock to decrease, scrap, or block. The flow follows the native erp-kit `inventory` lifecycle `DRAFT → SUBMITTED → CONFIRMED`, with `SUBMITTED → REJECTED`, `REJECTED → DRAFT` (resubmit), and `DRAFT → CANCELLED`. This template exposes **create + submit + confirm + reject + cancel**. The native `resubmit` transition (`REJECTED → DRAFT`) exists in the native lifecycle but is not surfaced by a resolver in this template.

## Actors Involved

- [Inventory Manager](../../actor/inventory-manager.md) — raises (creates), submits, and cancels stock adjustments
- [Approver](../../actor/approver.md) — confirms or rejects submitted stock adjustments

See [action-matrix.md](./action-matrix.md) for models involved and the action visibility matrix.

## Flow Diagram

```mermaid
sequenceDiagram
    participant IM as Inventory Manager
    participant AP as Approver
    participant S as System

    Note over IM,S: Authoring (DRAFT)

    IM->>S: Create stock adjustment (type, reason, lines)
    S->>S: Validate lines (item / location active, positive qty, category)
    S-->>IM: Adjustment created in DRAFT (no stock moved)

    IM->>S: Submit adjustment
    S->>S: Reject if not in DRAFT
    S-->>IM: Adjustment status → SUBMITTED (no stock moved)

    Note over AP,S: Approval (SUBMITTED)

    alt Approve
        AP->>S: Confirm adjustment
        S->>S: Post inventory ledger entries + update StockLevel rows
        S-->>AP: Adjustment status → CONFIRMED
    else Reject
        AP->>S: Reject adjustment (optional reason)
        S-->>AP: Adjustment status → REJECTED
    end

    Note over IM,S: A DRAFT can be cancelled instead of submitted

    IM->>S: Cancel adjustment
    S-->>IM: Adjustment status → CANCELLED

    Note over S: Confirm fails with INVENTORY_INSUFFICIENT_STOCK when there is not enough stock to decrease, scrap, block, or unblock
    Note over S: Submit / confirm / reject / cancel are refused with INVENTORY_INVALID_STATUS when the adjustment is not in the required status
```

## Stories

- [Create Stock Adjustment](./story/inventory-manager--create-stock-adjustment.md)
- [Submit Stock Adjustment](./story/inventory-manager--submit-stock-adjustment.md)
- [Confirm or Reject Stock Adjustment](./story/approver--confirm-or-reject-stock-adjustment.md)