Перейти к основному содержимому

Журнал ревью документации

Независимые ревью концепции и документации платформы. Каждая запись датирована, содержит модель-рецензента и итоговую оценку.

Ревью 2026-04-22 — Концепция системы​

Рецензент: Claude Opus 4.7 (независимый, без контекста разработки) Объект: Вся документация docs/vitiana-api-platform/ — 10 MD-файлов, ≈325 КБ Тип: Концептуальный ревью (код не написан, оцениваем логику и согласованность) Оценка: 5.5 / 10

Критические проблемы​

1. Название проекта не совпадает с содержимым​

Slug и заголовок — Vitiana API Platform. Внутри всех 10 документов слово «Vitiana» не встречается ни разу. Весь контент описывает продукт vitrip.store (339 упоминаний: домены, Docker-образы, namespace Kubernetes, JWT-структуры, SDK-классы).

Необходимо определиться: это ребрендинг или ошибка при создании проекта. Привести все документы к единому названию до начала разработки.

2. Все документы — «Черновик», нет источника правды​

Все 10 файлов имеют статус Черновик. При этом в overview/layers.md front-matter содержит draft: false — прямое противоречие со статусом в теле документа. Неясно, какие разделы считать актуальными и принятыми к реализации.

3. Внутренние противоречия схемы данных​

Три документа описывают одни и те же сущности по-разному:

  • storage.md описывает таблицы hotels.rooms и hotels.pricing
  • database-schema.md определяет hotels.room_types (другие поля) и не содержит hotels.pricing
  • SQL-запросы в business-services.md обращаются к hotels.rooms и полям guest_name, guest_email, agent_id, которых нет в схеме из database-schema.md

Нужен один эталонный документ схемы. database-schema.md — кандидат, остальные должны ссылаться на него.

4. Rate limits Partner API расходятся в 60 раз​

  • overview/layers.md: Sandbox — 100 requests/min, 1000/hour
  • reference/api-contracts.md: Sandbox — 100 requests/hour, 10/minute (burst)

Для партнёров это контрактное требование. Расхождение в 60× — критично для проектирования интеграций.

5. Отсутствующие сущности в схеме​

  • Partner API-ключи: Go-структура APIKey описана в layers.md, но таблицы для хранения ключей нет ни в database-schema.md, ни в storage.md. Ключи негде персистировать.
  • JWT refresh-token blacklist: упомянут в api-contracts.md как механизм отзыва токенов, но таблицы или Redis-структуры для blacklist нет.

Существенные проблемы​

6. Алгоритм матчинга отелей — два варианта с разными весами​

  • database-schema.md, SQL-функция: веса 0.4 (name) + 0.4 (location) + 0.2 (street) = 1.0
  • ingestion.md, Rust HotelMatcher: веса 0.4 + 0.4 + 0.2 + amenities×0.1 = 1.1 (сумма > 1.0)

В SQL-коде комментарий: «упрощённый расчёт, в реальности используется Rust-алгоритм». Нужен один эталонный алгоритм с корректными весами (сумма = 1.0).

7. Формат API-ключей партнёров несогласован​

  • layers.md: префикс sb_ (sandbox)
  • api-contracts.md и clients.md: префикс sb_test_

Формат ключа — часть публичного контракта партнёрского API. Должен быть одинаковым везде.

8. Тип поля coordinates​

database-schema.md: coordinates POINT. Используется с PostGIS-функциями (ST_DWithin, ST_MakePoint, ST_Distance) по всей документации. Тип POINT (нативный PostgreSQL) несовместим с PostGIS без явного приведения. Правильный тип: geography(Point, 4326).

9. Битые пути в ссылках​

  • overview/layers.md: ссылка на reference/reference/api-contracts.md — двойной reference/
  • reference/storage.md: ссылка на reference/reference/database-schema.md — та же ошибка

Оба документа уже существуют по корректным путям, ссылки не обновлялись.

10. Поле entity_id — конфликт типов​

content.images.entity_id объявлен как UUID. Но hotels.amenities.id и hotels.room_types.id — тип SERIAL (INTEGER). Записать изображение для amenity или room_type в таблицу content.images без приведения типа невозможно.

Структурные замечания​

11. layers.md — название вводит в заблуждение​

Файл называется «Слои архитектуры» (layers.md), но описывает только один слой — API Gateway. Остальные 5 слоёв разнесены по reference/. Либо переименовать в api-layer.md, либо дополнить обзором всех слоёв.

12. Навигация index.md ведёт не туда​

Ссылка «Обзор» в корневом index.md указывает на overview/layers.md (один слой), а не на overview/index.md (общая архитектура). Первый шаг навигации сбивает с толку.

13. Нет определения роли «агент»​

Термины «агент», «турагент», «travel agent», «agency member» используются смешанно. В bookings.reservations код использует agent_id, но в database-schema.md это поле называется user_id. Нужно закрепить: агент — это users.profiles с ролью agent, или отдельная сущность?

Стиль и язык​

  • Опечатка в ingestion.md: "homeogo" вместо "hometogo" — встречается только в одном месте, везде остальных написано верно
  • Timezone: 'Europe/Kiev' (устаревшее) — актуальное IANA: 'Europe/Kyiv'
  • HTML-entities в markdown (&amp;, &lt;) — признак copy-paste из HTML-экспорта, нужно заменить на & и <
  • Заголовки файлов: непоследовательный формат (с кавычками/без, рус/eng/смешанный)

Что хорошо​

  • Широкий охват: 10 документов, 6 архитектурных слоёв, 32 SVG-диаграммы
  • Конкретные примеры: YAML-манифесты, структуры данных, схемы потоков
  • Перекрёстные ссылки между разделами
  • Логичное разделение на слои по 6-уровневой архитектуре

Приоритеты до начала разработки​

  1. Определиться с названием: Vitiana или vitrip.store — привести все документы
  2. Выбрать один эталон схемы БД (database-schema.md) и устранить противоречия с storage.md и business-services.md
  3. Согласовать rate limits и форматы API-ключей во всех файлах
  4. Добавить схему хранения Partner API-ключей и JWT-blacklist
  5. Зафиксировать алгоритм матчинга с корректными весами (сумма = 1.0)
  6. Исправить тип coordinates → geography(Point, 4326)
  7. Определить роль «агент» как единую сущность