Глоссарий

Термины, которые встречаются во всех разделах документации.

Термин	Значение
Ядро A4, ядро на Rust	Часть на Rust, которая владеет документом: разбирает файл DOCX, держит модель документа, считает вёрстку и записывает изменения обратно в файл.
Ядро F1, ядро на Rust	Часть на Rust, которая владеет книгой: формулы, разрежённое хранение ячеек, история изменений и запись файла. Второго владельца нет — интерфейс только показывает и просит.
Поверхность редактора, Web Surface	Готовый пользовательский интерфейс, который размещают в окне браузера, в окне просмотра веб-страниц внутри приложения или в своём контейнере. На страницах A4 встречается под обоими именами: заголовки разделов называют его Web Surface, текст — поверхностью.
Surface Host, служба поверхности	Небольшая программа, которая отдаёт файлы этой поверхности и держит один сеанс документа. Слушает только локальный адрес — снаружи к ней не подключиться. Запускается на той же машине, где открыт документ.
fastdoc, fastsheet в именах	Внутренние имена движков: fastdoc — документного, fastsheet — табличного. Встречаются в названиях схем и событий, в переменных оформления и в имени объекта в окне браузера. Это не отдельные продукты: так назывались A4 и F1 до переименования, а имена в коде остались прежними — их смена сломала бы совместимость у тех, кто уже встроил редактор.
Ваше приложение, приложение-хост	Приложение, в которое встраивается редактор. Ему принадлежат бренд, пользовательский путь, вход, хранилище и рабочие процессы.
Адаптер к приложению	Ваш код между вашим приложением и редактором: запускает процесс ядра, читает параметры подключения, передаёт команды и разбирает ответы. Пишется под ваш язык и вашу среду; разметку документа он не разбирает и своей копии файла не держит.
Evaluation Kit, комплект для оценки	Собранный набор для первой пробы: примеры, образцы документов, сквозной путь на настоящем файле и заранее известный правильный результат каждого шага. Даётся, чтобы ваш инженер открыл свой документ за час, не собирая ничего сам.
Мэшап, mashup	Набор запросов Power Query, который хранится внутри книги: сами запросы, их группы, подключения к источникам и связи с листами. «Чужим» он называется, когда собран не в F1, а в Excel: такой набор F1 читает, обновляет и записывает обратно, не теряя того, чего не понимает.
DTO, объект передачи данных	Описание того, из каких полей состоит запрос или ответ: какие поля есть, какого они типа и какие обязательны. Не команда и не действие, а форма сообщения — по ней ваш код собирает запрос и разбирает ответ.
OEM, встраивание под своей маркой	Поставка, при которой ваш продукт включает чужой редактор как свою часть: пользователь видит ваш интерфейс и ваше имя, а не наше. Отсюда «OEM-профиль» — набор событий и настроек, нужный именно такой поставке.
Дымовой прогон	Короткая автоматическая проверка, что собранная программа вообще запускается и открывает документ. Она не проверяет функции по отдельности — только что дым не пошёл. В справочнике такие маршруты помечены отдельно: во встраивании они не нужны.
LTS, длительная поддержка	Версия, которую поддерживают дольше обычного: для неё выпускают исправления и обновления безопасности оговорённый срок, а не до следующего выпуска.
Единый вход, SSO	Вход в редактор той же учётной записью, которой пользователь уже вошёл в ваш продукт: отдельной пары имени и пароля у редактора нет. Проверяет пользователя ваша система, редактор получает от неё только проекцию учётной записи — кто это, какая роль и что ему разрешено.
Контракт сеанса, Rust Session Protocol	Узкая граница между вашим приложением и редактором: какие команды можно отправлять, какие события приходят, как живёт сеанс и что вообще доступно. У неё есть версия, и она меняется не молча. Все 28 команд перечислены в справочнике.
Сеанс JSONL	Самый простой способ обратиться к ядру: процессор запускается и обменивается с вашей программой строками — один запрос JSON в строке, один ответ JSON в строке. Буква L в названии и значит «строка»: каждая строка — законченный JSON, а не кусок общего.
Стандартный ввод и вывод, stdin и stdout	Два потока, через которые запущенная программа получает данные и отвечает. Ими и пользуется сеанс JSONL: своего сетевого порта ему не нужно.
Пропуск, токен	Случайная строка, которую процессор создаёт при запуске и без которой к его порту не подключиться: соединение без пропуска или с чужим отклоняется. Живёт, пока работает процесс, и на следующем запуске будет другой. В адресах и в полях запроса он называется token — на страницах это тот же пропуск.
Локальный адрес, 127.0.0.1	Адрес самой машины. Соединение по нему не выходит за её пределы: снаружи, даже из своей сети, к такому порту подключиться нельзя.
Точка применения политик	Заранее известный момент, в который редактор спрашивает ваше приложение, можно ли продолжать: перед выполнением команды, перед сохранением, перед выдачей данных наружу. Правила остаются вашими — редактор не хранит их у себя, а только даёт место, где ваш ответ будет учтён.
Агент	Программа, которая работает с документом вместо человека: сама читает его, предлагает правку и применяет её. От макроса отличается дорогой: агент ходит тем же контрактом, что и интерфейс, поэтому его действия видны, проверяемы и отменяемы. Щёлкать по кнопкам и править файл в обход редактора он не может.
Контракт операций, Compute Contract	Типизированная граница F1: через неё к ядру обращаются и интерфейс, и автоматизация, и адаптеры к чужим приложениям. Другого пути к книге нет. Все 203 операции — в справочнике.
Профиль возможностей	Именованный набор того, что входит в конкретную поставку: функции, платформы, форматы, операции и ограничения. Именно он, а не общие слова, определяет обещание.
Матрица возможностей	Таблица, где каждая возможность проверена по клеткам: формат, среда выполнения, действие, сохранность разметки и ограничения. Профиль отвечает на вопрос «что входит в поставку», матрица — «что из этого проверено и на чём».
Явный отказ	Отказ с кодом и причиной, приходящий до того, как документ изменится. Противоположность двум худшим исходам: когда операция молча не сработала и когда файл изменился наполовину. Где искать этот код, зависит от вызова: у правки документа он приходит полем ответа, а не признаком успеха в конверте — как читать ответ.
Сохранность неподдержанного	Части файла, которые редактор не понимает, переносятся в сохранённый файл без изменений — либо честно помечаются. Именно это отличает редактор от преобразователя, который теряет всё незнакомое.
Поставка под своим брендом	Редактор выходит под вашим названием, в вашем интерфейсе и внутри ваших процессов. Ядро при этом не раздваивается: настраивается оболочка, а не смысл документа.
В описанных границах	Перечислено ровно то, что сделано и проверено; остальное не обещается. За границей возможность отказывает предсказуемо — с понятной причиной, а не ломается.
Сеанс книги, subset, subsetId	Сеанс работы с книгой в F1. Открывается операцией open_workbook_subset и возвращает subsetId — идентификатор, который передают все последующие операции над этой книгой. Ядро держит в памяти не весь файл, а то, что нужно для текущего окна просмотра, отсюда и название. Закрывается операцией close_workbook_subset.
Viewport, окно просмотра	Прямоугольное окно листа, для которого ядро отдаёт данные: левый верхний угол (top, left) и размер в строках и столбцах (rows, cols). Индексы нулевые: первая строка — 0. Окно можно сдвинуть операцией synchronize_workbook_viewport, это не правка и в историю не попадает.
Ревизия, revision, expectedRevision	Номер состояния книги. Он растёт с каждой правкой, и вызывающий может передать в запросе тот номер, который видел последним. Если книга с тех пор изменилась, запрос отклоняется до того, как книга изменится, а не наполовину. Это защита от гонки, когда книгу правят из двух мест одновременно. В F1 поле необязательное: без него правка применяется безусловно — см. Как устроен сеанс API.
Power Query, M-выражение	Механизм получения и преобразования данных из внешних источников: запрос описывается на языке формул M и состоит из применённых шагов (applied steps), каждый из которых преобразует результат предыдущего. Совместим с одноимённым механизмом Microsoft Excel.
Mashup, набор запросов	Описание запросов Power Query в формате Microsoft, хранящееся внутри файла книги. «Внешним» (foreign) оно называется, когда создано не продуктом, а сторонним приложением: такие описания F1 читает, обновляет и записывает обратно, сохраняя то, что не понимает.
Writeback, обратная запись	Перенос изменений из внутренней модели документа обратно в файл формата — DOCX или XLSX. Части файла, которых правка не касалась, переносятся без изменений; за это отвечает preservation. Обратная запись принадлежит ядру: интерфейс не правит файл напрямую.
Projection, проекция	Ограниченный срез состояния, который ядро отдаёт интерфейсу: не весь документ или книга, а ровно то, что нужно для текущего окна просмотра или запроса. Благодаря этому большой файл не обязан целиком превращаться в DOM или объекты JavaScript.
Sparse workbook state, разрежённое хранение	Разрежённое хранение книги: в памяти держатся только заполненные ячейки и заданные форматы, а не полная матрица листа. Лист с миллионом строк не занимает память под пустые строки. Открытие тоже разрежённое — сначала загружается активный лист.
Headless, работа без интерфейса	Режим работы ядра без пользовательского интерфейса: команды приходят по контракту, ответом становятся данные или готовый файл. Так ядро используют на сервере и в пакетной обработке.
Dirty, есть несохранённые изменения	Состояние сеанса, когда в документе есть изменения, которых нет в сохранённом файле. В A4 признак вычисляется сравнением: хеш текущей модели отличается от хеша последнего сохранённого состояния. Хост обычно показывает это пользователю и спрашивает подтверждение перед закрытием окна.
Cold reopen, повторное открытие с нуля	Повторное открытие сохранённого файла заново — как правило, новым процессом, без опоры на состояние в памяти. Так проверяют, что в файл действительно попало то, что показывал редактор: правка, история, форматирование и неподдерживаемые части документа.
Acceptance, приёмка	Заранее согласованный набор документов и действий, на котором проверяется работа интеграции. Смысл в том, чтобы обещание совместимости было проверяемым: не «поддерживаем DOCX», а «на этих файлах эти операции дают такой результат».
Privacy level, уровень приватности	Уровень приватности источника данных в Power Query. Он ограничивает, данные каких источников можно смешивать в одном запросе, чтобы значения из закрытого источника не утекли в запрос к внешнему.