Домики · Rest&Go

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

SPEC-DATA-01. Модель данных

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

Документ задаёт сущности ТЗ §3.1, их поля, связи, статусы (ТЗ §3.2, §3.3), классификацию ПДн, хранение и подход к миграциям — в объёме, нужном мобильному приложению гостя.

2. Scope

Входит: Hotel, Capsule, CapsuleType, Amenity, Tariff, ExtraService, Booking, BookingExtra, Payment, PaymentMethod, Guest, Consent, KycCheck, Review, LoyaltyAccount, BonusTransaction, SupportThread, SupportMessage, Notification. Не входит: устройства, телеметрия, задачи персонала, франчайзи.

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

3.1. ERD

erDiagram
    HOTEL ||--o{ CAPSULE : has
    CAPSULE_TYPE ||--o{ CAPSULE : types
    HOTEL }o--o{ AMENITY : offers
    CAPSULE }o--o{ AMENITY : equips
    HOTEL ||--o{ TARIFF : prices
    CAPSULE_TYPE ||--o{ TARIFF : for
    HOTEL ||--o{ EXTRA_SERVICE : sells
    GUEST ||--o{ BOOKING : makes
    CAPSULE ||--o{ BOOKING : reserved
    BOOKING ||--o{ BOOKING_EXTRA : includes
    EXTRA_SERVICE ||--o{ BOOKING_EXTRA : chosen
    BOOKING ||--o{ PAYMENT : paid
    GUEST ||--o{ PAYMENT_METHOD : owns
    GUEST ||--o{ CONSENT : gives
    GUEST ||--o{ KYC_CHECK : "passes (ЕСИА)"
    BOOKING ||--o| REVIEW : rated
    GUEST ||--|| LOYALTY_ACCOUNT : has
    LOYALTY_ACCOUNT ||--o{ BONUS_TRANSACTION : logs
    GUEST ||--o{ SUPPORT_THREAD : opens
    SUPPORT_THREAD ||--o{ SUPPORT_MESSAGE : contains
    GUEST ||--o{ NOTIFICATION : receives

3.2. Сущности и поля

Общие поля каждой сущности: id uuid PK default gen_random_uuid(), created_at timestamptz not null default now(), updated_at timestamptz not null.

Сущность Поле Тип Ограничения / умолчание
Hotel name_ru, name_en text not null, ≤ 60 симв.
address text not null
location geography(Point,4326) not null, GIST-индекс
location_type enum(airport, station, highway, business, nature) not null
description_ru/en, directions_ru/en, rules_ru/en text
support_hours text default '24/7'
wifi_ssid, wifi_password text null — Wi-Fi нет (SR-34)
deposit_rub int ≥ 0, default 1000
travel_time_min int default 20 (SR-25, B-007)
status enum(draft, published, paused) клиенту видны только published (SR-10#1)
rating_avg, rating_count numeric(2,1), int агрегат Reviews
Capsule hotel_id FK Hotel on delete restrict
number text unique (hotel_id, number)
type_id FK CapsuleType
area_m2, capacity numeric(4,1), int > 0
service_levels enum[](full, self_service) ≥ 1 элемент
client_status enum(free, soon, busy, unavailable) проекция ADR-05
free_at timestamptz для soon и busy
last_cleaned_at timestamptz SR-16#1
cleanliness_avg numeric(2,1)
CapsuleType name_ru/en, icon text справочник: Базовая, Комфорт, Work & Rest, Премиум, Семейная
Amenity name_ru/en, icon, scope text, text, enum(capsule, territory) icon — имя Lucide
Tariff hotel_id, type_id FK
duration enum(h1, h3, h6, night, day) unique (hotel_id, type_id, duration); night — фиксированный интервал 22:00 – 08:00 местного времени отеля, при заезде после 22:00 цена не меняется (B-038)
price_rub int > 0
extension_hour_rub int на (hotel_id, type_id)
self_service_discount_pct int 0 – 50, default 20
ExtraService hotel_id, name_ru/en, price_rub, kind kind: toggle, counter
Booking number text unique, формат «A-NNNN», для отображения
guest_id, capsule_id FK on delete restrict
mode enum(now, scheduled)
starts_at, ends_at timestamptz ends_at > starts_at; exclusion constraint по capsule_id и tstzrange для статусов pending, confirmed, active
service_level enum
status enum(pending_payment, confirmed, active, completed, cancelled, no_show) SPEC-PROC-01
travel_deadline timestamptz для mode = now
amount_rub, deposit_rub, discount_rub, bonus_rub int
deposit_status enum(none, held, released, retained)
quote_id uuid идемпотентность цены (SPEC-SEC-01 T3)
Payment booking_id FK
kind enum(rent, extension, extra, deposit_hold, deposit_release, refund, deposit_retain)
amount_rub, status, provider_ref, receipt_url, idempotency_key idempotency_key unique
PaymentMethod guest_id, provider_token, kind, mask, brand, is_default одна is_default на гостя (частичный unique)
Guest phone_e164 text unique, шифруется
last_name, first_name, middle_name, birth_date, email шифруются; ФИО и дата рождения — из ЕСИА, только для чтения; middle_name и email null
kyc_status enum(none, approved, rejected) approved только после KycCheck с trust_level = trusted (SR-06#1)
locale, theme enum(ru, en), enum(system, light, dark) default ru, system
deleted_at timestamptz запрос удаления
Consent guest_id, kind, text_version, given_at, revoked_at kind: terms, pd, marketing, esia_data
KycCheck guest_id FK Guest
esia_oid text not null, шифруется; unique среди approved (одна учётная запись ЕСИА — один гость)
trust_level enum(trusted, standard, simplified) approved только при trusted
status enum(approved, rejected, cancelled)
reason text null; «Учётная запись Госуслуг не подтверждена», «Вход отменён», «Бронирование доступно с 18 лет»
passport_series, passport_number, passport_issued_at, passport_issuer text, text, date, text шифруются отдельным ключом (C3)
verified_at timestamptz null при rejected и cancelled
Review booking_id FK unique (SR-41#2)
rating 1 – 5, cleanliness, comfort, quiet smallint rating not null
tags, text (≤ 1000), photos (≤ 5)
admin_reply, admin_reply_at, status(published, hidden)
LoyaltyAccount guest_id, level(bronze, silver, gold), completed_stays, bonus_balance
BonusTransaction account_id, delta, reason, booking_id
SupportThread / SupportMessage guest_id, booking_id null; author(guest, agent), text, attachments, status
Notification guest_id, kind, title, body, payload, read_at

3.3. Классификация, шифрование, retention

Данные Класс (SPEC-SEC-01) At-rest Retention
Guest (ФИО, телефон, email, дата рождения) C2 pgcrypto до удаления аккаунта + 30 дней
KycCheck (esia_oid, паспорт) C3 pgcrypto, отдельный ключ KMS до удаления аккаунта + 30 дней
KycCheck (trust_level, status, verified_at) C2 pgcrypto до удаления аккаунта + 30 дней
Payment C2 платёжные шифрование диска 5 лет (402-ФЗ), после удаления аккаунта — обезличены
Review C0 после публикации — бессрочно, автор обезличивается при удалении аккаунта
SupportMessage C2 шифрование диска 3 года

3.4. Миграции и индексы

Миграции — Flyway, только вперёд, каждая обратно совместима с предыдущей версией приложения (expand → migrate → contract). Индексы: GIST hotel.location; capsule(hotel_id, client_status); booking(guest_id, status); exclusion booking(capsule_id, tstzrange(starts_at, ends_at)); review(hotel_id через capsule, created_at desc); notification(guest_id, created_at desc).

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

SR-06, SR-08, SR-09, SR-10, SR-15, SR-16, SR-20, SR-24, SR-34, SR-41, SR-42, SR-52.

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

depends-on: SPEC-ARCH-01.

6. Verification

Через TC перечисленных SR; ограничение уникальности отзыва — TC-089, TC-089-neg; exclusion-ограничение — TC-046, TC-046-neg.

Метаданные RENAR
id: SPEC-DATA-01
title: "Модель данных гостевого контура"
type: SPEC-DATA
source: { adapt: ADAPT-001, adapt-section: "Forward §1; B-035, B-038", tz-section: "§3.1 – §3.3; §11" }
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