title: Integração: Backup e Restore description: Estratégias para persistência de dados em arquivos .mbz e restauração com fidelidade histórica.

Backup e Restore¶

O local_middag integra-se plenamente ao motor de Backup e Restore do Moodle, permitindo que itens, metadados e configurações criados pelo framework viagem entre instâncias LMS ou sejam preservados durante o backup de um curso.

O que é¶

É a ponte técnica que permite ao Moodle ler as tabelas nativas do MIDDAG (middag_items, middag_itemmeta) e codificá-las em arquivos XML dentro do pacote .mbz (Moodle Backup Zip).

Essa integração exige: 1. Backup Adapters (backup/moodle2/): Definem quais partes do banco de dados do MIDDAG devem ser exportadas. 2. Restore Adapters (backup/moodle2/): Definem como reconstruir os dados no novo site, mapeando usuários e cursos antigos para os novos IDs. 3. Import Repository: Um repositório especializado em inserções diretas em massa no banco (bypass).

Por que existe¶

Sem a integração de backup, ao mover um curso do Moodle de um servidor para outro: * Perda de Dados: Todas as associações de itens e configurações das extensions desapareceriam. * Quebra de Contexto: O framework ficaria com "pontas soltas" (registros que apontam para IDs de cursos que não existem mais). * Inconsistência Forense: Se recriarmos os dados manualmente, as datas de criação (timecreated) ficariam erradas (mostrando a data de "hoje" em vez da data original do backup).

O objetivo é garantir a Fidelidade Histórica dos dados durante o ciclo de clonagem ou restauração de ambientes.

O Desafio do Restore (ByPass)¶

Restaurar um backup de 5 anos atrás é diferente de criar um registro novo hoje. Se usássemos o item_repository->create() padrão durante o restore: 1. Datas Modificadas: O repositório padrão geraria um novo timecreated (a data de hoje), destruindo a auditoria histórica. 2. Gatilhos Indesejados: O dispatcher dispararia centenas de Signals (como item_created), ativando webhooks e automações desnecessárias para dados antigos. 3. Performance Lenta: A hidratação de milhares de objetos de domínio para inserção é muito lenta para um processo de massa.

O framework resolve isso com o Import Repository, que realiza o ByPass da lógica de negócio, inserindo os dados diretamente via SQL bruto para preservar a fidedignidade do backup.

Decisões de design¶

Mapeamento de IDs: O Motor de Restore do Moodle fornece um mapeamento de IDs de usuários e cursos entre o site antigo e o novo. O framework utiliza esse mapeamento para garantir que um Item restaurado aponte para o usuário correto no novo ambiente.
Idempotência: O processo de restore é projetado para lidar com inserções repetidas sem gerar erros fatais, permitindo retomar um restore interrompido se necessário.
Isolamento de Negócio: Durante o restore, as regras de validação de domínio são suspensas (bypass), pois o conteúdo contido no arquivo de backup é considerado soberano e imutável.

O que não é¶

Não é uma Ferramenta de Migração Genérica: O backup/restore do Moodle é voltado a cursos e instâncias da plataforma. Para migrar dados do MIDDAG entre versões diferentes de código, use o upgrade.php.
Não é Reativo: Como mencionado, o restore é deliberadamente silencioso. Listeners e Effects não rodam durante a descompressão de um .mbz.
Não é Sincronização de Banco de Dados: É uma exportação estruturada em XML que permite ao Moodle orquestrar a reconstrução do curso.

Perspectiva para builders de extensions¶

Como desenvolvedor de extension: 1. Seus Itens Estão Seguros: Se você usar o sistema de Itens e Metadados do framework, eles serão incluídos automaticamente no backup sem que você precise escrever código XML extra. 2. Evite Tabelas SQL customizadas: Se você criar suas próprias tabelas em install.xml, você será responsável por implementar seus próprios adapters de backup em backup/moodle2/. 3. Cuidado com Relacionamentos Externos: Itens que apontam para arquivos no Moodle File API são restaurados corretamente, pois o motor do Moodle já cuida da exportação dos arquivos físicos.

Exemplo ilustrativo¶

O papel do Import Repository no Restore:

// No Restore Plugin do Moodle
public function process_middag_item($data) {
    // 1. Obtemos IDs mapeados do Moodle Motor
    $new_course_id = $this->get_mappingid('course', $data->old_course_id);

    // 2. Chamamos o Repositório de Importação (Bypass total)
    $import_repository = middag::get(import_repository_interface::class);

    // O save_raw() preserva 'timecreated' e não dispara Signals
    $import_repository->save_raw($data, $new_course_id);
}