cardy/development specification.md

# pnpm монорепо приложение для хранения скидочных карт (штрих/qr-код + тип кода, EAN-13, EAN-8, Code128, QR, PDF417, Aztec и т.д. + название + цвет + опционально лого + опционально скриншоты). 

# серверное приложение (fastify+react+vite+ts):
* хранение пользователей в файле users.yaml (по email) и их групп (по названиям). для пользователя может быть храниться признак того, что это - администратор или суперадминистратор. 
* пользователь является администратором только для своей группы. суперадминистратор - администратор всех групп.
* аутентификация пользователя для доступа к UI (не API) через заголовок Remote-Email
* для каждого пользователя может храниться несколько строковых ключей доступа. ключи хранятся в зашифрованном обратимым шифрованием AES-256-GCM виде, ключ расшифровки (32-байта в base64) в переменной окружении.
* административный (для суперадмина) CRUD UI для управления группами пользователей и выбора одной группы, как текущей. группу, к которой принадлежит хотя бы один суперадмин, невозможно удалить.
* административный UI CRUD пользователей текущей группы и приязанных к ним ключей доступа. ключи генерируются случайно (32 символа)
* хранилище списка карт в yaml файле в папке соответственной группы пользователей, картинки рядом с ним на диске в виде файлов. количество картинок на карту не ограничено. карты общие для всех пользователей одной группы. для каждой карты указывается числовой номер версии картинок.
* административный UI для CRUD всех хранящихся, включая удаленные, карт текущей группы пользователей, загрузки картинок к ним. изменение/добавление/удаление любой картинки увеличивает номер версии в карте. загруженные картинки хранятся как есть.
* UI для показа списка ключей текущего пользователя. Для одного выбранного ключа генерирутся QR код, содержащий адрес сервера и сам ключ. 
* API для клиентского приложения:
  * аутентификация пользователя по ключу (Authorization: Bearer)
  * получение списка всех карт (без пагинации). удаленные карты получить невозможно
  * получение картинок по выбранной карте
  * редактирование, удаление и добавление карт с их лого. удалённые карты помечаются, как удаленные и не удаляются
  * удаление и добавление картинок карт
* весь UI на английском

# клиентское мобильное приложение (react/vite/ts pwa + capacitor андроид):
* хранение ключа и пинкода для входа
* экран нового входа
  * поле для ввода адреса серверного API
  * показывает камеру, даёт отсканировать ключ из QR кода
  * позволяет ввести ключ текстом в открытом виде. 
  обязательна аутентификация на сервере для подтверждения правильности ключа. экран можно вызвать даже если ключ уже хранится в приложении, в этом случае старый ключ удаляется. хранится всегда только один последний ключ 
* экран цифрового кода (= "пинкода"). показывается для ввода пинкода (4 цифры) при смене ключа (пинкод сохраняется) и при каждом открытии приложения (пинкод сверяется с хранящимся). защиты от перебора нет.
* экран карт. список всех хранящихся локально карт (цветными названия с логотипами или, если их нет, с аббревиатурами на цветном фоне) с возможностью выбрать одну из них во весь экран. сортировка по давности использования
* экран (одной) карты: просмотр её названия, штрих/qr-кода и её хранящиеся локально картинки, если есть. яркость экрана на андроиде поднимается на максимум. открывание экрана считается использованием карты и сохраняет дату и время
* на экране карт кнопка "фильтр по названию" (по подстроке длиной от 1 символа)
* на экране карт кнопка "обновить". перекачивает заново список всех карт с сервера и обновляет сохраненный список (только если скачалось успешно). для изменившихся карт асинхронно по очереди (макс 5 запросов одновременно) скачиваются их картинки.
* экран редактирования/добавления новой карты: поле для ввода названия, выбора цвета (по умолчанию случайный), загрузки опционального лого, загрузки опциональных фото, ввода кода и выбора типа код карты текстом или распознаванием QR/штрих-кода и его типа с карты или из загруженной картинки. лого и картинки перед отправкой, пережимаются в webp до размера 1000px по наибольшей стороне, EXIF удаляется
* на экране карт кнопка "добавить", вызывает экран редактирования/добавления новой карты
* на экране карты кнопка "удалить" с подтверждением. 
* на экране карты кнопка "редактировать", вызывает экран редактирования/добавления новой карты
* весь UI на английском

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

вопросы деплоя в этом задании не рассматриваются


# Дополнительная информация

Пользователи и группы
* Пользователь состоит ровно в одной группе
* Первый суперадмин создаётся из переменной окружения SUPERADMIN_EMAIL
* При удалении группы все пользователи, ключи и карты удаляются.
* Текущая группа пользователя читается из users.yaml и сохраняется в cookie. UI суперадмина позволяет записать в эту cookie другое значение.
* При ошибка аутентификации отвечать ошибкой 401.
* Новые ключи генерируются только админом или суперадмином

Сессии и ключи
* Шифрование ключей: AES-256-GCM с 32-байтным ключом в base64 в env подойдёт?

Данные
* Где генерируется ID карты? На сервере, при добавлении. Возвращается клиенту.
* Конкурентные правки одной карты с разных устройств: побеждает последняя запись? Да.
* Дата последнего использования карты хранится только локально на устройстве и сохраняется при «обновить» по ID карты? Да.

Клиент и деплой
* Как менять PIN без смены ключа? Или только через повторный вход? Да.
* PWA раздаётся с того же домена что и API.
* Нужны ли Dockerfile и docker-compose с томом под данные и пример конфига прокси с bypass для /api? Нет.