# Listing

## Description

Listing is the channel-specific sellability record for one internal item on one channel. It preserves external identifiers, publication state, optional operational metadata, and the mapping bridge required to normalize inbound channel orders back to the internal item model.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Draft: createListing
    Draft --> Active: activateListing
    Active --> Paused: pauseListing
    Paused --> Active: activateListing
    Draft --> Retired: retireListing
    Active --> Retired: retireListing
    Paused --> Retired: retireListing
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| activate | DRAFT, PAUSED | ACTIVE | [activateListing](../commands/ActivateListing.md) |
| pause | ACTIVE | PAUSED | [pauseListing](../commands/PauseListing.md) |
| retire | DRAFT, ACTIVE, PAUSED | RETIRED | [retireListing](../commands/RetireListing.md) |

### Command Definitions

- [createListing](../commands/CreateListing.md) - Create a draft listing for one active item on one channel.
- [updateListing](../commands/UpdateListing.md) - Revise identifiers, assortment metadata, or publication prerequisites.
- [activateListing](../commands/ActivateListing.md) - Make the listing externally sellable when all required prerequisites are present.
- [pauseListing](../commands/PauseListing.md) - Temporarily stop new sellability without losing identifiers or history.
- [retireListing](../commands/RetireListing.md) - Permanently remove the listing from active sellability while preserving references.

### Query Definitions

- [getListing](../queries/GetListing.md) - Retrieve one listing with item, channel, and identifier context.
- [listListingsByChannel](../queries/ListListingsByChannel.md) - List channel assortment records under one channel.
- [getListingByExternalIdentifier](../queries/GetListingByExternalIdentifier.md) - Resolve the internal listing from a channel-provided external identifier.

### Models

- Listing

### Invariants

- Every listing belongs to exactly one company, one channel, and one sellable item.
- A listing cannot be ACTIVE unless the referenced item and channel are both ACTIVE and all required external identifiers are present.
- Historical channel orders remain able to reference a retired listing for audit and support traceability.
- External identifiers must be unique within the channel context according to operational policy.

### Relationships

- **References Channel**: `channelId` defines the external commercial context.
- **References Item (cross-module)**: `itemId` links the listing to the internal sellable SKU.
- **Optionally References SalesPriceRule**: Activation may require a price-linkage or pricing-eligibility check.
- **Referenced By ChannelOrder**: Inbound channel orders use the listing mapping to normalize external identifiers.
