464 lines
20 KiB
Markdown
464 lines
20 KiB
Markdown
Проработка:
|
||
- Прототипы интерфейсов
|
||
- Контракты API (swagger)
|
||
- Пользовательские сценарии (use cases)
|
||
- Sequence диаграммы
|
||
- Сервис лицензий, или какой-то способ модульной поставки сервисов? Может с помощью helm чартов?
|
||
- UI спецификация? Обработка ошибок на UI
|
||
- Система логирования бека, фронта, дебагинг, мониторинг, алертнинг
|
||
- Схема деплоя. Ставимся в кластер? А что если нет кластера? Как упаковывать коробку?
|
||
- Аналитика фичей по отдельности, разделить MVP на небольшие кусочки, поставлять фичи этапами
|
||
- Нагрузочное тестирование
|
||
|
||
|
||
Вопросы от Леши:
|
||
- Оценка временных затрат
|
||
- Оценка денежных затрат (человеческий ресурс от минимум до комфорт, дать диапазон с ролями, стоимостью по сотрудникам)
|
||
|
||
---
|
||
|
||
## Архитектурные решения
|
||
|
||
### ADR-001: Стратегия работы с данными PMS
|
||
|
||
**Контекст:**
|
||
Система интегрируется с PMS (и другими системами) для получения данных о гостях, номерах и бронированиях. Нужно определить, как работать с этими данными.
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Pass-through (запрос по требованию)**
|
||
|
||
Каждый раз запрашиваем данные из PMS когда нужно.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Данные всегда актуальные | Зависимость от доступности PMS |
|
||
| Не нужно хранить и синхронизировать | Задержки на каждый запрос |
|
||
| Нет проблем с консистентностью | Нет истории (кто был в номере вчера?) |
|
||
|
||
**Вариант 2: Полная репликация**
|
||
|
||
Храним копию данных, синхронизируем по событиям или периодически.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Работаем автономно при падении PMS | Сложность синхронизации |
|
||
| Быстрый доступ к данным | Возможны расхождения данных |
|
||
| Есть история | Дублирование хранилища |
|
||
|
||
**Вариант 3: Гибридный**
|
||
|
||
Храним только то, что нужно для задач + кэшируем справочники.
|
||
|
||
*Что храним у себя:*
|
||
- Ссылку на номер/гостя (ID из PMS)
|
||
- Снапшот данных на момент создания задачи (имя гостя, номер комнаты)
|
||
- Историю задач с контекстом
|
||
|
||
*Что запрашиваем из PMS:*
|
||
- Актуальный статус номера (грязный/чистый/занят)
|
||
- Текущие бронирования
|
||
- Справочник номеров (с кэшированием)
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Автономность** — должна ли система работать при недоступности PMS?
|
||
2. **История** — нужно ли знать "для какого гостя делали задачу месяц назад"?
|
||
3. **Частота изменений** — как часто меняются данные в PMS (заезды/выезды)?
|
||
4. **API PMS** — поддерживает ли PMS push-уведомления (webhooks) или только pull?
|
||
5. **Объём** — сколько номеров/гостей в типичном отеле?
|
||
6. **Сценарий** — горничной нужен актуальный статус номера или достаточно того, что было при создании задачи?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-002: Мультитенантность
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
В NFR-SCALE-003 указано, что система должна поддерживать несколько отелей на одной инсталляции. Нужно определить архитектуру изоляции данных.
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Shared Database + tenant_id**
|
||
|
||
Все отели в одной БД, данные разделены по `hotel_id`.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Простота развёртывания | Риск утечки данных между отелями |
|
||
| Легко делать кросс-отельную аналитику | Сложнее масштабировать отдельный отель |
|
||
| Экономия ресурсов | Один отель может "положить" всех |
|
||
|
||
**Вариант 2: Database per Tenant**
|
||
|
||
Отдельная БД на каждый отель.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Полная изоляция данных | Сложность управления миграциями |
|
||
| Можно масштабировать независимо | Больше ресурсов |
|
||
| Проще соответствовать требованиям безопасности | Сложнее кросс-отельная аналитика |
|
||
|
||
**Вариант 3: Schema per Tenant**
|
||
|
||
Одна БД, но отдельная schema на отель.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Баланс изоляции и простоты | Ограничения PostgreSQL на количество schema |
|
||
| Проще бэкапы отдельных отелей | Всё ещё shared resources |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Количество отелей** — сколько отелей планируется на одной инсталляции?
|
||
2. **Требования безопасности** — есть ли требования к физической изоляции данных?
|
||
3. **Кросс-отельная аналитика** — нужны ли отчёты по всем отелям сразу?
|
||
4. **Модель продаж** — SaaS (много мелких) или Enterprise (мало крупных)?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-003: API Gateway — готовое решение или самописный
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
В архитектуре указан API Gateway Layer, но не определено — это готовое решение или часть кода. От этого зависит где происходит аутентификация, rate limiting, routing.
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Готовое решение (Kong / Traefik / AWS API Gateway)**
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Готовый rate limiting, auth, metrics | Дополнительная зависимость |
|
||
| Battle-tested | Может быть избыточно для MVP |
|
||
| Меньше кода | Vendor lock-in (для облачных) |
|
||
|
||
**Вариант 2: Самописный на FastAPI**
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Полный контроль | Нужно писать и поддерживать |
|
||
| Нет лишних зависимостей | Rate limiting, auth — своими руками |
|
||
| Гибкость | Риск ошибок безопасности |
|
||
|
||
**Вариант 3: Nginx + Lua / OpenResty**
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Высокая производительность | Lua — дополнительный язык |
|
||
| Проверенное решение | Сложнее отлаживать |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Где аутентификация?** — Gateway проверяет JWT или каждый сервис сам?
|
||
2. **Rate limiting** — нужен ли в MVP?
|
||
3. **Инфраструктура** — есть ли уже Kubernetes Ingress / Load Balancer?
|
||
4. **Команда** — есть ли опыт с Kong/Traefik?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-004: Разделение users-service и permissions-service
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
В архитектуре есть два отдельных сервиса: `users-service` (пользователи, профили) и `permissions-service` (RBAC, роли). Возможно это избыточно для MVP.
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Два отдельных сервиса (текущий)**
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Чёткое разделение ответственности | Overhead на межсервисное взаимодействие |
|
||
| Можно развивать независимо | Сложнее для MVP |
|
||
| Permissions можно переиспользовать | Больше точек отказа |
|
||
|
||
**Вариант 2: Объединить в один auth-service**
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Проще для MVP | Может разрастись |
|
||
| Меньше latency | Сложнее разделить потом |
|
||
| Один источник правды о пользователе | — |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Сложность RBAC** — насколько сложная система прав планируется?
|
||
2. **Переиспользование** — будут ли другие системы использовать permissions-service?
|
||
3. **MVP scope** — что минимально необходимо для запуска?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-005: WebSocket масштабирование
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
`notification-service` использует WebSocket для real-time уведомлений. При нескольких инстансах сервиса нужен механизм доставки сообщения на нужный инстанс.
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Sticky Sessions**
|
||
|
||
Клиент всегда идёт на один и тот же инстанс.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Просто реализовать | Неравномерная нагрузка |
|
||
| Не нужен pub/sub | При падении инстанса — переподключение |
|
||
|
||
**Вариант 2: Redis Pub/Sub**
|
||
|
||
Все инстансы подписаны на Redis, сообщение доставляется всем.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Равномерная нагрузка | Дополнительная зависимость |
|
||
| Отказоустойчивость | Больше трафика |
|
||
|
||
**Вариант 3: Kafka → все инстансы**
|
||
|
||
Каждый инстанс читает из Kafka и отправляет своим клиентам.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Уже есть Kafka | Дублирование сообщений |
|
||
| Персистентность | Нужна фильтрация на клиенте |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Количество инстансов** — сколько реально будет в production?
|
||
2. **Частота сообщений** — сколько уведомлений в секунду?
|
||
3. **Критичность доставки** — что если уведомление не дошло?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-006: Scheduler — гарантия единственного выполнения
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
`scheduler-service` создаёт задачи по расписанию. При нескольких инстансах может создать дубликаты.
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Distributed Lock (Redis/PostgreSQL)**
|
||
|
||
Только один инстанс выполняет задачу.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Гарантия единственности | Сложность реализации |
|
||
| Отказоустойчивость | Lock может "застрять" |
|
||
|
||
**Вариант 2: Leader Election**
|
||
|
||
Один инстанс — лидер, остальные в standby.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Простая логика в коде | Нужен механизм выбора лидера |
|
||
| — | Single point of failure |
|
||
|
||
**Вариант 3: Один инстанс scheduler'а**
|
||
|
||
Просто не масштабируем этот сервис.
|
||
|
||
| Плюсы | Минусы |
|
||
|-------|--------|
|
||
| Максимально просто | Нет отказоустойчивости |
|
||
| — | Для MVP может быть достаточно |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Критичность** — что если задача не создалась вовремя?
|
||
2. **Частота** — как часто запускаются scheduled задачи?
|
||
3. **MVP** — нужен ли scheduler в MVP вообще? (В ROADMAP он в этапе 3)
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-007: Консистентность данных между сервисами
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
При создании задачи нужно: сохранить в БД, отправить уведомление, записать в аудит. Что если одна из операций упадёт?
|
||
|
||
#### Проблемы
|
||
|
||
1. **Частичное выполнение** — задача создана, но уведомление не отправлено
|
||
2. **Дубликаты** — retry создал задачу дважды
|
||
3. **Порядок событий** — аудит записал раньше, чем задача реально создалась
|
||
|
||
#### Варианты
|
||
|
||
**Вариант 1: Saga Pattern**
|
||
|
||
Цепочка компенсирующих транзакций.
|
||
|
||
**Вариант 2: Outbox Pattern**
|
||
|
||
Сначала пишем в локальную таблицу outbox, потом отдельный процесс отправляет в Kafka.
|
||
|
||
**Вариант 3: Event Sourcing**
|
||
|
||
Храним события, состояние вычисляется.
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Критичность** — насколько критична потеря уведомления?
|
||
2. **Идемпотентность** — как обрабатывать повторные запросы?
|
||
3. **Сложность** — готовы ли усложнять архитектуру ради гарантий?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-008: Жизненный цикл файлов
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
К задачам прикрепляются файлы (фото уборки). Нужно определить что с ними происходит при удалении/архивации задачи.
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Удаление задачи** — удалять файлы или оставлять?
|
||
2. **Архивация** — нужно ли переносить старые файлы в "холодное" хранилище?
|
||
3. **Дедупликация** — один файл может быть привязан к нескольким задачам?
|
||
4. **Квоты** — есть ли лимит на размер файлов / количество на задачу?
|
||
5. **Доступ** — как генерировать URL? Presigned URLs или через API?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-009: gRPC vs REST — когда что использовать
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
В архитектуре указаны оба протокола. Нужно определить границы применения.
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Внешний API** — только REST или gRPC тоже?
|
||
2. **Межсервисное** — всё через gRPC или только критичные вызовы?
|
||
3. **Команда** — есть ли опыт с gRPC?
|
||
4. **Клиенты** — мобильные приложения будут использовать gRPC?
|
||
|
||
#### Потенциальное решение
|
||
|
||
- **REST** — внешний API (клиенты, адаптеры)
|
||
- **gRPC** — межсервисное взаимодействие (tasks ↔ permissions)
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-010: Отсутствующие компоненты в архитектуре
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
При анализе выявлены компоненты, которые не описаны, но могут быть необходимы.
|
||
|
||
#### Что не описано
|
||
|
||
| Компонент | Зачем нужен | Критичность для MVP |
|
||
|-----------|-------------|---------------------|
|
||
| **Health checks** | Kubernetes liveness/readiness probes | Высокая |
|
||
| **Circuit Breaker** | Защита от каскадных отказов | Средняя |
|
||
| **Rate Limiting** | Защита от DDoS/abuse | Средняя |
|
||
| **Service Discovery** | Как сервисы находят друг друга | Высокая (если не K8s) |
|
||
| **Distributed Tracing** | Отладка цепочек вызовов | Низкая для MVP |
|
||
| **Config Service** | Централизованная конфигурация | Низкая |
|
||
| **Secret Management** | Хранение credentials | Высокая |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Kubernetes** — будет ли K8s? Если да, многое решается из коробки
|
||
2. **MVP scope** — что из этого критично для первого релиза?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-011: Безопасность Kafka
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
Через Kafka ходят данные о задачах, гостях, бронированиях. Нужно определить уровень защиты.
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Шифрование** — нужен ли TLS между сервисами и Kafka?
|
||
2. **Аутентификация** — SASL или открытый доступ внутри кластера?
|
||
3. **Авторизация** — ACL на топики (кто может читать/писать)?
|
||
4. **Сетевая изоляция** — Kafka только во внутренней сети?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения*
|
||
|
||
---
|
||
|
||
### ADR-012: Версионирование API
|
||
|
||
**Статус:** Открыт
|
||
|
||
**Контекст:**
|
||
API будет развиваться. Нужна стратегия обратной совместимости.
|
||
|
||
#### Варианты
|
||
|
||
| Подход | Пример | Плюсы | Минусы |
|
||
|--------|--------|-------|--------|
|
||
| URL versioning | `/api/v1/tasks` | Явно, просто | Дублирование кода |
|
||
| Header versioning | `Accept: application/vnd.api.v1+json` | Чистые URL | Сложнее тестировать |
|
||
| Query parameter | `/api/tasks?version=1` | Просто | Некрасиво |
|
||
|
||
#### Вопросы для принятия решения
|
||
|
||
1. **Клиенты** — кто будет потреблять API? Только свои или внешние?
|
||
2. **Частота изменений** — как часто планируются breaking changes?
|
||
|
||
#### Решение
|
||
|
||
*Ожидает обсуждения* |