docs: вопросы для уточнения с командой Keycloak/Nubes

2026-05-30 07:27:01 +03:00
parent 09ffa4c385
commit c9143b879d
1 changed files with 80 additions and 0 deletions
@@ -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): заглушка, убрать перед продакшеном
+```