MStore Email Order (mstoremailorder)

Введение

Плагин MStore Email Order (кодовое имя: mstoremailorder) разработан для интеграции функционала оформления заказов через email в модуль витрины товаров mstore, основанный на модуле Pages в CMF Cotonti Siena v.0.9.26 (PHP 8.4). Плагин позволяет пользователям (включая гостей) оформлять заказы на товары, отправлять уведомления по email покупателю и продавцу, а также просматривать входящие и исходящие заказы в профиле пользователя. Он обеспечивает простой и удобный интерфейс для оформления заказов, их администрирования и интеграции с существующей системой Cotonti.

Основные функции

1. Ссылки на оформление заказа: Добавляет кнопки/ссылки в карточку товара (mstore.tpl) и список товаров (mstore.list.tpl) для перехода к форме заказа.
2. Форма заказа: Отдельная страница с полями для ввода email, телефона и количества товара. IP-адрес фиксируется автоматически. Поддержка гостей (обязательные поля: email и телефон).
3. Просмотр заказов: В профиле пользователя (users.details.tpl) добавляются ссылки на "Входящие" (заказы от покупателей для продавца) и "Исходящие" (собственные заказы пользователя).
4. Уведомления по email: После оформления заказа отправляются письма покупателю и продавцу с деталями: ссылка на товар, название, дата, количество, телефон, IP, а также ссылки на профили покупателя (если не гость) и продавца.
5. Админ-панель: Раздел для просмотра всех заказов с пагинацией.
6. Локализация: Поддержка русского и английского языков.
7. База данных: Создание таблицы cot_mstore_orders для хранения заказов с поддержкой foreign keys.

Требования

• CMF: Cotonti Siena v.0.9.26 или выше.
• PHP: 8.4.
• Модули: Установленный модуль mstore (на основе Pages).
• База данных: MySQL/MariaDB с поддержкой InnoDB (для foreign keys).
• Email: Настроенный сервер отправки email (SMTP или PHP mail()).
• Зависимости: Таблицы cot_mstore (для товаров) и cot_users (для пользователей).

Структура файлов

Плагин размещается в директории plugins/mstoremailorder/ и имеет следующую структуру:

/mstoremailorder/
├── inc/
│   └── mstoremailorder.functions.php         # Вспомогательные функции (отправка email, генерация текста письма).
├── lang/
│   ├── mstoremailorder.en.lang.php           # Локализация на английском языке.
│   └── mstoremailorder.ru.lang.php           # Локализация на русском языке.
├── setup/
│   ├── mstoremailorder.install.sql           # SQL-скрипт для создания таблицы заказов.
│   └── mstoremailorder.uninstall.sql         # SQL-скрипт для удаления таблицы.
├── tpl/
│   ├── mstoremailorder.admin.tpl             # Шаблон админки для списка заказов.
│   ├── mstoremailorder.user.tpl              # Шаблон для просмотра заказов пользователя (входящие/исходящие).
│   └── mstoremailorder.tpl                   # Шаблон формы оформления заказа.
├── mstoremailorder.admin.php                 # Логика админ-панели (хуки: tools).
├── mstoremailorder.global.php                # Глобальное подключение (хуки: global) — языки и функции.
├── mstoremailorder.php                       # Основная логика (хуки: standalone) — обработка формы, просмотр заказов.
├── mstoremailorder.setup.php                 # Конфигурация плагина (права доступа, настройки).
├── mstoremailorder.users.details.tags.php    # Хук для профиля пользователя (хуки: users.details.tags) — добавление ссылок на заказы.
├── mstoremailorder.mstore.tags.php           # Хук для карточки товара (хуки: mstore.tags) — добавление кнопки заказа.
└── mstoremailorder.mstore.loop.php           # Хук для списка товаров (хуки: mstore.list.loop) — добавление кнопки заказа.

Описание файлов

1. inc/mstoremailorder.functions.php:

   • Содержит вспомогательные функции:
     • mstoremailorder_send_email: Отправляет email с заголовками (From, Content-Type).
     • mstoremailorder_generate_order_email: Генерирует тело письма с плейсхолдерами: {ITEM_TITLE}, {ITEM_URL}, {QUANTITY}, {PHONE}, {DATE}, {BUYER_PROFILE_URL}, {SELLER_PROFILE_URL}.
   • Ссылки на профили добавляются в email: покупателя (если не гость) и продавца.
   • Используется в mstoremailorder.php для отправки уведомлений.

2. lang/mstoremailorder.en.lang.php и lang/mstoremailorder.ru.lang.php:

   • Файлы локализации для английского и русского языков.
   • Содержат строки для интерфейса (названия кнопок, заголовки), сообщений об ошибках и шаблонов email.
   • Плейсхолдеры {BUYER_PROFILE_URL} и {SELLER_PROFILE_URL} добавлены для ссылок на профили.

3. setup/mstoremailorder.install.sql:

   • SQL-скрипт создает таблицу cot_mstore_orders с полями: order_id, order_item_id, order_user_id, order_seller_id, order_quantity, order_phone, order_email, order_date, order_ip, order_status, order_notes.
   • Использует foreign keys для связи с cot_mstore (товары) и cot_users (пользователи).

4. setup/mstoremailorder.uninstall.sql:

   • Удаляет таблицу cot_mstore_orders при деинсталляции.

5. tpl/mstoremailorder.admin.tpl:

   • Шаблон для админ-панели.
   • Отображает таблицу всех заказов с полями: ID, товар, покупатель (email), продавец, количество, телефон, дата, статус.
   • Поддерживает пагинацию и чередование строк (odd/even).

6. tpl/mstoremailorder.user.tpl:

   • Шаблон для просмотра заказов пользователя.
   • Блоки OUTGOING (исходящие) и INCOMING (входящие) показывают заказы с деталями (ID, товар, количество, дата, статус, email/телефон для входящих).
   • Поддерживает пагинацию и чередование строк.

7. tpl/mstoremailorder.tpl:

   • Шаблон формы заказа.
   • Поля: email, телефон, количество. Кнопка отправки.
   • Отображает сообщения об ошибках/успехе.

8. mstoremailorder.admin.php:

   • Логика админ-панели (хук tools).
   • Выводит список всех заказов с пагинацией через XTemplate.
   • Использует таблицу cot_mstore_orders, JOIN с cot_mstore и cot_users для получения названий товаров и имен продавцов.

9. mstoremailorder.global.php:

   • Подключает языковые файлы и функции глобально (хук global).
   • Не содержит сложной логики, только инициализация.

10. mstoremailorder.php:

    • Основной файл плагина (хук standalone).
    • Обрабатывает три сценария:
      • Форма заказа: Отображает форму (mstoremailorder.tpl) по ?item_id=ID. Валидирует данные, сохраняет заказ в БД, отправляет email.
      • Исходящие заказы (?m=outgoing): Показывает заказы пользователя/гостя (по order_user_id или order_email) с пагинацией.
      • Входящие заказы (?m=incoming): Показывает заказы продавца (по order_seller_id) с пагинацией.
    • Использует XTemplate для рендеринга.

11. mstoremailorder.setup.php:

    • Конфигурация плагина: код, имя, описание, версия, права доступа, настройки (email_from, email_subject).
    • Права: Гости — только чтение (R), пользователи — чтение/запись (RW).

12. mstoremailorder.users.details.tags.php:

    • Хук users.details.tags.
    • Добавляет теги USER_INCOMING_ORDERS_LINK и USER_OUTGOING_ORDERS_LINK для ссылок на заказы в профиле.

13. mstoremailorder.mstore.tags.php:

    • Хук mstore.tags.
    • Добавляет тег MSTORE_ORDER_LINK для кнопки заказа в карточке товара.

14. mstoremailorder.mstore.loop.php:

    • Хук mstore.list.loop.
    • Добавляет тег MSTORE_ROW_ORDER_LINK для кнопки заказа в списке товаров.

Порядок установки

1. Скопировать файлы:

   • Поместите директорию mstoremailorder в plugins/ вашего сайта Cotonti.

2. Установка через админку:

   • Перейдите в Администрирование > Расширения > Плагины.
   • Найдите MStore Email Order и нажмите "Установить".
   • Это выполнит SQL-скрипт mstoremailorder.install.sql, создав таблицу cot_mstore_orders.

3. Настройка конфигурации:

   • В админке откройте настройки плагина (Администрирование > Расширения > MStore Email Order > Настройки).
   • Укажите:
     • email_from: Email-адрес отправителя (например, no-reply@site.com).
     • email_subject: Тема писем (например, New Order Notification).

4. Интеграция в шаблоны:

   • См. раздел "Интеграция в шаблоны" ниже.

5. Проверка:

   • Убедитесь, что таблица cot_mstore_orders создана в БД.
   • Проверьте работу формы заказа (plug.php?e=mstoremailorder&item_id=ID).
   • Проверьте отправку email (убедитесь, что сервер настроен).
   • Проверьте списки заказов (?m=incoming, ?m=outgoing) и админку (admin.php?m=other&p=mstoremailorder).

6. Удаление:

   • В админке нажмите "Удалить" для плагина.
   • Выполнится mstoremailorder.uninstall.sql, удаляющий таблицу cot_mstore_orders.

Предупреждение: Перед установкой сделайте бэкап БД. Убедитесь, что таблицы cot_mstore и cot_users существуют, так как плагин использует foreign keys.

Интеграция в шаблоны

Для работы плагина нужно добавить теги в шаблоны модулей mstore и users. После изменений очистите кэш шаблонов в админке (Администрирование > Кэш).

1. Карточка товара (modules/mstore/tpl/mstore.tpl):

   • Добавьте в нужное место (например, после цены или описания):

     <a href="{MSTORE_ORDER_LINK}">{PHP.L.mstoremailorder_order_button}</a>

2. Список товаров (modules/mstore/tpl/mstore.list.tpl):

   • Внутри блока <!-- BEGIN: MSTORE_ROW --> ... <!-- END: MSTORE_ROW --> добавьте:

     <a href="{MSTORE_ROW_ORDER_LINK}">{PHP.L.mstoremailorder_order_button}</a>

3. Профиль пользователя (modules/users/tpl/users.details.tpl):

   • В разделе меню или информации о пользователе добавьте:

     <a href="{USER_OUTGOING_ORDERS_LINK}">{PHP.L.mstoremailorder_outgoing_orders}</a>
     <a href="{USER_INCOMING_ORDERS_LINK}">{PHP.L.mstoremailorder_incoming_orders}</a>

Принцип работы

Общая логика

• Хуки Cotonti:
  • global: Подключает языки и функции.
  • standalone: Основная страница плагина (форма заказа, списки заказов).
  • tools: Админ-панель для просмотра заказов.
  • users.details.tags: Ссылки в профиле пользователя.
  • mstore.tags: Кнопка заказа в карточке товара.
  • mstore.list.loop: Кнопка заказа в списке товаров.
• База данных: Таблица cot_mstore_orders хранит заказы. Foreign keys (order_item_id, order_user_id, order_seller_id) обеспечивают целостность данных.
• Гости: Поддержка гостей реализована через order_user_id=0. Email и телефон обязательны. Ссылка на профиль покупателя в email добавляется только если order_user_id > 0.
• Шаблоны: Используется XTemplate для рендеринга формы, списков и админки. Поддержка пагинации и чередования строк (odd/even).
• Переменная вывода: Контент плагина передается в $pluginBody для отображения в Cotonti.

Работа формы заказа

1. Переход к форме:
   • Пользователь кликает на кнопку заказа в карточке товара (MSTORE_ORDER_LINK) или списке (MSTORE_ROW_ORDER_LINK).
   • URL: plug.php?e=mstoremailorder&item_id=ID.
2. Отображение формы:
   • Загружается шаблон mstoremailorder.tpl.
   • Поля: email (предзаполнено для авторизованных), телефон, количество.
3. Отправка формы:
   • Валидация: Проверка на пустые email/телефон, количество > 0, существование товара.
   • Сохранение: Данные заказа (order_item_id, order_user_id, order_seller_id, order_quantity, order_phone, order_email, order_date, order_ip, order_status=0) записываются в cot_mstore_orders.
   • Email: Генерируются письма для покупателя (с {SELLER_PROFILE_URL}) и продавца (с {BUYER_PROFILE_URL}, если не гость).
   • Редирект: После успеха — на plug.php?e=mstoremailorder&id=ORDER_ID с сообщением.
4. Ошибки: Если валидация не пройдена, ошибки отображаются в форме.

Просмотр заказов

• Исходящие заказы (?m=outgoing):
  • Запрос по order_user_id (авторизованные) или order_email (гости).
  • JOIN с cot_mstore для получения названия товара.
  • Пагинация: Ограничение по Cot::$cfg['maxrowsperpage'].
  • Шаблон: mstoremailorder.user.tpl, блок OUTGOING.
• Входящие заказы (?m=incoming):
  • Запрос по order_seller_id.
  • JOIN с cot_mstore для названия товара.
  • Пагинация и шаблон: mstoremailorder.user.tpl, блок INCOMING.

Админ-панель

• Доступ: admin.php?m=other&p=mstoremailorder.
• Функционал: Выводит все заказы из cot_mstore_orders с JOIN (cot_mstore, cot_users) для получения названий товаров и имен продавцов.
• Шаблон: mstoremailorder.admin.tpl.
• Пагинация: Ограничение по Cot::$cfg['maxrowsperpage'].

Уведомления по email

• Генерация:
  • Функция mstoremailorder_generate_order_email заменяет плейсхолдеры в шаблонах из lang/*.lang.php.
  • Плейсхолдеры: {ITEM_TITLE}, {ITEM_URL}, {QUANTITY}, {PHONE}, {DATE}, {BUYER_PROFILE_URL}, {SELLER_PROFILE_URL}.
  • {BUYER_PROFILE_URL} пусто, если order_user_id=0 (гость).
• Отправка:
  • Используется PHP mail() с заголовками (From: email_from, Content-Type: HTML).
  • Покупателю: Подтверждение заказа с ссылкой на профиль продавца.
  • Продавцу: Уведомление о новом заказе с ссылкой на профиль покупателя (если не гость).

Конфигурация и кастомизация

Настройки

• email_from: Email-адрес отправителя (например, no-reply@site.com).
• email_subject: Тема писем (например, New Order Notification).
• Редактируются в админке: Администрирование > Расширения > MStore Email Order > Настройки.

Кастомизация

• Добавление полей: Расширьте таблицу cot_mstore_orders (например, для оплаты или комментариев) и обновите install.sql, mstoremailorder.php, шаблоны.
• Статусы заказов: Поле order_status можно использовать для добавления статусов (например, "В обработке", "Завершен"). Доработайте админку для управления статусами.
• Локализация: Добавьте новые языки в lang/, обновите строки в *.lang.php.
• Шаблоны: Настройте *.tpl для изменения дизайна или добавления полей.
• Дополнительные хуки: Используйте другие хуки Cotonti для интеграции (например, ajax для асинхронных заказов).

Возможные проблемы и отладка

1. Email не отправляются:
   • Проверьте настройки сервера (SMTP или PHP mail()).
   • Убедитесь, что email_from валиден.
   • Проверьте логи Cotonti или сервера.
2. Ошибки в БД:
   • Убедитесь, что таблицы cot_mstore и cot_users существуют.
   • Проверьте foreign keys в install.sql.
   • Логи SQL-запросов: Включите debug в Cotonti (config.php).
3. Гости:
   • Исходящие заказы видны только если email совпадает с user_email авторизованного пользователя.
   • {BUYER_PROFILE_URL} пусто для гостей.
4. Пагинация:
   • Если заказов много, настройте maxrowsperpage в настройках Cotonti.
   • Проверьте работу cot_pagenav в mstoremailorder.php и mstoremailorder.admin.php.
5. Шаблоны:
   • Если теги не отображаются, очистите кэш шаблонов.
   • Проверьте правильность интеграции тегов (MSTORE_ORDER_LINK, USER_OUTGOING_ORDERS_LINK и т.д.).
6. Редирект:
   • Редирект на ?id=ORDER_ID пока не обрабатывает детали заказа. Можно доработать в mstoremailorder.php для отображения конкретного заказа.

Примеры использования

Оформление заказа

1. Пользователь переходит на товар (mstore.php?id=123).
2. Кликает "Заказать" (plug.php?e=mstoremailorder&item_id=123).
3. Заполняет форму: email, телефон, количество.
4. После отправки получает email с подтверждением и ссылкой на профиль продавца.
5. Продавец получает email с деталями заказа и ссылкой на профиль покупателя (если не гость).

Просмотр заказов

1. В профиле пользователя кликает "Исходящие заказы" (plug.php?e=mstoremailorder&m=outgoing).
2. Видит список своих заказов с пагинацией.
3. Продавец кликает "Входящие заказы" (plug.php?e=mstoremailorder&m=incoming) и видит заказы на свои товары.

Админка

• Админ заходит в admin.php?m=other&p=mstoremailorder.
• Видит таблицу всех заказов с пагинацией.

Лицензия и автор

• Автор: webitproff.
• Лицензия: BSD License.
• Версия: 1.0.0 (от 2025-08-31).
• Вопросы, обсуждения, поддержка