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

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

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

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

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

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

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

## Прогресс и продолжение

Перенос не выполняется одним длинным HTTP-запросом. Модуль последовательно
проходит этапы:

1. резервная копия целевых таблиц;
2. очистка только стартовых данных;
3. перенос таблиц порциями;
4. нормализация полей, запросов, блоков, пользователей и настроек;
5. сверка количества строк.

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

Если закрыть вкладку, потерять соединение или получить временную ошибку,
выполнение останавливается на сохранённой позиции. Откройте этот запуск в
истории и нажмите **Продолжить**. Уже завершённые таблицы повторно не
переносятся.

Кнопка **Откатить перенос** появляется только после полного создания резервной
копии. Незавершённый файл копии не используется для восстановления.

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

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

Главная страница переносится вместе с документом `ID 1`. Стартовая главная
чистой установки удаляется перед записью. Страница 404 также входит в общий
перенос документов, а её ID берётся из перенесённых настроек старого сайта.
Поэтому ссылки и связи между документами не перенумеровываются.

Публичный пользователь `ID 1`, созданный установщиком вместе с текущим
администратором, сохраняется. Строка `ID 1` из старой таблицы пользователей
пропускается, остальные пользователи записываются со своими прежними ID.

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

Колонки, которых не было в старой AVE.cms, заполняются безопасными начальными
значениями. Например, для документов создаются пустые `guid` и
`module_catalog`, а для рубрик — пустой OG-шаблон. Допустимые в старой MyISAM
значения `NULL` приводятся к формату обязательных колонок новой схемы.

Основные настройки старого сайта переносятся одновременно в системный реестр и
в публичную конфигурацию. Старые опечатки в именах параметров хлебных крошек
исправляются автоматически. Пароли БД, SMTP и другие секреты не копируются:
их нужно заполнить заново после проверки переноса.

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

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

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

Это относится только к таблицам старых модулей в исходной БД. Модули, уже
установленные в новой системе, не мешают полной миграции. Их таблицы,
настройки, версии и состояние включения не проверяются на пустоту, не очищаются
и не изменяются.

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

## Что считается чистой установкой

Установщик создаёт два документа, одну стартовую рубрику, шаблон, поля, меню и
служебные строки для главной и 404. Эти данные не блокируют миграцию и будут
заменены.

Если в документах, рубриках или шаблонах уже появился другой рабочий контент,
анализ остановит запуск. Ключевые слова, ревизии и просмотры тоже допустимы,
пока они относятся только к стартовым документам `ID 1` и `ID 2`.

Такое ограничение защищает от случайного запуска миграции поверх уже
наполненного нового сайта.

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

| Хук | Данные | Назначение |
| --- | --- | --- |
| `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-код. При любом расхождении не удаляйте исходную БД и локальную
резервную копию запуска.

Если запись остановилась, отчёт показывает целевую таблицу и ID исходной
строки, на которой MySQL вернул ошибку. Это позволяет исправить конкретное
значение в копии старой БД и повторить анализ, не перебирая весь дамп.

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