Post-Odoo warehouse implementation artifacts

Attribute	Value
Scope	Confirmed Odoo readback through published warehouse reporting
Status	Executable pilot reference; not a production deployment
Event contract	odoo.readback.confirmed.v1
Reporting contract	Ecommerce Reporting API 1.0.0
Required foundation	Platform tenant, connection, operation, attempt, and outbox tables

These artifacts implement the boundary after an Odoo mutation has passed authoritative readback. They establish concrete database, event, mart, API, test, and monitoring contracts. Application workers, infrastructure, environment-specific grants, and production evidence remain deployment work.

Processing sequence

flowchart LR Readback[Readback worker] Confirm[confirm_odoo_readback] Snapshot[(Readback snapshot)] Outbox[(Transactional outbox)] Dispatcher[Outbox dispatcher] Consumer[Warehouse consumer] Facts[(Warehouse facts)] Queue[(Refresh requests)] DBT[dbt refresh worker] Tests[Quality gates] Marts[(Published marts)] API[Reporting API] Readback --> Confirm Confirm --> Snapshot Confirm --> Outbox Outbox --> Dispatcher --> Consumer Consumer --> Facts Consumer --> Queue --> DBT --> Tests --> Marts --> API

1. The readback worker compares fresh Odoo state with the operation's expected invariant.
2. confirm_odoo_readback locks the operation and atomically stores the matched readback, marks the operation confirmed, and writes one deduplicated outbox event.
3. The dispatcher delivers the event at least once. It does not mark the outbox row delivered until the broker or direct consumer acknowledges durable receipt.
4. consume_odoo_readback_confirmed verifies tenant context, schema major version, and content hash; deduplicates by consumer and event ID; loads facts; and queues affected mart partitions.
5. The refresh worker claims a fenced refresh request and runs the affected dbt models. The posting-health model rebuilds complete affected grains; the finance document mart performs a current-state rebuild so a later readback cannot leave an obsolete aggregate grain behind.
6. Database controls and dbt tests must pass before publication. The worker then updates mart_refresh_state, emits warehouse.mart.refreshed.v1, and invalidates or refreshes reporting caches.

Artifact inventory

Artifact	Repository source	Contract role
Readback and outbox migration	db/migrations/0001_ecommerce_odoo_readback_outbox.sql	Atomic confirmation and event production
Warehouse consumer migration	db/migrations/0002_ecommerce_warehouse_readback_consumer.sql	Inbox, facts, refresh queue, refresh state, and idempotent consumer
Readback event schema	Download JSON Schema	Producer and consumer validation
Mart refresh event schema	Download JSON Schema	Publication and cache/freshness notification
Reporting API	Download OpenAPI 3.1	Tenant-scoped read-only report surface
dbt project and models	dbt_project.yml, dbt/models/	Incremental posting health plus current-state Odoo document and tenant-health marts
Database control tests	db/tests/	Readback, outbox, warehouse fact, and refresh-state invariants
dbt model tests	dbt/models/marts/schema.yml	Grain uniqueness, required values, and status constraints
Alert rules	monitoring/prometheus/ecommerce-warehouse.rules.yml	Readback lag, unknown outcomes, stale marts, queue stalls, controls, failures
Static artifact validator	scripts/check_ecommerce_artifacts.py	CI validation of schemas, references, required controls, and artifact coverage

The included dbt models are the first post-Odoo slice, not the complete ecommerce warehouse. Source-order, refund, fee, settlement, payout, clearing, and inventory facts and marts remain governed by the warehouse contract and must be added as their upstream canonical contracts are implemented.

Deployment order

1. Deploy the platform foundation schema from the platform specification, including tenant-scoped unique keys required by the foreign keys.
2. Review and apply the two numbered PostgreSQL migrations through the environment's migration tool under a non-runtime owner role.
3. Grant only the readback worker permission to execute confirm_odoo_readback; grant only the warehouse consumer permission to execute consume_odoo_readback_confirmed and write the required tenant context.
4. Register both immutable event schemas by event type, version, and checksum.
5. Deploy the outbox dispatcher and warehouse consumer with dead-letter handling, bounded retries, metrics, and tenant-scoped transactions.
6. Configure dbt from dbt/profiles.yml.example, then deploy a fenced refresh worker that updates refresh state only after tests pass.
7. Implement the OpenAPI document in the reporting service over published marts or authorized serving views.
8. Load the Prometheus rules, connect every metric to a tenant-safe exporter, and exercise the linked runbooks before pilot enablement.

Validation commands

python scripts/check_ecommerce_artifacts.py
python scripts/build_site.py --strict
dbt build --project-dir . --profiles-dir dbt --target pilot

The first two commands run in repository CI. dbt build and the SQL control tests require a disposable PostgreSQL integration database populated with the platform foundation schema; static CI does not replace that runtime test.

Production gates

• Execute both migrations and every SQL control test against the exact supported PostgreSQL version.
• Prove forced RLS and worker grants with positive and cross-tenant negative tests.
• Prove same-event replay is a no-op and same-event-ID/different-content replay is rejected.
• Exercise worker crash points before and after readback, outbox insert, delivery, fact load, quality tests, and publication.
• Prove a failed refresh retains the last valid partition and exposes stale state through the API and alerts.
• Reconcile source, canonical, Odoo, settlement, fact, and mart controls for the pilot fixtures.
• Record migration, restore, backfill, one-tenant rebuild, rollback-of-release, and runbook evidence.

See Odoo posting, API and events, warehouse marts, and operations and acceptance for the normative behavior surrounding these files.