# Миграция из старой AVE.cms

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

Модуль `legacy_migration` переносит содержимое старой AVE.cms в
чистую native-установку. Он не является обычным импортом: ID
документов, рубрик, полей, шаблонов и связей сохраняются.

## Когда использовать

Миграция рассчитана на новую установку с двумя стартовыми
документами. На сайте, где уже создан рабочий контент, запуск будет
заблокирован. Для повторяемой загрузки CSV, Excel или XML используйте
[«Импорт документов»](document-import.md).

## Порядок работы

1. Создайте отдельную пустую AVE.cms и установите модуль.
2. Откройте **Модули → Миграция AVE.cms** и добавьте доступ к старой БД.
3. Запустите анализ. Он читает схему и счётчики, но не меняет обе БД.
4. Исправьте критические замечания: отсутствующие модули, таблицы или типы полей.
5. Начните перенос. Перед очисткой стартового контента модуль создаст
   сжатую JSONL-копию затрагиваемых таблиц, настроек и системных пользователей.
6. Дождитесь сверки количества строк.
7. Упакуйте старый `uploads/` в ZIP и загрузите его в завершённый запуск.
8. Установите нужные модули, проверьте PHP-код и переиндексируйте поиск/каталог.

## Что переносится

- шаблоны, рубрики, группы и поля;
- документы, значения полей, ревизии, теги, keywords, редиректы и просмотры;
- запросы и условия, меню и пункты, блоки;
- публичные пользователи и группы;
- поддерживаемые таблицы каталога, контактов, RSS и корзины, если их модули уже установлены;
- привилегированные legacy-пользователи групп 1 и 3 как системные учётные записи.

Новые JSON-настройки полей создаются из legacy-значений. Для старых условий
запросов создаётся корневая группа. Обычные визуальные блоки переводятся в
единый реестр блоков.

Скомпилированный SQL и подтверждение Native не переносятся между базами:
условия сохраняются, но запрос запускается в Legacy до новой проверки в
Adminx. В конце переноса удаляются старые JSON-снимки документов и схем рубрик.
На первом публичном открытии они строятся заново пакетно из уже перенесённых
данных. Откат выполняет такой же сброс, поэтому кеш не может остаться от
отменённого переноса.

## Что не переносится автоматически

- активные сессии, remember-токены, API-ключи и аудит;
- пароли и секреты платёжных систем;
- старые PHP-модули и их файлы;
- код темы и другие исполняемые файлы;
- неизвестные модульные таблицы.

Такие таблицы попадают в отчёт как несопоставленные. Сначала нужно установить
нативный аналог модуля или написать адаптер на хуках.

## Хуки миграции

| Хук | Данные | Назначение |
| --- | --- | --- |
| `legacy_migration.plan` | `profile`, `tables`, `plan` | Дополнить план после анализа. |
| `legacy_migration.row` | `run`, `job`, `row` | Изменить одну строку перед записью. |
| `legacy_migration.completed` | `run`, `report` | Запустить постобработку после сверки. |

Обработчик `legacy_migration.row` должен вернуть весь контекст с изменённым
`row`. Через него модуль-приёмник может перекодировать колонку или перевести
значение старого модуля в новый формат.

## Безопасность файлов

ZIP распаковывается порциями. Модуль отклоняет:

- абсолютные пути и `../`;
- символические ссылки;
- `.htaccess`, `.user.ini`, точечные и исполняемые файлы;
- двойные исполняемые расширения;
- архивы свыше 100 000 файлов или 10 ГБ после распаковки.

Файлы записываются только в `uploads/`. По умолчанию существующие файлы не
заменяются.

## После переноса

Автоматическая сверка проверяет строки, но не заменяет приёмку. Откройте
реальные страницы каждой рубрики, проверьте меню, запросы, блоки, медиа и
сохранённый PHP-код. При любом расхождении не удаляйте исходную БД и локальную
резервную копию запуска.

Кнопка **Откатить перенос** доступна для завершённого, ошибочного или отменённого
запуска. Она восстанавливает снимок целевой БД. Файлы, уже записанные из ZIP в `uploads/`,
автоматически не удаляются: перед файловым переносом сохраните отдельную копию `uploads/`.