IPWhiteList/docs/plan-gemini.md

Актуальный план разработки — IP WhiteList Microservice

Автор: GitHub Copilot (Gemini 3.1 Pro Preview) Дата: 2026-05-30 Основание: ТЗ (WhiteIPlist.txt) + Реальный код (Node.js/Express)

1. Анализ предыдущего плана и моё мнение

Мой предыдущий план (plan-gemini.md) оказался полностью оторванным от реальности. Я предполагал писать всё с нуля на Python/FastAPI+SQLModel. На деле же ядро полностью готово и написано на Node.js, Express, EJS и чистом SQL (pg pool). Писать с нуля на питоне — это плодить техдолг и выкидывать рабочий код. Более того, серверная валидация, структура БД, CRUD и UI уже в целом соответствуют ТЗ, но сильно не хватает связующих звеньев.

Поэтому мой главный тезис: хватит придумывать архитектуру, нужно закрывать дыры по функциональным требованиям ТЗ в текущем Node.js проекте.

2. Разрыв между ТЗ (WhiteIPlist.txt) и кодом (Node.js)

Что готово и работает:

• База данных: Полная структура (companies, whitelist_entries, audit_log), реализован soft delete (deleted_at).
• Слой данных (queries.js): Работает базовый CRUD, сохраняются логи аудита, обрабатываются ограничения (глобальные и кастомные).
• Валидация (validators.js): Реализованы проверки на IPv4, маски /22-/32, зашиты все запрещённые диапазоны (RFC1918, CGNAT, Loopback и т.д.).
• UI: Причесанный EJS-шаблон добавления/просмотра/удаления.

Чего не хватает по ТЗ (Фокус дальнейшей разработки):

1. Авторизация (Keycloak OIDC): Сейчас сделан временный парсинг JWT через Base64 без валидации ключей (DEV_MODE).
2. Multi-company и Роли (Админ/Клиент): Не реализованы переключатель компаний и админские страницы (видимость всех записей, изменение лимитов, просмотр аудита).
3. Редактирование записей: Метод updateEntry написан в БД-слое, но UI и роут отсутствуют. Формально ТЗ не закрыто.
4. Агрегация в Экспорте: Маршрут GET /export просто выплёвывает адреса в столбик, тогда как ТЗ жёстко требует суммаризировать подсети в минимальный набор CIDR.
5. Клиентская валидация: ТЗ явно требует валидировать формат и маски на фронтенде перед отправкой.

3. Детальный план по шагам (Node.js)

Этап 1: Исправление багов в текущем MVP

• Баг с overlaps: В validators.js функция overlaps() содержит логическую ошибку в start/end (может пропускать пересекающиеся подсети). Переписать условие.
• UI Редактирования: Добавить роут POST /update/:id в server.js и добавить кнопку/форму "Изменить" в index.ejs, подключив существующую updateEntry(...).

Этап 2: Строгое соответствие ТЗ (Валидация и Экспорт)

• Суммаризация CIDR: Так как в Node.js нет ipaddress.collapse_addresses, необходимо использовать библиотеку вроде cidr-tools (функция merge() отлично справится) для GET /export.
• Клиентская валидация: Добавить минимальный JavaScript в index.ejs для проверки валидности вводимого IP-адреса и маски до ухода POST-запроса, чтобы экономить серверные ресурсы (Требование ТЗ).

Этап 3: Подключение OIDC Keycloak

• Установка библиотеки openid-client (или passport-openidconnect).
• Настройка middleware: получение сертификатов из Keycloak, валидация подписи JWT-токена.
• Извлечение claim clientID (и логика переключения между компаниями, если clientID является массивом). Определение роли (кто админ, WZ01112). Обязательный отказ от dev-заглушки в PROD.

Этап 4: Админ-панель (пользователь WZ01112)

• Роут GET /admin и шаблон admin.ejs. Таблица со всеми компаниями и их лимитами, фильтрацией.
• Функционал установки custom_limit для компании.
• Страница/вкладка GET /admin/audit для просмотра audit_log.
• Переключатель отображения Soft-deleted записей.

4. Зависимости

В package.json придется добавить лишь две новые production-зависимости, не усложняя проект:

• cidr-tools (для агрегации при экспорте)
• openid-client / jsonwebtoken (для безопасной работы с Keycloak)

Всё остальное будет реализовано в рамках существующего стека.