Пособие разработчику - boomchik93/TerraBazar GitHub Wiki

В проекте выделяются две основные части: фронтенд (маршруты для пользователей и интерфейс магазина, включая регистрацию, просмотр товаров, работу с корзиной и оформлением заказов) и административная панель (маршруты, защищённые проверкой is_admin/admin_required, для управления товарами и промокодами). Общие задачи приложения – предоставить пользователям возможность зарегистрироваться, смотреть товары, добавлять их в корзину, применять промокоды и оформлять заказы; а администраторам – добавлять/удалять товары и промокоды, просматривать статистику и заказы.

В файле app.py определены маршруты (@app.route) для разных операций. Ниже перечислены все роуты, их методы, параметры и возвращаемые результаты.

• GET / – главная страница магазина.

  • Методы: GET.

  • Описание: Отображает список доступных товаров (например, товары из БД).

  • Параметры: нет.

  • Возвращает: рендер шаблона (например, index.html) с контекстом: список продуктов, текущий пользователь и количество товаров в корзине (эти данные поступают через функции-инъекторы inject_user и inject_cart_items_count).

• GET /register и POST /register – регистрация нового пользователя.

  • Методы: GET (открыть форму регистрации), POST (отправить данные).

  • Описание: При GET-запросе возвращает форму регистрации (например, шаблон register.html). При POST-запросе принимает данные из формы: имя, email, пароль, телефон и т.д. Сначала выполняется валидация (напр. проверка формата телефона через format_phone_number и regex_match), затем создаётся новый пользователь в базе (с хешированным паролем).

  • Параметры (POST): поля формы (обычно name, email, password, phone и др.).

  • Возвращает: при успешной регистрации обычно происходит редирект на страницу входа или профиль пользователя. В случае ошибок валидации – шаблон регистрации с сообщениями об ошибках (с помощью flash или встроенной валидации).

• GET /login и POST /login – вход пользователя.

  • Методы: GET (форма входа), POST (подача логина).

  • Описание: GET-запрос отдаёт форму логина. POST-запрос получает email и пароль, проверяет их в базе (хеши пароля) и устанавливает сессию пользователя (напр., session['user_id'] = ...).

  • Параметры (POST): email и пароль из формы.

  • Возвращает: при успехе – редирект на главную или профиль; при неудаче – повторно форму логина с уведомлением об ошибке.

• GET /logout – выход пользователя.

  • Методы: GET.

  • Описание: Завершает сессию (удаляет session['user_id']) и перенаправляет на главную страницу.

  • Параметры: нет.

  • Возвращает: редирект на /.

• GET /products (или аналогичный маршрут) и GET /product/<int:id> – просмотр каталога товаров и деталей одного товара.

  • Методы: GET.

  • Описание: /products выводит список товаров (примерно как /), а /product/<id> – детальную страницу одного товара с возможностью добавить в корзину.

  • Параметры: для /product/<id> в URL передаётся id товара.

  • Возвращает: рендер шаблона (products.html или product_detail.html) с информацией о товаре(ах) из базы (название, описание, цена и т.д.).

• POST /cart/add – добавление товара в корзину.

  • Методы: POST.

  • Описание: Обрабатывает форму или AJAX-запрос на добавление выбранного товара в корзину.

  • Параметры (POST): обычно JSON или форма с полями product_id и quantity.

  • Возвращает: после добавления выполняется редирект на страницу корзины или возвращается JSON с результатом (success: true и обновлённым количеством товаров), в зависимости от реализации.

• GET /cart – просмотр корзины.

  • Методы: GET.

  • Описание: Отображает содержимое корзины текущего пользователя: список товаров, их количество, цены, возможная скидка по промокоду и итоговую сумму (подсчитывается функцией calculate_cart_total).

  • Параметры: нет.

  • Возвращает: рендер шаблона cart.html (или подобного) с данными корзины: все позиции (название товара, цена, количество), текущая сумма, активный промокод, поле для ввода промокода и т.д.

• POST /cart/remove/<int:product_id> – удаление товара из корзины.

  • Методы: POST.

  • Описание: Удаляет указанный товар из корзины пользователя (по product_id). Возможно, уменьшает количество или полностью удаляет позицию.

  • Параметры: в URL — product_id; обычно могут быть и данные формы.

  • Возвращает: после удаления – редирект на /cart или JSON-ответ об успехе (зависит от метода вызова).

• GET /checkout и POST /checkout – оформление заказа (чекаут).

  • Методы: GET (форма оформления заказа), POST (отправка заказа).

  • Описание: GET-версия показывает форму оформления заказа: адрес доставки, контактный телефон и т.д. Здесь может применяться format_phone_number для проверки телефона. При POST-запросе собираются данные корзины и данные клиента, создаётся запись заказа в БД (с товарами из корзины), корзина очищается. Возможно, вызывается calculate_cart_total для расчёта суммы.

  • Параметры (POST): поля формы (адрес, контактные данные, выбранный промокод и т.д.), а также информация о товарах из корзины (часто берётся на сервере из сессии или базы).

  • Возвращает: при успешном оформлении заказа – редирект на страницу с подтверждением или JSON с результатом (например, номером заказа). В случае ошибки – повторно шаблон checkout.html с сообщениями об ошибках.

• GET /orders (или /profile/orders) – история заказов пользователя.

  • Методы: GET.

  • Описание: Показывает список прошлых заказов текущего пользователя, их статусы, даты и т.д.

  • Параметры: нет.

  • Возвращает: шаблон orders.html с перечислением заказов из базы.

• GET /admin – главная страница панели администратора.

  • Методы: GET.

  • Описание: Защищена декоратором @admin_required. Отображает админ-панель (например, сводку: кол-во пользователей, заказов, новые заявки).

  • Параметры: нет.

  • Возвращает: шаблон admin/index.html с данными для администратора.

• GET /admin/products и POST /admin/products – управление товарами в админ-панели.

  • Методы: GET (список товаров), POST (добавление нового товара).

  • Описание: GET-версия выводит таблицу товаров с опциями редактирования/удаления. POST-версия получает данные новой позиции (название, цена, описание, изображение) и сохраняет товар в базу.

  • Параметры (POST): поля формы (например, name, price, description, image_url).

  • Возвращает: после добавления/изменения – редирект обратно на /admin/products.

• POST /admin/products/delete/<int:product_id> – удаление товара (в админке).

  • Методы: POST (или DELETE).

  • Описание: Удаляет товар с указанным product_id из базы.

  • Параметры: product_id в URL.

  • Возвращает: редирект на список товаров или JSON с результатом удаления.

• GET /admin/promo и POST /admin/promo – управление промокодами.

  • Методы: GET (вывод списка промокодов), POST (добавление нового промокода).

  • Описание: GET-версия показывает таблицу имеющихся промокодов (код, скидка, лимит использований, срок действия). POST-версия принимает форму с параметрами нового промокода и добавляет его в базу (используя validate_promo при проверке входных данных).

  • Параметры (POST): code, discount_percent, usage_limit, expires_at и др.

  • Возвращает: после добавления – редирект на /admin/promo.

• DELETE /admin/promo/delete/<int:promo_id> – удаление промокода.

  • Методы: DELETE (или POST с методом DELETE).

  • Описание: Удаляет промокод с идентификатором promo_id. Защищён проверкой admin_required.

  • Параметры: promo_id в URL.

  • Возвращает: JSON с результатом (success: true/false и сообщением) или редирект на список промокодов, если вызов произведён через браузер.

• POST /api/apply_promo – API для применения промокода к корзине.

  • Методы: POST.

  • Описание: Принимает JSON с полем promo_code (и, возможно, текущей суммой корзины) и пытается применить скидку. Вызывает функцию validate_promo, проверяет ограничения (срок действия, лимит, повторное использование) и рассчитывает новую сумму, используя calculate_cart_total.

  • Параметры (JSON в теле запроса): { "promo_code": "...", "cart_total": 123.45 }.

  • Возвращает: JSON-ответ:

    • при успехе, например { "success": true, "discount": 10.0, "new_total": 113.45 } – где discount и new_total рассчитаны на основе исходной суммы и условий промокода;

    • при неудаче { "success": false, "error": "описание ошибки" }, если код недействителен или превышен лимит.

• Другие API-эндпоинты (по аналогии):
  Возможно, предусмотрены дополнительные API (например, для AJAX-подгрузки товаров). Например, POST /api/order или POST /api/cart/update. Они принимают JSON-запросы и возвращают JSON-ответы с success/error и данными. Конкретные пути и параметры зависят от реализации.

В app.py определён ряд функций, не являющихся маршрутами, но поддерживающих логику приложения:

• calculate_cart_total(cart_items) – вычисление итоговой суммы корзины.
  Принимает список позиций корзины (cart_items), где каждая позиция содержит цену и количество. Возвращает сумму цен с учётом количества и (опционально) применённой скидки. Используется при отображении корзины и в логике оформления заказа.

• is_admin(user) – проверка роли пользователя.
  Функция получает объект текущего пользователя (или его идентификатор) и возвращает True, если у пользователя есть права администратора. Обычно проверяет поле user.is_admin или user.role == 'admin'. Используется внутри admin_required.

• @admin_required (декоратор) – защита админ-маршрутов.
  Оборачивает маршрут: если is_admin(current_user) возвращает False (или пользователь не авторизован), выполняет перенаправление на страницу логина/ошибки или возвращает 403 ошибку. Гарантирует, что внутренняя функция выполняется только для администраторов.

• validate_promo(code) – проверка промокода.
  Принимает строковый код промокода, ищет его в базе и проверяет несколько условий: промокод существует, не истёк (expires_at), не превысил usage_limit и пользователь ещё не использовал его. Если все проверки пройдены, возвращает объект промокода или истину; иначе – False или сообщение об ошибке. Используется в маршруте /api/apply_promo и в админ-панели при создании промокода.

• format_phone_number(raw_phone) – форматирование номера телефона.
  Принимает введённый пользователем номер (с произвольными символами) и преобразует его в унифицированный формат (например, +7XXXXXXXXXX). Обычно убирает пробелы, дефисы, проверяет через regex_match, корректирует код страны. Если номер не соответствует шаблону, может выдать ошибку. Используется при регистрации или оформлении заказа для стандартизации контактов.

• regex_match(pattern, string) – проверка строки регулярным выражением.
  Принимает шаблон (pattern) и строку (string); возвращает True, если строка соответствует шаблону. Помогает валидации входных данных (например, телефон или email). Если регулярное выражение не задано или строка пуста, может возвращать False или True в зависимости от логики.

• @app.context_processor def inject_cart_items_count(): – инъекция количества товаров в корзине.
  Функция без параметров, возвращающая словарь, например {'cart_count': N}, где N – общее число позиций в текущей корзине пользователя (или сумма количеств). Flask автоматически добавляет cart_count во все шаблоны, что позволяет, например, в шапке сайта показывать иконку корзины с числом позиций.

• @app.context_processor def inject_user(): – инъекция информации о текущем пользователе.
  Возвращает {'current_user': ...} – объект или данные текущего пользователя (если залогинен), иначе None. Позволяет в шаблонах проверять, залогинен ли пользователь, отображать его имя и т.п.

• @app.context_processor def inject_timezone(): – инъекция часового пояса или текущего времени.
  Возвращает информацию о часовой зоне или текущем времени (например, {'timezone': 'UTC+3'}) на основе настроек пользователя или сервера. Используется для корректного отображения времени (например, даты заказа) в шаблонах.