Домики · Rest&Go

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

SPEC-PROC-01. Жизненный цикл брони

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

Документ задаёт состояния брони (ТЗ §3.3), переходы, таймеры, денежные операции на каждом переходе и компенсации при сбоях.

2. Scope

Входит: бронь от создания до завершения, продление, отмена, неявка. Не входит: жизненный цикл капсулы (уборка, ТО — админ-панель и эксплуатация), открытие замка (Сервис доступа).

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

3.1. Диаграмма

stateDiagram-v2
    [*] --> pending_payment: гость нажал «Оплатить» (котировка зафиксирована)
    pending_payment --> confirmed: списание и холд успешны
    pending_payment --> cancelled: 10 мин без оплаты
    confirmed --> active: «Начать проживание»
    confirmed --> cancelled: отмена гостем
    confirmed --> no_show: истёк travel_deadline / 15 мин после заезда
    active --> active: продление оплачено
    active --> completed: «Завершить проживание»
    completed --> [*]
    cancelled --> [*]
    no_show --> [*]

3.2. Состояния и переходы

Из В Триггер Действия системы ref
— pending_payment POST /bookings с quote_id блокировка интервала (exclusion), таймер 10 мин SR-24#1
pending_payment confirmed ответ провайдера: списание и холд успешны фискализация, push «Бронь подтверждена», для now — travel_deadline = now + travel_time_min; для «Ночи» с starts_at 22:00 в будущем travel_deadline не задаётся SR-24#1, SR-25#1
pending_payment cancelled таймер 10 мин снятие блокировки интервала; void частичных операций SR-24#4
confirmed cancelled отмена гостем возврат по правилам отмены, снятие холда, фискализация возврата SR-27#2
confirmed no_show travel_deadline (now) или starts_at + 15 мин (scheduled) снятие холда; возврат — по правилам отмены (B-007, B-008); push SR-25#2
confirmed active «Начать проживание» аренда считается от starts_at (B-023) SR-32#1
active active продление оплачено ends_at += длительность, проверка exclusion SR-35#4
active completed «Завершить проживание» событие booking.completed → админ-панель (уборка), начисление бонусов, расчёт итога, push SR-36#2, SR-37#1

3.2.1. Интервал тарифа «Ночь» (B-038)

Решение заказчика 11.11.2026: тариф «Ночь» — фиксированный интервал 22:00 – 08:00 по местному времени отеля.

  1. Если «Ночь» выбрана в режиме «Сейчас» с 08:00 до 21:59, то система должна задать starts_at = сегодня 22:00 и ends_at = завтра 08:00.
  2. В этом случае система должна сохранить бронь с mode = scheduled.
  3. Если «Ночь» выбрана в режиме «Сейчас» с 22:00 до 07:59, то система должна задать starts_at = текущее время и ends_at = ближайшее 08:00.
  4. Цена брони из п. 3 должна быть равна цене тарифа «Ночь».
  5. Когда «Ночь» выбрана в режиме «Запланировать», система должна задать starts_at = выбранная дата 22:00 и ends_at = следующий день 08:00.
  6. Для «Ночи» с starts_at в будущем таймер на дорогу не должен применяться; неявка считается от starts_at + 15 мин.
  7. Ключ доступа для брони «Ночь» должен быть доступен с 21:50.
  8. Проверка exclusion должна использовать реальный интервал брони tstzrange(starts_at, ends_at) без времени до 22:00.

Просрочка выезда (B-016): после ends_at бронь остаётся active; каждые начатые 60 мин — списание по extension_hour_rub; push «Время проживания истекло».

3.3. Участники

Гость (мобильное приложение), Booking (state-machine), Payments, Worker (таймеры), платёжный провайдер, ОФД, Notifications, Админ-панель (получает события, удерживает залог).

3.4. Happy path

  1. Котировка POST /quotes → quote_id, TTL 10 мин (SR-20#1, SR-23#2).
  2. Создание брони → pending_payment (SR-24#1).
  3. Списание «Итого» и холд залога → confirmed (SR-24#1).
  4. Таймер на дорогу (SR-25#1).
  5. Начало проживания → active (SR-32#1).
  6. Выселение → completed (SR-36#2).
  7. Холд залога снимается админ-панелью после проверки или автоматически через 24 ч (B-006).

3.5. Альтернативы и исключения

Ситуация Поведение ref
Интервал занят при создании 409 INTERVAL_TAKEN + ближайшее свободное время SR-20#3
Отказ списания бронь pending_payment, C-16e SR-24#2
Списание успешно, холд отклонён void списания, бронь pending_payment, ошибка TC-054-neg
Двойное нажатие «Оплатить» одна операция по ключу идемпотентности SR-24#3
Продление пересекается со следующей бронью вариант недоступен SR-35#2
Нет ответа провайдера 30 с статус платежа запрашивается повторно каждые 5 с до 5 мин, затем компенсация —

3.6. Timeouts и compensation

Таймер Значение Компенсация
Котировка 10 мин новая котировка
Оплата 10 мин отмена, снятие блокировки, void
Время на дорогу travel_time_min, по умолчанию 20 мин; не применяется к «Ночи», выбранной до 22:00 no_show
Ожидание запланированного заезда 15 мин после starts_at no_show
Сервис доступа 10 с состояние «Ошибка», бронь не меняется

Сага «оплата»: шаг 1 — списание; шаг 2 — холд; при отказе шага 2 — компенсация шага 1 (void или refund).

3.7. SLA

Переход confirmed отображается гостю не позднее 3 с после ответа провайдера (p95). Таймеры срабатывают с отклонением не более 30 с.

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

SR-20, SR-24, SR-25, SR-27, SR-32, SR-35, SR-36, SR-37.

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

depends-on: SPEC-DATA-01, SPEC-INT-01.

6. Verification

TC-054 … TC-059, TC-062, TC-063, TC-069, TC-079 … TC-081 и парные -neg.

Метаданные RENAR
id: SPEC-PROC-01
title: "Жизненный цикл брони"
type: SPEC-PROC
source: { adapt: ADAPT-001, adapt-section: "Forward §3, §4; B-007, B-008, B-009, B-016, B-023, B-038", tz-section: "§3.3; §4 сц. 1 – 3" }
depends-on: [SPEC-DATA-01, SPEC-INT-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