ESWF · Система прав

Платформне рішення доступу до даних, побудоване на трьох ідеях:

1. Каталог ролей у коді — core/services/role_catalog.py. 14 системних ролей з фіксованими наборами прав. Source of truth.
2. Матеріалізація в БД per-tenant — apply_system_roles(tenant) копіює каталог у Role + RolePermission. Тенант адмін може правити свою копію через UI; «Скинути до каталогу» повертає до коду.
3. HasRolePermission — DRF permission-class — резолвить entity_code із view (URL kwargs / атрибут / queryset.model через EntityRegistry), мапить DRF action → action каталогу, перевіряє (entity, action) у наборі юзера.

Принципи: - Closed-by-default: якщо нова сутність не додана у каталог, її побачить лише tenant_admin (бо він має *:all wildcard). - Multi-tenant: ролі — per-tenant; усі apply_system_roles створюють однаковий набір ролей у кожному тенанті, але призначення (UserRole) — окремі. - Backward-compat: is_superuser та is_tenant_admin короткозамикають перевірку → завжди allow. Безпечно для існуючих admin-flow.

Документи розділу

Файл	Про що
role-catalog.md	Каталог 14 системних ролей з описами, scope, demo-юзерами
architecture.md	Моделі (Role/RolePermission/UserRole), HasRolePermission, entity resolution, action mapping
frontend-integration.md	useActivePermissions, useFilteredSections, requiresEntities, sidebar gating
editing-via-ui.md	Admin Tools → Roles Matrix: редагування клітинок, Save / Discard / Reset to catalog
adding-new-entities.md	Чек-ліст для нових сутностей / модулів — як одразу прив'язати до ролей
demo-users.md	Усі демо-логіни trzh tenants з ролями

Дотичні документи (інші частини проєкту): - eswf/infrastructure/seed-methodology.md — як демо-юзери та призначення ролей створюються під час seed_demo - .claude/skills/custom-form/SKILL.md — checkpoint D: каталог ролей при створенні нового довідника / документа - .claude/skills/new-module/SKILL.md — checkpoint 12: ролі при створенні нового модуля

Quick start

Як подивитись поточну матрицю: ERP → Адмін-інструменти → Матриця ролей. Колонки = ролі, рядки = entity_code.

Як змінити права ролі: Та ж сторінка → клікни чекбокси → Зберегти. Зміни одразу видно у /auth/me/ залогінених юзерів (їм треба перелогінитись для оновлення).

Як відкотити правки до коду: Та ж сторінка → Скинути до каталогу → confirm. БД переписується значеннями з role_catalog.py.

Як додати нову сутність до ролей: Якщо ти розробник — редагуй core/services/role_catalog.py, потім «Скинути до каталогу» в UI або seed_demo --only=extras_<tenant>. Якщо тенант-адмін — після появи нової сутності у тенанті відкривай Roles Matrix → постав чекбокси для відповідних ролей → Save.

Що поки не зроблено

• Custom (non-system) ролі через UI — поки лише edit існуючих системних
• Полевий-рівень прав (приховати поле salary від не-HR)
• Скоупи own / department / organization — зараз усе tenant-wide
• Захист mobile-API endpoints (/api/v1/mobile/, /api/v1/sales-mobile/) — окремий sprint
• Захист custom @action endpoints, не покритих HTTP-method fallback'ом

Деталі — gaps section.