# Orders Schema Draft (Generic)

## Context
- This is a generic schema proposal for external orders import/sync.
- API docs from Apilo were used only as an example of a rich order payload shape.
- Target is integration-agnostic storage (no vendor lock in table/column names).

## Proposed tables
- `orders`
- `order_addresses`
- `order_items`
- `order_payments`
- `order_shipments`
- `order_documents`
- `order_notes`
- `order_status_history`
- `order_tags_dict`
- `order_tag_links`
- `integration_order_sync_state`

SQL draft:
- [20260302_orders_schema_v1.sql](/C:/visual%20studio%20code/projekty/orderPRO/database/drafts/20260302_orders_schema_v1.sql)

## Design principles
- Keep one row per imported source order in `orders`.
- Store child collections in dedicated tables (1:N).
- Keep source IDs and selected business scalars as first-class columns.
- Keep raw payload snapshots (`payload_json`) for diagnostics and replay safety.
- Keep import idempotent:
  - unique `(integration_id, source_order_id)` in `orders`,
  - unique child keys per order and source child ID.
- Keep event timeline in separate `order_status_history`.

## Why these extra tables
- `order_status_history`: audit + timeline reconstruction + sync debugging.
- `integration_order_sync_state`: robust incremental fetch cursor.
- `order_tags_*`: proper many-to-many, easy filtering and deduplication.

## Notes before implementation
- Draft is intentionally in `database/drafts` (not auto-run by Migrator).
- Before production migration:
  - confirm source-specific mapping in service layer,
  - confirm retention policy for `payload_json`,
  - decide merge strategy for child rows (upsert by source IDs vs hard refresh per sync).