From c9143b879d17fa1ca0c25806987c128483ea403e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Sat, 30 May 2026 07:27:01 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B2=D0=BE=D0=BF=D1=80=D0=BE=D1=81?=
 =?UTF-8?q?=D1=8B=20=D0=B4=D0=BB=D1=8F=20=D1=83=D1=82=D0=BE=D1=87=D0=BD?=
 =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F=20=D1=81=20=D0=BA=D0=BE=D0=BC=D0=B0?=
 =?UTF-8?q?=D0=BD=D0=B4=D0=BE=D0=B9=20Keycloak/Nubes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/questions.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/questions.md

diff --git a/docs/questions.md b/docs/questions.md
new file mode 100644
index 0000000..8ae9733
--- /dev/null
+++ b/docs/questions.md
@@ -0,0 +1,80 @@
+# Вопросы для уточнения — IP WhiteList
+
+> Дата: 2026-05-30  
+> Кому: команда Keycloak / Nubes  
+> Статус: ждём ответов
+
+---
+
+## 1. Admin-роль: «отдельный чек-бокс»
+
+**ТЗ:** Администратор = `clientId = WZ01112` + отдельный чек-бокс.
+
+**Вопросы:**
+- В каком claim приходит этот чек-бокс? (realm_role, client_role, group, attribute?)
+- Как точно называется claim? Примеры возможных значений:
+  - `"roles": ["whitelist-admin"]`
+  - `"resource_access.whitelist.roles": ["admin"]`
+  - `"is_admin": true`
+- Нужна ли поддержка нескольких админов (не только WZ01112)?
+
+**Как обойти:** захардкодить `clientId === 'WZ01112'` как признак админа, добавить `TODO` с ссылкой на этот файл.
+
+---
+
+## 2. Multi-company: формат claims
+
+**ТЗ:** Пользователь может принадлежать нескольким компаниям, в UI — переключатель.
+
+**Вопросы:**
+- `clientID` в токене — это строка или массив строк?
+- Если массив — как называется claim? (`clientIDs`, `groups`, что-то ещё?)
+- Есть ли claim с названием компании (для отображения в переключателе)?
+- Пример реального payload токена (без секретов) для пользователя с 2+ компаниями.
+
+**Как обойти:** всегда считать `clientId` строкой (один клиент), переключатель не делать, добавить `TODO`.
+
+---
+
+## 3. IP-ограничение /export
+
+**ТЗ:** Endpoint экспорта «на старте может работать без авторизации (по сетевому ограничению)».
+
+**Вопросы:**
+- Ограничение делаем в приложении или на уровне ingress (nginx/traefik)?
+- Если в приложении — где взять список разрешённых IP? (env var, файл, БД?)
+- Если ingress — кто настраивает?
+
+**Как обойти:** оставить `/export` открытым, добавить `TODO`.
+
+---
+
+## 4. Email пользователя
+
+**ТЗ:** `email` — идентификация пользователя для аудита.
+
+**Вопросы:**
+- Как называется claim с email? (`email`, `preferred_username`, что-то ещё?)
+- Всегда ли он присутствует в токене?
+
+**Как обойти:** брать `payload.email` с fallback на `payload.sub`, добавить `TODO`.
+
+---
+
+## 5. DEV_MODE
+
+**Вопросы:**
+- Нужен ли dev-режим на платформе Nubes (не локально)?
+- Или всегда только реальный Keycloak?
+
+**Как обойти:** оставить `DEV_MODE=true` с проверкой что в production падает при включении.
+
+---
+
+## Условные обозначения в коде
+
+```
+// TODO(Keycloak): уточнить формат claim — см. docs/questions.md#1
+// FIXME(Keycloak): временно, заменить после ответа команды
+// HACK(DEV_MODE): заглушка, убрать перед продакшеном
+```