Перейти к содержанию

Контракт: sales/orders

Метаданные

  • Namespace: sales
  • Name: orders
  • Version: 2.1.0
  • Owner: sales-integration
  • Email: sales-data@company.ru
  • Slack: #sales-data-alerts

Описание

Заказы клиентов из системы 1C Бухгалтерия. Содержит информацию о всех заказах клиентов, включая сумму, статус, товары и дату создания.

Используется для: - Аналитики продаж - Расчёта выручки - BI дашбордов - ML моделей прогнозирования

Kafka Topics

Topic Описание Retention
sales.orders.raw Сырые данные из 1C 7 дней
sales.orders_prod Провалидированные данные 30 дней
sales.orders_dlq Проблемные записи 90 дней

Schema (Avro)

schema.avsc
{
  "type": "record",
  "name": "Order",
  "namespace": "sales.orders",
  "doc": "Заказ клиента из 1C",
  "fields": [
    {
      "name": "order_id",
      "type": "string",
      "doc": "Уникальный ID заказа (формат: ord_XXXXXXXXXXXX)"
    },
    {
      "name": "customer_id",
      "type": "string",
      "doc": "ID клиента"
    },
    {
      "name": "total_amount",
      "type": "double",
      "doc": "Общая сумма заказа (RUB)"
    },
    {
      "name": "status",
      "type": {
        "type": "enum",
        "name": "OrderStatus",
        "symbols": [
          "draft",
          "pending",
          "confirmed",
          "paid",
          "shipped",
          "delivered",
          "cancelled",
          "refunded"
        ]
      },
      "doc": "Статус заказа"
    },
    {
      "name": "items",
      "type": {
        "type": "array",
        "items": {
          "type": "record",
          "name": "OrderItem",
          "fields": [
            {"name": "sku", "type": "string"},
            {"name": "quantity", "type": "int"},
            {"name": "price", "type": "double"}
          ]
        }
      },
      "doc": "Товары в заказе"
    },
    {
      "name": "created_at",
      "type": {"type": "long", "logicalType": "timestamp-millis"},
      "doc": "Дата создания заказа"
    }
  ]
}

Quality Rules

Critical (error)

  • ✅ order_id не null
  • ✅ order_id соответствует паттерну ^ord_[a-z0-9]{12}$
  • ✅ customer_id не null
  • ✅ total_amount не null и >= 0
  • ✅ status не null и один из допустимых значений
  • ✅ items не пустой массив
  • ✅ created_at не старше 1 часа (freshness)
  • ✅ order_id уникальный в батче

Warnings

  • ⚠️ customer_email валидный формат email
  • ⚠️ customer_phone формат +7XXXXXXXXXX
  • ⚠️ currency = "RUB" (если другое, проверить курс)

SLA

Availability

  • Target: 99.9%
  • Schedule: 24/7
  • Maintenance: Воскресенье 03:00-04:00 MSK

Freshness

  • Max age: 1 час
  • Alert threshold: 2 часа
  • Critical threshold: 4 часа

Response Time

Priority Response Recovery
Critical 15 мин 2 часа
High 1 час 4 часа
Medium 4 часа -
Low 1 день -

Retention

Layer Duration Storage
Kafka raw 7 дней Kafka
Kafka prod 30 дней Kafka
Kafka DLQ 90 дней Kafka
DWH hot 1 год SSD
DWH warm 3 года HDD
DWH cold 7 лет S3 Glacier

Physical Layout (Iceberg)

Partitioning

strategy: "iceberg_hidden"
spec:
  - source_column: "created_at"
    transform: "day"          # Партиция по дню

  - source_column: "customer_id"
    transform: "bucket[32]"   # 32 бакета по customer_id

Sort Order

columns:
  - column: "customer_id"
    direction: "asc"

  - column: "created_at"
    direction: "desc"

Parquet Settings

  • Compression: ZSTD level 3 (~4.5x)
  • Row group size: 128 MB
  • Dictionary encoding: status, currency
  • Bloom filters: order_id, customer_id

Consumers

System Team Usage Criticality
Clickhouse DWH analytics Аналитика продаж critical
Sales Dashboard business-intelligence Реалтайм дашборды high
Revenue Forecast ML data-science ML модели medium

Runbook

DLQ переполняется

Симптомы: - Alert: "DLQ size > 1000 messages" - Lag в consumer group растёт

Действия: 1. Проверить DLQ: kafkacat -b kafka:9092 -t sales.orders_dlq 2. Связаться с sales-integration в #sales-data-alerts 3. Создать тикет в Jira (DATA-*) 4. После исправления переотправить данные

SLA: 2 часа

Данные не поступают

Симптомы: - Alert: "No messages in last 1 hour"

Действия: 1. Проверить статус 1C 2. Проверить connectivity к API Gateway 3. Проверить mTLS сертификат 4. Связаться с sales-integration

SLA: 1 час (critical)

История версий

v2.1.0 (2026-01-23)

  • ➕ Добавлено поле discount_amount (nullable)
  • ➕ Добавлено поле customer_phone (nullable)
  • Breaking: Нет

v2.0.0 (2026-01-15)

  • 🔄 Поле status теперь enum вместо string
  • ➖ Удалено deprecated поле old_customer_id
  • Breaking: Да

v1.0.0 (2025-12-01)

  • 🎉 Первая версия контракта

Ссылки