# Brink POS API PoC Checklist

## Purpose

Track the minimum implementation work needed to prove the Brink POS API pull PoC end to end.

## Completion Criteria

The PoC is complete when one tenant-location can be pulled from Brink, raw payloads are preserved, the agreed staging subset is loaded, and the first curated tables are populated without advancing checkpoints on failure.

## Checklist

### 1. Foundation and configuration

- [ ] Confirm one tenant can be mapped to one Brink location and endpoint stack.
- [ ] Decide the Brink adapter implementation approach for the PoC:
  - generated SOAP clients, or
  - thin hand-written SOAP client
- [ ] Define the minimum Brink configuration set:
  - server base
  - `AccessToken`
  - `LocationToken`
  - tenant/location identifier
  - enabled streams
- [ ] Ensure secrets are not written to logs or raw payload metadata.

### 2. Raw pull proof

- [ ] Prove `Sales2.GetOrders` can be called successfully.
- [ ] Prove `Kitchen.GetOrderBumpTimes` can be called successfully.
- [ ] Prove `Kitchen.GetOrderItemBumpTimes` can be called successfully.
- [ ] Prove `Settings2.GetLastModifiedTime` can be called successfully.
- [ ] Prove at least the required settings lookup calls can be called successfully:
  - items
  - modifier groups
  - destinations
  - taxes
  - tenders
  - employees
  - kitchen queues

### 3. Raw payload capture

- [ ] Save raw SOAP responses to S3 under the tenant/source prefix.
- [ ] Record the main raw S3 path on `IngestionBatch` when practical.
- [ ] Ensure failed pulls still preserve the raw payload or error artifact.

### 4. Metadata and checkpointing

- [ ] Reuse existing `IngestionBatch` for Brink stream runs.
- [ ] Reuse existing `IngestionCheckpoint` for Brink watermarks.
- [ ] Implement checkpoint keys for the PoC:
  - `location:{location_key}:orders:modified-time`
  - `location:{location_key}:order-bumps:bump-time`
  - `location:{location_key}:item-bumps:bump-time`
  - `location:{location_key}:settings:last-modified`
- [ ] Ensure checkpoints advance only after successful end-to-end completion.
- [ ] Ensure failed runs do not advance checkpoints.

### 5. Structured logging

- [ ] Log one structured event per Brink call with:
  - `tenant_id`
  - `batch_id`
  - `source_type`
  - `service_name`
  - `operation_name`
  - `endpoint_url`
  - `request_window_start`
  - `request_window_end`
  - `result_code`
  - `status`
  - `raw_response_s3_path`
- [ ] Verify logs are sufficient to diagnose a failed call without inspecting code.

### 6. Staging schema

- [ ] Add the Brink staging bootstrap location under tenant SQL bootstrap.
- [ ] Create PoC staging tables:
  - `staging.brink_orders`
  - `staging.brink_order_entries`
  - `staging.brink_order_entry_modifiers`
  - `staging.brink_order_taxes`
  - `staging.brink_order_entry_taxes`
  - `staging.brink_order_payments`
  - `staging.brink_order_payment_details`
  - `staging.brink_items`
  - `staging.brink_modifier_groups`
  - `staging.brink_modifier_group_items`
  - `staging.brink_destinations`
  - `staging.brink_tables`
  - `staging.brink_kitchen_queues`
  - `staging.brink_taxes`
  - `staging.brink_tenders`
  - `staging.brink_employees`
  - `staging.brink_order_bump_times`
  - `staging.brink_order_item_bump_times`
- [ ] Ensure each staging table preserves ETL metadata columns:
  - `_etl_batch_id`
  - `_etl_source_type`
  - `_etl_ingested_at`

### 7. Source-to-staging normalization

- [ ] Map `GetOrders` responses into Brink order staging tables.
- [ ] Map settings responses into Brink lookup staging tables.
- [ ] Map kitchen bump responses into Brink kitchen staging tables.
- [ ] Preserve stable join keys between orders, entries, payments, and bump events.

### 8. Curated publication

- [ ] Implement curated mapping for the first agreed supported tables:
  - `curated.kitchen_item_status_events`
  - `curated.kitchen_order_items`
  - `curated.kitchen_orders`
  - `curated.pos_transaction_items`
  - `curated.pos_transactions`
  - `curated.pos_transaction_tenders`
  - `curated.pos_tables`
  - `curated.pos_tenders`
  - `curated.pos_catalog_items`
  - `curated.pos_modifiers`
- [ ] Keep optional curated targets out unless mapping stays simple:
  - `curated.pos_orders`
  - `curated.pos_order_items`
  - `curated.pos_menu_items`

### 9. Failure behavior

- [ ] Confirm transport failures mark the batch failed.
- [ ] Confirm Brink business failures (`ResultCode != 0`) mark the batch failed.
- [ ] Confirm failed runs do not publish partial curated state as successful output.
- [ ] Confirm failed runs do not advance checkpoints.

### 10. Exit review

- [ ] Validate that one tenant-location can run end to end.
- [ ] Validate that raw S3 capture, batch metadata, and checkpoints are all visible.
- [ ] Validate that the first curated outputs are queryable.
- [ ] Document known gaps that remain intentionally out of PoC scope.