Домики · Rest&Go

renar/guest-app/spec/SPEC-INT-01.md · Исходный файл

SPEC-INT-01. Интеграции

Уточнение от 12.11.2026: демонстрационные интеграции доступа и верификации. При расхождении применяется уточнение.

1. Назначение

Документ задаёт контракты обмена с внешними системами гостевого контура, поведение при сбоях, идемпотентность и наблюдаемость. Конкретные провайдеры, кроме карт, не выбраны (ADAPT-001 B-027): контракт описан как порт системы, адаптер под провайдера реализует его.

2. Scope

Входит: платёжный провайдер, онлайн-касса, Госуслуги (ЕСИА), SMS-шлюз, push-шлюзы, Яндекс MapKit и геокодер, внешние навигаторы, Сервис доступа (только контракт порта), Админ-панель (события каталога). Не входит: протоколы замков, IoT, контроллеры.

3. Разделы, специфичные для типа

3.1. Платёжный провайдер (порт PaymentGateway)

Операция Вход Выход Ошибки
tokenizeCard (через SDK/веб-форму провайдера) — token, mask, brand CARD_DECLINED, 3DS_FAILED
charge token, amount, idempotencyKey, bookingId providerRef, status INSUFFICIENT_FUNDS, DECLINED, TIMEOUT
hold / releaseHold / captureHold token, amount, idempotencyKey holdRef HOLD_NOT_SUPPORTED (СБП)
refund / void providerRef, amount status ALREADY_REFUNDED
webhook payment.status подпись HMAC — неверная подпись → 401, событие отброшено

Требования к провайдеру: холд с последующим списанием или снятием, рекуррентные списания по токену (продление, просрочка), СБП, Apple Pay, Google Pay, Mir Pay, 3-D Secure 2, сплит — заделом (B-027).

3.2. Онлайн-касса (порт FiscalRegistrar)

registerReceipt(paymentId, items[], customerContact) → receiptUrl. Признак расчёта: «приход» (аренда, услуги, продление), «возврат прихода» (возврат). Холд залога не фискализируется; удержание залога — «приход» (B-005).

3.3. Госуслуги — ЕСИА (порт IdentityVerifier)

Решение заказчика 11.11.2026 (ADAPT-001 B-035): подтверждение личности выполняется через ЕСИА вместо KYC-провайдера. Фото документов и селфи система не получает.

Протокол — OAuth 2.0 Authorization Code с PKCE и OpenID Connect; сеть регистрируется в ЕСИА как информационная система-потребитель, запросы подписываются ключом ГОСТ Р 34.10-2012 через сертифицированное СКЗИ на стороне сервера. Авторизация проходит во встроенном браузере приложения (SPEC-UI-02, C-05); client_secret и обмен кода на токен — только на сервере (модуль Identity, esia-identity-service).

Операция Вход Выход Ошибки
startAuthorization guestId, redirectUri authorizationUrl, state (одноразовый, 10 мин), codeVerifier хранится на сервере —
callback redirectUri code, state accessToken, idToken (sub = esia_oid) access_denied (гость отменил вход) → «Вход отменён»; неверный или просроченный state → 400, попытка отброшена
fetchPerson accessToken, esia_oid ФИО, дата рождения, паспорт РФ (серия, номер, дата выдачи, кем выдан), признак trusted (подтверждённая учётная запись) trusted = false → «Учётная запись Госуслуг не подтверждена»; нет паспорта РФ в профиле → та же причина; TIMEOUT → тост «Повторить»

Запрашиваемые scope: openid, fullname, birthdate, id_doc; признак подтверждённости учётной записи читается из ответа fetchPerson (trusted). Номер телефона берётся из входа по SMS-коду, а не из ЕСИА.

Результат проверки синхронный: состояние «На проверке» отсутствует. Токены ЕСИА не сохраняются после получения данных; сохраняются esia_oid, уровень доверия и время подтверждения (SPEC-DATA-01). Таймаут вызова ЕСИА — 15 с, 1 повтор; затем состояние «Ошибка» на C-05 с «Повторить» (SR-06#2).

3.4. SMS, push, карты

Система Контракт Сбой
SMS-шлюз send(phone, text); текст «Rest&Go: код 123456. Никому не сообщайте» + Web OTP-хвост 2 повтора через 5 с; затем тост на C-02 (TC-007-neg); резервный шлюз — задел
APNs, FCM, RuStore Push send(deviceToken, payload{type, bookingId, title, body}) невалидный токен удаляется; доставка не гарантирована — каждое событие дублируется в C-41
Яндекс MapKit SDK подложки, геокодер, routeTime(from, to, mode) без времени в пути — показывается только расстояние
Навигаторы deeplink yandexnavi://, yandexmaps://, dgis://, maps://, geo: без приложений — веб-ссылка (SR-15#3)

3.5. Админ-панель (входящие события)

hotel.published, hotel.paused, capsule.status_changed{client_status, free_at, last_cleaned_at}, tariff.updated, review.replied, deposit.released, deposit.retained{reason}. Доставка — outbox → брокер, at-least-once.

3.6. Сервис доступа (порт AccessService, механика вне рамок)

Операция Вход Выход
open bookingId, capsuleId, deviceId opened | error{code} за ≤ 10 с
getBackupCode bookingId code (6 цифр), validFrom, validTo
revoke bookingId ok (вызывается при completed, cancelled, no_show)

Технология (BLE, NFC, QR, PIN), офлайн-режим и подписи — внутри Сервиса доступа и не входят в комплект. Для стенда — эмулятор (SPEC-TEST-01).

3.7. Идемпотентность и dedup

Каждый мутирующий вызов к провайдерам несёт idempotencyKey = sha256(bookingId + operation + attempt-group). Входящие webhook и события дедуплицируются по eventId (таблица обработанных событий, хранение 7 дней).

3.8. Безопасность между системами

mTLS или подпись HMAC на webhook; IP-allowlist провайдеров; секреты — SPEC-SEC-01 §3.4.

3.9. Наблюдаемость

X-Correlation-Id от мобильного приложения проходит через BFF, Core и в метаданные вызовов провайдеров; метрики на каждый порт: доля ошибок, p95, число ретраев; алерт при доле ошибок оплаты > 5 % за 5 мин.

4. Связь с требованиями

SR-03, SR-06, SR-07, SR-10, SR-15, SR-24, SR-31, SR-37, SR-51.

5. Связь с другими SPEC

depends-on: SPEC-ARCH-01.

6. Verification

TC-007, TC-015, TC-016, TC-018, TC-054, TC-065, TC-066, TC-096 и парные -neg — против эмуляторов SPEC-TEST-01. Интеграционные contract-TC против sandbox провайдеров — после выбора провайдеров (README, «Известные пробелы»).

Метаданные RENAR
id: SPEC-INT-01
title: "Интеграции гостевого контура"
type: SPEC-INT
source: { adapt: ADAPT-001, adapt-section: "Forward §10; B-005, B-006, B-027", tz-section: "§1.4; §5.2 C-02, C-05, C-06, C-10, C-16, C-22, C-41" }
depends-on: [SPEC-ARCH-01]
ai-provenance:
  generated-by: "anthropic-claude-opus-5-5@2026-11-11"
  generated-at: "2026-11-11T12:00:00Z"
  prompt-template: "renar-agent-ru.md@1.0"
  context-tokens: null
  output-tokens: null
  human-edits: false