Data Flow & Sync Protocol

Halaman ini menjelaskan bagaimana data mengalir antara Store Router, DC Edge, dan Cloud Hub -- termasuk format event, protokol sinkronisasi, conflict resolution, dan MQTT topics.

Event-Driven Architecture

RetailOS menggunakan model event sourcing lite: setiap perubahan di edge (toko/DC) dicatat sebagai event, kemudian dikirim ke Cloud Hub secara batch.

Event Envelope Format

Setiap event dibungkus dalam EventEnvelope:

{
  "event_id": "evt_01HX9YZABC123",
  "origin": "pos-01",
  "origin_type": "pos",
  "store_id": "STORE-001",
  "type": "sale.completed",
  "version": 1,
  "sequence": 12345,
  "occurred_at": "2026-03-22T14:30:00Z",
  "payload": {
    "transaction_id": "TXN-001-20260322-0045",
    "total": 35500,
    "items": [...],
    "payments": [...]
  },
  "crc32": 2847561234
}

Event Types

Type	Origin	Deskripsi
sale.completed	POS	Transaksi penjualan selesai
sale.voided	POS	Transaksi dibatalkan
return.completed	POS	Retur barang selesai
shift.opened	POS	Kasir buka shift
shift.closed	POS	Kasir tutup shift
session.opened	Store Admin	Store session dibuka
session.closed	Store Admin	Store session ditutup
stock.received	Receiving	Barang diterima
stock.transferred	Transfer	Stok ditransfer
stock.adjusted	Adjustment	Stok disesuaikan
opname.completed	Opname	Stock opname selesai
settlement.submitted	Cash Ops	Settlement harian dikirim
recon.submitted	Daily Recon	Rekonsiliasi harian dikirim

Command Flow (Cloud to Edge)

Cloud Hub mengirim perintah ke toko/DC melalui command polling:

Command Types

Type	Deskripsi
price.update	Update harga produk
promo.push	Push aturan promo baru
product.sync	Sync master data produk
member.sync	Sync data member
config.update	Update konfigurasi toko
force.sync	Paksa full sync

Sync Agent Internals

Batch Claiming

Sync Agent menggunakan ClaimBatch untuk menghindari mengirim event yang sama dua kali:

1. Claim: Set sync_batch_id pada batch event, tandai sebagai "in-flight"
2. Send: POST batch ke Cloud Hub
3. Success: MarkSyncedByBatch -- set synced=1 pada semua event dalam batch
4. Failure: UnclaimBatch -- reset sync_batch_id agar bisa di-claim ulang

Circuit Breaker

State: CLOSED (normal)
  ↓ 5 failures
State: OPEN (skip semua request)
  ↓ 30 detik timeout
State: HALF-OPEN (coba 1 request)
  ↓ success → CLOSED
  ↓ failure → OPEN

HMAC Request Signing

Store Router menandatangani setiap request ke Cloud Hub menggunakan HMAC-SHA256:

• Header: X-Service-ID: store-router
• Header: X-Signature: hmac-sha256=<hex_signature>
• Cloud Hub memverifikasi signature sebelum menerima events

MQTT Topics

Store Router meng-embed MQTT broker untuk push real-time ke mobile apps:

Topic	Publisher	Subscriber	Data
store/{id}/sale	Store Router	Customer Display, Stock App	Transaction summary
store/{id}/stock/{sku}	Store Router	Stock App	Stock level update
store/{id}/alert	Store Router	Store Admin	System alerts
store/{id}/sync	Sync Agent	Store Admin	Sync status changes

Conflict Resolution

RetailOS menggunakan last-write-wins untuk sebagian besar data karena:

1. Toko adalah source of truth untuk transaksi -- tidak ada konflik karena setiap toko punya sequence number unik
2. Cloud Hub adalah source of truth untuk master data -- command price.update selalu menang vs data lokal
3. Member points menggunakan event log replay -- Cloud Hub menghitung ulang poin dari semua event

Data Integrity

• CRC32 checksum pada setiap event untuk deteksi corruption
• Sequence numbers per origin untuk deteksi missing events
• Idempotency keys pada mutation endpoints untuk mencegah duplikasi
• UUIDv7 untuk semua IDs -- time-sortable dan collision-free