# SyncJob

## Description

SyncJob records one import, export, retry, or replay execution against a channel integration. It is the operational log that captures timing, direction, counts, and error outcome separately from ChannelOrder business state so integration reliability can be managed without blurring demand semantics.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Running: startSyncJob
    Running --> Succeeded: startSyncJob
    Running --> PartiallySucceeded: startSyncJob
    Running --> Failed: startSyncJob
    Running --> Cancelled: cancelSyncJob
    Failed --> Running: retrySyncJob
    PartiallySucceeded --> Running: retrySyncJob
    Cancelled --> Running: retrySyncJob
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| succeed | RUNNING | SUCCEEDED | [startSyncJob](../command/StartSyncJob.md) |
| partiallySucceed | RUNNING | PARTIALLY_SUCCEEDED | [startSyncJob](../command/StartSyncJob.md) |
| fail | RUNNING | FAILED | [startSyncJob](../command/StartSyncJob.md) |
| cancel | RUNNING | CANCELLED | [cancelSyncJob](../command/CancelSyncJob.md) |
| retry | FAILED, PARTIALLY_SUCCEEDED, CANCELLED | RUNNING | [retrySyncJob](../command/RetrySyncJob.md) |

### Command Definitions

- [startSyncJob](../command/StartSyncJob.md) - Create and start a sync execution for one channel and direction.
- [retrySyncJob](../command/RetrySyncJob.md) - Replay a failed or partial sync job with controlled idempotency.
- [cancelSyncJob](../command/CancelSyncJob.md) - Stop a running or queued sync job when policy allows.

### Query Definitions

- [getSyncJob](../query/GetSyncJob.md) - Retrieve one sync job with timing, counts, and error summary.
- [listSyncJobs](../query/ListSyncJobs.md) - List sync jobs for monitoring, support, and replay management.

### Models

- SyncJob

### Invariants

- Every sync job belongs to exactly one company and one channel.
- A sync job records one direction at a time, such as import or outbound status push.
- Processed, succeeded, failed, and retried counts reflect one execution attempt and do not silently merge unrelated runs.
- Terminal sync-job outcome is tracked independently from ChannelOrder business state.

### Relationships

- **References Channel**: `channelId` scopes the integration execution context.
- **References Company (cross-module)**: `companyId` ensures tenant-safe sync isolation.
- **Referenced By ChannelOrder**: channel orders may store the originating or latest sync job for support traceability.
