arm-core/openspec/specs/users-admin/spec.md

users-admin Specification

Purpose

Администрирование доступа: пользователи, назначение ролей и матрица «роль × право» как данные (role_permission), с аудитом; минимальный экран администратора во фронте.

Requirements

Requirement: Пользователи — список, создание, изменение, деактивация

Маршруты /api/v1/admin/users (право USERS_ADMIN): GET — список с ролями и филиалом (поиск по email/ФИО, фильтр is_active, пагинация); POST — создание с обязательными email (уникален без учёта регистра → 409 EMAIL_EXISTS), full_name, regional_office_id, необязательными employee_no, business_segment, roles (коды); PATCH …/{id} — full_name, employee_no, regional_office_id, business_segment, is_active. Удаление MUST NOT предоставляться. external_id через API не задаётся. Каждая мутация пишет audit_event(USER_CHANGE, section = USERS).

Scenario: Создание с ролью

• WHEN администратор создаёт пользователя с roles = ["KA_RF"]
• THEN появляются app_user и user_role, GET /me от его имени (dev-токен) возвращает права KA_RF

Scenario: Email в другом регистре

• WHEN создаётся пользователь с email, отличающимся от существующего только регистром
• THEN ответ 409 EMAIL_EXISTS

Requirement: Назначение ролей

PUT /api/v1/admin/users/{id}/roles (тело: список кодов) SHALL заменять набор ролей пользователя: отсутствующие в наборе назначения удаляются, новые добавляются; неизвестный или неактивный код роли → 422; пишется audit_event(USER_ROLE_CHANGE, before_value = прежний набор, after_value = новый). Замена набора ролей MUST NOT оставить систему без активного пользователя с USERS_ADMIN (409 LAST_ADMIN): администратор не может снять с себя последнюю роль, дающую USERS_ADMIN, если он — единственный активный обладатель этого права; при наличии другого активного администратора снятие у себя разрешено (решение №34).

Scenario: Замена набора ролей

• WHEN у пользователя роли [KA_RF], администратор ставит [KA_GO, EXPERT]
• THEN user_role содержит ровно две новые строки, в аудите before_value = ["KA_RF"], after_value = ["KA_GO","EXPERT"]

Scenario: Последний администратор

• WHEN единственный активный пользователь с USERS_ADMIN снимает с себя роль ADMIN
• THEN ответ 409 LAST_ADMIN, роли не изменены

Requirement: Матрица прав

GET /api/v1/admin/roles SHALL отдавать роли с их правами; GET /api/v1/admin/permissions — справочник прав (16 кодов, только чтение; создание прав MUST NOT предоставляться); PUT /api/v1/admin/roles/{code}/permissions (тело: список кодов прав) SHALL заменять набор прав роли и писать audit_event(ROLE_PERMISSION_CHANGE) с before/after. Системные роли (is_system) нельзя деактивировать или переименовать; нельзя снять USERS_ADMIN с роли, если после этого ни у одного активного пользователя не останется этого права (409 LAST_ADMIN).

Scenario: Изменение матрицы

• WHEN у роли EXPERT добавляется право EXPORT
• THEN role_permission содержит новую строку, пользователь с ролью EXPERT при следующем запросе /me видит EXPORT, в аудите ROLE_PERMISSION_CHANGE

Scenario: Снятие USERS_ADMIN с единственной роли

• WHEN у роли ADMIN (единственной с USERS_ADMIN у активных пользователей) убирают USERS_ADMIN
• THEN ответ 409 LAST_ADMIN

Requirement: Минимальный экран администратора

SPA SHALL содержать маршрут /admin (пункт «Система → Пользователи и роли» в боковом меню), доступный при наличии USERS_ADMIN в ответе /api/v1/me: таблица пользователей с выбором ролей и формой создания, таблица «роль × право» с чекбоксами и кнопкой сохранения; запросы идут через общий API-клиент с заголовком Authorization: Bearer. В режиме разработки SHALL быть доступен ввод email для получения dev-токена (POST /api/v1/dev/token); в сборке для прода этот ввод отсутствует.

Scenario: Назначение роли через экран

• WHEN администратор на /admin выбирает пользователю роль KA_GO и сохраняет
• THEN вызывается PUT /admin/users/{id}/roles, таблица показывает новую роль, ошибка API показывается уведомлением

Scenario: Нет права

• WHEN пользователь без USERS_ADMIN открывает /admin
• THEN страница показывает сообщение об отсутствии доступа и не делает запросов к /admin/*

Requirement: Краткий справочник пользователей

GET /api/v1/users/brief?ids=<uuid>,… SHALL быть доступен любому аутентифицированному пользователю без отдельного права и отдавать [{id, full_name, is_active}] для найденных id, включая неактивных; неизвестные id MUST NOT возвращаться и MUST NOT давать ошибку; больше 200 id — 422 TOO_MANY_IDS; некорректный UUID — 422. Админский список пользователей не меняется.

Scenario: Имя загрузившего

• WHEN аналитик без права USERS_ADMIN запрашивает ids из uploaded_by двух файлов и неизвестный UUID
• THEN 200, два элемента с ФИО, неизвестный UUID отсутствует

Scenario: Слишком много id

• WHEN передан 201 id
• THEN 422 TOO_MANY_IDS