05. Модель данных и API

1. Общие принципы

• PostgreSQL 16, кодировка UTF-8, timezone UTC.
• Первичные ключи: uuid (v7) для пользовательских сущностей, bigserial для логов/событий.
• Все таблицы содержат created_at, updated_at.
• Мягкое удаление: deleted_at там, где нужна история.
• Деньги: numeric(12,2), только RUB в MVP.
• Секреты: bytea/text с шифрованием AES-256-GCM + key_version.
• JSON-поля: jsonb с валидацией на уровне приложения.
• Внешние ключи с ON DELETE RESTRICT по умолчанию; каскады только для логов.

---

2. ERD (упрощённо)

users 1──N sessions
users 1──N oauth_identities
users 1──N connections 1──N activations
users 1──N activations N──1 bundles N──1 services (source/target)
activations 1──N runs 1──N run_logs
activations 1──N webhook_endpoints
activations 1──N subscriptions N──1 payments
users 1──N notifications
users 1──N audit_log (actor)
services 1──N service_versions
services 1──N triggers/actions (в манифесте, кэш в БД)
bundles 1──N bundle_versions

---

3. Таблицы

3.1. users

Индексы: lower(email), status.

3.2. sessions

Индексы: (user_id, expires_at), token_hash.

3.3. oauth_identities

UNIQUE (provider, provider_user_id).

3.4. services

3.5. service_versions

UNIQUE (service_id, version).

3.6. bundles (каталог)

Индексы: status, category, GIN по title/description (pg_trgm).

3.7. bundle_versions

История изменений шаблона связки: id, bundle_id, version, snapshot jsonb, created_at. Нужна для воспроизводимости активаций.

3.8. connections

Индексы: (user_id, service_id), status.

3.9. activations

Индексы: (user_id, status), bundle_id.

3.10. webhook_endpoints

Токен в URL — случайные 32+ байта base64url; в БД только хеш.

3.11. events

UNIQUE (activation_id, dedup_key); индекс (activation_id, received_at DESC). Партиционирование по месяцу.

3.12. runs

Индексы: (activation_id, created_at DESC), (user_id, created_at DESC), (status, created_at). Партиционирование по месяцу.

3.13. run_logs

Индекс (run_id, id).

3.14. subscriptions

UNIQUE activation_id (одна подписка на активацию).

3.15. payment_methods

3.16. payments

3.17. refunds

id, payment_id, amount_rub, reason, status, provider_refund_id, created_at, processed_at.

3.18. notifications

Индекс (user_id, status, created_at DESC).

3.19. audit_log

Индексы: (entity_type, entity_id), (actor_id, created_at DESC).

3.20. connector_health

connector_key, status (ok/degraded/down), latency_ms, error_rate, checked_at, message.

3.21. usage_counters

id, activation_id, period_start, runs_count, updated_at. UNIQUE (activation_id, period_start).

3.22. feature_flags

key, enabled, description, updated_at, updated_by.

3.23. legal_acceptances

id, user_id, document (offer, privacy, consent), version, accepted_at, ip, user_agent.

3.24. support_requests (P1)

id, user_id, subject, message, run_id, status, created_at.

---

4. Правила целостности

1. Нельзя активировать связку с неактивным подключением.
2. Нельзя удалить подключение, если есть активная активация (без подтверждения).
3. При удалении пользователя: анонимизация, связи с платежами сохраняются в объёме, требуемом законом.
4. При удалении активации: вебхук отключается, очередь очищается, история помечается на удаление через 90 дней.
5. Подписка не может быть активной без активации.
6. Платёж идемпотентен по idempotency_key.

---

5. REST API

5.1. Общие правила

• Base URL: https://api.easy-connect.ru/api/v1.
• Формат: JSON UTF-8.
• Аутентификация: httpOnly cookie сессии для web; Authorization: Bearer для будущего публичного API.
• Версионирование в пути.
• Пагинация: ?limit=20&cursor=..., ответ { data, next_cursor }.
• Сортировка: ?sort=-created_at.
• Идемпотентность: заголовок Idempotency-Key для POST платежей/активаций.
• Rate limit: заголовки X-RateLimit-*, 429 с Retry-After.
• Каждый ответ содержит request_id.

5.2. Формат ошибки

{
  "error": {
    "code": "CONNECTION_INVALID_TOKEN",
    "message": "Telegram не принял токен. Проверьте, что бот существует и токен скопирован полностью.",
    "details": { "field": "token" },
    "request_id": "req_01HX..."
  }
}

5.3. Аутентификация

5.4. Каталог

Пример ответа каталога:

{
  "data": [
    {
      "slug": "tilda-to-telegram",
      "title": "Заявка Tilda → сообщение в Telegram",
      "source": { "key": "tilda", "name": "Tilda", "icon_url": "..." },
      "target": { "key": "telegram", "name": "Telegram", "icon_url": "..." },
      "category": "forms",
      "price_rub": 200,
      "popularity": 98,
      "status": "published"
    }
  ],
  "next_cursor": null
}

5.5. Подключения

5.6. Активации

Создание:

{
  "bundle_slug": "tilda-to-telegram",
  "name": "Заявки с сайта",
  "source_connection_id": "uuid",
  "target_connection_id": "uuid",
  "mapping": {
    "chat_id": { "type": "static", "value": "-1001234567890" },
    "text": { "type": "template", "value": "Новая заявка: {{name}}, {{phone}}" }
  },
  "filter": null
}

5.7. Запуски

Ответ детали:

{
  "id": "run_01HX...",
  "status": "succeeded",
  "trigger_type": "webhook",
  "attempt": 1,
  "duration_ms": 1240,
  "started_at": "2026-10-18T09:41:02Z",
  "finished_at": "2026-10-18T09:41:03Z",
  "logs": [
    { "step": "ingest", "level": "info", "message": "Событие получено" },
    { "step": "map", "level": "info", "message": "Сопоставлено 3 поля" },
    { "step": "action", "level": "info", "message": "Сообщение отправлено" }
  ],
  "input_masked": { "name": "Иван", "phone": "+7•••••1234" },
  "error": null
}

5.8. Биллинг

Checkout:

{
  "activation_ids": ["uuid"],
  "save_payment_method": true,
  "return_url": "https://easy-connect.ru/app/billing/success"
}

Ответ: { "confirmation_url": "https://yoomoney.ru/..." }.

5.9. Уведомления

5.10. Пользователь

5.11. Админка

5.12. Служебные

---

6. Внутренние события (очереди)

6.1. event.received

{
  "event_id": 123456,
  "activation_id": "uuid",
  "dedup_key": "sha256...",
  "trigger_type": "webhook",
  "received_at": "2026-10-18T09:41:02Z"
}

6.2. run.requested

{
  "run_id": "uuid",
  "activation_id": "uuid",
  "event_id": 123456,
  "attempt": 1,
  "trace_id": "..."
}

6.3. run.finished

{
  "run_id": "uuid",
  "activation_id": "uuid",
  "status": "succeeded",
  "duration_ms": 1240,
  "error_type": null
}

6.4. connection.needs_reauth

{
  "connection_id": "uuid",
  "user_id": "uuid",
  "service": "telegram",
  "reason": "invalid_grant"
}

---

7. OpenAPI и контракты

• Спецификация генерируется из NestJS (@nestjs/swagger), публикуется /openapi.json.
• Клиентские типы — openapi-typescript.
• Валидация запросов/ответов — Zod-схемы, общие для web и api (пакет @easy-connect/contracts).
• Breaking changes — только в новой версии API (/api/v2), с периодом поддержки ≥ 6 месяцев.
• Публичный API (P1) использует API-ключи со scopes: catalog:read, activations:read, activations:write, runs:read.

---

8. Вебхуки наружу (P2)

• Подписка на события: run.succeeded, run.failed, activation.paused.
• Подпись X-EC-Signature: t=...,v1=HMAC-SHA256(t.body).
• Повторы 5 раз, DLQ, журнал доставок.
• Секрет per endpoint, ротация.

---

9. Требования к API

• p95 ответа ≤ 300 мс для чтения, ≤ 500 мс для записи (без внешних вызовов).
• Идемпотентность POST с Idempotency-Key (24 часа).
• Никаких секретов в ответах и логах.
• Все списки — с пагинацией; лимит по умолчанию 20, максимум 100.
• Все даты — ISO 8601 UTC.
• Локализация ошибок — русский, коды стабильны.
• CORS: только https://easy-connect.ru, https://www.easy-connect.ru, staging.
• CSP, HSTS, X-Content-Type-Options: nosniff.
• Аудит всех мутаций в админке.