tz

TZs/TZ_real.md

@@ -0,0 +1,130 @@
+# Техническое задание
+## Микросервис управления доверенными адресами клиентов (Белые списки IP)
+
+---
+
+# 1. Назначение
+
+Клиенты облачного провайдера через личный кабинет управляют своими доверенными IPv4-адресами. Эти адреса исключаются из блокировки при DDoS-атаках.
+
+Администраторы Нубеса могут просматривать и редактировать списки всех клиентов.
+
+---
+
+# 2. Авторизация
+
+## 2.1. Вход
+
+Пользователь входит через Keycloak (OIDC). После входа приложение запрашивает IAM API — сервис авторизации экосистемы Nubes.
+
+IAM возвращает:
+- email пользователя
+- список компаний, к которым он принадлежит
+- активную компанию
+- флаг администратора (isAdmin)
+
+## 2.2. Роли
+
+| Роль | Возможности |
+|---|---|
+| Клиент | Видит и редактирует только записи своих компаний |
+| Администратор Нубеса | Видит и редактирует записи всех компаний, меняет лимиты, смотрит аудит, выгружает списки |
+
+Администратором считается пользователь с `isAdmin = true` в IAM и `clientId = WZ01112`. Если у пользователя несколько компаний, он переключается между ними.
+
+## 2.3. Режим администратора
+
+Пользователь Нубеса видит переключатель «Администратор». В обычном режиме интерфейс как у клиента. При включении — выпадающий список всех компаний, ссылки на аудит и управление лимитами.
+
+---
+
+# 3. Управление записями
+
+## 3.1. Просмотр
+
+Клиент видит таблицу записей своей компании. Администратор выбирает компанию из списка.
+
+Для каждой записи показывается: адрес/подсеть, комментарий, кто добавил, даты создания и изменения. Удалённые записи отображаются зачёркнутыми и полупрозрачными, без кнопок редактирования. Кнопки «Изменить» и «Удалить» — в строке таблицы.
+
+Счётчик: «X из N записей».
+
+## 3.2. Добавление
+
+Форма: IPv4-адрес или CIDR, комментарий (необязательно, до 255 символов).
+
+Проверки:
+- Формат: только IPv4, одиночный адрес или подсеть /22–/32
+- Нормализация: хост-биты обнуляются, пользователь уведомляется
+- Запрещённые диапазоны: 14 служебных подсетей (RFC1918, CGNAT, loopback и др.)
+- Нет дубликатов и пересечений внутри компании
+- Лимит компании (по умолчанию 15)
+
+При превышении лимита — блокировка с сообщением.
+
+## 3.3. Редактирование
+
+Изменение адреса и комментария. Все проверки — как при добавлении.
+
+## 3.4. Удаление
+
+Логическое (soft delete): запись помечается удалённой, но физически сохраняется. Освобождает место в лимите. Исключается из выгрузки.
+
+---
+
+# 4. Лимиты
+
+- По умолчанию: 15 записей на компанию
+- Администратор задаёт индивидуальный лимит компании (больше или меньше)
+- Снижение лимита не удаляет существующие записи, но блокирует новые
+
+---
+
+# 5. Экспорт
+
+Администратор выгружает агрегированный список всех активных CIDR.
+
+- По умолчанию — JSON: `{ cidrs: [...], count: N }`
+- `?format=txt` — текстовый файл, одна подсеть на строку
+- `?company=<id>` — выгрузка по конкретной компании
+
+---
+
+# 6. Аудит
+
+Все изменения (создание, редактирование, удаление) пишутся в журнал. Записи неизменяемы.
+
+Состав записи: кто сделал, когда, компания, действие, старое и новое значение.
+
+При имперсонации добавляется поле «имперсонировал» — кто на самом деле совершил действие.
+
+Журнал доступен только администратору. Фильтр по компании.
+
+---
+
+# 7. Имперсонация
+
+Администратор IAM может «притворяться» другим пользователем или компанией. Приложение получает флаг `is_impersonated` из IAM.
+
+При активной имперсонации:
+- Жёлтый баннер: «Режим имперсонации — от имени Компания (вы: originalUserEmail)»
+- CRUD идёт в контексте имперсонируемой компании
+- Аудит: `created_by = имперсонируемый`, `impersonated_by = реальный админ`
+
+Без имперсонации `impersonated_by = NULL`.
+
+---
+
+# 8. Интерфейс
+
+- Главная страница: таблица записей, форма добавления, переключатель компаний
+- Аудит: `/audit` — журнал с фильтром по компании
+- Лимиты: `/admin` — список компаний с лимитами
+- Экспорт: `/export` — выгрузка списка
+
+Шапка: логотип, версия приложения, email пользователя, переключатель «Администратор», кнопка «Выйти».
+
+---
+
+# 9. Технологии
+
+Node.js, Express, EJS, PostgreSQL, Keycloak OIDC, IAM API.