# IP WhiteList — План разработки

> **Дата:** 2026-05-30  
> **Основание:** [WhiteIPlist.txt](../WhiteIPlist.txt) (ТЗ) + фактический код в [ipwhitelist-app](../../ipwhitelist-app)  
> **Статус:** каноничный — единственный актуальный план

---

## 1. Текущее состояние

### Готово ✅

| Слой | Файлы | Что есть |
|---|---|---|
| БД | `sql/schema.sql` | `companies`, `whitelist_entries` (soft delete), `audit_log` + индексы |
| Валидатор | `src/validators.js` | Все 14 запрещённых диапазонов Приложения А, /22–/32, нормализация host-битов, проверка пересечений |
| CRUD | `src/queries.js` | `createEntry`, `updateEntry`, `deleteEntry` (soft), `listEntries`, `getExportCIDRs`, `getAudit`, `getLimit` |
| UI | `views/index.ejs` | Список, форма добавления, кнопка удаления, стиль Nubes |
| Роуты | `server.js` | `GET /`, `POST /add`, `POST /delete/:id`, `GET /export`, `GET /healthz` |

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

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

---

## 2. Что требует ТЗ, но отсутствует

| # | Требование | Готовность |
|---|---|---|
| 1 | Редактирование записи из UI | ❌ queries есть, роута нет |
| 2 | Админ-панель (все компании, лимиты, аудит, фильтры) | ❌ |
| 3 | OIDC Keycloak вместо base64-заглушки | ❌ |
| 4 | Суммаризация CIDR в `/export` | ❌ отдаёт сырой список |
| 5 | Клиентская валидация (JS в форме) | ❌ |
| 6 | Переключатель компаний (multi-company) | ❌ |
| 7 | Просмотр soft-deleted записей админом | ❌ |
| 8 | Изменение `custom_limit` для компании | ❌ |

---

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

### Этап 1 — Пользовательский сценарий (client-flow)

- [x] Валидатор IPv4/CIDR — полный
- [x] Создание / удаление / экспорт
- [ ] **Добавить `POST /update/:id`** в `server.js`
- [ ] **Добавить inline-форму редактирования** в `views/index.ejs`
- [ ] **Клиентская валидация** (JS: формат, маска, длина комментария)

### Этап 2 — Административная панель

- [ ] Определение admin-роли (`clientId === 'WZ01112'` + чекбокс)
- [ ] `GET /admin` — страница со всеми компаниями
- [ ] `POST /admin/limit/:companyId` — изменение custom_limit
- [ ] `GET /admin/audit` — журнал аудита
- [ ] Фильтр по компании + показ удалённых записей

### Этап 3 — Авторизация Keycloak OIDC

- [ ] `npm install openid-client`
- [ ] Замена base64-decode на проверку подписи JWT
- [ ] Маппинг claims → `req.user` (clientId, email, role)
- [ ] Оставить `DEV_MODE` только для локальной разработки

### Этап 4 — Экспорт и Multi-company

- [ ] `npm install cidr-tools` — суммаризация в `GET /export`
- [ ] Переключатель активной компании (если несколько `clientId` в claims)

### Этап 5 — Завершение

- [ ] Автотесты (`jest` + `supertest`)
- [ ] Пагинация (если лимит > 50)
- [ ] Сверка всех пунктов ТЗ

---

## 4. Что НЕ делать

- ❌ Не переписывать на Python/FastAPI
- ❌ Не менять схему БД
- ❌ Не переписывать `validators.js` (он полный)
- ❌ Не переписывать `queries.js`
- ❌ Не делать SPA

---

## 5. Зависимости для установки

```
npm install cidr-tools openid-client
npm install --save-dev jest supertest
```

Всё остальное — в рамках Express + EJS + pg.

---

## 6. Риски

- **Admin-роль:** неясно как «отдельный чек-бокс» из ТЗ попадает в токен — требует уточнения с командой Keycloak
- **Multi-company claims:** ТЗ говорит о нескольких компаниях, но в claims только `clientID` — нужен реальный формат
- **IP-ограничение `/export`:** делать в приложении или на уровне ingress — решить при деплое