# ChannelOrder

## Description

ChannelOrder stores the normalized representation of externally sourced demand before or alongside internal sales-order conversion. It preserves the originating channel identity, normalized commercial payload, raw troubleshooting context, and the operational lifecycle that distinguishes pending conversion, successful conversion, exception handling, and channel-side cancellation.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> PendingConversion: recordChannelOrder
    PendingConversion --> Converted: convertChannelOrder
    PendingConversion --> Exception: markChannelOrderException
    Exception --> PendingConversion: recordChannelOrder
    PendingConversion --> CancelledByChannel: cancelChannelOrder
    Exception --> CancelledByChannel: cancelChannelOrder
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| convert | PENDING_CONVERSION | CONVERTED | [convertChannelOrder](../commands/ConvertChannelOrder.md) |
| markException | PENDING_CONVERSION | EXCEPTION | [markChannelOrderException](../commands/MarkChannelOrderException.md) |
| record | EXCEPTION | PENDING_CONVERSION | [recordChannelOrder](../commands/RecordChannelOrder.md) |
| cancel | PENDING_CONVERSION, EXCEPTION | CANCELLED_BY_CHANNEL | [cancelChannelOrder](../commands/CancelChannelOrder.md) |

### Command Definitions

- [recordChannelOrder](../commands/RecordChannelOrder.md) - Create or refresh the normalized channel-order record from inbound payload data.
- [convertChannelOrder](../commands/ConvertChannelOrder.md) - Materialize or link the internal sales order after mapping succeeds.
- [markChannelOrderException](../commands/MarkChannelOrderException.md) - Move the order into an actionable exception state with retry context.
- [cancelChannelOrder](../commands/CancelChannelOrder.md) - Record cancellation received from the originating channel before internal execution progresses too far.

### Query Definitions

- [getChannelOrder](../queries/GetChannelOrder.md) - Retrieve one normalized channel order with status, mapping, and linked sales-order details.
- [listChannelOrdersByStatus](../queries/ListChannelOrdersByStatus.md) - List channel orders by operational lifecycle for support and replay queues.

### Models

- ChannelOrder
- ChannelOrderLine

### Invariants

- Every channel order belongs to exactly one company and one originating channel.
- The tuple of company, channel, and external order identity is unique so duplicate deliveries remain idempotent.
- A channel order must enter PENDING_CONVERSION before an internal sales order is created or updated.
- Moving to CONVERTED requires a stored link to the internal sales order.
- Moving to EXCEPTION preserves actionable error context and retry metadata.

### Relationships

- **References Channel**: `channelId` identifies the origin of the external demand.
- **References Listing**: normalized order lines use listing mappings to resolve internal items.
- **References BusinessPartner (cross-module)**: customer resolution may map buyer identity to a business partner.
- **References SalesOrder**: `salesOrderId` is recorded once conversion succeeds.
- **Belongs To SyncJob**: ingestion and replay attempts are associated with a sync execution record.
