summarum/ARCHITECTURE.ru.md

# Архитектура

[English](ARCHITECTURE.md)

Приложение состоит из двух частей: **движок вычислений на TypeScript + UI** в WebView2
и тонкая **оболочка на Rust** (Tauri 2) для всего, что касается ОС.

```
src/
  engine/          сам калькулятор (чистый TS, без DOM)
    lexer.ts         строка → сырые лексемы (числа, слова, символы)
    vocab-data.ts    таблицы слов en+ru: единицы, валюты, операторы
    vocab.ts         объединённый поиск по таблицам
    unitdata.ts      коэффициенты конвертации (базовые единицы на измерение)
    extraunits.ts    скорость/давление/энергия/мощность/частота/топливо + крипто
    registry.ts      фраза → токен; строится один раз при запуске
    tokenizer.ts     лексемы + реестр → семантические токены
    parser.ts        токены → AST (Pratt-парсер, терпимый к «мусору»)
    evaluator.ts     AST + контекст документа → значения с единицами
    formatter.ts     значения → строки для отображения
    datetime.ts      карта часовых поясов, календарная арифметика
    index.ts         фасад SumEngine + API расширений + итоги листа
  ui/
    editor.ts        обвязка CodeMirror 6: подсветка, оверлей результатов, копирование
    search.ts        оверлей поиска по всем листам (текст + запросы по значению)
    export.ts        рендерит лист + результаты в PNG (буфер обмена/файл)
    app.css          темы (светлая/тёмная через CSS-переменные)
  main.ts            запуск приложения: документы, настройки, строка статуса, dnd
  storage.ts         команды Tauri / запасной вариант на localStorage
  extensions.ts      запускает пользовательские .js-файлы в песочнице
                     QuickJS/WASM, мост к API numi.* движка
  i18n.ts            строки интерфейса (en/ru)
  updater.ts         проверка tauri-plugin-updater, установка + перезапуск
src-tauri/
  src/main.rs        трей, скрытие в трей, команды хранилища, загрузка курсов
                     (open.er-api.com + CoinGecko + Yahoo Finance v8 chart)
                     с кэшем, исторические курсы (frankfurter.dev, постоянный
                     кэш на каждую дату), резервные копии, миграция папки
                     данных, открытие файлов, регистрация плагинов (autostart,
                     global-shortcut, single-instance, opener, dialog,
                     updater, process)
```

## Как строка превращается в результат

1. **Lexer** разбивает `"5 дюймов в см"` на лексемы: `5`, `дюймов`, `в`, `см`.
   Тот же lexer сегментирует фразы из словаря, чтобы совпадение было последовательным.
2. **Registry** хранит все фразы, которые понимает движок, по первой лексеме.
   Побеждает наиболее длинное совпадение; регистрозависимые записи (`m` vs `M`, `kB`)
   проверяются раньше регистронезависимых, а неоднозначная нижняя форма (`mm` vs `Mm`)
   просто не получает нечувствительный к регистру запасной вариант.
3. **Tokenizer** проходит по лексемам, спрашивает реестр и выдаёт типизированные токены.
   Несколько контекстных хаков: например, `in` сразу после числа в конце строки
   означает дюймы (`6 ft 3 in`).
4. **Parser** — Pratt-парсер, терпимый к шуму: неизвестные слова отбрасываются
   до разбора (поэтому `потратил 20 на пиццу плюс 5` работает) — кроме слов
   сразу после оператора конвертации, которые могут называть часовой пояс.
   Приоритет от наименьшего к наибольшему: конвертации на уровне строки →
   поразрядные → аддитивные → мультипликативные (включая `20% от x`) →
   унарные → постфиксные (единицы, `%`, `!`, `^`) → первичные.
5. **Evaluator** вычисляет тройки `{ value: Decimal, unit }`. Операнды одного
   измерения конвертируются через базовые единицы (`toBase`/`fromBase`);
   температуры несут смещение, единицы расхода топлива могут быть обратными
   (mpg ↔ л/100км). Контекст документа предоставляет переменные и результаты
   предыдущих строк для `сумма`/`avg`/`prev`.
6. **Formatter** отображает значение в формате единицы, с точностью и группировкой
   из настроек, или в hex/binary/дроби/римских цифрах и т.д.

Числа — `decimal.js` везде, никаких артефактов двоичной арифметики.

## Как добавлять вещи

**Единицу** — добавь строку в `UNIT_DATA` в `unitdata.ts` (id, измерение, коэффициент
к базовой единице измерения) и её названия в `vocab-data.ts` в соответствующей
категории (`"myunit.variants": "name,names,имя"`, `"myunit.format": "sym"`).
Для совершенно нового измерения расширь объединение `Dimension` в `types.ts`
и используй `extraunits.ts` — фразы живут прямо там.

**Валюту** — фиатные коды берутся из таблицы `Currency` в `vocab-data.ts`;
крипто идёт в `CRYPTO` в `extraunits.ts` (код, id CoinGecko, фразы, снимок цены)
плюс зеркальный список в `src-tauri/src/main.rs`.

**Оператор/функцию** — зарегистрируй фразу в `buildRegistry()` (`registry.ts`),
добавь токен/узел AST если нужен новый синтаксис, реализуй в `evaluator.ts`.
Большинство слов-операторов — это данные, а не код.

**Город часового пояса** — одна строка в карте `Z` в `datetime.ts`.

## Подводные камни движка

- Конфликты фраз реальны: одиночные буквы регистрозависимы по замыслу
  (`m` метр / `M` миллион, `k` тысяча / `K` кельвин). Генерация префиксов
  фильтруется там, где пересекается со словами — например, секунды получают
  только ms/µs/ns/ps, потому что символ «аттосекунды» затенил бы слово `as`.
- `и`/`или` двойного назначения: `и` складывает (`5 и 3` = 8), `или` — побитовое.
  `от/без/на` работают только с процентом в левой части; иначе это просто текст.
  Тот же токен `на` используется как разделитель даты для исторических курсов
  (`в EUR на 2024-01-01`) — `parseSeq` проверяет `pctop(on)` + `datelit`
  сразу после цели конвертации валюты и поглощает оба при совпадении.
- Курсы валют — «единиц за 1 USD»; соотношение единицы валюты вычисляется при
  вычислении из текущей карты курсов, поэтому обновление курсов пересчитывает
  всё при следующей оценке. Исторические курсы живут отдельно в
  `historicalRates: Map<date, Map<code, number>>` на `SumEngine` и передаются
  через `EvalCtx` в `evalConv`.
- Живые рыночные данные (акции, сырьё через Yahoo Finance) объединяются в ту же
  карту курсов через `applyAllRates()` в `main.ts`, чтобы один вызов `setRates()`
  не перезаписывал другой.
- Поиск неизвестного (`? * 1.2 = 1000`): `?` токенизируется как `{ t: "unknown" }`,
  разбирается в узел `{ k: "unknown" }`. `parseLine` обнаруживает `unknown` + `assign`
  и строит `{ k: "goalseek", lhs, rhs }`. Решатель пробует линейный метод (f(0),
  f(1) → точный корень для аффинных выражений) и переходит к бисекции для нелинейных.
- `ChartValue` (`kind: "chart"`) возвращается из `evalAgg("chart", …)` и
  минует `formatValue` — оверлей результатов рисует SVG-спарклайн вместо текста.
- Реестр не пересобирается никогда; расширения мутируют его (добавляют фразы/функции)
  при запуске. `buildRegistry()` (`registry.ts`) — тонкий оркестратор над
  `registerCoreVocab` / `registerUnits` / `registerAreaVolume` /
  `registerCurrencies` / `registerExtraUnits` / `registerCrypto` /
  `registerCompletions` — **порядок вызовов важен**: `Registry.addPhrase`
  оставляет *первую* регистрацию одинаковой фразы и отбрасывает последующие
  (базовый словарь обязан побеждать фразы единиц/валют, если они случайно
  совпадают).
- Умножение двух величин одного измерения (`2 kg * 500 g`) конвертирует
  правый операнд в единицу левого перед умножением, чтобы результат имел
  осмысленную единицу (`1 kg`, а не `1000` в подписи `kg`). Умножение разных
  измерений (`$12 * 3`, `5 hours * 2`) не затронуто — там правая часть
  трактуется как простой числовой множитель.
- `//` начинает комментарий только в начале строки или после пробела
  (`findCommentStart` в `index.ts`), поэтому URL вида `see https://example.com`
  не обрезается на двойном слэше.
- **Литералы и форматы дат.** Помимо ISO (`2024-01-01`), лексер понимает
  `D.M.YYYY` / `M/D/YYYY` (`31.12.2024`, `12/31/2024`) с одинаковым
  разделителем с обеих сторон и 4-значным годом. Порядок день/месяц
  разрешается для каждого литерала отдельно: компонент `>12` однозначно
  определяет, где день; если оба `≤12`, решает настройка движка `dateFormat`.
  Все три формы литералов отклоняют компоненты вне диапазона через
  round-trip проверку (`validDateMs` в `lexer.ts` — `new Date(y, mo-1, d)`
  молча *перекатывает* невалидные даты вроде `2026-13-45` вместо ошибки,
  поэтому построенные год/месяц/день сравниваются обратно со входом).
  `SumEngine` разрешает `dateFormat: "system"` в реальный порядок день/месяц
  один раз через `detectDateOrder()` (`datetime.ts`, пробует
  `Intl.DateTimeFormat` на фикстуре `2000-12-31`) и передаёт его в
  `tokenize()` → `lexLine()` при каждом вызове; настройки `"dmy"`/`"mdy"`
  пропускают детекцию. Отображение работает так же в обратную сторону:
  `formatter.ts` либо использует форматирование `Intl` по локали ОС
  (`"system"`), либо строит фиксированную строку `YYYY-MM-DD` / `DD.MM.YYYY` /
  `MM/DD/YYYY` через `Intl.DateTimeFormat(...).formatToParts()` (это нужно,
  чтобы уважать собственный IANA-часовой пояс значения, чего форматтер на
  основе голого `ms` сделать не может). Экземпляры `Intl.DateTimeFormat`
  кэшируются по ключу опций в `formatter.ts` (`dtf()`), так как их создание
  сравнительно дорого, а каждая строка с датой пересобирает формат при
  каждой отрисовке.
- У разбора названий часовых поясов (`time in Europe/Berlin`) есть две
  независимые ловушки. Во-первых, шумовой фильтр `parseLine` оставляет
  word-токены только сразу после `conv`-токена (`in`/`as`/...); любой другой
  тип токена сбрасывает это состояние — голый `/` между двумя словами
  часового пояса обычно отбросил бы второе слово раньше, чем его увидит
  парсер, поэтому фильтр отдельно разрешает `/`, встреченный при сборе
  post-conv слов. Во-вторых, цикл сбора слов в `parseTarget()` зеркалит то же
  исключение, чтобы продолжать читать после `/`, а не останавливаться на
  первом слове. Нужны оба места — исправление только одного всё равно
  урезает `Europe/Berlin` до `Europe`.

## Ссылки между листами

`@Sheet.key` лексится напрямую в `lexer.ts` (не через реестр фраз — названия
листов это произвольный текст пользователя, а не словарь), давая лексему
`xref` с `{ sheet, key }`. Движок умеет только *спросить* значение:
`EvalCtx.resolveXRef?.(sheet, key)` возвращает
`{ ok: true; value } | { ok: false; reason }`; без резолвера (тесты,
расширения, `evaluateExpression`) ссылка просто не резолвится. Нерешённые
ссылки бросают `XRefError` внутри, он ловится в `SumEngine.evaluateDocument`
и превращается в `LineResult.error` (рисуется как `#ref?` в колонке
результатов) — все прочие ошибки вычисления по-прежнему тихо дают пустую
строку, это не изменилось.

Движок не знает про "другие листы" — это целиком живёт в `src/workspace.ts`.
`Workspace` читает тексты всех листов из `data.contents` приложения,
кэширует экспорт каждого листа (его присвоенные переменные, `total`, `last`)
после первого вычисления, и сбрасывает кэш листа плюс всех его транзитивных
зависимых (находятся сканированием текста на `@Name.`) при правке листа или
обновлении курсов. `Workspace.evaluateSheet(id, text)` кладёт `id` в стек
резолвинга на всё время вызова, поэтому лист, ссылающийся сам на себя —
напрямую или через другой лист — сразу натыкается на проверку "уже в
стеке" и получает `circular reference` вместо бесконечной рекурсии.

## Особенности UI

- CodeMirror встраивает свою базовую тему во время выполнения *после* `app.css`,
  поэтому всё, что должно побеждать (отступ контента для колонки результатов,
  цвет курсора), живёт в расширении `EditorView.theme(...)`, а не в стилях.
- Колонка результатов — абсолютно позиционированный оверлей; каждый результат
  размещается по координатам `view.lineBlockAt(...)` и перерисовывается при
  прокрутке/изменении геометрии. Клик для копирования читает `data-value`.
- Оценка движка синхронная на каждое нажатие клавиши — полный разбор листа
  занимает менее миллисекунды, поэтому нет дебаунса и воркеров.
- Поиск по всем листам (`Ctrl+F`) — простое построчное сканирование текста
  каждого открытого листа, а не расширение поиска CodeMirror — ему нужно
  пересекать документы, поэтому он не трогает активный редактор, пока не
  кликнут результат (`editor.goToLine`). Живёт в `src/ui/search.ts`
  (`initSearch()`), который владеет DOM `#search-overlay` и собственным
  дебаунсом ввода на 150 мс — запрос по значению (`>1000`) пересчитывает
  каждый открытый лист, так что дебаунс важен, как только листов становится
  больше пары.
- Поповер настроек разбит на четыре вкладки (Общие / Формат / Данные /
  Обновления) в `index.html`, каждая — `.settings-tabpanel`, переключаемая
  кнопкой `#settings-tabs .tab` в `bindSettingsUI()` (`main.ts`) — обычный
  `classList.toggle`, без роутера. Стиль вкладок повторяет идиому сайдбара
  `doc-item.active` (`background: var(--sel)` для активной таблетки) вместо
  нового визуального паттерна.

## Хранилище

- `settings.json` всегда находится в `%APPDATA%/app.summarum.calc`.
- `documents.json` (все листы) + `backups/` живут либо там, либо в папке данных,
  выбранной пользователем (путь хранится в настройках).
- Ежедневный снимок при запуске (`backups/documents-YYYY-MM-DD.json`, хранится 14);
  удалённые листы становятся `.numi`-файлами в `backups/deleted/` и удаляются по возрасту.
  Сохранение откладывается на 400 мс.

## Платформы и упаковка

- Одна кодовая база, три десктопных платформы. Всё общее лежит в
  `tauri.conf.json`, платформенные куски — в `tauri.windows.conf.json`,
  `tauri.linux.conf.json` и `tauri.macos.conf.json`, которые Tauri накладывает
  поверх базового конфига (JSON Merge Patch) в зависимости от собираемой цели.
  Каждый задаёт только `bundle.targets` и опции своего упаковщика: NSIS на
  Windows, deb/rpm/AppImage на Linux, .app/.dmg на macOS.
- `release.yml` собирает пять артефактов на трёх видах раннеров: Windows x64 и
  arm64, Linux x64 (`ubuntu-22.04` — самый старый раннер с webkit2gtk-4.1, что
  держит планку glibc низко), macOS arm64 и x64. Две отдельные macOS-цели вместо
  `universal-apple-darwin`: так же, как Windows уже собирается по архитектурам,
  вдвое меньше вес загрузки, и апдейтер получает ключи `darwin-aarch64` /
  `darwin-x86_64`, которые ищет по умолчанию.
- Вся матрица остаётся `max-parallel: 1`. Все джобы отдают артефакты в *один и
  тот же* объект GitHub Release, а проверка find-or-create в tauri-action гонит,
  если две джобы доходят до неё одновременно — добавление платформ это
  ограничение не сняло, а распространило на большее число джоб.
- Подписи ОС нет нигде. Windows выходит неподписанным; macOS подписан *ad-hoc*
  (`bundle.macOS.signingIdentity: "-"`) — сертификат Apple для этого не нужен, но
  без него Apple Silicon вообще откажется запускать скачанный бинарник (сочтёт
  повреждённым, а не просто предупредит). Gatekeeper в любом случае попросит
  пользователя разрешить приложение при первом запуске.
- `bundle.fileAssociations` покрывает `.numi`/`.sum` на Windows (записи в реестр
  из NSIS) и macOS (`CFBundleDocumentTypes`). На Linux он не даёт ничего
  полезного: там для регистрации расширения нужен ещё XML для shared-mime-info,
  который Tauri не генерирует, так что `.numi` открываются перетаскиванием в
  окно, а не из файлового менеджера.
- `icons/icon.icns` создаёт `scripts/gen-icon.ts` рядом с PNG и `.ico`, вручную
  и без зависимостей: магия `icns` + общая длина, дальше по чанку
  `[OSType][длина][PNG]` на размер, с современными PNG-тегами, которые выдаёт
  `iconutil` (`icp4`/`icp5`, `ic07`–`ic14`). После правки картинки перегенерить
  через `npm run icons`.

## Автообновление

- `updater.ts` вызывает `check()` из `tauri-plugin-updater` при запуске; если
  подписанное обновление доступно, пользователю предлагают установить, затем
  `downloadAndInstall()` + `relaunch()` из `tauri-plugin-process`.
  `checkForUpdate()` возвращает `AvailableUpdate | null | "error"` — `null`
  значит проверка прошла успешно и ничего новее нет, `"error"` значит сама
  проверка не удалась (офлайн, рассинхрон подписи и т.п.); различие важно
  только для ручного пути ниже. Теперь виден любой исход: сбои через
  `console.warn`, а успешный результат «нет обновления» логирует текущую
  версию рядом с «это последний опубликованный релиз» через `console.info` —
  самый частый ложный сигнал тревоги это когда установленная сборка И ЕСТЬ
  последний релиз (например, сразу после его установки), что раньше было
  неотличимо от молча сломанной проверки.
- Закрытие окна прячет его в трей вместо завершения процесса (см.
  `on_window_event` в `main.rs`), поэтому проверка только при старте может
  долго оставаться незамеченной на машине, которую редко перезагружают.
  `main.ts` также перезапускает `checkUpdate()` через `setInterval` (каждые
  6 часов), чтобы долгоживущий трей-процесс всё равно замечал новые релизы,
  а в настройках (вкладка «Обновления») есть кнопка «Проверить обновления»
  (`checkUpdate(true)`), которая сообщает «последняя версия» / «не удалось
  проверить» через toast — эти уведомления подавлены на автоматических
  фоновых проверках, чтобы приложение не напоминало о себе каждые несколько
  часов. Тумблер `SettingsData.autoUpdateEnabled` отключает и проверку при
  запуске, и периодическую (значение перечитывается из `settings` на каждом
  тике интервала, так что переключение прямо во время работы срабатывает
  сразу); ручная кнопка тумблер игнорирует и работает всегда.
- Эндпоинт обновлений — `latest.json`, публикуемый вместе с каждым GitHub
  Release. `release.yml` подписывает артефакт обновления каждой платформы парой
  ключей minisign (это собственная подпись обновлений Tauri, к подписи кода в ОС
  отношения не имеет):
  публичная половина зашита в `tauri.conf.json`; приватная половина + пароль
  живут только как секреты репозитория `TAURI_SIGNING_PRIVATE_KEY(_PASSWORD)`
  (write-only — в репозитории нет постоянной копии). Потеря этого ключа
  означает, что уже установленные копии никогда больше не смогут доверять
  будущему подписанному релизу.

## Хранилище (кэш-файлы)

Все файлы ниже живут в `%APPDATA%/app.summarum.calc` (или в папке данных пользователя):

| Файл | Содержимое | TTL |
|------|-----------|-----|
| `settings.json` | настройки | постоянно |
| `documents.json` | все листы | постоянно (дебаунс 400 мс) |
| `rates.json` | живые курсы валют (open.er-api.com + CoinGecko) | 1 час |
| `market.json` | котировки акций/сырья (Yahoo Finance v8 chart, по запросу на символ) | 15 минут |
| `rates-YYYY-MM-DD.json` | исторические курсы ЕЦБ за одну дату (frankfurter.dev) | навсегда |
| `backups/documents-YYYY-MM-DD.json` | ежедневные снимки | 14 дней |
| `backups/deleted/*.numi` | мягко удалённые листы | настраивается |

## Тесты

`npm test` запускает 259 vitest-кейсов: `src/engine/*.test.ts` покрывает все
классы выражений, оба языка, детерминированные инжектированные курсы, поиск
неизвестного, исторические курсы (инжектированные), литералы и отображение
форматов дат (отдельные движки с явным `dateFormat` — формат «system» по
умолчанию зависит от локали машины CI), плюс набор регрессий по всем известным
исправленным багам; `src/workspace.test.ts` покрывает межлистовые ссылки,
кэширование и обнаружение циклов. UI проверяется вручную; движок — там где
живёт вся сложность.