# Отчёт №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: большая таблица доступов (раздел × подраздел × роль), рекомендуемые шаблоны прав и пошаговый план переписывания логики прав с чек-листом файлов.
