# RecalculateSalesOrderBillingStatus

## Permission Scope

salesOrder

## Overview

RecalculateSalesOrderBillingStatus updates sales-order billing progress from an external receivables source. The caller supplies the current billed quantity per sales-order line. The command updates line projections, derives `billingStatus`, and updates each affected sales order.

## Business Rules

- Each referenced sales-order line must exist
- Billed quantity must be zero or positive
- The caller supplies the current source-of-truth billed quantity for each affected line
- Billed quantities are decimal strings and are stored without binary floating-point conversion
- The command does not read receivables tables

## Process Flow

```mermaid
flowchart TD
    A[Receive billing progress] --> B{Any line progress?}
    B -->|No| C[Return no updated sales order ids]
    B -->|Yes| D[Validate quantities and referenced lines]
    D --> E[Apply billed quantities]
    E --> F[Derive billingStatus]
    F --> G[Return updated sales order ids]
```

## External Dependencies

- None

## Error Scenarios

- **NEGATIVE_BILLED_QUANTITY**: Supplied billed quantity is negative
- **LINE_NOT_FOUND**: Referenced line does not exist on the target document

## Test Cases

- updates billingStatus to partially billed
- updates billingStatus to billed
- resets billingStatus to not billed
- returns no updated orders when no progress is supplied
- rejects negative billed quantity
- returns error when a sales-order line does not exist