# Рабочий план — 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)
- Тонкая настройка прав