# Техническое задание
## Микросервис управления доверенными адресами клиентов (Белые списки 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.