Botoscope^®

У рушії ніде немає ID орендаря. init() входить одним клієнтом-ботом TDLib, відкриває один пул knex і одне з'єднання Redis та читає домен магазину, API-ключ клієнта, ліміт товарів і прапорець безкоштовного тарифу зі змінних середовища. Ізоляція між магазинами — питання розгортання: кожен бот отримує власний екземпляр зі своєю текою бази TDLib і схемою MySQL.

Так запити й ключі Redis лишаються простими (chat:<id>:<key>) ціною одного процесу на магазин. Ключі Redis не мають префікса бота, тому два екземпляри не повинні ділити одну базу Redis.

Бот входить через TDLib (tdl з tdl-tdlib-addon) за токеном бота й тримає одне довге з'єднання з Telegram. Оновлення надходять у client.on('update'), тож рушію не потрібен ні URL вебхука, доступний із Telegram, ні цикл опитування getUpdates.

Головна причина — модель екранів. TDLib повідомляє про власні вихідні повідомлення бота як updateNewMessage та updateMessageSendSucceeded в тому самому потоці, що й повідомлення покупця. Один обробник реєструє кожен ID повідомлення в приватному чаті, надісланого чи отриманого, а коли екран змінюється, рушій видаляє їх через deleteMessages (revoke: true). У чаті лишається тільки поточний екран, а набрані вводи, як пошуковий запит чи адреса, зникають разом із ним. Той самий потік дає рушію змогу дочекатися, поки фотоальбом справді надійде, перш ніж надсилати панель товару.

TDLib також покриває виклики, яких немає в HTTP Bot API: getMessage зчитує текст повідомлення, яке бот надіслав раніше, і панель згрупованих товарів використовує це, щоб перемалювати свої кнопки. На getChat і getUser відповідає клієнт TDLib з увімкненою базою інформації про чати, а медіа надсилаються з локальних шляхів або за віддаленим ID файлу через базу файлів. База повідомлень вимкнена, бо бот не веде історії, оптимізатор сховища очищає файли TDLib, а TDLib працює в одному робочому потоці.

Ціна в тому, що семантика TDLib просочується в застосунок: ID повідомлень тимчасові, доки сервер їх не підтвердить (див. завдання про зіставлення ID), а тека сесії прив'язує бота до одного процесу.

Можливі наступні кроки, які TDLib уже пропонує: увімкнути його базу повідомлень для історії та пошуку по чатах і надсилати файли більші за ліміт вивантаження 50 MB в HTTP Bot API. Рушій наразі не робить ні того, ні іншого; документи обмежені 50 MB.

Answer перетворює оновлення TDLib на події шини: do_callback_query для натискань кнопок, do_command для тексту, pre_checkout_query і successful_payment для платежів. Кошик, обране, бронювання, підтримка та інші підписуються й обробляють лише власні дії, тож не імпортують обробники одне одного.

Для компонування інтерфейсу є два реєстри хуків. Hooks зберігає колбеки на chat_id (поточне контекстне меню, додаткові кнопки товару), відсортовані за пріоритетом, де додавання хука з наявним пріоритетом замінює його. GlobalHooks робить те саме для всіх чатів; розширення підтримки використовує його, щоб додати кнопку на панелі товарів, які йому не належать. Хуки чату скидаються, коли чат видаляється.

Список активних розширень (купони, доставка, підтримка, бронювання, маркетинг, b2b та інші) синхронізується в таблицю опцій. Extensions.init() перетворює кожен slug на ім'я класу й створює екземпляр до побудови основних модулів, щоб їхні хуки існували першими. Основні модулі перевіряють наявність розширення через необов'язкові гетери та змінюють поведінку; наприклад, оформлення замовлення пропускає крок промокоду, коли купони вимкнено.

Вимкнення розширення не може вивантажити код, що вже зареєстрував слухачів, тому скидання кешу розширень перезапускає процес через PM2. У коментарях коду зазначено, що це перериває користувачів посеред сесії.

Commander запускає звичайний http-сервер з /health і /command. Відомі команди (payment_success, order_is_done, reset_cache, update_product_cache) обробляються напряму. Усе інше надсилається як exec_command; модуль-власник записує is_executed і answer у спільний об'єкт body, який точка повертає після короткого фіксованого очікування.

reset_cache оновлює один кеш налаштувань або всі, причому розширення завжди останні, бо саме воно перезапускає процес. reset_db_cache() кожного модуля повторно зчитує свій JSON-блоб у таблицю опцій і очищає копію в пам'яті.

ecosystem.config.cjs запускає один fork-екземпляр (режим cluster закоментований; один токен бота означає одну сесію TDLib), обмежує old space V8, перезапускає при зростанні пам'яті й вимагає 30 с роботи, перш ніж запуск вважається стабільним. Обробники SIGTERM, SIGINT і SIGQUIT знищують пул knex перед виходом, а таймер логує використання пулу, коли є активність.

Кеші в пам'яті, як-от кошики та вибрані валюти, очищаються за таймерами, а мапа ID повідомлень спорожнюється при кожній зміні екрана.

sendMessage у TDLib повертає тимчасовий локальний ID; справжній ID приходить пізніше в updateMessageSendSucceeded разом з old_message_id. Рушій зберігає ID, який повернув send(), у контексті чату (top_message_id, taxonomies_btn_mgs_id тощо) і розв'язує його через MessageMapping, коли потрібно відредагувати або видалити це повідомлення.

Спершу зіставлення жило в Redis, потім було перенесене в мапу на чат у пам'яті, яка очищається при кожній зміні екрана, щоб лишатися малою. Без нього редагування inline-клавіатури після кліку зверталося б до ID, якого вже не існує.

Кожен новий ID повідомлення в приватному чаті додається в chat:<id>:messages. make_messages_castling() переносить цей список у chat:<id>:old_messages і скидає зіставлення ID, модуль малює новий екран, а clear_display() потім видаляє старі повідомлення. Новий вміст з'являється раніше, ніж зникає старий, тож чат ніколи не стає порожнім між екранами.

Повне очищення чату пробували й лишили в коді лише як попередження: на деяких телефонах воно викидало користувача з бота.

Постійне нижнє меню показує кнопку кошика з живим лічильником товарів. Telegram не дозволяє редагувати текст повідомлення, що несе клавіатуру відповідей, тож Cart.redraw_menu() надсилає свіже верхнє повідомлення й видаляє попереднє за його зіставленим ID, а нижній підсумок, inline-повідомлення, редагується на місці після короткої затримки.

Поточне меню зберігається як хук context_menu на чат. change_menu_buttons_text() переписує лише кнопку, що починається з емодзі кошика, у серіалізованому меню, тож будь-який екран може оновити лічильник кошика, не знаючи власного компонування.

format_string_before_send() обробляє strong, em, u, s, code, pre та a href. Він знаходить найближчий відкривний тег, видаляє його разом із закривним і записує початкову та кінцеву позиції в очищеному рядку; вони стають зміщеннями textEntity у formattedText. Іменовані й числові HTML-сутності з WooCommerce декодуються першими. Некоректний або незакритий тег змушує функцію повернути вихідний текст без сутностей замість надсилання зламаного форматування.

Поруч два прийоми верстки: послідовність порожніх символів Брайля вирівнює повідомлення, щоб картки товарів мали однакову ширину, а об'єднувальний накладний символ малює закреслену стару ціну всередині підписів кнопок, де сутності заборонені.

Кнопки клавіатури відповідей приходять як звичайний текст мовою користувача, тож маршрутизація порівнює вхідний текст із підписами, що будує get_menu_command_text() для цього чату. Коли крок чекає на вільний текст (пошуковий запит, SKU, адреса, промокод, повідомлення в підтримку), контекст містить is_waiting_user_input і команду для продовження. Answer зберігає текст як user_message_text і відтворює цю команду, якщо тільки текст не є командою зі слешем або підписом навігації.

Обробники введення при оформленні повторюють перевірку щодо підписів власного кроку, тож натискання «Назад» під час очікування адреси веде назад, а не зберігає це слово як адресу.

Картка товару — це медіаальбом, за яким іде текстова панель із кнопками. print_products_blocks() надсилає альбом, чекає до 10 с на подію new_message_coming цього чату, потім робить паузу перед надсиланням панелі, тож панель ніколи не опиняється вище за свої фото. Короткі фіксовані паузи перед кожним надсиланням і видаленням розподіляють запити в часі.

Швидкі натискання «далі» й «назад» інакше запустили б другу заміну екрана, поки перша не видалила свої повідомлення. Прапорець nowdo на чат ігнорує навігацію, поки екран замінюється, і знімається через секунду після видалення старих повідомлень.

get_rest_data() і send_remote_data() надсилають POST на єдиний URL проксі Botoscope. Магазин названий у заголовку client-domain, кінцева точка — в іншому заголовку, а запит автентифікується API-ключем клієнта й проходом, виведеним через HMAC-SHA256. Завантаження файлів користуються тим самим проксі через його кінцеву точку fetch-file.

Рушію ніколи не потрібні власні REST-ключі магазину, а стороні WordPress лишається тільки відповідати проксі. Збої повертають null, а викликачі трактують null як відсутність даних, тож збій магазину деградує до порожніх списків, а не обвалює екран.

Products.reset_db_cache() читає кількість товарів, виконує truncate для products і products_vs_terms, запускає ALTER TABLE ... DISABLE KEYS на обох таблицях MyISAM і витягує products/{offset}/{limit} сторінками по 100. Кожна сторінка вставляється пакетами по 100 рядків; помилка на одній сторінці логується, а імпорт переходить до наступної. MyISAM не має транзакцій, тож рядки, уже записані з невдалої сторінки, лишаються. Ключі знову вмикаються в блоці finally, тож навіть невдалий імпорт лишає індексовані таблиці. Поки йде імпорт, бот показує частину каталогу, завантажену на цей момент.

Імпорт не запускається при старті. Коментар пояснює, що для великого каталогу він міг би завісити сервер після кожного перезапуску, тому запускається лише за явною командою reset_cache від магазину.

insert_product_batch() розкладає поля, за якими рушій запитує (price, sale_price, прапорці залишків, type, parent_id, publish_date, menu_order, мінімум, максимум і крок кошика), у колонки, а решту даних серіалізує в data. Списки медіа, завантаження, дні доступу чи зовнішній URL товару можна додати на боці магазину без зміни схеми. ID категорій потрапляють і в список через кому в рядку, і в products_vs_terms для індексованого пошуку за категоріями.

install.sql виконується при кожному старті з CREATE TABLE IF NOT EXISTS, тож новий екземпляр сам створює свою схему.

Коли товар змінюється у WooCommerce, сторона магазину надсилає update_product_cache на /command. update_product_cache() отримує products_filter/{id}, що повертає товар з його варіаціями, потім видаляє рядок товару, рядки з цим parent_id і його зв'язки з категоріями та вставляє нові рядки. Один запит несе товар і його варіації, тож рядки переписуються один раз на зміну.

Ліміт тарифу рахує лише батьківські товари. Повний імпорт обрізає основні товари на сторінку й завжди зберігає їхні варіації; інкрементальний шлях пропускає новий товар, коли кількість різних товарів у products_vs_terms досягає ліміту.

Для товарів з обліком залишків таймер кожні три хвилини виставляє is_in_stock за stock_quantity в обидва боки, тож кнопка купівлі слідує за фактичною кількістю, навіть коли надісланий прапорець застарів. Покупці можуть підписатися на товар, якого немає в наявності, або на окрему варіацію; stock_notify зберігає product_id і chat_id. Кожні дві години рушій знаходить підписані товари, що знову в наявності, повторно надсилає картку кожному підписнику й видаляє підписку.

Кожен запит до каталогу також порівнює publish_date з поточним часом, тож заплановані товари лишаються прихованими до своєї дати.

Команда /filter і кнопки Filter відкривають filter_page_url як Web App з дописаним chat_id. Фільтрація виконується на боці WordPress. Результат повертається до рушія як команда filtered_products_ids на /command, а Products виводить ці ID як звичайний постраничний каталог у цьому чаті.

Так підрахунок фасетів і логіка атрибутів лишаються в одному місці, у магазині, а чат усе одно показує результати у власному форматі карток.

Cart.get() віддає зі статичної мапи на чат і звертається до Redis (chat:<id>:cart); update() пише в обидва. Підпис кнопки кошика, підсумки та кожна панель товару читають кошик, тож кеш щоразу заощаджує звернення до Redis. Позиції можуть мати термін дії, який використовують утримання бронювань, і при читанні відкидаються після спливу. Малюючи кошик, спершу прибирають ID, яких уже немає в локальному каталозі, тож товар, видалений у WooCommerce, не може потрапити в оформлення.

Кнопки кількості поважають quantity_step, min_cart_count і облік залишків, а варіація без власних значень успадковує їх від батьківського товару.

get_buy_buttons_panel() читає комбінацію атрибутів кожної варіації й упорядковує атрибути за порядком атрибутів магазину. Перший рядок перелічує кожен використаний термін; кожен наступний — лише терміни, що разом із вибором вище збігаються принаймні з однією наявною варіацією. Атрибут із трьома чи більше варіантами може відображатися як компактний рядок «попередній / поточний / наступний» замість сітки.

Зміна верхнього атрибута скидає нижні й переходить на першу відповідну комбінацію. Товар відкривається на найдешевшій варіації. Вибір зберігається в контексті на чат і товар, а панель редагується на місці при кожному дотику.

Базові кроки: промокод, адреса доставки, спосіб доставки, спосіб оплати, коментар і підтвердження. Кроки вимкнених розширень видаляються при старті. Потім get_checkout_steps() оглядає кошик, обходячи згруповані товари та варіації їхніх змінних дочірніх, щоб знайти будь-яку фізичну позицію; кошик без неї пропускає обидва кроки доставки. Нульова сума перемикає на подарунковий шлюз і пропускає вибір оплати, магазин з одним шлюзом вибирає його наперед, а оплата в Stars примусово вмикає шлюз Stars.

Обов'язкові кроки блокують next(), доки значення не збережено, а будь-який крок можна знову відкрити в режимі редагування з екрана підтвердження й повернутися одразу до нього.

generate_payment_button() викликає create_order, лише коли в контексті ще немає order_id, потім зберігає ID. Якщо покупець повертається й змінює спосіб оплати, адресу, промокод чи коментар, кожен обробник викликає orders.edit(order_id, ...), тож замовлення WooCommerce правиться, а не дублюється.

Замовлення несе chat_id Telegram і назву бота, тож історія замовлень береться по чату, а посилання «оплатити за мене» може пізніше знайти замовлення.

Слоти приходять із магазину на товар і день з capacity та capacity_used, а слоти, які магазин позначає зарезервованими, відфільтровуються. Коли покупець вибирає слот, рушій записує утримання з терміном дії й додає бронювання в кошик з тим самим часом утримання. is_freezed() рахує активні утримання для цього слота, дати й ключа та блокує слот, коли утримання досягають місткості мінус зайняті місця. Видалення позиції з кошика знімає її утримання через подію done_remove_from_cart.

Календарні дати та фільтрація минулих слотів використовують часовий пояс магазину з налаштувань, а не годинник сервера. Утримання живуть у пам'яті процесу бота, тож діють лише для покупців цього бота й скидаються при перезапуску; бронювання, зроблені на сайті в ту саму мить, не утримуються.

Маркетингові кампанії використовують формули на кшталт 'c >= 6 & c < 12; 25%; 3n, me, cap=3'. parse_formula() розбиває їх на умови за кількістю товарів, відсоткову чи фіксовану знижку й модифікатори (кожна n-та одиниця, спершу найдешевша чи найдорожча, ліміт). get_applied_amount() розгортає кошик у по одному запису на одиницю товарів кампанії, застосовує формули по порядку й позначає використані одиниці, щоб пізніша формула не знижувала їх повторно.

Вікна кампаній перевіряються в часовому поясі магазину, кампанії в тестовому режимі діють лише для чату адміністратора, а знижка кампанії пропускається, коли вже діє купон. Купони, прив'язані до товару, поширюються на дочірні згрупованих і змінних товарів.

Підсумки кошика, знижки та доставка рахуються в базовій валюті. format_price() конвертує у вибрану валюту чату за синхронізованим курсом і застосовує позицію символу та десяткові знаки, округлюючи вгору, коли копійки приховано. generate_payment_button() перераховує суму у вибрану валюту перед викликом шлюзу. Замовлення, отримані з WooCommerce в іншій валюті, діляться на збережений курс замовлення, тож історія й підсумки збігаються з власною арифметикою бота.

Коли магазин не дозволяє платити в інших валютах, на кроці оплати вибір скидається до базової, і покупцеві пояснюють чому.

Stars налаштовуються як валюта з назвою XTR у списку валют магазину, тож їхній курс приходить через ту саму синхронізацію. Сума — це базова сума помножена на курс XTR, округлена вгору. Рахунок надсилається як inputMessageInvoice з порожнім токеном провайдера та JSON-payload у base64, що містить order_id, chat_id, amount і gateway. На pre-checkout запит відповідають, а на messagePaymentSuccessfulBot payload декодується, і магазину повідомляється, що замовлення оплачено.

Без валюти XTR варіант Stars повідомляє про помилку замість рахунку.

Для CryptoBot рушій створює рахунок у фіатній валюті з терміном дії 900 с і опитує getInvoices кожні 8 с. Map таймерів за chat_id тримає одне активне опитування на покупця, а відкриття кошика його скасовує. Після оплати замовлення переходить у processing, а кошик очищається; при простроченні чи скасуванні покупець отримує повідомлення.

CoinGate працює навпаки: його callback URL вказує на проксі Botoscope, який пересилає вебхук на /command як payment_success, і замовлення завершується, коли вебхук повідомляє про оплату.

Кожен шлюз має власний конструктор: Stripe — через Checkout Session, LiqPay — через base64-блоб даних, підписаний SHA-1 над приватним ключем, даними й приватним ключем. Посилання надсилається як кнопка Web App або URL, за бажанням з кнопками політик повернення, конфіденційності та доставки перед нею. Конструктор PayPal (облікові дані клієнта OAuth, потім платіж із URL повернення й скасування) у цьому коді надсилає платіж на кінцеву точку sandbox PayPal, тож працює лише для тестування.

Офлайн-методи (реквізити банківської картки, SWIFT, подарунок, «оплатити за мене») показують перекладені інструкції та кнопку підтвердження замість посилання.

Вибір «оплатити за мене» завершує оформлення посиланням t.me, що запускає бота з payforme_<order_id>. Коли інший користувач його відкриває, рушій завантажує замовлення з магазину, застосовує валюту замовлення, прибирає офлайн-методи й метод «оплатити за мене» та показує решту шлюзів для суми замовлення. Після оплати чат покупця отримує повідомлення з іменем платника.

send_media_gallery() хешує кожен URL медіа, при першому використанні зберігає файл у media_files_cache/<перші два hex-символи>/<hash>, а далі передає TDLib локальний шлях. Файли нульового розміру видаляються й пропускаються, альбом обмежений 8 елементами, а варіація без власних зображень бере медіа батьківського товару.

Посилання на пости t.me оминають кеш і йдуть у TDLib як віддалені файли.

downloadFileToLocal() приймає лише URL http(s) на власному домені клієнта або хостах Telegram, відхиляє розширення виконуваних файлів і скриптів у прямих посиланнях, надсилає запит HEAD, щоб відхилити файли понад ліміт (10 MB для зображень і аудіо, 50 MB для відео та документів), потім передає файл потоком через кінцеву точку fetch-file проксі з тим самим лімітом. Порожні, завеликі та невдалі завантаження видаляються з диска.

Answer стежить за постами каналів. Коли відео з'являється в каналі, де бот є учасником, бот відповідає віддаленим ID файлу цього відео. Посилання на пост t.me або цей ID потім можна використати як медіа товару, і рушій надсилає його як віддалений файл, тож Telegram віддає його зі свого сховища без вивантаження для кожного покупця.

Коли кошик містив товари для завантаження, а замовлення оплачене онлайн або безкоштовне, do_after_pay() надсилає кожне завантаження цих товарів як документ. Файли кешуються під ім'ям, виведеним з ID завантаження через shiftUUID(), тож збережене ім'я — не ID магазину, а документи понад 50 MB відхиляються. Товари з обмеженим доступом показують залишок днів, обчислений від дати оплати замовлення.

PDF-рахунки з кінцевої точки рахунків магазину йдуть тим самим шляхом.

Сім мовних файлів (en, es, pt, ru, pl, kz, ua) з однаковими 215 ключами завантажуються при старті. __() зливає мовний файл чату з перевизначеннями, які власник ввів в адмінці (синхронізуються як interface_translations та індексуються як s<number>); якщо ключа все ще немає, повторює спробу з англійською плюс перевизначення. Вибрана мова зберігається на чат; при першому контакті вона береться з language_code клієнта Telegram, якщо ця мова ввімкнена, інакше — зі значення магазину за замовчуванням.

Оскільки кнопки меню зіставляються за їхнім локалізованим текстом, підписи для чату розв'язуються паралельно через Promise.all при кожній перевірці маршрутизації.

Товари, категорії, бренди, meta-поля, способи доставки й оплати несуть об'єкт translations. translate_to() повертає 0, коли чат використовує мову за замовчуванням, тож у типовому випадку всі пошуки пропускаються; інакше get_field_translation() вибирає перекладене поле й повертається до оригіналу. Пошук за заголовком виконує LIKE і по колонці title, і по збереженому JSON перекладів із мінімумом 3 символи, тож запит будь-якою активною мовою знаходить товар.

Дати в meta товарів і періоди доступу форматуються з мовою чату як локаллю.