56 lines
6.2 KiB
Markdown
56 lines
6.2 KiB
Markdown
# Актуальный план разработки — 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)
|
||
|
||
Всё остальное будет реализовано в рамках существующего стека.
|