Como Desenvolver um Módulo Dolibarr para Anexar e Rotular Imagens JPEG em Relatórios

Em fluxos de gestão de projetos técnicos, vistorias em campo ou laudos de engenharia, a documentação visual é indispensável. No entanto, o comportamento padrão de muitos sistemas de ERP/CRM, incluindo o Dolibarr, limita-se a um repositório genérico de arquivos, sem permitir categorização direta ou atribuição de rótulos específicos para imagens atreladas a etapas do relatório.

Neste artigo, você entenderá a arquitetura necessária para criar um módulo customizado no Dolibarr focado no upload, validação e rotulagem de imagens JPEG diretamente na visualização de projetos.

1. Arquitetura de Módulos no Dolibarr

O Dolibarr adota uma estrutura modular baseada em hooks e triggers, permitindo estender funcionalidades nativas sem alterar o núcleo (core) do sistema. Isso garante manutenibilidade e compatibilidade com futuras atualizações.

Para implementar a funcionalidade de anexo e rotulagem de imagens, a estrutura básica do módulo dentro do diretório /custom/ deve conter:

• core/modules/modReportImageTagger.class.php: Descritor principal contendo metadados, permissões e registros de tabelas SQL.
• class/actions_reportimagetagger.class.php: Classe de contexto para interceptação de eventos via hooks.
• sql/llx_project_image_tags.sql: Tabela responsável por armazenar a relação entre o projeto, o caminho da imagem e a etiqueta/rótulo atribuído.

2. Modelagem de Dados e Relacionamento

Para armazenar o rótulo da imagem sem comprometer a estrutura do módulo nativo de gerenciamento de documentos (ecm), a criação de uma tabela auxiliar é a abordagem mais indicada:

sql
CREATE TABLE llxprojectimagetags (
rowid INT AUTOINCREMENT PRIMARY KEY,
fkproject INT NOT NULL,
filename VARCHAR(255) NOT NULL,
imagelabel VARCHAR(100) NOT NULL,
datecreation DATETIME DEFAULT CURRENTTIMESTAMP,
fkusercreat INT NOT NULL,
CONSTRAINT fkprojectimage FOREIGN KEY (fkproject) REFERENCES llxprojet(rowid) ON DELETE CASCADE
) ENGINE=InnoDB;

Essa estrutura estabelece a integridade referencial com a tabela principal de projetos (llx_projet), assegurando que a exclusão de um projeto remova automaticamente os registros das imagens vinculadas.

3. Upload Seguro e Manipulação de Imagens JPEG

Ao lidar com upload de arquivos, a validação não deve depender apenas da extensão .jpg ou .jpeg enviada pelo cliente. O processamento precisa validar o MIME type e a integridade do arquivo binário.

Boas práticas de implementação:

1. Validação do MIME Type: Checagem rigorosa via mime_content_type() ou extensão finfo no backend PHP.
2. Sanitização de Nomes: Conversão de caracteres especiais e geração de hashes únicos para evitar colisões e vulnerabilidades de path traversal.
3. Otimização de Armazenamento: Uso da biblioteca GD ou Imagick para normalizar a orientação EXIF e aplicar compressão controlada antes de salvar no diretório seguro de documentos do Dolibarr (DOL_DATA_ROOT).

Em sistemas que desenvolvo, priorizo isolar o armazenamento físico dos arquivos fora da raiz web pública, servindo as imagens através do handler nativo document.php do Dolibarr para assegurar o controle de permissões de acesso por usuário.

4. Injeção de Interface via Hooks

Para permitir que o usuário faça o upload e insira a legenda da imagem diretamente na aba do relatório do projeto, utilizamos os hooks de interface:

• formObjectOptions ou addMoreActionsButtons: Para injetar o formulário modal de envio de imagens e seleção de tags.
• printObjectSubTitle ou seções customizadas: Para renderizar a galeria de imagens anexadas com seus respectivos rótulos e miniaturas.

O processamento do formulário é delegado ao método doActions() na classe controladora do módulo, garantindo separação clara entre camada de apresentação e lógica de negócios.

5. Fluxo de Implementação Recomendado

1. Scaffolding: Gerar a estrutura do módulo usando a ferramenta modulebuilder do próprio Dolibarr para padronizar cabeçalhos e namespaces.
2. Definição de Hooks: Habilitar os hooks correspondentes ao contexto projectcard.
3. Camada de Upload: Criar o endpoint de processamento multipart validando o token CSRF (token) nativo do Dolibarr.
4. Visualização no Relatório: Integrar as imagens marcadas aos modelos de exportação em PDF (usando TCPDF/FPDF) para que os relatórios gerados já incluam as fotos e legendas organizadas.

Conclusão

A criação de módulos customizados no Dolibarr permite alinhar o ERP exatamente aos processos operacionais do negócio sem gerar débitos técnicos. Compreender a mecânica de hooks, segurança de uploads e modelagem relacional é fundamental para soluções estáveis e escaláveis.

Se sua empresa necessita de módulos personalizados, integrações ou consultoria avançada em Dolibarr, entre em contato para avaliarmos a arquitetura ideal para o seu projeto.