Справочник
Пакет доработок
Что находится внутри ZIP Holkas, как прочитать manifest.json и найти файл объекта. Версия формата, релиз Паруса, имена файлов и ограничения совместимости.
На этой странице
Для чего нужен пакет
ZIP хранит снимок выбранных объектов на момент выгрузки. Его можно передать в другой контур, загрузить как источник и сравнить с базой получателя. Исходная база для этого уже не нужна. Порядок действий и реальные экраны — Передать доработку через ZIP.
В пакет входят определения объектов целиком, а не только команды последнего плана. Обычная таблица TBP сохраняет структуру; строки справочника переносятся отдельным объектом DAT. Рабочие документы и вся база в пакет автоматически не попадают.
Как устроен архив
От строки в оглавлении — к файлу объекта
contracts-1.1.zipmanifest.jsonОглавление и сведения об источнике. Перечисляет пять объектов; у каждого есть отдельный JSON с его содержимым.
- CLS
HolkasSiteContractsClass/HolkasSiteContracts.jsonСвойства класса, атрибуты и визуальные формы.
- TBP
parus.hksite_contractsTablePostgres/parus.hksite_contracts.jsonСтруктура таблицы, ограничения, индексы и другие части.
- JFP
parus.f_hksite_contract_checkFunctionPostgres/parus.f_hksite_contract_check.jsonОпределение функции, владелец и права.
- MET
HolkasSiteContracts|CheckAmountMethod/HolkasSiteContracts%7CCheckAmount.jsonМетод класса — самостоятельный объект пакета.
- MEC
HolkasSiteContracts|UserDefinedMethodMethodCall/HolkasSiteContracts%7CUserDefinedMethod.jsonВызов метода. Разделитель в имени закодирован как %7C.
В практической главе выбраны класс, таблица и функция. При чтении класс раскрылся также в метод и вызов метода: поэтому в архиве пять объектов, а не три.
В корне находится manifest.json, рядом — каталоги типов с JSON-файлами объектов. Для чтения важны имена записей, а не порядок, в котором архиватор их показывает.
Встроенный manifest.json — не манифест состава формата holkas-manifest/2. Первый описывает уже сохранённый снимок внутри ZIP. Второй — отдельный список для выбора объектов из источника. Их нельзя подставлять друг вместо друга.
Поля manifest.json
| Поле | Тип | Значение |
|---|---|---|
dbms | Строка | СУБД источника: обычно postgres или oracle. Один пакет относится к одной СУБД. |
formatVersion | Целое число | Версия устройства пакета. Holkas принимает 1. Это не версия Holkas и не версия вашей доработки. |
createdAt | Строка даты и времени | Момент выгрузки в UTC, в формате ISO 8601. |
createdBy | Объект | name и email автора выгрузки. Это сведения о происхождении, а не подпись файла или разрешение на применение. |
objects | Массив | Оглавление пакета: по одной записи на объект. Holkas перечисляет содержимое по этому списку. |
objects[].typeCode | Строка | Код типа, например CLS, TBP, JFP. По нему определяется тип объекта и каталог файла. |
objects[].name | Строка | Полное имя объекта Holkas. Для составных имён важны все части и разделители. |
parusRelease | Строка, может отсутствовать | Дата релиза Паруса источника: yyyy-MM-dd. Нужна для правил совместимости. В старых пакетах поле отсутствует; это трактуется как исходный релиз раньше всех учитываемых изменений. |
singleTransaction | Логическое значение, может отсутствовать | true требует полной установки одной транзакцией PostgreSQL. При обычной выгрузке поле опускается. Это требование установки, а не свойство отдельного списка объектов. |
Эти поля формирует Holkas. Перенос произвольного ZIP с похожими именами файлов не поддерживается. Смена dbms или parusRelease вручную не переводит SQL и не преобразует содержимое под другую базу.
Заголовок учебного пакета, без массива objects, показанного на иллюстрации:
{
"dbms": "postgres",
"formatVersion": 1,
"createdAt": "2026-10-20T18:36:59.5596977+00:00",
"createdBy": {
"name": "site-guide",
"email": "site-guide@holkas.local"
},
"parusRelease": "2024-11-28"
}
Это фрагмент для чтения, не полный файл для замены manifest.json.
Требование одной транзакции
При выгрузке в S3 или файл пакета параметр «Перенести одной транзакцией» записывает singleTransaction: true в оглавление. При чтении такого ZIP требование сильнее настроек сервера, подключения и плана: у операции показана метка «одной транзакцией · требует пакет», а источник итогового значения в REST — package. Явное выключение в плане вызывает отказ.
| Приёмник пакета | Что произойдёт |
|---|---|
| База PostgreSQL | Весь план применяется одной транзакцией. Исключённые команды или команды «вне плана» — отказ до первой записи. |
| S3 или файл пакета | Требование сохраняется в новом ZIP. |
| SQL-файл PostgreSQL | SQL оборачивается в BEGIN … COMMIT; для выполнения используйте psql -v ON_ERROR_STOP=1. |
| База или SQL-файл Oracle | Отказ: общий откат DDL невозможен. |
| Git | Требование теряется; план предупреждает, что при следующем переносе его придётся задать заново. |
Для установки нужен Holkas 0.1.25 или новее: прежние версии не обеспечивают это требование. В отдельном манифесте состава такого поля нет. Как выгрузить пакет и проверить обязательный режим.
Как определяется путь объекта
Путь имеет вид КаталогТипа/ЗакодированноеИмя.json. Каталог не равен короткому коду типа: CLS хранится в Class, TBP — в TablePostgres, JFP — в FunctionPostgres. Коды и назначение типов описаны в справочнике объектов.
В имени файла символы /, \, :, *, ?, ", <, >, | и % заменяются на %XX с шестнадцатеричным кодом. Например, | становится %7C, / — %2F, а сам % — %25. Точки, пробелы и кириллица сохраняются. Внутри ZIP каталог отделяется прямым слешем /.
| Имя объекта | Имя файла |
|---|---|
parus.f_hksite_contract_check | parus.f_hksite_contract_check.json |
HolkasSiteContracts|CheckAmount | HolkasSiteContracts%7CCheckAmount.json |
Раздел/Статусы | Раздел%2FСтатусы.json |
Первые два имени — из учебного архива; третье иллюстрирует кодирование. Не переименовывайте файл независимо от objects[].name: Holkas вычисляет ожидаемый путь из типа и имени. Просто добавить JSON в архив тоже недостаточно — в оглавлении должна быть соответствующая запись.
Все каталоги типов
| Код | Каталог в ZIP |
|---|---|
ACT | Action |
APP | Application |
CLS | Class |
CLO | ClassObject |
CTP | CompositeTypePostgres |
CNS | Constraint |
PCE | CustomProcedure |
REP | CustomReport |
SCR | CustomScript |
DAT | DataSet |
DOM | Domain |
JFN | FunctionOracle |
JFP | FunctionPostgres |
LNK | Link |
MSG | Message |
MEC | MethodCall |
MET | Method |
JPG | PackageOracle |
PRM | Parameter |
PIC | Pictogram |
JPR | ProcedureOracle |
JPP | ProcedurePostgres |
JSQ | SequenceOracle |
SQP | SequencePostgres |
STY | Stereotype |
JSY | SynonymOracle |
JTB | TableOracle |
TBP | TablePostgres |
UAP | UserApplication |
VIW | View |
JVW | ViewOracle |
JVP | ViewPostgres |
Что хранится в JSON объекта
JSON использует UTF-8 и имена полей в camelCase. Поля со значением null при записи опускаются. Строки SQL могут содержать \n и Unicode-последовательности: после разбора JSON это обычный текст с переносами строк.
Форма содержимого зависит от типа. У функции из учебного пакета есть schema, name, body, owner и grants; у класса — свойства, attributes и visualForms; у таблицы — columns, constraints, indexes, triggers и grants. Идентификатор объекта задаётся строкой оглавления, поэтому поле name не обязано повторяться внутри каждого типа.
У объектов PostgreSQL — таблицы, последовательности, представления, функции, процедуры и составного типа — поле owner обязательно. Если его нет или оно пустое, перенос останавливается до плана и называет такие объекты; роль схемы не подставляется. У объектов Oracle owner не записывается: владельца задаёт схема.
У DAT файл содержит definition и rows: описание набора и считанные строки. Это больше, чем отдельное описание holkas-dataset/1. Формат обеих частей разобран на странице Описание набора данных.
Класс и его подчасти
У класса и каждой его подчасти — ограничения, связи, действия, метода, вызова метода, представления и записи реестра — свой файл и своя строка в objects. В Class/Request.json лежат только реквизиты класса, атрибуты и формы. Метод Request|Save записан в Method/Request%7CSave.json и указан в оглавлении как MET. Так устроены ZIP и из S3, и из «Файла пакета»: архив можно выгрузить одним способом и загрузить другим.
Подчасть можно выгрузить и без класса: она сохранится отдельным файлом. Применить её к базе можно, только если класс уже есть в приёмнике или создаётся в том же переносе.
В ZIP, которые S3 записывал в Holkas 0.1.30 и раньше, подчасти лежали внутри Class/<код>.json, а в objects был указан только класс. Такие архивы читаются и сейчас — через S3 и через «Файл пакета». Обратного нет: Holkas 0.1.30 и более ранних версий не прочитает через S3 новый ZIP с классом и сообщит, что у класса нет поля $.constraints. Обновите Holkas получателя.
Пакет сохраняет положительную спецификацию: перечисленные объекты должны существовать в приёмнике. Отсутствие другого корневого объекта в ZIP не означает команду его удалить. Правила частей и строк набора рассматриваются в модели переноса и справочнике DAT.
Совместимость и проверка
При открытии Holkas ищет manifest.json, разбирает его и проверяет formatVersion. Для перечисленных объектов затем определяются типы и читаются ожидаемые JSON-файлы. Неизвестные текущей версии Holkas типы пропускаются с сообщением в журнале; типы уровня СУБД фильтруются по СУБД, указанной в пакете. Поэтому успешное открытие архива само по себе ещё не подтверждает пригодность всех его объектов.
Логические объекты Паруса могут переноситься между Oracle и PostgreSQL по поддерживаемым правилам. SQL-функция PostgreSQL не становится функцией Oracle от смены приёмника. Перед применением проверяйте состав, журнал, аномалии и команды плана. Покрытие релизов — в проверках совместимости.
У пакета нет поля hash, аналогичного отдельному манифесту состава. Не приписывайте ему правила контрольной суммы holkas-manifest/2. Для контроля передачи всего файла можно отдельно сравнить SHA-256 ZIP на отправляющей и принимающей сторонах; это проверка байтов файла, не электронная подпись.
Если пакет не читается
| Сообщение или ситуация | Что проверить |
|---|---|
| Архив не открывается | Скачивание завершилось полностью; передан ZIP, а не HTML страницы или начальный фрагмент ответа MCP. |
Нет manifest.json | Файл лежит именно в корне архива. Не добавилась внешняя папка при перепаковке. |
formatVersion … is unsupported | Версия формата не поддерживается текущим Holkas. Сверьте версии отправителя и получателя; ручная замена числа не конвертирует пакет. |
| Объект не найден по ожидаемому пути | Имя из objects соответствует имени и каталогу JSON; кодирование символов не изменено. |
У класса нет поля $.constraints | ZIP записан новым Holkas, а читает его через S3 Holkas 0.1.30 или старше. Обновите Holkas получателя или загрузите ZIP как «Файл пакета». |
| JSON объекта не разбирается | Файл не обрезан и не изменён несовместимым образом. Получите исходный пакет повторно. |
| В составе меньше объектов, чем ожидалось | Сверьте оглавление и журнал: неизвестные или несовместимые типы могут быть пропущены. |
Для изменения доработки предпочтительно изменить источник и выгрузить новый пакет: так оглавление и содержимое будут согласованы. Сборка ZIP вручную не заменяет проверку плана на приёмнике.
Дальше: практический перенос ZIP, манифест состава, описание набора данных.
Старые пакеты и пустые списки
Отсутствующий список, null и [] не взаимозаменяемы. Обязательный список без значения вызывает отказ с именем объекта и поля. Явный пустой список означает известное отсутствие элементов и может породить Delete в приёмнике.
Для отдельных добавленных сведений предусмотрена совместимость: старые формы без назначений и связей с приложениями сохраняют их в приёмнике; отсутствующие настройки регистрации таблицы класса и типы документов связи отчёта тоже сохраняются. Это не доказательство полного совпадения этих частей.
Особый случай — родитель параметра отчёта: старый файл его не содержит и может очистить существующую связь. Альтернативные рабочие места со старым числовым MainWorkPlace нужно выгрузить заново. Старые временные таблицы Oracle без режима хранения читаются как постоянные. Полный перечень действий — переход на 0.1.30.