Expand AppVersionTrack documentation with guidelines for adding new app versions.

android/dushanbe/AppVersionTrack.h

@@ -13,6 +13,39 @@ namespace Dushanbe {
 // На момент введения каркаса форматы 3.2.33 и 3.2.38 практически идентичны,
 // поэтому отдельных веток ещё нет — трек служит явным швом для будущих
 // расхождений и читаемым маркером в логах/дампах.
+//
+// ─────────────────────────────────────────────────────────────────────────
+// КАК ДОБАВЛЯТЬ НОВУЮ ВЕРСИЮ ПРИЛОЖЕНИЯ
+// ─────────────────────────────────────────────────────────────────────────
+// Отдельные скрипты на каждую версию НЕ нужны — по умолчанию все версии
+// обслуживает один общий комплект скриптов. Выбирайте по объёму изменений:
+//
+// 1) Формат экранов не изменился (типичный апдейт банка — косметика,
+//    переименование полей в той же структуре).
+//    → НИЧЕГО не делаем. Новая версия новее последнего порога и автоматически
+//      трактуется как новейший трек (см. trackForVersion). Можно опционально
+//      завести эталонные дампы в assets/dushanbe/<версия>/ для сверки.
+//
+// 2) Изменился один-два экрана.
+//    → Добавляем новый элемент в enum (например V3_2_45) и НОВЫЙ порог в
+//      trackForVersion(). Затем в методе, который парсит изменившийся экран,
+//      ставим точечную ветку:
+//          if (m_track >= AppVersionTrack::V3_2_45) { …новый формат… }
+//          else                                     { …существующий…   }
+//      Скрипты остаются ОБЩИМИ. Старые ветки (Legacy/3.2.33) не удаляем —
+//      на устройствах в поле могут оставаться старые версии.
+//      Версионно-зависимые точки сегодня: ScreenXmlParser (профиль/боковое
+//      меню, label-value пары), GetLastTransactionsScript (детали транзакции),
+//      PayBy{Card,Phone}Script (чек «Платеж выполнен»).
+//
+// 3) Версия разошлась радикально (другой флоу, другие экраны почти везде) —
+//    КРАЙНИЙ случай.
+//    → Только тогда выносим версию в отдельный класс скрипта и выбираем его
+//      по треку в EventHandler::startThreadForTask(). Точка ветвления по
+//      версии уже есть (app.appVersion → trackForVersion), переход дешёвый.
+//
+// Значения enum упорядочены по возрастанию версии — можно сравнивать через
+// <, <=, >, >= (например `m_track >= V3_2_38`).
 enum class AppVersionTrack {
     Legacy,   // < 3.2.33 — старый blob-формат (один content-desc с "Версия:"/"Сборка:")
     V3_2_33,  // 3.2.33 .. < 3.2.38