Docs›Gestão de Documentos (GED)›Visão geral do GED
Gestão de Documentos (GED)

Visão geral do GED

Modelo de dados, conexão ged, rotas e as 5 telas (DocumentList, DocumentForm, FolderForm, DocumentDetail, ConfigForm).

Visão geral do GED

O GED (Gestão Eletrônica de Documentos) é o módulo de arquivos do MAD: pastas em árvore, documentos com versionamento, tags, favoritos, permissões granulares, compartilhamento público via link tokenizado e lixeira/arquivo morto. Não é uma feature separada do framework — é um módulo de aplicação construído com as mesmas peças que qualquer tela sua: models Eloquent, MadComponent/MadDataGrid, MadForm, mad-db-blocks, mad-tree-view. Use-o como referência de implementação, não só como funcionalidade pronta.

Modelo de dados

Tudo vive na conexão ged (uma das 6 conexões lógicas do MAD — ver Conexões de banco), em app/Models/Ged/*:

Model Tabela Papel
Document mad_ged_document O registro do documento — título, descrição, pasta, status (active|trash|archived), aponta para a versão corrente via current_version_id.
Folder mad_ged_folder Nó de árvore (parent_id auto-referente), com slug único por (parent_id, slug).
DocumentVersion mad_ged_document_version Uma revisão física do arquivo — storage_path, mime_type, file_size, version_number.
Tag / DocumentTag mad_ged_tag / mad_ged_document_tag Etiqueta e o pivot many-to-many com documentos.
DocumentPermission / FolderPermission mad_ged_document_permission / mad_ged_folder_permission ACL direta (usuário ou grupo → nível) em documento/pasta.
SharedLink mad_ged_shared_link Link público tokenizado de um documento.
Favorite mad_ged_favorite Documento favoritado por um usuário.
ActivityLog mad_ged_activity_log Trilha de auditoria (quem fez o quê, quando).

As configurações do módulo (retenção da lixeira, máximo de versões, tamanho máximo de upload, extensões permitidas) não têm model próprio: vivem nas preferências do sistema (mad_sys_preference, chaves prefixadas ged_) e são lidas por App\Service\Ged\GedSettingsService. O antigo App\Models\Ged\Config / tabela mad_ged_config não existe mais — ver Upload e versionamento.

O arquivo físico de cada versão fica no disco de uploads do MAD (mad_uploads por default, storage/app/mad; ou S3 via MAD_UPLOAD_DISK), sob a chave relativa files/ged/{document_id}/v{N}_{nome} — todo o IO passa pela API de Filesystem do Laravel (Mad\Service\MadUploadStorage + App\Service\Ged\GedStorage), nunca por caminho absoluto.

Todos os models usam os traits padrão do MAD (HasIdPolicy, HasMadAudit, HasMadSoftDeletes, BelongsToTenant) — mas vale notar duas pegadinhas reais deste módulo específico:

  • Auditoria não é automática aqui. HasMadAudit só carimba created_by/created_at sozinho quando o model declara o mapeamento de coluna ($madAudit ou a propriedade legada). Nenhum model do GED declara isso — as telas (DocumentForm, FolderForm, ...) setam created_by manualmente a partir de session('userid') antes de salvar.
  • Soft delete está desligado. Pelo mesmo motivo (nenhuma coluna mapeada), HasMadSoftDeletes é um no-op em todos os models do GED — ->delete() é uma exclusão real. A "Lixeira" do GED é um mecanismo próprio, via coluna status, sem relação com o soft delete do framework. Detalhes em Lixeira.

Rotas

Telas administrativas (autenticadas, mad.auth + mad.permission) ficam em routes/modules/documents.php:

Route::middleware(['mad.auth', 'mad.permission'])->group(function () {
    MadRoutes::resource('documents', 'DocumentList', 'DocumentForm'); // /app/documentos
    // FolderForm é tela AUXILIAR do DocumentList (drawer "Nova pasta"):
    // herda a permissão da lista, senão o botão morre silencioso num banco
    // sem o programa "GED Folder Form" seedado.
    MadRoutes::expose('folders', 'FolderForm', ['permissionFrom' => 'DocumentList']);
});

// Download AUTENTICADO de uma versão — só `mad.auth`, SEM `mad.permission`:
// a autorização real é a ACL por-documento (GedPermissionService::hasAccess),
// mais forte que a permissão de programa/tela.
Route::middleware('mad.auth')->group(function () {
    Route::get('/app/ged/download/{document}/{version?}', GedDownloadController::class)
        ->whereNumber('document')->whereNumber('version')
        ->name('ged.download');
});

O link público (sem login) fica fora desses grupos, declarado direto em routes/web.php — ver Compartilhamento público.

As telas

Tela Tipo O que faz
DocumentList MadDataGrid (card-view) Tela principal: grid de documentos com sidebar de pastas (mad-tree-view) e tags, modos de visualização (todos, recentes, favoritos, compartilhados comigo, lixeira, arquivo morto) e busca.
DocumentForm MadComponent (drawer) Um único drawer com 3 modos (new/edit/version) — criar documento, editar metadados/mover de pasta, ou enviar nova versão de um arquivo existente.
FolderForm MadComponent (drawer) Criar/editar pasta — gera slug único entre irmãos e impede reparentar uma pasta para dentro dela mesma (ciclo).
DocumentDetail MadComponent (painel teleportado) Painel lateral com abas: detalhes, tags, versões, compartilhamento (permissões + links públicos) e atividade. Não tem rota própria — é injetado via teleport() a partir de DocumentList::onShowDetail().
PreferenceForm (aba "GED") MadComponent Configurações do módulo (retenção da lixeira, limite de versões, tamanho máximo de upload, extensões permitidas). Não é uma tela do GED: é a tela de preferências do sistema, onde as chaves ged_* são editadas.
GedDownloadController Controller Laravel Download autenticado de uma versão (/app/ged/download/{document}/{version?}), autorizado pela ACL por-documento.

DocumentList e DocumentDetail se comunicam por MadResponse::teleport() (abrir o painel) e MadResponse::manageRow()/removeRow() (sincronizar a linha do grid depois de uma ação no painel) — o mesmo padrão que qualquer par lista+detalhe reativo no MAD usa.

Ver também