ipwhitelist-app/docs/ТЗ-плюс.md

ТЗ-плюс — уточнения и дополнения от заказчика

Основа: docs/ТЗ.md
Файл для фиксации уточнений, дополнений и решений по мере обсуждения с заказчиком/DevOps.
Каждая запись = дата + источник + формулировка + статус.

---

1. Аутентификация и Keycloak

1.1. client_id приложения в Keycloak

• Дата: 2026-06-02
• Источник: HAR Files/nubes_login.har
• Факт: client_id = deck-test.ngcloud.ru (в URL auth-запроса)
• Статус: 🔴 требует подтверждения — этот ли client_id для ipwhitelist, или будет отдельный?

1.2. ClientID в JWT — УТОЧНЕНО

• ТЗ: claim ClientID — идентификатор компании
• Факт (HAR): ClientID: "WZ01325", нет массива
• Факт (token.txt): ClientID отсутствует, вместо него claims[] с названиями namespace'ов
• Уточнение заказчика (01.06.2026): в claims приходит clientid. Формат может быть разный.
  • Одно значение: WZ04228, 1700, asokolov-test
  • Несколько через запятую: WZ11125, WZ03816, WZ52235, WZ62587, WZ02315
  • Логика: первое «слово» до запятой определяет общий ЛК. Пользователи с одинаковым первым словом → общий whitelist.
• Что делать в коде: брать первый clientid до запятой как активную компанию. Остальные (если есть) — дополнительные компании пользователя для переключателя.
• Статус: 🟡 уточнено, требует реализации в коде

1.3. Несколько компаний на пользователя — УТОЧНЕНО

• ТЗ, п.3.1: «поддерживается сценарий, когда пользователь принадлежит нескольким компаниям»
• Уточнение заказчика (01.06.2026): поле clientid в claims содержит список через запятую. Примеры: WZ11125, WZ03816, WZ52235, WZ62587, WZ02315.
• Логика ЛК: первое значение до запятой — активная компания. Пользователи с одинаковым первым clientid видят общий whitelist. Переключатель между компаниями — все значения из списка.
• Открытый вопрос: какое именно поле в Keycloak за это отвечает? Заказчик уточнит.
• Статус: 🟡 уточнено, требует реализации в коде

1.4. Admin-роль в Keycloak

• ТЗ: admin = ClientID = WZ01112 + отдельный чек-бокс
• Вопрос: чек-бокс — это claim? Какой? is_admin, realm_access.roles, groups?
• Статус: 🔴

1.5. JWKS URL

• Вариант A: https://keycloak.nubes.ru/realms/cloud/protocol/openid-connect/certs
• Вариант B: https://auth-api... (через API Gateway)
• Статус: 🔴

1.6. Redirect URI

• Предложение: https://white.nodejsk8s.dev.nubes.ru/callback
• Статус: 🔴 требует подтверждения DevOps

---

2. Инфраструктура и деплой

2.1. Платформа

• Статус: 🔴 уточнить — Node.js на k8s? Какой кластер?

2.2. Деплой

• Статус: 🔴 уточнить — CI/CD? Как поставлять jsonEnv?

2.3. Сетевое ограничение для /export

• Вопрос: какие IP/подсети будут потребителями внешней выдачи?
• Статус: 🔴

---

3. Функциональные уточнения

3.1. Мульти-компания в UI

• ТЗ, п.3.1: «переключатель активной компании»
• Вопрос: дизайн переключателя? Dropdown в шапке? Отдельная страница?
• Статус: 🔴

3.2. Soft-delete и фильтр «показать удалённые»

• ТЗ, п.4.1: «для администратора предусмотрен фильтр»
• Код: includeDeleted всегда false
• Статус: 🟡 не реализовано в коде

3.3. Индивидуальные лимиты компаний

• ТЗ, п.4.5: админ может задать индивидуальный лимит
• Код: ?
• Статус: 🔴 проверить реализацию

3.4. Уведомление о нормализации

• ТЗ, п.5: «пользователь должен быть уведомлен, что ввел адрес из хостовой части»
• Статус: 🔴 проверить реализацию в UI

---

4. Тестовые данные

4.1. Тестовые пользователи

Email	ClientID	Компания	Роль
tazet@narod.ru	WZ01325	Тест	Клиент
admin@nubes.ru	WZ01112	Нубес	Админ
tazetdinovn@gmail.com	?	?	? (из token.txt)

4.2. HAR-сессия

• Файл: Files/nubes_login.har
• Пользователь: tazet@narod.ru
• Дата: 2026-05-30
• Окружение: deck-test

---

6. Уточнения от заказчика (01.06.2026)

6.1. Формат clientid в токене

• Поле: clientid в claims JWT
• Формат: строка, значения через запятую если несколько
• Примеры:
  • "WZ04228" — одна компания
  • "1700" — числовой ID
  • "asokolov-test" — текстовый ID
  • "WZ11125, WZ03816" — две компании
  • "WZ52235, WZ62587, WZ02315" — три компании
• Правило: первое «слово» до запятой = активная компания (определяет ЛК)
• Общий доступ: пользователи с одинаковым первым словом имеют общий whitelist

6.2. Экспорт — подтверждение формата

• GET-endpoint отдаёт txt файл
• Одна строка = один объект (адрес/подсеть)
• Без разделителей, без заголовков

6.3. Текущее демо — одобрено

• https://white.nodejsk8s.dev.nubes.ru/login — ✓
• https://white.nodejsk8s.dev.nubes.ru/exp — ✓ (вывод без токена для тестирования)

6.4. Что ещё уточняется

• Какое именно поле Keycloak маппится в clientid claim? (Заказчик уточнит)
• Как определяется admin-роль? (отдельный чек-бокс в Keycloak?)
• client_id и client_secret для регистрации приложения

6.5. Права внутри компании — уточнено (02.06.2026)

• Вопрос: может ли любой юзер компании редактировать whitelist всей компании?
• Ответ заказчика: «Да, любой юзер, который может войти может редактировать»
• Вывод: внутри компании роли не разграничиваются. Любой сотрудник компании имеет полный доступ к whitelist своей компании (создание, редактирование, удаление). Аудит фиксирует кто именно сделал изменение.

---

5. Решения и договорённости

Сюда записывать принятые решения с датой и контекстом.

(пока пусто)

---

Легенда статусов

Статус	Значение
🔴	Требует уточнения
🟡	Уточнено, не реализовано
🟢	Реализовано / подтверждено
⚫	Отменено / не актуально