Auth

src/auth/

Захист ендпоінтів. Defense in depth: @UseGuards(AuthGuard, RolesGuard) на контролері + @ApiRoles([роли], options?) на ендпоінті.

Що це

• AuthGuard — читає Authorization: Bearer <jwt>, прокидає req.user. Сам зараз завжди повертає true (опціональний валідатор, не gate).
• RolesGuard — читає 'roles' метадату з handler. Без @ApiRoles пропускає — тобто @UseGuards(RolesGuard) без декоратора нічого не закриває. Це найважливіший нюанс — забутий @ApiRoles робить ендпоінт публічним.
• @ApiRoles(roles, options?) — комбінує Roles(...) + ApiOperation(...). Додає **Доступно для ролей:** ... у Swagger description.

Розподіл доступу за групами

• Legend — director, topManager
• tips-memory — POST захищені роллю operator; GET (health/status) публічні
• Module legend загалом — для системних викликів зі stack
• Module tips-memory загалом — для електронного клієнта оператора

Нюанси

• Не використовуй окремий @ApiOperation поряд із @ApiRoles — він перетре опис.
• Конвенція відповідей: усі ендпоінти повертають HTTP 200 з body {success, data, message?}. Реальний код помилки губиться в HTTP-status. Це проєктна legacy-конвенція AllExceptionsFilter. Не намагайся повертати реальні 4xx/5xx — це поламає клієнтів.

Зв’язки

• Використовується скрізь у services (controllers @UseGuards)
• Глобальні ролі — roles у stack-docs