# Установка модуля из ZIP

← [К разделу «Модули»](README.md)

Панель управления принимает административный модуль или составной
public/admin-пакет AVE.cms.
После проверки архив распаковывается в штатный каталог и сразу устанавливается.

Архивы модулей распространяет владелец системы. Для загрузки требуются два
отдельных права: управление модулями и установка исполняемого кода.

## Сборка архива

Не создавайте ZIP вручную. Штатный сборщик добавляет обязательный manifest и
проверяет архив после упаковки:

```bash
php tools/build-module-package.php modules/reviews
php tools/build-module-package.php adminx/modules/Notes
```

По умолчанию результат сохраняется в `storage/releases/modules/`. Путь можно
переопределить параметром `--output=...`.

## Допустимая структура

Только панель управления:

```text
notes.zip
└── Notes/
    ├── module.php
    └── ...
```

Составной пакет:

```text
reviews.zip
└── reviews/
	├── AVE-MODULE.json
    ├── app/
    │   ├── module.php
    │   └── ...
    └── admin/
        ├── module.php
        └── ...
```

Самодостаточный пакет готового сайта может дополнительно содержать проверенные
архивы зависимостей:

```text
site-package.zip
└── site_package/
    ├── admin/
    ├── app/
    └── packages/
        └── modules/
            ├── search-1.2.4.zip
            └── contacts-1.0.4.zip
```

Не добавляйте эти архивы вручную. Перечислите коды в
`package.embedded_dependencies` административного `module.php`, и штатный
сборщик сам соберёт зависимости, вычислит SHA-256 и создаст manifest формата
`ave-module-package-v2`.

Допускается архив без внешней папки. В корне должен находиться ровно один
`module.php` либо один `admin/module.php`, а также `AVE-MODULE.json`.

Для составного пакета имя папки обязано совпадать с `code`. Код начинается с
строчной латинской буквы, содержит только строчные буквы, цифры и `_`, его
максимальная длина — 64 символа.

## Обязательные свойства

```php
'lifecycle' => array('managed' => true),
'admin_extension' => array(/* метаданные раздела */),
```

`lifecycle.adopt_existing` запрещён: он предназначен только для контролируемого
переезда уже существующего функционала. Код нового архива не должен совпадать с
кодом уже обнаруженного модуля.

## Ограничения безопасности

| Ограничение | Значение |
| --- | --- |
| Формат | Только ZIP |
| Размер архива | До 25 МБ |
| Файлов и каталогов | До 1500 |
| Один распакованный файл | До 25 МБ |
| Общий распакованный размер | До 100 МБ |

Установщик запрещает абсолютные пути, `..`, управляющие символы, дубликаты,
символические ссылки и подозрительный коэффициент сжатия. Требуется
PHP-расширение `zip`; каталоги `<admin-directory>/modules` и `modules` должны
быть доступны web-процессу на запись. В команде сборки выше `adminx` обозначает
исходный каталог проекта; установленная система определяет фактический каталог
панели автоматически.

До выполнения `module.php` установщик сверяет формат, владельца, code, версию,
тип пакета, полный перечень файлов и SHA-256. Лишний, отсутствующий или изменённый
файл останавливает установку. Checksum защищает целостность, но архив всё равно
должен поступать по доверенному каналу владельца.

## Порядок установки

1. Откройте **Система → Модули**.
2. Выберите установку из архива и загрузите ZIP.
3. После успеха проверьте версию и зависимости.
4. Назначьте права ролям и заполните настройки модуля.
5. Проверьте административные и публичные маршруты.

Для самодостаточного пакета зависимости обрабатываются раньше основного
lifecycle. Отсутствующая зависимость устанавливается, устаревшая обновляется, а
такая же или более новая версия используется без замены. Удаление основного
пакета не удаляет общие модули: в них уже могут находиться пользовательские
данные.

При ошибке до проверки manifest временная и целевая папки удаляются. Если
manifest уже проверен и часть миграций выполнилась, пакет остаётся на месте:
устраните причину и повторите обычную установку.

ZIP является исполняемым PHP-кодом. Устанавливайте пакет только из доверенного
источника и делайте backup перед миграциями существующих данных.

Для публикации нескольких официальных ZIP через HTTPS используйте
[удалённый подписанный каталог](repository.md).