plan.md

Rama main · réplica de lectura del repositorio original.

# Ревью архитектуры IAM

| Раздел | Что сейчас | Что предлагаю | Почему |
|--------|------------|---------------|---------|
| User Store | Два источника (`front_users` + `users`) | Максимально быстро прийти к одному источнику истины | Две таблицы пользователей почти всегда приводят к рассинхронизации и сложным миграциям. |
| Админка | Работает через Node → Proxy → Backend | Оставить, но описать контракт API отдельно | Чтобы при замене Node или появлении другого клиента API не пришлось переписывать. |
| Роли | Роли + группы + дерево + пользовательские override | Добавить встроенные системные роли (`admin`, `manager`, `user`) | Большинство пользователей не требуют сложной матрицы прав. Простые роли сильно упрощают администрирование. |
| Права | `allow/deny` | Добавить понятие Scope (`global`, `org`, `group`, `user`) | Позволит легче расширять систему и уменьшит количество условий в коде. |
| Permission Keys | Строки (`internet`, `shared_kb`) | Сделать namespace (`system.internet`, `rag.shared`, `tools.web_search`) | Через год появится 50+ прав. Namespace значительно упрощает поддержку. |
| Дерево подразделений | Materialized Path | Сразу описать возможность смены реализации | Если организация вырастет, можно заменить реализацию без изменения API. |
| Конфликт прав | deny > allow | Добавить таблицу приоритетов в документацию | Чтобы алгоритм был очевиден всем разработчикам. |
| Эффективные права | Кэш Redis | Добавить локальный LRU-кэш процесса | Большинство запросов не должны идти даже в Redis. |
| Аудит | JSON Before/After | Добавить тип события (`CREATE`, `UPDATE`, `DELETE`, `LOGIN`, `LOGOUT`) | Потом станет проще искать и строить отчеты. |
| Аудит | Только администратор | Логировать изменения системных настроек отдельно | Такие изменения обычно самые критичные. |
| Password Policy | Есть | Сделать полностью конфигурируемой | Чтобы не менять код при изменении требований безопасности. |
| MFA | Отложено | Сразу предусмотреть интерфейс второго фактора | Тогда потом можно подключить TOTP, WebAuthn или LDAP без переделки логики. |
| Права Backend | Проверяются Backend | Запретить проверки во Frontend кроме UI | Backend должен быть единственным местом принятия решений. |
| API | Не описано | Добавить OpenAPI/Swagger | Это автоматически станет документацией и облегчит разработку. |
| База данных | Таблицы описаны | Добавить ER-диаграмму | Архитектура станет значительно понятнее. |
| Оргструктура | Только дерево | Отделить организацию от должности | Один человек может менять должность без смены подразделения. |
| Пользователь | Один отдел | Предусмотреть возможность нескольких подразделений | Часто сотрудники работают в нескольких проектах или филиалах. |
| Права | Нет версионирования | Добавить ревизию ACL | Можно понять, какие права были у пользователя неделю назад. |
| Сессии | Redis | Добавить Device ID | Позволит завершать отдельные устройства. |
| Сессии | Только Logout | Добавить "Выйти со всех устройств" | Практически стандарт современных IAM. |
| Блокировка | locked_until | Добавить причину блокировки | Администратору легче понимать ситуацию. |
| Создание пользователя | Вручную | Подготовить слой Provisioning | Потом можно будет подключить LDAP или AD без переписывания ядра. |
| Импорт | CSV | Сделать Import Framework | Потом можно добавить LDAP, Excel, REST API. |
| Профиль | История сообщений | Добавить вкладку "Эффективные права" | Самая полезная страница для поиска проблем доступа. |
| Права | Вычисляются динамически | Добавить Explain API | Возвращает "почему пользователь получил именно это право". Это сильно помогает при отладке. |
| Архитектура | IAM внутри backend | Выделить сервис Authorization | Даже если пока это модуль, интерфейс должен быть отдельным. |
| Бизнес-логика | Размазана | Сделать отдельный Authorization Engine | Все проверки проходят через одну точку. |
| Будущий SSO | Через внешний IdP | Добавить абстракцию IdentityProvider | Тогда подключение Keycloak или Entra ID станет адаптером, а не переписыванием системы. |








===========

## Дополнительные разделы, которые рекомендуется добавить

| Раздел | Зачем нужен |
|--------|-------------|
| **Нефункциональные требования** | Зафиксировать требования к производительности, времени отклика, масштабируемости, максимальному количеству пользователей, доступности системы и целевым SLA. Это позволит принимать архитектурные решения исходя из реальных ограничений. |
| **Диаграмма компонентов** | Наглядно показать взаимодействие между Node.js (BFF), Backend, PostgreSQL, Redis, фронтендом и внешними сервисами. Упростит понимание архитектуры новым разработчикам. |
| **Диаграмма последовательности Login** | Отобразить полный процесс аутентификации: ввод логина и пароля, проверка пользователя, создание сессии, запись аудита, выдача ответа клиенту. Значительно упрощает реализацию и поиск ошибок. |
| **Диаграмма вычисления прав** | Визуализировать алгоритм расчёта эффективных прав (User → Group → Org Unit → Default), правила наследования и разрешения конфликтов (`allow`/`deny`). Это одна из самых сложных частей системы, поэтому её лучше оформить отдельной схемой. |
| **ER-диаграмма базы данных** | Показать связи между таблицами пользователей, групп, подразделений, прав, аудита и сессий. Позволяет заранее выявить архитектурные проблемы и уменьшает вероятность переработки схемы БД после начала разработки. |
| **State Machine пользователя** | Описать жизненный цикл учётной записи (`Active → Locked → Disabled → Deleted`) и допустимые переходы между состояниями. Это исключит неоднозначность поведения системы. |
| **Threat Model** | Зафиксировать перечень угроз, которые должна предотвращать система (брутфорс, эскалация привилегий, обход авторизации, компрометация сессий, инсайдерские действия и т.д.), а также меры противодействия каждой угрозе. |
| **Требования к логированию** | Определить, какие события должны фиксироваться в журнале аудита (входы, изменения прав, создание пользователей, блокировки, ошибки авторизации и др.), сроки хранения и требования к неизменяемости логов. |
| **План миграции** | Описать стратегию перехода со старой схемы пользователей на новую: порядок миграций, синхронизацию данных, откат изменений и обеспечение совместимости на переходном этапе. |
| **План тестирования** | Определить стратегию проверки системы: Unit-тесты, Integration-тесты, End-to-End, Security-тесты, нагрузочное тестирование, а также критерии успешного прохождения каждого этапа. |