# Отчёт №1 — Роли и ограничения (для согласования с заказчиком) Документ описывает роли портала МКД, их ограничения по разделам и данным, связь с базой данных и соотношение с ролями workflow согласования счетов. После согласования используется как основа для отчёта №2 и переработки логики прав. --- ## 1. Список ролей портала (после переработки) Рекомендуется сохранить текущие коды ролей в БД. Ниже — код, название для UI и краткое описание назначения. | Код (БД) | Название для UI | Описание назначения | |------------|-----------------|----------------------| | DIRECTOR | Директор | Полный доступ ко всем разделам портала. Руководство, контроль показателей, настройки. | | ENGINEER | Гл. Инженер | Производство, участки, заявки, офис, развитие. Оперативное управление технической и производственной частью. | | MASTER | Мастер | Участки и заявки. Работа в рамках назначенных участков (дома, заявки, штат участка). | | LAWYER | Юрист | Сводка, юр. отдел, участки, заявки. Работа с договорами, судами, досудебной работой, долгами. | | FINANCIER | Финансист | Сводка, финансы, офис, участки. Реестр счетов, календарь оплат, отчёты, закупки. | | HR_MANAGER | HR-менеджер | Сводка, кадры, офис. Сотрудники, календарь, вакансии, подбор, охрана труда. | | PR_MANAGER | PR-менеджер | Сводка, PR и NPS, заявки. SMM, мероприятия, обратная связь, отчёты, NPS, негатив. | --- ## 2. Ограничения по каждой роли ### 2.1 Разделы по умолчанию При пустом поле `permissions` у пользователя применяются разделы по роли (из таблицы ниже). «all» означает доступ ко всем разделам портала. | Роль | Разделы по умолчанию | |------------|------------------------| | DIRECTOR | all (все разделы) | | ENGINEER | dashboard, objects, requests, office, development | | MASTER | objects, requests | | LAWYER | dashboard, legal, objects, requests | | FINANCIER | dashboard, finance, office, objects | | HR_MANAGER | dashboard, hr, office | | PR_MANAGER | dashboard, pr, requests | Соответствие кодов разделов и названий: dashboard — Сводка; objects — Участки; requests — Заявки; pr — PR и NPS; finance — Финансы; legal — Юр. отдел; development — Развитие; hr — Кадры; office — Офис; admin — Панель управления. ### 2.2 Уровень доступа по умолчанию По умолчанию для роли по всем доступным разделам и подразделам задаётся уровень **«редактирование»** (edit): пользователь может просматривать и изменять данные в рамках своих разделов. Различие «только чтение» / «только своё» задаётся только через кастомные `permissions` у пользователя или через шаблоны прав. ### 2.3 Ограничение по данным (участки) | Роль | Scope по умолчанию | Пояснение | |------------|--------------------|------------| | DIRECTOR | all | Все участки | | ENGINEER | all | Все участки | | MASTER | own_district | Только свои назначенные участки (из employee_districts / assigned_district_id) | | LAWYER | all | Все участки | | FINANCIER | all | Все участки | | HR_MANAGER | all | Все участки | | PR_MANAGER | all | Все участки | При `scope = own_district` список разрешённых участков для фильтрации данных (дома, заявки и т.д.) формируется из таблицы **employee_districts** (многие ко многим); при отсутствии записей — из поля **employees.assigned_district_id**. ### 2.4 Особые ограничения - **Счета на оплату:** в API поддерживается параметр `scope=own` — показ только счетов, созданных текущим пользователем (`created_by = employee_id`). Это отдельно от роли портала и может использоваться для любой роли при необходимости. - **Workflow согласования счетов** задаётся таблицей **user_roles** (manager, finance_manager, director и т.д.) и не дублирует роли портала (см. раздел 4). При необходимости в будущем можно ввести особые ограничения вида «только свои заявки» через уровень доступа «только своё» (own) по подразделу и проверки на бэкенде. --- ## 3. Связь с базой данных ### 3.1 portal_users - **role** (VARCHAR) — код роли портала (DIRECTOR, ENGINEER, MASTER, LAWYER, FINANCIER, HR_MANAGER, PR_MANAGER). - **permissions** (JSONB) — массив строк прав. Если массив не пустой — используются только эти права (разделы/подразделы и уровни); иначе применяются права по роли из единого справочника (ROLE_ACCESS и уровень edit по умолчанию). - **scope** (VARCHAR: 'all' | 'own_district') — ограничение по участкам: все участки или только назначенные сотруднику. При пустом `permissions` бэкенд и фронт вычисляют доступ по полю `role` и единому справочнику разделов/уровней по умолчанию. ### 3.2 employees и участки - **employees.assigned_district_id** (VARCHAR, один участок) — для обратной совместимости; используется как fallback, если у сотрудника нет записей в employee_districts. - **employee_districts** (таблица связей employee_id, district_id) — многие ко многим: один сотрудник может быть назначен на несколько участков. При **scope = own_district** список доступных district_id для фильтрации данных должен формироваться так: сначала выборка из **employee_districts** по employee_id пользователя; если записей нет — использовать **assigned_district_id** (один участок). Все API, которые фильтруют данные по участку (дома, при необходимости заявки, отчёты и т.д.), должны использовать этот единый список. ### 3.3 permission_templates - Шаблоны хранят: name, description, **permissions** (JSONB), **scope**, for_position, suggested_role. Применение шаблона к пользователю подставляет permissions и scope (и при необходимости suggested_role) в portal_users. Структура БД менять не требуется; при переработке важно сохранять тот же формат permissions и scope. ### 3.4 Новые поля или таблицы - Текущей модели достаточно. Матрица «роль → разделы/уровень/scope» по умолчанию может храниться в едином модуле констант в коде (общий для фронта и бэкенда). При желании в будущем можно вынести матрицу в таблицу (например, role_default_access) для настройки без деплоя. --- ## 4. user_roles (workflow) и роли портала - **user_roles** — таблица для цепочки согласования счетов на оплату. Роли: manager, finance_manager, financier, finance_director, director, top_management. Используются только в модуле согласования счетов (paymentInvoiceWorkflow и связанные API). - **Роли портала** (portal_users.role) определяют доступ к разделам и данным портала (меню, вкладки, фильтр по участкам). Они не задают права согласования счетов. - Связывать user_roles с portal_users.role не обязательно: один и тот же человек может быть DIRECTOR в портале и не иметь роли в user_roles, или иметь роль manager/finance_manager в user_roles при другой роли в портале. - В админке целесообразно показывать «роль в портале» и «роли в workflow» отдельно (например, в карточке пользователя — раздел «Согласование счетов» с назначением ролей из user_roles). --- После согласования данного отчёта переходим к отчёту №2: большая таблица доступов (раздел × подраздел × роль), рекомендуемые шаблоны прав и пошаговый план переписывания логики прав с чек-листом файлов.