/data-contract

/data-contract

Amaç

Producer-consumer sözleşmesi — schema + semantics + SLA + ownership. "Event yayınladık, downstream çalışmıyor" → contract eksik.

Ne Zaman Kullanılır

• Yeni event publish (producer çıkıyor)
• Yeni consumer onboard
• Breaking change kararı (major bump)
• Schema drift bulgu (CI fail veya production poison)
• Catalog API entity ekleme (Backstage)
• Privacy review PII field annotation
• DB warehouse contract (dbt)
• Kafka topic onboarding
• Retry storm / DLQ olmadığı tespit

Input

• <event> — örn. events.order.created
• veya <api> — örn. payments-svc REST
• veya <topic> — Kafka topic

Delege

api-contract-guardian lider — REST/GraphQL/AsyncAPI sahibi.

Alt-delege:

• system-design-architect — contract-first design
• backend-implementer — producer + consumer impl
• database-implementer — dbt warehouse contracts
• database-optimizer — warehouse query patterns
• observability-engineer — consumer lag + DLQ alarm
• privacy-engineer — PII annotation + retention bağı
• release-manager — schema version + sunset plan
• migration-planner — major bump consumer migration

data-contracts skill'i prosedürü taşır. Rule: rules/data-contracts.md.

Beklenen Davranış

1. rules/data-contracts.md + rules/observability.md + rules/privacy-engineering.md yükle.
2. Discovery — producer + consumer inventory; schema location.
3. Contract spec — AsyncAPI 3.0 (event) veya OpenAPI 3.x (REST); SLA ekle.
4. Schema Registry register — Confluent / Apicurio; compatibility BACKWARD.
5. Versioning karar — semver; major BC-breaking; sessiz remove yasak.
6. Producer impl — pre-publish schema validate + idempotency event_id + headers (schema_version, trace_id).
7. Consumer impl — idempotent dedup + business invariant check + DLQ pattern.
8. DLQ topic — schema_invalid / business_invariant / transient retry; 30g retention; > 10 msg/dk alarm.
9. CI gate — AsyncAPI validate + schema compat check + Pact verify + drift check.
10. Catalog integration — Backstage API entity + owner.
11. PII annotation — x-pii: pseudo/direct + retention.
12. Database contract (dbt) varsa — contract: enforced.
13. Findings Critical/High/Medium/Low.
14. Action items issue + sahip.

Yasaklar

• Schema yok / wiki.
• Producer-consumer copy-paste.
• Versioning yok.
• Sessiz field remove.
• Field anlam değişikliği.
• PII annotation yok.
• DLQ yok.
• Idempotency key yok.
• At-most-once kabul.
• Schema Registry yok.
• Compatibility mode NONE.
• CI contract test yok.
• SLA yok.
• Backstage API entity yok.
• Ownership belirsiz.

Örnek Kullanım

/data-contract events.order.created
/data-contract payments-svc-rest-v2
/data-contract --topic events.notification.sent
/data-contract --audit                  # tüm event/api drift taraması
/data-contract --dbt orders             # warehouse contract

Örnek Çıktı (özet)

# Data Contract: events.order.created

## Discovery
- Producer: checkout-svc
- Consumers: 7 (notifications-svc, marketing-svc, analytics-svc,
  fulfillment-svc, fraud-svc, accounting-svc, billing-svc)
- Schema location: YOK (wiki + copy-paste)

## Contract Spec (AsyncAPI 3.0)
- events/order-created.yaml v1.0.0 (yeni)
- SLA: latency p99 500ms, at_least_once, lag alarm 60s

## Findings
- Critical: 3 consumer dedup yok (duplicate process)
- Critical: notifications-svc DLQ yok, retry storm 2h sustained
- High: PII user_email plaintext payload
- High: schema_version header yok
- High: 7 consumer copy-paste, Pact yok
- Medium: CI contract test yok
- Medium: Backstage API entity yok
- Low: SLA dokümante değil

## Action Items
| P0 | AsyncAPI spec events/order-created.yaml + Schema Registry register | @payments | 2026-05-23 |
| P0 | PII pseudonymize user_email → user_id_hash | @payments | 2026-05-23 |
| P0 | DLQ topic + alert 3 consumer | @platform | 2026-05-30 |
| P0 | Idempotency event_id producer + processed_events 7 consumer | @payments | 2026-06-06 |
| P1 | schema_version header + Pact 7 consumer | @api | 2026-06-13 |
| P1 | CI contract test (AsyncAPI validate + Pact + compat) | @platform | 2026-06-13 |
| P1 | Backstage API entity | @platform | 2026-06-20 |
| P2 | SLA dokümante (Backstage TechDocs) | @payments | 2026-06-30 |