MOD-CURRENCY — Мультивалютность, курсы и конвертация

Лицензия: Платный

Модуль отвечает за одну вещь, которую нельзя размазывать по остальным: за курс валюты и за то, откуда он взялся. В справочнике из коробки 20 валют с ISO-кодами, символами, точностью и названиями на трёх языках; базовая валюта учёта — одна и защищена уникальным индексом, поэтому «двух базовых» в системе не бывает. Конвертация возвращает не только цифру, но и происхождение курса, так что любую сумму можно объяснить постфактум.

Курсы приходят из настраиваемых источников: по умолчанию включён лондонский FX-фиксинг (бесплатный агрегатор open.er-api), рядом — Банк России и Европейский центральный банк, а фид Народного банка Сербии засиден выключенным, потому что требует регистрации и ключа. Поверх рыночных котировок работают ручные курсы на неделю, месяц или квартал (политика manual_first отдаёт им приоритет, при этом периоды одного вида для одной пары не пересекаются) и правила наценки за обмен — по паре, по валюте или глобальные, с процентом и фиксированной комиссией. Адрес любого источника проверяется на SSRF дважды: при сохранении и повторно перед самим HTTP-запросом, а api_key вырезается и из логов, и из last_error, который виден администратору.

Возможности

Справочник валют: 20 предустановленных валют с ISO-4217, символом, знаками после запятой и названиями ru/en/sr
Единственная базовая валюта учёта; выключенная валюта не участвует в конвертации
Конвертация суммы: чистый курс и сумма с наценкой, с указанием происхождения курса
Курс пары на дату отдельным инструментом — без расчёта суммы, по той же политике
Источники курсов: JSON и XML-фиды, период опроса, источник по умолчанию, фоновая синхронизация
Предустановленные источники: лондонский FX-фиксинг (по умолчанию), Банк России, ЕЦБ, НБ Сербии (выключен, нужен ключ)
Проверка фида без записи в базу: количество котировок и первые пары
Принудительная синхронизация источника вне расписания
Ручные курсы по периодам «неделя / месяц / квартал» с контролем пересечений
Политика курса market или manual_first — рыночный курс либо приоритет ручного
Правила наценки за обмен: по паре, по валюте или для любой пары; процент и фиксированная комиссия
Защита от SSRF: адреса фидов во внутренних и служебных сетях отклоняются на записи и перед запросом
Маскирование api_key в выдаче источников и в тексте ошибок синхронизации
Настройки модуля применяются без перезапуска: политика курса, источник по умолчанию, валюта отображения, автообновление

Основные MCP-инструменты

Инструмент	Назначение
`currency__currency.list`	Справочник валют: код, символ, точность, названия, активность
`currency__currency.upsert`	Создать или изменить валюту в справочнике
`currency__currency.set_active`	Включить или выключить валюту (выключенная не участвует в конвертации)
`currency__currency.convert`	Конвертировать сумму: чистый курс и сумма с наценкой, с происхождением курса
`currency__currency.get_rate`	Курс пары на дату без расчёта суммы, по той же политике
`currency__rate_source.list`	Настроенные источники курсов (`api_key` маскируется), время и причина сбоя синхронизации
`currency__rate_source.upsert`	Создать или изменить источник курсов; сделать его источником по умолчанию
`currency__rate_source.delete`	Удалить источник вместе с его котировками
`currency__rate_source.test`	Загрузить и разобрать фид БЕЗ записи в базу: сколько котировок и первые пары
`currency__rate_source.sync`	Принудительно опросить источник и записать котировки вне расписания
`currency__manual_rate.list`	Ручные курсы по периодам с фильтром по паре валют
`currency__manual_rate.upsert`	Задать ручной курс пары на период (неделя, месяц или квартал)
`currency__manual_rate.delete`	Удалить ручной курс
`currency__spread_rule.list`	Правила наценки за обмен: по паре, по валюте или глобальные
`currency__spread_rule.upsert`	Создать или изменить правило наценки; пустой код валюты означает «для любой»
`currency__spread_rule.delete`	Удалить правило наценки
`currency__settings.describe`	Схема настроек модуля: политика курса, источник по умолчанию, валюта отображения, автообновление

Блоки холста

currency_rates_table — «Курсы валют»: таблица актуальных курсов с датой и источником
currency_converter — «Конвертер валют»: пересчёт суммы из одной валюты в другую по курсу на дату

Связанные модули

MOD-FINANCE — управленческий учёт, для которого фиксируется курс на дату и базовая валюта
MOD-FUNDS — фонды и распределение прибыли в базовой валюте учёта
MOD-PRODUCTS — каталог и цены, которые показываются в валюте отображения
MOD-CRM — сделки в валюте клиента и их пересчёт в валюту учёта
MOD-CONTRACT-TM — подрядные ставки и выручка в разных валютах