Домики · Rest&Go

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

SPEC-ARCH-01. Архитектура

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

Документ задаёт границы системы guest-app — мобильного приложения гостя Rest&Go и серверных модулей, нужных ему для поиска, бронирования, оплаты, проживания (на уровне интерфейса), отзывов, профиля, поддержки и уведомлений. Документ ведёт перечень экранов системы — источник для покрытия SPEC-UI.

2. Scope

Входит: мобильное приложение iOS и Android; BFF мобильного API; серверные модули «Идентификация», «Каталог», «Бронирование», «Платежи», «Отзывы», «Профиль и лояльность», «Поддержка», «Уведомления»; хранилища этих модулей; интеграционные адаптеры.

Не входит (вынесено за рамки комплекта): механика связи приложения с отелем — edge-контроллер, IoT-хаб, замки, датчики, телеметрия, шкафчики, вендинг, метеринг ресурсов; на их месте — внешняя система «Сервис доступа» с контрактом SPEC-INT-01 §3.6. Также не входят: веб-клиент, админ-панель (источник данных каталога и ответов на отзывы — внешняя система «Админ-панель»), приложение исполнителя, кабинеты франчайзи и B2B, аналитическое хранилище.

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

3.1. Системный контекст (C4 L1)

flowchart LR
    G(["Гость"]) --> APP["guest-app<br/>мобильное приложение + серверные модули"]
    APP --> PSP["Платёжный провайдер<br/>карты, СБП, кошельки, холд"]
    APP --> OFD["Онлайн-касса / ОФД<br/>54-ФЗ"]
    APP --> ESIA["Госуслуги (ЕСИА)<br/>OAuth2 / OIDC"]
    APP --> SMS["SMS-шлюз"]
    APP --> PUSH["APNs / FCM / RuStore Push"]
    APP --> MAPS["Яндекс MapKit + геокодер"]
    APP --> ACC["Сервис доступа<br/>(вне рамок; контракт SPEC-INT-01 §3.6)"]
    ADM["Админ-панель<br/>(вне рамок)"] --> APP
    APP --> NAV["Внешние навигаторы<br/>deeplink"]
Внешняя система Что получает / отдаёт
Платёжный провайдер токен карты, списание, холд, снятие холда, возврат, статус
Онлайн-касса фискализация оплат и возвратов, ссылка на чек
Госуслуги (ЕСИА) авторизация гостя → ФИО, дата рождения, паспорт, подтверждённость учётной записи; отказ или отмена входа
SMS-шлюз текст с OTP-кодом
Push-шлюзы уведомления по событиям брони и поддержки
Яндекс MapKit подложка карты, геокодирование, время в пути
Сервис доступа запрос «открыть капсулу X по брони Y» → «открыто» / ошибка; выдача резервного кода
Админ-панель публикация отелей, капсул, тарифов, услуг, справочников; статусы капсул; ответы на отзывы; удержание залога

3.2. Контейнеры (C4 L2)

Контейнер Технология (ADR) Ответственность
Mobile App Flutter 3 (ADR-02) UI по SPEC-UI, локальный кэш, push, deeplink
Mobile BFF Kotlin + Spring Boot (ADR-03) агрегирует ответы модулей под экраны, аутентификация, rate limit
Core (модульный монолит) Kotlin + Spring Boot (ADR-01, ADR-03) 8 доменных модулей, outbox-события
PostgreSQL 16 + PostGIS (ADR-04) данные модулей, геопоиск; схема identity шифруется отдельно
Redis 7 сессии OTP, кэш карты, блокировки интервалов брони
Объектное хранилище S3 фото отелей, капсул, отзывов, вложений чата
Worker Kotlin таймеры брони, outbox → push, ретраи интеграций

3.3. Компоненты (C4 L3)

Mobile App: ui-kit (компоненты SPEC-UI-01), features/{auth, map, hotel, booking, stay, reviews, profile, support, notifications}, api-client (сгенерирован из OpenAPI BFF), cache (последние данные карты, текущая бронь, резервный код), push, l10n, analytics-events.

Mobile BFF: auth-filter (проверка access-токена), screen-aggregators (по одному на экран-группу), rate-limiter, idempotency-filter (ключ на мутирующих запросах), error-mapper (коды → тексты-ключи).

Core:

Модуль Компоненты
Identity otp-service, session-service, profile-service, esia-identity-service, consent-registry, account-deletion
Catalog hotel-query (PostGIS), capsule-query, availability-projection (статусы капсул для клиента), tariff-service, extras-service
Booking quote-service, booking-service, state-machine (SPEC-PROC-01), timers, cancellation-policy, extension-service
Payments payment-method-service, charge-service, hold-service, refund-service, receipt-service, ledger (append-only)
Reviews review-service, rating-aggregator
Loyalty level-calculator, bonus-ledger
Support chat-service, attachments, quick-topics, faq
Notifications event-subscriber, template-renderer (RU/EN), push-dispatcher, inbox

Worker: booking-timers, outbox-relay, integration-retry, pd-deletion-job.

3.4. Quality attributes

Атрибут Значение Обоснование
Latency: карта (пины видимой области) p95 ≤ 800 мс на BFF SR-10; первые данные до скелетона 300 мс
Latency: создание брони и оплата p95 ≤ 3 с без учёта 3-D Secure SR-24
Latency: ответ сервиса доступа таймаут 10 с SR-31#2
Throughput 50 RPS на BFF с запасом ×10 100 модулей, несколько тысяч броней в месяц (тех. требования §4)
Availability: бронирование, оплата 99,9 % в месяц критичный контур 24/7
Availability: каталог и карта 99,5 % в месяц при деградации — кэш на устройстве
Холодный старт приложения ≤ 2 с до карты на устройстве среднего класса SR-02

Значения — предложение исполнителя, требуют подтверждения (ADAPT-001 B-033).

3.5. ADR-журнал

№ Решение Статус Причина
ADR-01 Модульный монолит с outbox-событиями вместо микросервисов proposed нагрузка мала, доменов много (тех. требования §6)
ADR-02 Flutter для iOS и Android proposed одна кодовая база; дизайн-система из собственных компонентов без нативных стилей
ADR-03 Kotlin + Spring Boot для BFF и Core proposed зрелая экосистема, платёжные SDK, OAuth2-клиенты
ADR-04 PostgreSQL + PostGIS, хостинг в российском облаке (Yandex Cloud) proposed геопоиск; 152-ФЗ ст. 18 ч. 5
ADR-05 Статус капсулы для клиента — проекция availability-projection, обновляемая событиями админ-панели и брони proposed клиенту видны 4 статуса из 6 (ТЗ §3.2)
ADR-06 Технология физического доступа скрыта за контрактом «Сервис доступа» accepted (решение заказчика в чате 11.11.2026) механика связи с отелем вынесена за рамки
ADR-07 Платёжный провайдер с холдом и рекуррентами; конкретный провайдер не выбран proposed B-006, B-027
ADR-08 Запуск на карте без онбординга; вход только по телефону и SMS-коду при нажатии «Забронировать»; подтверждение личности через Госуслуги (ЕСИА) вместо KYC-провайдера accepted (решение заказчика 11.11.2026) B-035; снижает трение до первой брони; данные паспорта приходят подтверждёнными, без хранения фото документов и биометрии

3.6. Перечень экранов системы

Источник — ТЗ §5.2 и SR комплекта; экраны, добавленные интерпретацией, отмечены ADAPT.

Код Название Источник SPEC-UI
C-02d Диалог «Войдите, чтобы забронировать» решение заказчика 11.11.2026; SR-01#2 SPEC-UI-02
C-02 Вход ТЗ C-02; SR-03 SPEC-UI-02
C-03 Код из SMS ТЗ C-03; SR-04 SPEC-UI-02
C-05 Подтверждение личности через Госуслуги ТЗ C-05; решение заказчика 11.11.2026; SR-05, SR-06 SPEC-UI-02
C-06 Способ оплаты ТЗ C-06; SR-07 SPEC-UI-02
C-10 Карта (экран запуска) ТЗ C-10; SR-02, SR-10 … SR-13 SPEC-UI-03
C-11 Фильтры ТЗ C-11; SR-14 SPEC-UI-03
C-12 Карточка отеля ТЗ C-12; SR-15 SPEC-UI-03
C-13 Карточка капсулы ТЗ C-13; SR-16 SPEC-UI-03
C-14 Время и тариф ТЗ C-14; SR-20, SR-21 SPEC-UI-04
C-15 Дополнительные услуги ТЗ C-15; SR-22 SPEC-UI-04
C-16 Подтверждение и оплата ТЗ C-16; SR-23, SR-24 SPEC-UI-04
C-16e Ошибка оплаты ТЗ C-16 «Состояния»; SR-24#2 SPEC-UI-04
C-17 Бронь подтверждена ТЗ C-17; SR-25 SPEC-UI-04
C-20 Брони ТЗ C-20; SR-26 SPEC-UI-05
C-21 Детали брони ТЗ C-21; SR-27, SR-31#4 SPEC-UI-05
C-22 Ключ доступа (интерфейс) ТЗ C-22; SR-31 SPEC-UI-05
C-23 Начало проживания ТЗ C-23; SR-32 SPEC-UI-05
C-24 Активное проживание ТЗ C-24; SR-33, SR-34 SPEC-UI-05
C-24a Продление ТЗ C-24a; SR-35 SPEC-UI-05
C-24b Выселение ТЗ C-24b; SR-36 SPEC-UI-05
C-24c Итог ТЗ C-24c; SR-37 SPEC-UI-05
C-24s Срочная помощь ТЗ C-24 «тревожная кнопка»; ADAPT-001 B-026 SPEC-UI-05
C-25 Отзывы об отеле ТЗ C-25; SR-41, SR-42 SPEC-UI-06
C-26 Оставить отзыв ТЗ C-26; SR-40 SPEC-UI-06
C-30 Профиль ТЗ C-30; SR-06#3, SR-08, SR-09, SR-61, SR-62 SPEC-UI-07
C-31 Лояльность ТЗ C-31; SR-08 SPEC-UI-07
C-32 Способы оплаты и история платежей ТЗ C-32; SR-07#4 SPEC-UI-07
C-40 Поддержка ТЗ C-40; SR-50 SPEC-UI-07
C-41 Уведомления ТЗ C-41; SR-51, SR-52 SPEC-UI-07

Вложенные экраны C-30 («Личные данные», «Документы», «Правила и FAQ», «О приложении») описаны в SPEC-UI-07 как части C-30; если реализация выделяет их в отдельные маршруты, перечень дополняется новой версией комплекта до реализации.

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

BR-01 … BR-07 целиком; каждый SR комплекта реализуется контейнерами 3.2.

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

Корень графа depends-on. От него зависят SPEC-SEC-01, SPEC-DATA-01, SPEC-PROC-01, SPEC-INT-01, SPEC-TEST-01; экраны 3.6 покрыты SPEC-UI-02 … SPEC-UI-07.

6. Verification

Структурная проверка (носитель): каждый код 3.6 присутствует в screens[] хотя бы одного SPEC-UI, и каждый экран SPEC-UI присутствует в 3.6. Поведение — через TC утверждений SR.

Метаданные RENAR
id: SPEC-ARCH-01
title: "Архитектура мобильного приложения гостя и его серверной части"
type: SPEC-ARCH
source: { adapt: ADAPT-001, adapt-section: "Forward §1, §10", tz-section: "§1.2; §1.4; §5; §8" }
depends-on: []
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