Envelope: Ingest Servisi

Topic: qapu.ingest
DLQ: qapu.dlq.ingest
Producer: ingest-service

Ingest servisi, cihazlardan gelen CPS (Çok Punkt Sistem) uyumlu paketleri alır, doğrular ve dört tipte event üretir:

• Başarılı kabul: ingest.accepted.v1
• İşlemle başarısız: ingest.failed.v1
• Duplicate tespiti: ingest.duplicate_detected.v1
• Stuck cihaz (tekrar paket): ingest.stuck_detected.v1

Event Envanteri

Event	Ne zaman üretilir?	Consumer	Amaç
ingest.accepted.v1	Paket başarıyla doğrulanıp kabul edildiğinde	Stream Servisi	Pipeline'ı tetiklemek
ingest.failed.v1	Parse, schema, auth veya storage hatası olduğunda	Observer, Replay Worker	Hata görünürlüğü ve replay
ingest.duplicate_detected.v1	Aynı paket eşik üzerinde tekrar geldiğinde	Observer, Ops	Duplicate uyarısı
ingest.stuck_detected.v1	Cihaz uzun süre aynı paket gönderdiğinde	Observer, Ops	Stuck cihaz uyarısı

---

ingest.accepted.v1

Özet

Başlık	Değer
Topic	qapu.ingest
Producer	ingest-service
Consumer	Stream Servisi
Tetikleyici	HTTP ile gelen CPS paketi başarıyla doğrulanıp raw DB'ye yazıldığında
Kritiklik	Yüksek — downstream pipeline'ının başlangıcı

Payload

{
  "event": "ingest.accepted.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i0",
    "producer_service": "ingest-service",
    "produced_at": "2026-04-15T10:00:00.100Z",
    "process_ms": 9
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": 12345,
    "stream_id": null,
    "device_time": "2026-03-11T15:22:06Z",
    "stream_time": "2026-03-11T15:22:00.100Z",
    "iccid": "8990000111111111111",
    "imei": "357042111111111",
    "firmware": "2.3.0"
  },
  "data": {
    "current_stage": "accepted",
    "state_version": 1,
    "packet_size_bytes": 312,
    "message_type": "timed",
    "field_count": 24
  },
  "error": null
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
context.device_id	string	Evet	Cihazın DS28C kimliği
context.raw_id	integer	Evet	raw_packets tablosuna yazılan paket kimliği
context.stream_id	integer	Hayır	Henüz stream oluşmadığı için null
context.device_time	datetime	Evet	Cihazın paket üretim zamanı
context.stream_time	datetime	Evet	Ingest servisinde paket alındığı zaman
context.iccid	string	Hayır	SIM ICCID'si (paket içinde varsa)
context.imei	string	Hayır	Modem IMEI'si (paket içinde varsa)
context.firmware	string	Hayır	Cihaz firmware versiyonu (paket içinde varsa)
data.current_stage	string	Evet	Sabit: accepted
data.state_version	integer	Evet	device_buffer Redis state sürümü; idempotency amaçlı
data.packet_size_bytes	integer	Hayır	Gelen CPS paketinin bayt boyutu
data.message_type	string	Evet	CPS mesaj tipi: timed | event | alert | diagnostic | config
data.field_count	integer	Hayır	Paket içindeki alan sayısı

---

ingest.failed.v1

Özet

Başlık	Değer
Topic	qapu.ingest
Producer	ingest-service
Consumer	Observer, Replay Worker
Tetikleyici	Parse, schema, auth (device_id doğrulama) veya storage hatası
Kritiklik	Yüksek — istek reddedildi; HTTP 4xx/5xx döndü

Payload

{
  "event": "ingest.failed.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i1",
    "producer_service": "ingest-service",
    "produced_at": "2026-04-15T10:00:05.200Z",
    "process_ms": 2
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": null,
    "stream_time": "2026-04-15T10:00:05.200Z",
    "iccid": null,
    "imei": null,
    "firmware": null
  },
  "data": {
    "http_status": 422,
    "request_size_bytes": 512
  },
  "error": {
    "code": "SCHEMA_VALIDATION_ERROR",
    "message": "Required field 'device_time' missing in payload",
    "stage": "schema_validation",
    "retryable": false
  }
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
context.device_id	string	Hayır	Çıkarılabilmişse cihaz kimliği; parse hatası ise null
context.device_time	datetime	Hayır	Payload'da varsa cihaz zamanı; yoksa null
data.http_status	integer	Evet	HTTP yanıt kodu: 400, 413, 422, 500 vb.
data.request_size_bytes	integer	Hayır	Gelen istek boyutu
error.code	string	Evet	PARSE_ERROR | SCHEMA_VALIDATION_ERROR | AUTHENTICATION_ERROR | RAW_STORAGE_ERROR | REDIS_ERROR | PAYLOAD_SIZE_ERROR
error.retryable	boolean	Evet	Storage hatası ise true; schema/parse hatası ise false

---

ingest.duplicate_detected.v1

Özet

Başlık	Değer
Topic	qapu.ingest
Producer	ingest-service
Consumer	Observer, Ops
Tetikleyici	Aynı paket (device_id + device_time + hash) belirtilen eşik üzerinde tekrar geldiğinde
Kritiklik	Orta — uyarı; pipeline bloke olmaz

Payload

{
  "event": "ingest.duplicate_detected.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i2",
    "producer_service": "ingest-service",
    "produced_at": "2026-04-15T10:00:15.000Z",
    "process_ms": 3
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": null,
    "stream_time": "2026-04-15T10:00:15.000Z",
    "iccid": null,
    "imei": null,
    "firmware": null
  },
  "data": {
    "duplicate_count": 11,
    "first_occurrence": "2026-04-15T10:00:00.100Z",
    "consecutive_count": 11,
    "payload_hash": "sha256:ab12ef34cd56ef78gh90ijkl..."
  },
  "error": null
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
data.duplicate_count	integer	Evet	Tespit edilen toplam tekrar sayısı
data.first_occurrence	datetime	Evet	İlk paket alındığı zaman
data.consecutive_count	integer	Evet	Son duplicate event'ten beri ardışık tekrar sayısı
data.payload_hash	string	Hayır	Tekrar eden paketin SHA256 hash özeti

---

ingest.stuck_detected.v1

Özet

Başlık	Değer
Topic	qapu.ingest
Producer	ingest-service
Consumer	Observer, Ops
Tetikleyici	Cihaz belirtilen zaman periyodu boyunca sadece aynı paket gönderdiğinde
Kritiklik	Orta — cihaz durma uyarısı; pipeline bloke olmaz

Payload

{
  "event": "ingest.stuck_detected.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i3",
    "producer_service": "ingest-service",
    "produced_at": "2026-04-15T10:15:00.000Z",
    "process_ms": 2
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": null,
    "stream_time": "2026-04-15T10:15:00.000Z",
    "iccid": null,
    "imei": null,
    "firmware": null
  },
  "data": {
    "stuck_duration_minutes": 15,
    "repeated_count": 45,
    "payload_hash": "sha256:ab12ef34cd56ef78gh90ijkl...",
    "device_time_last": "2026-04-15T09:50:33Z"
  },
  "error": null
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
data.stuck_duration_minutes	integer	Evet	Cihazın stuck olduğu toplam dakika
data.repeated_count	integer	Evet	Bu periyotta tekrar gelen paket sayısı
data.payload_hash	string	Hayır	Tekrar eden paketin SHA256 hash özeti
data.device_time_last	datetime	Evet	Cihazın son rapor ettiği device_time (değişmiyorsa stuck)