==================================
CURRENCIES — Мультивалютность
==================================

Версия: 1.0.0
Зависимости: нет (интегрируется с basket и payments)

─────────────────────────────────────────────────────────────────────────────
ОПИСАНИЕ
─────────────────────────────────────────────────────────────────────────────
Плагин добавляет поддержку нескольких валют. Позволяет отображать цены
в выбранной пользователем валюте с пересчётом по курсам. Курсы обновляются
автоматически (с сайта ЦБ РФ) или задаются вручную.

─────────────────────────────────────────────────────────────────────────────
УСТАНОВКА
─────────────────────────────────────────────────────────────────────────────

1. Установите плагин через панель администратора.
   Создаётся таблица: {prefix}\_currencies
   В таблицу автоматически добавляется базовая валюта из настроек.
2. Настройте базовую валюту (Плагины → currencies → Настройки).
3. Добавьте остальные валюты в панели управления:
   Плагины → currencies → Управление валютами.
4. Для автообновления курсов настройте cron:
   Добавьте задачу вызова плагина с параметром cron в системный планировщик.

─────────────────────────────────────────────────────────────────────────────
НАСТРОЙКИ (Плагины → currencies → Настройки)
─────────────────────────────────────────────────────────────────────────────
base — ISO-код базовой валюты (RUB, UAH, USD)
Все цены в системе хранятся в этой валюте
rate_source — источник курсов: cbr (ЦБ РФ) или manual (вручную)
format — формат отображения цены: %s — сумма, %c — символ
Пример: %s %c → «1 234.50 ₽»

─────────────────────────────────────────────────────────────────────────────
УПРАВЛЕНИЕ ВАЛЮТАМИ (Плагины → currencies → Управление)
─────────────────────────────────────────────────────────────────────────────
Поля каждой валюты:
code — ISO-код (RUB, USD, EUR, UAH, …)
name — название («Российский рубль»)
symbol — символ (₽, $, €, ₴)
rate — курс относительно базовой валюты
Пример: базовая RUB, курс USD = 0.011 (1 RUB = 0.011 USD)
is_base — флаг базовой валюты (курс всегда 1.0)

─────────────────────────────────────────────────────────────────────────────
URL-СТРАНИЦЫ ПЛАГИНА
─────────────────────────────────────────────────────────────────────────────
/currencies/switch/?code=USD — переключить валюту пользователя
(redirect на реферер, cookie на 1 год)

─────────────────────────────────────────────────────────────────────────────
ПЕРЕМЕННЫЕ НА ВСЕХ СТРАНИЦАХ САЙТА
─────────────────────────────────────────────────────────────────────────────
Плагин добавляет переменные через add_act('index', …) на каждую страницу:

{{ currency_active }} — ISO-код активной валюты пользователя («RUB»)
{{ currencies_list }} — массив всех валют из БД:
[{ id, code, name, symbol, rate, is_base }, …]
{{ currency_switch_link }} — базовый URL переключателя (/currencies/switch/)

─────────────────────────────────────────────────────────────────────────────
PHP-ФУНКЦИИ ДЛЯ ИСПОЛЬЗОВАНИЯ В ДРУГИХ ПЛАГИНАХ
─────────────────────────────────────────────────────────────────────────────
currencies_get_active(): string
Возвращает ISO-код активной валюты пользователя.

currencies_get_all(): array
Возвращает все валюты из БД (кешируется на время запроса).

currencies_get_rate(string $code): float
Возвращает курс валюты относительно базовой.

currencies_convert(float $price, string $from, string $to): float
Конвертирует сумму из одной валюты в другую.
Пример: currencies_convert(1000, 'RUB', 'USD')

currencies_format(float $price, string $baseCurrency = ''): string
Форматирует сумму в активной валюте пользователя с символом.
Пример: currencies_format(1000) → «11.00 $» (если активна USD)
baseCurrency — валюта, в которой хранится цена (по умолчанию — настройка base)

─────────────────────────────────────────────────────────────────────────────
ПРИМЕР: ПЕРЕКЛЮЧАТЕЛЬ ВАЛЮТ В ШАБЛОНЕ
─────────────────────────────────────────────────────────────────────────────
В файле шаблона header.tpl или sidebar.tpl:

  <div class="currency-switcher">
    {% for c in currencies_list %}
      <a href="{{ currency_switch_link }}?code={{ c.code }}"
         class="{% if c.code == currency_active %}active{% endif %}">
        {{ c.symbol }} {{ c.code }}
      </a>
    {% endfor %}
  </div>

─────────────────────────────────────────────────────────────────────────────
ПРИМЕР: ВЫВОД ЦЕНЫ В АКТИВНОЙ ВАЛЮТЕ
─────────────────────────────────────────────────────────────────────────────
В шаблоне новости/товара (если цена берётся из xfield «price»):

{{ xfields_price }} — цена в базовой валюте (как хранится в xfields)

Для конвертации используйте PHP в своём плагине/виджете:
$priceConverted = currencies_format((float)$newsRow['xfields_price']);
// → «11.00 $»

─────────────────────────────────────────────────────────────────────────────
АВТООБНОВЛЕНИЕ КУРСОВ (CRON)
─────────────────────────────────────────────────────────────────────────────
Функция plugin_currencies_cron() вызывается системным крон-планировщиком.
При source = 'cbr' обращается к https://www.cbr.ru/scripts/XML_daily.asp
и обновляет курсы всех валют, которые уже есть в таблице currencies.

Валюты, отсутствующие в таблице, игнорируются (добавьте их вручную).

─────────────────────────────────────────────────────────────────────────────
ИНТЕГРАЦИЯ С PAYMENTS
─────────────────────────────────────────────────────────────────────────────
Адаптеры плагина payments читают базовую валюту через:
pluginGetVariable('payments', 'currency')

Для синхронизации задайте одинаковый ISO-код в настройках обоих плагинов.
