132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
# План разработки 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 — логическая ошибка
|
||
|
||
```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 достаточно для ТЗ
|