ERP Platform Docs

Overview

время чтения ~4 мин.

User Service

Ответственность

Управление франшизами (tenant), юридическими лицами, сотрудниками и клиентами. Tenant-сущность franchises с флагом type (corporate / individual). Права владельцев партнёров — через скрытые роли (roles.owner_legal_entity_id). Scope-вычисление по владению ЮЛ + employee_role_stores через отдельный internal endpoint (BR 1.4.4).

Ключевые функции

Юридические лица (BR 1.1)

  • CRUD юридических лиц (два типа: franchise и franchisee)
  • Назначение главного ЮЛ (для автоподстановки в документы)
  • Приостановка / возобновление ЮЛ Франчайзи (синхронный вызов Store Service)
  • Soft delete с проверкой привязанных ТТ
  • Импорт из xlsx (двухэтапный: preview → apply)
  • Ролевой доступ — по scope (см. Ролевая модель): владелец франшизы — все ЮЛ; владелец партнёра — только свои + ограниченное редактирование
  • BR 1.4.2 + BR 1.4.4: создание ЮЛ Франчайзи атомарно создаёт владельца в одной транзакции. Поле role enum удалено в BR 1.4.4 — владельцу назначается либо системная роль «Администратор» (режим «Полный доступ»), либо скрытая персональная роль с настраиваемыми permissions (режим «Настроенные права»)
  • BR 1.4.4 §3: tenant franchises.type (corporate / individual) — для individual создание партнёра запрещено (403 FRANCHISE_TYPE_INDIVIDUAL)

Сотрудники (BR 1.4, обновлено BR 1.4.2, BR 1.4.3, BR 1.4.4)

  • CRUD сотрудников. Поле role (enum) удалено (BR 1.4.4) — сотруднику назначаются только permissions-роли, каждая со своим набором ТТ
  • Привязка сотрудников к торговым точкам — через employee_role_stores (per-role); employee_stores остаётся как legacy для PIN lookup
  • PIN-менеджмент (4-digit PIN, уникальный в рамках ТТ, для POS-авторизации)
  • Деактивация / реактивация сотрудников
  • Permissions-роли (BR 1.4.3): сотруднику назначается N permissions-ролей, каждая со своим набором ТТ
  • Scope-вычисление (BR 1.4.4): scope считается отдельным internal endpoint GET /internal/users/{id}/scope по правилам владения ЮЛ + employee_role_stores. Используется Auth Service для кэширования и downstream-сервисами для фильтрации данных
  • Internal API для Auth Service: валидация credentials (с scope), поиск по email (с scope), валидация PIN (с проверкой pos.access), получение permissions / scope по user_id

Роли и permissions (BR 1.4.3, обновлено BR 1.4.4)

  • CRUD permissions-ролей (таблицы roles, role_permissions, employee_roles, employee_role_stores)
  • Каталог permission-ключей — константа в коде (back-office: 17 разделов, 32 ключа; POS: 14 ключей on/off)
  • Системная роль «Администратор» с полными правами, автосоздаётся при seed франшизы
  • Soft delete с защитой от удаления назначенных ролей (ROLE_IN_USE)
  • Скрытые роли владельцев партнёров (BR 1.4.4 §5.2): roles.owner_legal_entity_id — UUID NULL FK на legal_entities. Если задано, роль не отображается в /admin/roles, редактируется только через карточку ЮЛ партнёра (GET/PUT /api/v1/legal-entities/{id}/owner-permissions). При создании ЮЛ партнёра с режимом «Настроенные права» — создаётся скрытая роль с минимумом permissions (pos.access, stores.read, employees.read форсятся всегда)
  • Internal API GET /internal/users/{id}/permissions — агрегированный список permissions для кэша Auth Service

Расписание и учёт рабочего времени (BR 1.4.1)

  • Шаблоны смен (CRUD, макс. 4 на ТТ)
  • Расписание (плановые смены, CRUD, только будущие дни)
  • Фактические смены (clock in/out, перерывы, ручной и POS-ввод)
  • Автоматический расчёт статуса смены (on_schedule / off_schedule / missed / unplanned)
  • Автозакрытие через 24ч (scheduled job)
  • Корректировка прошедших смен (увеличение/уменьшение часов)
  • Дашборд активности (агрегация по ТТ за дату)

Зарплата (BR 1.4.1)

  • Формулы начисления (по роли + индивидуальные, 3 типа: hourly/fixed/mixed)
  • Платёжные ведомости (расчёт, подтверждение, отметка о выплате)
  • CSV-экспорт ведомостей
  • Юридические детали сотрудника (ИНН, паспорт, ВУ, СНИЛС)

Отчёт по смене (BR 2.2)

  • Public endpoint GET /shift-records/{id}/report — полный X/Z отчёт по конкретной смене
  • Собирает данные смены из shift_records + вызывает Order Service internal endpoint за финансовой агрегацией
  • X-отчёт (смена открыта, clock_out IS NULL) vs Z-отчёт (смена закрыта)
  • Ролевой доступ: Franchise — все, Franchisee — свои ТТ, Manager — своя ТТ, Cashier — 403

Дашборд активности (BR 1.4.1)

  • Public endpoint GET /dashboard/activity?store_id=&date= — активность сотрудников по ТТ за дату
  • Агрегирует shift_records + payroll_records в единый view для EmployeeActivityPage и TerminalsDashboardPage в админке
  • Реализован в DashboardController (User Service), кэшируется в admin-bff

Клиенты вынесены в отдельный Customer Service

(Перенесено в BR 3.1). Планировавшаяся функциональность CRM (клиенты, адреса, группы) перенесена в отдельный микросервис Customer Service (:3013). User Service больше не отвечает за клиентов — он управляет сотрудниками, ЮЛ, ролями, сменами, зарплатой. Permission-каталог расширяется ключами customers.*, customer_groups.* через константу кода — см. ниже.

Авторизация

ADR-001

JWT валидируется локально (HS256 + shared JWT_SECRET). Auth Service будет подключён после BR по сотрудникам.

Зависимости

  • PostgreSQL (user_db) — основное хранилище
  • Store Service — internal API:
    • POST /internal/stores/count-by-legal-entities — количество ТТ по ЮЛ (для списка)
    • GET /internal/stores?legal_entity_id={id} — список ТТ по ЮЛ (для проверки удаления, модалки приостановки)
    • POST /internal/stores/unpublish-by-legal-entity — снятие ТТ с публикации при приостановке
    • GET /internal/stores/{id} — валидация существования ТТ при создании/обновлении сотрудника

Конфигурация

VariableDescriptionDefault
DATABASE_URLPostgreSQL connection string—
SERVICE_TOKENТокен для internal API—
STORE_SERVICE_URLURL Store Servicehttp://store-service:3003
ORDER_SERVICE_URLURL Order Servicehttp://order-service:3005
  • Order Service — internal API:
    • GET /internal/orders/shift-report — агрегация заказов за период смены (BR 2.2)

Ссылки

Вид графа

Обратные ссылки