IPWhiteList/docs/plan-actual.md

План разработки IP WhiteList — актуальный (30.05.2026)

Основан на ТЗ (WhiteIPlist.txt) и реальном состоянии кода.
Все предыдущие планы (plan.md, plan-v2.md, plan-working.md, plan-gemini.md, plan-gpt54.md) устарели.

---

Что уже работает (не трогать)

Компонент	Файл	Состояние
Валидатор IPv4/CIDR	src/validators.js	✅ Полный — все 14 диапазонов Приложения А
CRUD функции	src/queries.js	✅ createEntry, updateEntry, deleteEntry, listEntries, getExportCIDRs, getAudit
Soft delete	src/queries.js + sql/schema.sql	✅ deleted_at, deleted_by
Схема БД	sql/schema.sql	✅ Все таблицы и индексы
Аудит-лог запись	src/queries.js	✅ Пишется при CREATE/UPDATE/DELETE
UI главная страница	views/index.ejs	✅ Стиль Nubes
Экспорт txt	server.js GET /export	✅ Работает (без суммаризации)
Лимит + custom_limit	src/queries.js	✅

---

Что есть в queries.js, но не подключено к роутам

• updateEntry — написана, роута POST /update/:id нет, UI-кнопки нет
• getAudit — написана, роута и страницы нет
• listEntries(companyId, includeDeleted=true) — параметр есть, но нигде не вызывается с true

---

Что отсутствует полностью

A. Роуты (server.js)

• POST /update/:id — редактирование записи
• GET /admin — страница администратора
• POST /admin/limit/:companyId — изменение лимита компании
• GET /admin/audit — журнал аудита (только для admin)

B. UI (views/)

• Кнопка и inline-форма редактирования в таблице
• Страница admin (views/admin.ejs):
  • Список всех компаний
  • Записи с фильтром по компании
  • Переключатель "показать удалённые"
  • Журнал аудита
  • Изменение лимита компании

C. Авторизация

• Текущий код: наивный base64 decode JWT — не проверяет подпись, не Keycloak
• Нужно: openid-client (OIDC), интеграция с Keycloak, проверка clientID и email из claims
• Admin-роль: clientId === 'WZ01112' — определяется из claim

D. Суммаризация CIDR в экспорте

• ТЗ требует агрегацию в минимальный набор CIDR
• Нужна библиотека: npm install cidr-tools или ip-range-check
• Или самописный merge (sorted ranges → contiguous merge)

E. Клиентская валидация

• ТЗ: валидация на клиенте обязательна, серверная — авторитетная
• Сейчас: только серверная
• Нужно: JS в index.ejs — проверить формат CIDR, маску /22–/32, не RFC1918

F. Переключатель компаний

• ТЗ: пользователь может быть в нескольких компаниях (несколько clientId в токене)
• Нужно: UI-dropdown, переключение активного clientId, хранение выбора в сессии

---

Обнаруженные баги

overlaps() в validators.js — логическая ошибка

// Текущий код (неверно):
return a.start <= b.end && b.start <= a.start ||
       b.start <= a.end && a.start <= b.start;

// Правильно:
return a.start <= b.end && b.start <= a.end;

Стандартное условие пересечения отрезков. Текущий код даёт false positive для некоторых смежных диапазонов.
Приоритет: высокий — влияет на корректность проверки пересечений.

---

Порядок реализации

Этап 1 — Критические фиксы (не ломают работу)

1. Исправить overlaps() в validators.js
2. Добавить POST /update/:id в server.js
3. Добавить кнопку редактирования + inline-форму в views/index.ejs

Этап 2 — Полнота ТЗ

4. Клиентская валидация (JS в index.ejs)
5. Суммаризация CIDR в GET /export (cidr-tools или ручной merge)
6. Определение admin-роли (clientId === 'WZ01112')
7. Страница /admin + роут GET /admin
8. Роут POST /admin/limit/:companyId
9. Журнал аудита для admin (GET /admin/audit)

Этап 3 — Авторизация (блокирующая для продакшена)

10. npm install openid-client — OIDC Keycloak
11. Заменить auth middleware на реальную проверку токена
12. Убрать DEV_MODE (или оставить только для локальной разработки)

Этап 4 — Опционально

13. Переключатель компаний (multi-company claim)
14. Автотесты: npm install --save-dev jest supertest
15. Пагинация (только если лимит вырастет > 50)
16. Audit UI для клиента (не только admin)

---

Зависимости

openid-client   — OIDC / Keycloak
cidr-tools      — суммаризация CIDR в экспорте

Всё остальное — в рамках существующего стека (Express, EJS, pg).

---

Что НЕ нужно делать

• Переписывать validators.js (только исправить overlaps)
• Переписывать queries.js — всё уже написано
• Менять схему БД — она полная
• Пересобирать стек — Express + EJS достаточно для ТЗ