# Актуальный план разработки — 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)

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