cyberdas-dev / api Goto Github PK

Сейчас спецификация сервиса с очередями (/queue и т.д) имеет недочеты и не выглядит достаточно REST-овой

Нужно:

• Переименовать ресурс /queque в ресурс /queques
• Убрать POST запрос на /queques/{quequeName}, резервирующий слот в очереди
• Убрать GET запрос на /queques/{quequeName}
• Добавить ресурс /queques/{quequeName}/slots, возвращающий все слоты в очереди
• Добавить ресурс /queques/{quequeName}/slots/{slot_id}, представляющий собой индивидуальный слот
• Добавить POST запрос на /queques/{quequeName}/slots/{slot_id}, резервирующий этот слот
• Добавить привилегированные методы (PUT, PATCH, DELETE) для вышеуказанных ресурсов

Нужно подумать о том, как ограничить число занимаемых слотов одним человеком в stateless стиле.
Один из вариантов - ввести токены, дающие возможность зарезервировать слот. Такие токены будут выдаваться аутентификационным сервисом.

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

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

• Убрать эндпоинт /verify
• Убрать эндпоинт /resend

Также это позволит избежать возможных DoS-атак на эндпоинт регистрации.

Если смягчить требования к сессиям и убрать их обязательное продление каждые N минут, то можно будет избавиться от довольно сложной системы с remember-me и убрать еще несколько эндпоинтов:

• Убрать эндпоинт /refresh
• Убрать эндпоинт /restore

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

• Убрать пароль из регистрации и логина

Нужно реализовать эндпоинты для механизма очередей:

• GET /queues, возвращающий список доступных очередей и их описание
• GET /queues/{queueName}, возвращающий информацию о выбранной очереди
• GET /queues/{queueName}/slots, возвращающий слоты в выбранной очереди в указанный (с помощью query) промежуток дат
• GET /queue/{queueName}/slots/{slotId}, возвращающий информацию о выбранном слоте
• POST /queue/{queueName}/slots/{slotId}/reservation, резервирующий за пользователем выбранный слот в выбранной очереди; при этом важно не забыть ограничить число резервируемых слотов
• DELETE /queue/{queueName}/slots/{slotId}/reservation, отменяющий бронь слота

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

Сейчас для регистрации в обязательном порядке нужно указывать свой факультет и ФИО.

В дальнейшем планируется расширять API, и не в каждом сервисе нужны будут эти данные. Необходимый минимум - эмэйл. При этом, каждый сервис может выкладывать свои требования к данным, и пользователя будет встречать предупреждение: 'для пользования таким-то сервисом укажите такие-то данные'.

Это сделает более приятным процесс регистрации: указал почту и готово. Надо продумать возможные последствия и то, насколько хорошо будет встречать пользователя предупреждениями о том что ему надо указать данные.

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

Иначе - возвращать HTTP 442 (#47).

Он должен быть инициализируемым, то есть быть классом с методом __call__.

Сейчас логи удаляются при каждом релизе, потому что хранятся просто в файлах в руте проекта.
Нужно или просто перенести их в системные папки (/var/log/...), или использовать отдельный сервис для стрима туда логов и доступа к ним через веб.

• эндпоинт /account/password/lost, принимающий адрес электронной почты, и высылающий на неё письмо с токеном для восстановления, если этот адрес был подтвержден, иначе - отправляющий ошибку с адресом почты поддержки
• эндпоинт /account/password/reset, принимающий токен для восстановления или старый пароль, а также новый пароль

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

Тем не менее, нужно куда-то записывать персональные данные пользователей (ФИО) для передачи администрации списков. Эта система должна быть комбинацией эндпоинтов регистрации и резерва слота с небольшими модификациями.

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

Нужно сделать эндпоинты очередей и слотов доступными без авторизации.

Имеет смысл предусмотреть возможность расширения такого функционала и на другие планируемые эндпоинты (запись на оказание технических услуг и т.д)

Реализовать то, что было создано в спецификации в рамках #38

• Модель данных
• Тесты
• Эндпоинты

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

Разные сервисы требуют разных данных о пользователе. Требовать при регистрации их все - плохо (#44).

Поэтому могут возникнуть ошибки при попытке воспользоваться сервисом, для которого у тебя недостаточно данных. Эта ситуация попадает под HTTP 403 Foribdden, но этот код возвращается почти всеми эндпоинтами и фронтенду будет сложно понять, когда пользователю не хватает данных, а когда - прав.

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

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

Задачи:

• эндпоинт /verify, принимающий генерируемый в signup токен для подтверждения адреса почты.
• эндпоинт /resend, позволяющий попросить отправить письмо с токеном снова, так как он действует один час

Реализовать то, что было создано в спецификации в рамках #51

• Добавить пользователю два новых поля - корпус и комнату
• Модель данных (должна включать в себя корпус и комнату, несмотря на то что они есть у пользователя; потому что у пользователя они могут поменяться, а заявка была оставлена на старую комнату)
• Тесты
• Эндпоинты

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

После закрытия #19, нужно привести код к соответствию спецификации.

Зачищаем остатки старой системы:

• Удалить все старые эндпоинты и тесты на них
• Удалить модель данных long_session
• Обновить модели данных user и session
• Удалить сервис pass_checker
• Обновить JSON schem'ы
• Переработать сервис session (убрав из него весь функционал 'remember me' сессий) или вообще убрать его

Пишем новую:

• Создать новый шаблон письма - на логин
• Написать модуль для отправки транзакционных писем
• Написать тесты на новые /login, /login/validate, /signup, /signup/validate, /logout
• Написать новые эндпоинты /login, /login/validate, /signup, /signup/validate, /logout

Сейчас при бронировании места в очереди присылается письмо с уведомлением и токеном на отмену.

Нужно посылать письма с уведомлениям об отмене, но в них не должно быть токенов или чего-то подобного. Поэтому, нужно 'отпочковать' подкласс просто шаблонных писем от TransactionMail и переделать фабрику мэйл-сендеров на производство как TransactionMail, так и просто TemplateMail.

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

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

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

Важно не забыть о:

• Secure
• HttpOnly
• CSRF-токене
• SameSite

Полезный линк о безопасности куки

Сам логин должен быть простым до ужаса - пользователь посылает эмэйл и пароль и получает в ответ куки. В дальнейшем посылает её с каждым запросом и этим авторизуется.

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

Нужно сделать:

1. логгинг входящих запросов (аналог access-логов в веб-серверах)
2. внутренний логгинг через middleware-компонент, в который будут отправляться ошибки и просто статус-репорты о выполнении операций

Структура технических услуг во многом похожа на структуру обратной связи (#38), если представлять maintenance как одного из recipient:

• GET /maintenance возвращает заявки, должен поддерживать query-параметры для фильтрации по дате, требует авторизации (не аутентификации)
• POST /maintenance создает новую заявку, требует аутентификации (пользователь должен иметь корпус и комнату, проверяется с помощью хука из #49)
• GET /maintenance/{id} возвращает конкретную заявку, требует авторизации

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

Сейчас у нас деплоится в продакшн всё, что находится в main'е, а для активной разработки используется отдельная ветка - next, которая тоже деплоится, но на другой URL.

Нужно переделать систему деплоя на использование гитхабовских релизов в качестве триггера для деплоя на продакшн. При удалении релиза продакшн будет откатываться до последнего доступного. При этом main будет непрерывно деплоится на текущий URL next'а, а от next'а мы откажемся.

Это позволит не заботиться о синхронизации next'а и main'а.

Также, отдельным пунктом: нужно для каждого исполнения воркфлоу тестов создавать свою папку, потому что в случае исполнения сразу двух тестов они удаляют у друг друга файлы.

Нужно реализовать ресурс, представляющий из себя аккаунт пользователя.

• GET, который возвращает информацию о пользователе: эмэйл, имя, фамилия и т.д.
• PUT, который позволяет изменить эту информацию (кроме адреса почты)

Это нужно для отображения и изменения различной информации в личном кабинете

Нужно реализовать эндпоинты для управления очередями:

• PUT /queues/{queueName}, создающий очередь или перезаписывающий о ней информацию
• DELETE /queues/{queueName}, удаляющий очередь
• PUT /queues/{queueName}/slots, создающий или перезаписывающий массив слотов в очереди
• PATCH /queues/{queueName}/slots, добавляющий слоты в очередь (в дальнейшем нужно будет переработать этот эндпоинт, что бы он был действительно PATCH'ом)
• DELETE /queue/{queueName}/slots/{slotId}, удаляющий выбранный слот
• DELETE /queue/{queueName}/slots/{slotId}/reservation, отменяющий бронь слота другим пользователем

• Забыл в workflows добавить заполнение FRONTEND_URL
• Нужно передавать в параметре backend в ссылке в письме не абсолютный URL, а относительный (т.е не 'api.cyberdas.net/v1/queues/...', а '/queues/...'). Если фронтенд смог направить клиента на эндпоинт отправки писем, он и так знает где находится бэкенд
• Нужно добавить в спецификацию упоминания о параметре next, позволяющем указать эндпоинтам, посылающим письма, куда нужно направить клиента
• Добавить в модель пользователя курс

• GET /feedback возвращает список получателей обратной связи (администрация сайта, студком, и т.д) и их схему данных (какие поля обязательные, какие есть категории и т.д)
• POST /feedback/{recipient} создает новый объект обратной связи для получателя
• GET /feedback/{recipient} возвращает объекты обратной связи получателя, должен поддерживать некоторые query-параметры для фильтрации, требует авторизации (не аутентификации)
• GET /feedback/{recipient}/{id} возвращает конкретный объект обратной связи, требует авторизации

Для реализации любых управляющих методов API должен различать обычных пользователей и администраторов. Так как, вероятно, возникнут и другие роли (например, редактор, если мы решим добавить раздел новостей), то лучше реализовать систему ролей.

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

Сейчас quick_auth можно присоединить в качестве хука на эндпоинт. Это требует отправки персональных данных в 'request body' на эндпоинт, который не должен с ними работать. Например, планируемый эндпоинт обратной связи.

Систему можно улучшить, превратив её в микросервис с JWT-токенами.
Нужен эндпоинт /account/ott, при этом POST возвращает одноразовый токен (One Time Token), позволяющий совершить одно действие. В токен записываются данные, отправленные на этот эндпоинт.

Остальные эндпоинты должны явно прописывать то, что они принимают такие токены (хуком или переменной класса, если сделать middleware).

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

Хорошей выглядит такая структура эндпоинтов:
PUT /account/email - отправляет письмо на новую почту для смены адреса
GET /account/email/validate - адрес для редиректа из письма, подтверждающий смену почты

• Автоматическая валидиция сессии при доступе к ресурсам
• Автоматическая валидация CSRF-токенов при POST запросах
• Эндпоинт /refresh, позволяющий клиенту продлить сессию

Первые две задачи удобно выполнить с помощью middleware-компонентов.
Третью задачу можно было бы заменить другой: автоматическое продление сессий при каждом запросе. Но этот подход имеет множество минусов, главный из которых - нагрузка на БД и невозможность продлить сессию 'в фоне'.

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

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

Сейчас обратная связь реализована просто на прием обращений, а получение их списка через веб еще не реализовано.

Хорошим решением до внедрения ролей пользователей (и возможности сделать получения списка обращений через веб) было бы пересылать фидбэк на почту. В модели данных получателя она уже присутствует (поле 'email').

Нужно дать возможность пользователю управлять своими активными сессиями. Это нужно для повышения безопасности.

• Список активных сессий (с информацией о IP, user-agent, времени последней активности)
• Возможность закончить любую сессию

Мне кажется хорошей вот такая структура эндпоинтов:
GET /account/sessions - коллекция сессий
GET /account/sessions/{sid} - конкретный предмет сессий
DELETE /account/sessions/{sid} - закончить конкретную сессию

• Поменять обязательные поля в signup_schema
• Изменить модель данных пользователя, сделав часть полей nullable

А так же:

• Изменить поведение quick_auth, добавив обновление данных пользователя, если он уже зарегистрирован и послал новые (необходимо для добавления данных в только что появившиеся поля)