docs: рабочий план с учётом разведки (Node.js, lk-api-gateway)

docs/plan-working.md

@@ -0,0 +1,103 @@
+# Рабочий план — IP WhiteList
+
+> **Автор:** GitHub Copilot (Claude Sonnet 4.6)
+> **Дата:** 2026-05-29
+> **Стек:** Node.js + Express + pg + EJS
+> **Деплой:** nubes_nodejs + nubes_postgres (через веб-кабинет)
+
+---
+
+## Что выяснили
+
+| Факт | Детали |
+|---|---|
+| **API шлюз** | `lk-api-gateway.ngcloud.ru`, за DDOS-Guard |
+| **JWT** | `iss: auth-api`, claims: `ClientID`, `company_id`, `company_name`, `email` |
+| **Токен для dev** | `secrets.txt`, tech-токен, долгий |
+| **Валидация JWT** | Шлюз делает сам, нам не нужно |
+| **Деплой** | Пользователь создаёт инстансы через веб-кабинет |
+| **isAdmin** | ❓ В JWT нет, нужно уточнить как передавать |
+| **Мульти-компании** | ❓ В JWT одна компания, список — в authData (localStorage) |
+
+---
+
+## Файлы проекта (всё в корне)
+
+```
+├── server.js          # Express: старт, роуты, middleware
+├── db.js              # pg Pool
+├── .env.example       # DB_DSN, PORT, DEFAULT_LIMIT, DEV_MODE
+├── package.json
+├── views/             # EJS-шаблоны
+│   └── index.ejs      # таблица + форма
+├── public/
+│   └── style.css
+├── sql/
+│   └── schema.sql     # CREATE TABLE companies, whitelist_entries, audit_log
+└── .gitignore
+```
+
+---
+
+## Схема БД
+
+```sql
+companies (id, client_id UNIQUE, name, custom_limit)
+whitelist_entries (id, company_id FK, value_cidr, comment, created_by, created_at, updated_by, updated_at, deleted_by, deleted_at)
+audit_log (id, user_email, company_id, action, old_value, new_value, created_at)
+```
+
+- `deleted_at IS NULL` = активная запись
+- `custom_limit IS NULL` = использовать DEFAULT_LIMIT (15)
+
+---
+
+## Порядок действий
+
+### Шаг 1 — Каркас
+- package.json (express, pg, ejs, dotenv)
+- server.js (Express, EJS, static, health check `/healthz`)
+- db.js (pg Pool, `SELECT 1` при старте)
+- .env.example
+
+### Шаг 2 — Схема БД
+- sql/schema.sql
+- Запустить на своём PG
+
+### Шаг 3 — Валидатор IPv4
+- Функция validateCIDR(input) → { cidr, wasNormalized } | error
+- Правила: /32–/22, запрет серых, нормализация host-битов
+
+### Шаг 4 — CRUD (сырой pg, без ORM)
+- Список записей компании
+- Создание (проверка лимита, дубликатов, пересечений)
+- Редактирование
+- Soft-delete
+
+### Шаг 5 — Auth middleware
+- DEV_MODE=true: читать заголовок X-Dev-User
+- PROD: читать JWT из Authorization (шлюз уже проверил)
+
+### Шаг 6 — UI
+- Таблица + форма создания/редактирования
+- Индикатор лимита «X из N»
+- Сообщения: нормализация, превышение, пересечение
+
+### Шаг 7 — Аудит
+- Запись в audit_log при create/update/delete
+
+### Шаг 8 — Экспорт
+- GET /api/v1/export — txt, все активные CIDR
+
+### Шаг 9 — Деплой
+- Завести nubes_postgres и nubes_nodejs через кабинет
+- Подключить к API-шлюзу (уточнить процедуру)
+
+---
+
+## Что откладываем
+
+- Keycloak OIDC (шлюз делает)
+- Полноценный админ-интерфейс
+- Переключатель компаний (multi-profile)
+- Тонкая настройка прав