Диагностика и контрольный список

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

Если первый запуск не идёт, найдите симптом в таблице: рядом с ним — что именно проверить.

Симптом	Что проверить
Приложение не найдено	Путь установки: `/Applications/A4.app` на macOS, `C:\Program Files\A4` на Windows (каталог можно было сменить при установке), `/opt/A4` на Linux — если ставили пакетом `deb` или `rpm`. У поставки `AppImage` каталога установки нет: файлы лежат внутри самого образа, и достать их можно распаковкой — `./A4-….AppImage --appimage-extract`, дальше `squashfs-root/resources/`. Проверьте также, что скачана сборка под вашу архитектуру
Процессор не запускается	Пакет приложения повреждён или скопирован не полностью. На macOS и Linux проверьте, что у файла есть право на запуск
В ответе `ok: false`	Прочитайте поля `error`, `cmd` и `id`: в них сказано, какая команда отклонена и почему. Проверьте путь к файлу и поля операции
Файл не изменился	Сохраняете ли вы в новый путь; что показывают ревизия и признак несохранённых изменений; прочитайте результат заново командой `model-docx`
Поверхность отключилась	Перезагрузка страницы, пропуск, порт локального интерфейса, жизненный цикл дочернего процесса и переподключение после разрыва
`window.fastdocShell` не определён	Код выполняется вне окна самого приложения A4 — там этих объектов нет. Для встраивания используйте внешний контракт: обмен строками JSON, WebSocket или поверхность

Контрольный список первой интеграции

Найти установленное приложение и fastdoc-cli внутри него — пути для трёх систем даны в Установке и проверке.
На macOS и Linux проверить, что у fastdoc-cli стоит флаг исполняемого файла; на Windows такого флага нет.
ping → ok: true, pong: true.
open с указанием document_id.
model — сохранить исходный текст для сравнения.
Правка с transaction_order: 1.
Сохранить в новый output.docx.
Повторно прочитать output.docx тем же процессором.
Открыть output.docx в A4 и увидеть изменение.
shutdown и завершение процесса.

Что приложить к обращению

Если по таблице выше причина не нашлась, напишите на support@plantype.ru. Разбор идёт быстрее, когда в письме сразу есть:

версия сборки A4 и система, на которой это видно;
имя команды (cmd) и текст отказа (error) целиком, вместе с id запроса;
одна строка запроса и одна строка ответа как есть, без пересказа;
наименьший обезличенный DOCX, на котором это повторяется;
повторяется ли это в новом процессе — после shutdown и запуска заново.

Куда смотреть дальше

Формат запроса и ответа, включая поля, которых может не быть, — Объекты запросов и ответов.
Полный перечень команд с параметрами — справочник Session Protocol.
Коды и тексты отказов транспорта — Транспорт и формат сообщений A4.
Поведение после разрыва соединения — Встраивание Surface.