Жизненный цикл документа

Интеграция строится вокруг сеанса, команд, ревизий и событий, а не вокруг прямого доступа к внутренней разметке редактора.

1. Ваше приложение получает документ. Ваша система проверяет пользователя и передаёт байты разрешённого DOCX либо безопасный путь к файлу.

2. A4 открывает сеанс. Ядро разбирает файл, строит основную модель документа, профиль доступных возможностей и первую ревизию.

3. Поверхность показывает документ. Пользователь видит страницы и доступные команды, а ваше приложение получает событие готовности.

4. Приходит намерение. Команда несёт тип операции, устойчивую ссылку на место в документе и ожидаемую ревизию; оболочка сама разметку не правит.

5. Ядро применяет или отклоняет. При успехе появляется новая ревизия и признак несохранённых изменений. Отказ не оставляет документ изменённым наполовину.

6. Ваше приложение сохраняет результат. Ядро записывает изменения в файл и отдаёт DOCX, а вы заводите версию и запись в журнале.

7. Повторное открытие подтверждает. Сохранённый файл открывается заново в новом процессе — это доказывает, что изменение дошло до диска, а не осталось на экране.

Основные объекты API

Объект	Назначение
Сеанс	Изолированный жизненный цикл одного открытого документа.
Команда, или намерение	Типизированное действие: что сделать, с чем и при какой ожидаемой ревизии.
Конверт результата	Успех, предупреждения, явный отказ с причиной, диагностика и идентификатор, по которому ответ связан с запросом.
Событие	Готовность, несохранённые изменения, сохранение, ошибка и прочие смены состояния.
Профиль возможностей	Перечень доступных команд и ограничений — без умолчаний.
Артефакт	Байты DOCX, контрольная точка или диагностика — всё, чем распоряжается ваше приложение.

Как публикуется результат

Сохранение не пишет поверх существующего файла: сначала создаётся временный файл рядом с целевым, содержимое сбрасывается на диск, и только потом временный файл атомарно занимает место цели. Поэтому оборванное сохранение не оставляет наполовину записанный DOCX — на диске либо прежняя версия, либо новая целиком.

Для вашего приложения это значит: появление файла по нужному пути уже само по себе признак завершённой записи — ждать и проверять размер не нужно.

Сохранение контрольной точкой делает ещё один шаг: перед публикацией оно сверяет файл с тем состоянием, которое видело ваше приложение, и отказывает, если его успели изменить снаружи — другой программой, вторым сеансом или синхронизацией. Чужая правка не затирается молча.

Дальше

• Как устроены запросы и ответы — Объекты запросов и ответов.
• Что продукт делает с документом — карта возможностей.
• Границы сегодня — Готовность и границы.