# RecalculateSalesOrderFulfillmentStatus

## Permission Scope

salesOrder

## Overview

RecalculateSalesOrderFulfillmentStatus updates sales-order fulfillment progress from posted outbound-shipment evidence. The caller supplies a fulfilled-quantity delta per sales-order line. The command locks affected sales-order headers, adds each delta to its line projection, derives `fulfillmentStatus`, and updates each affected sales order.

## Business Rules

- Each referenced sales-order line must exist
- Each fulfilled-quantity delta must be zero or positive
- Only `CONFIRMED` sales orders accept new fulfillment progress
- A physical-fulfillment line cannot be fulfilled beyond its ordered quantity
- A line that does not require physical fulfillment cannot receive shipment progress
- The caller supplies only the quantity fulfilled by the current posting event
- Fulfilled-quantity deltas are decimal strings and are added without binary floating-point conversion
- The command does not read outbound-shipment tables

## Process Flow

```mermaid
flowchart TD
    A[Receive fulfillment progress] --> B{Any line progress?}
    B -->|No| C[Return no updated sales order ids]
    B -->|Yes| D[Validate deltas and referenced lines]
    D --> E[Lock affected sales-order headers]
    E --> F{All orders confirmed?}
    F -->|No| G[Return INVALID_ORDER_STATUS]
    F -->|Yes| H[Add fulfilled quantities]
    H --> I[Derive fulfillmentStatus]
    I --> J[Return updated sales order ids]
```

## External Dependencies

- None

## Error Scenarios

- **NEGATIVE_FULFILLED_QUANTITY**: Supplied fulfilled-quantity delta is negative
- **LINE_NOT_FOUND**: Referenced line does not exist on the target document
- **INVALID_ORDER_STATUS**: Sales order status does not allow this operation
- **OVER_FULFILLMENT**: Shipment would exceed ordered quantity or target a non-physical line

## Test Cases

- updates fulfillmentStatus to partially fulfilled
- updates fulfillmentStatus to fulfilled
- adds multiple posting deltas without lost updates
- adds fractional quantities without binary floating-point drift
- returns no updated orders when no progress is supplied
- rejects negative fulfilled quantity
- rejects over-fulfillment
- rejects fulfillment for a non-confirmed order
- returns error when a sales-order line does not exist