Практические материалы по запуску и развитию

Собственные роли в Synchra.24 для внутренних сервисов строятся через права приложений. Это отдельный набор полномочий, который нужен не для базовых экранов платформы, а для ваших встраиваемых сервисов и микроприложений.

Идея простая:

• вы создаете собственное право доступа;
• добавляете его в роль сотрудника;
• внутри своего сервиса читаете список прав из контекста провайдера;
• на основании этого списка показываете или скрываете действия, разделы и сценарии.

Что именно создается

В мобильном приложении есть отдельный раздел, где можно создать свои права доступа для встроенных сервисов и микроприложений.

У каждого такого права есть два поля:

• Название — человекочитаемое имя, которое видят администраторы при настройке ролей;
• Ключ — техническое имя права, которое будет использоваться в логике приложения.

Пример:

• Название: Управление заявками подрядчиков
• Ключ: contractor_requests_manage

Где это используется

После создания право появляется в настройках ролей в разделе Приложения. Это значит, что администратор может:

• открыть редактирование роли;
• найти блок полномочий встроенных сервисов;
• включить или выключить ваше право для конкретной роли.

Именно поэтому права приложений удобно использовать для сценариев, где вам нужно тонко разделить доступ внутри собственного сервиса:

• просмотр и редактирование разных сущностей;
• доступ к отдельным вкладкам;
• публикация, согласование, удаление;
• запуск внутренних операций только для части сотрудников;
• разделение прав между линейными сотрудниками, руководителями и администраторами.

Как создать право через интерфейс

Ниже самый прямой сценарий, если вы настраиваете доступ без кода администратора платформы.

Шаг 1. Откройте раздел прав приложений

Внутри активности компании откройте экран, где настраиваются права приложений.
Это отдельный список всех пользовательских прав, которые относятся именно к вашим сервисам.

Шаг 2. Нажмите кнопку добавления

В правом верхнем углу нажмите кнопку добавить.

После этого откроется форма создания нового права.

Шаг 3. Заполните название

В поле названия укажите понятное имя, которое потом будет видно при настройке ролей.

Хорошие примеры:

• Редактирование заявок подрядчиков
• Согласование выездов
• Просмотр финансового отчета

Название стоит писать так, чтобы администратор роли сразу понимал, что именно разрешает это право.

Шаг 4. Заполните ключ

Во втором поле укажите короткий технический ключ.

Например:

• contractor_requests_edit
• trip_approve
• finance_report_view

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

Шаг 5. Сохраните право

После сохранения новое право появится в общем списке прав приложений.

На этом этапе оно уже создано, но еще не выдано ни одной роли.

Шаг 6. Перейдите к ролям

Откройте экран ролей и выберите роль, которой нужно выдать доступ.

Внутри редактирования роли найдите раздел Приложения. Там отображаются права, созданные специально для встроенных сервисов.

Шаг 7. Включите нужное право у роли

Найдите ваше право по названию и включите его для нужной роли.

Например:

• для обычного сотрудника можно включить только просмотр;
• для старшего сотрудника — просмотр и редактирование;
• для руководителя — просмотр, редактирование и согласование.

Шаг 8. Проверьте доступ внутри сервиса

После этого пользователь с выбранной ролью сможет открыть сервис, а внутри приложения вы сможете проверить наличие этого права и показать нужные действия.

Ограничения по ключу

Поле ключа проверяется по шаблону:

^[a-z_]+$

То есть в ключе допустимы только:

• латинские буквы в нижнем регистре;
• символ _.

Подходящие примеры:

• requests_view
• requests_edit
• warehouse_admin
• service_publish

Неподходящие примеры:

• RequestsView
• service-edit
• service.1
• роль_админа

Рекомендуем договориться о едином стиле именования. Обычно лучше всего работают ключи в формате:

<сервис>_<сущность>_<действие>

Например:

• contractor_requests_view
• contractor_requests_edit
• contractor_requests_approve

Как выглядит жизненный цикл

1. Создайте право приложения

В разделе Права приложений создайте новый ключ:

• задайте понятное название;
• задайте технический alias;
• сохраните право.

2. Добавьте право в роль

Откройте редактирование роли и включите это право в разделе Приложения.

3. Получите права внутри своего сервиса

Во встраиваемом приложении используйте provider context из @synchra24/app:

const provider = await synchra.getProviderContext();

console.log(provider.role.permissions);

В provider.role.permissions придет массив строк, где будут и ваши кастомные ключи.

4. Примените их в интерфейсе

Пример проверки:

const provider = await synchra.getProviderContext();

const canEditRequests = provider.role.permissions.includes(
  'contractor_requests_edit'
);

if (canEditRequests) {
  // показываем кнопку редактирования
}

Когда имеет смысл создавать свои права

Используйте кастомные права, если в сервисе есть хотя бы один из сценариев:

• часть пользователей должна только просматривать данные;
• часть пользователей должна редактировать данные;
• только руководители могут согласовывать или публиковать;
• у разных ролей должен быть доступ к разным вкладкам;
• в одном сервисе есть административные и обычные действия.

Если у всех сотрудников одинаковый доступ и никакой ролевой логики не требуется, отдельные права можно не создавать.

Рекомендуемая схема прав

Для нового сервиса удобно сразу закладывать несколько уровней доступа:

• service_view
• service_edit
• service_approve
• service_admin

Тогда роль можно собрать гибко:

• сотруднику — только view;
• старшему сотруднику — view + edit;
• руководителю — view + approve;
• администратору — полный набор.

Поиск и сопровождение

Экран CustomPermissions поддерживает:

• поиск по созданным правам;
• сортировку;
• редактирование существующих ключей;
• удаление ненужных прав.

Это удобно, если у вас уже несколько сервисов и прав становится много.

Практический совет

Не создавайте слишком общие ключи вроде:

• admin
• editor
• manager

Лучше делать ключи предметными и привязанными к конкретному сервису. Тогда:

• проще читать конфигурацию ролей;
• проще поддерживать логику в коде;
• ниже риск конфликтов между разными внутренними сервисами.

Хорошо:

• inventory_writeoff_edit
• inventory_writeoff_approve
• vendor_orders_view

Плохо:

• edit
• admin_role
• service_access

Что важно помнить

• Права приложений создаются отдельно от стандартных системных permission платформы.
• Они предназначены именно для ваших встроенных сервисов.
• Пользователь не получает право автоматически только потому, что сервис открыт в активности — право должно быть явно добавлено в роль.
• Логика доступа внутри интерфейса вашего сервиса реализуется на вашей стороне через provider.role.permissions.

Что дальше

После настройки собственных прав обычно следующим шагом делают:

1. структуру ролей и сценариев доступа;
2. проверки прав в интерфейсе;
3. скрытие или блокировку действий без нужного permission;
4. разделение API-операций по ролям, если это требуется на сервере.

Если вы только начинаете, сначала стоит пройти:

• Быстрый старт — чтобы поднять собственный сервис;
• Bridge library — чтобы понять, как получать provider context и работать с интеграционным SDK.