Overview

Photo Organizer v1.0 fornece um pipeline local e controlável para coletar, indexar e organizar fotografias. Esta seção apresenta o propósito e o escopo da versão inicial — uma linha de base para desenvolvedores e usuários técnicos.
  • Propósito: permitir ingestão confiável de coleções fotográficas e facilitar a identificação e gestão de duplicatas para reduzir armazenamento manual e trabalho repetitivo.
  • Escopo desta versão: indexação local, extração de metadados, detecção de duplicatas (exatas e perceptuais), organização automática por políticas configuráveis e um painel para revisão humana.
  • Público-alvo: usuários que gerenciam coleções de fotos localmente e equipes técnicas que precisam de um ponto de partida auditável para automações posteriores.
  • O que esta seção não documenta: detalhes implementacionais e tecnologia — esses estão nas seções específicas (Arquitetura, Tecnologias, Requisitos).

Quick Start

Instalação rápida: 
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
Executar (modo dry-run): 
python main.py --dry-run --input "C:\path\to\photos" --output output/organized
Iniciar dashboard web: 
python app.py
# abrir http://localhost:5000

Requisitos Funcionais

🔍
Varredura de Diretórios
Escaneia diretórios configurados recursivamente procurando arquivos de imagem suportados e valida tipos via detecção de MIME.
Suporte inicial: JPEG, PNG e formatos comuns
📊
Extração de Metadados
Extrai metadados EXIF (data/hora, GPS, modelo) e normaliza informações para indexação.
EXIF, GPS, parsing de datas
🔐
Cálculo de Hashes
Gera MD5 para duplicatas exatas e hashes perceptuais (pHash/dHash) para identificar similares visuais.
MD5 + pHash/dHash
🎯
Detecção de Duplicatas
Agrupa e marca duplicatas exatas e visuais para revisão ou ações automáticas conforme políticas.
Detecção exata e por similaridade
🌐
Interface Web
Dashboard web para visualização de resultados e controle de operações (relatórios gerados por scripts offline).
Flask + templates

Futuros Funcionais

🤖
Análise Visual Avançada
Adicionar reconhecimento de rostos, objetos e cenas para melhorar agrupamento e classificação.
🔐
Interface Web Aprimorada
Suporte a upload via web, autenticação, filtros avançados e galerias para revisão.
🔗
API REST Completa
Expandir endpoints para integração com sistemas externos e webhooks.
📸
Suporte a Mais Formatos
Adicionar suporte a RAW (CR2, NEF), WebP e outros formatos modernos.
🧠
Machine Learning
Modelos para classificação automática e agrupamento semânticos.
📊
Geração de Relatórios
Geração de relatórios por scripts offline (ex.: `scripts/generate_reports.py`) — possível integração futura com o dashboard.

Requisitos Não Funcionais

💾
Persistência de Dados
Persistência local via SQLite para registro de caminhos, metadados e hashes, com opções de exportação e backup.
SQLite, exportação de backup
⚙️
Arquitetura Modular
Código organizado em módulos especializados para facilitar manutenção, testes e escalabilidade.
Separação de responsabilidades

Futuros Não Funcionais

🧪
Testes Unitários Completos
Aumentar cobertura de testes para >80%, incluindo mocks para operações de arquivo e integração contínua.
🔧
Refatoração Adicional
Quebrar componentes remanescentes em unidades menores seguindo princípios de responsabilidade única.
⚡
Otimização de Performance
Processamento paralelo, batching de I/O e cache inteligente para melhorar throughput em coleções grandes.

Casos de Uso Principais

📥
UC01 — Importar Fotos
Processo que permite ao usuário importar um diretório ou arquivos individuais para o sistema, validando tipos e gerando miniaturas.
Atores: Usuário / Operador
Pré-condições: Caminho de origem acessível; permissões de leitura.
Fluxo Principal:
  1. Usuário seleciona diretório ou arrasta arquivos para a interface.
  2. Sistema valida tipos MIME e extensões suportadas (JPEG, PNG, WebP).
  3. Arquivos inválidos são rejeitados com mensagem; válidos são enfileirados.
  4. Processador extrai metadados (EXIF/GPS/datetime) e gera miniaturas.
  5. Registros são gravados no banco e arquivos copiados/movidos para `output/organized` (modo de operação).
Fluxos Alternativos: Import parcial se conexão interrompida; ignorar arquivos corruptos; modo `--dry-run` não grava alterações.
Pós-condições: Imagens registradas no banco; miniaturas geradas; relatórios de import disponíveis.
🔎
UC02 — Detectar Duplicatas
Rotina que identifica duplicatas exatas e similares entre as imagens processadas, agrupando para revisão ou quarentena.
Atores: Sistema automático / Usuário (revisão)
Pré-condições: Imagens indexadas com hashes calculados (MD5 ou perceptual). Fluxo Principal:
  1. Sistema lista candidatos a verificar (novas imagens ou volume selecionado).
  2. Calcula hash MD5 e hash perceptual (pHash/dHash) conforme configuração.
  3. Compara hashes, aplica thresholds e agrupa similares por score.
  4. Resultado disponibilizado no dashboard com thumbnails e meta-informações.
  5. Usuário pode aprovar ações (mover para quarentena, excluir, manter).
Fluxos Alternativos: Ajuste de sensibilidade para reduzir falsos positivos; execução incremental para grandes coleções.
Pós-condições: Grupos de duplicatas registrados; possíveis ações aplicadas (movimento/remoção/quarentena).
🗂️
UC03 — Organizar Fotos
Aplica regras de organização (por data, evento, etiqueta) para mover e renomear imagens em estrutura final.
Atores: Usuário / Sistema (políticas automáticas)
Pré-condições: Metadados disponíveis e política de organização configurada. Fluxo Principal:
  1. Usuário seleciona política (por data, tags, ou regras customizadas).
  2. Sistema simula mudanças (modo `--dry-run`) e mostra preview de destino.
  3. Ao confirmar, sistema executa movimentos atômicos garantindo rollback parcial em erro.
  4. Atualiza caminhos no banco e registra logs de auditoria.
Fluxos Alternativos: Conflitos de nome → renomeação automática ou prompt; falta de permissões → operação abortada e log de erro.
Pós-condições: Arquivos organizados em `output/organized`; banco atualizado; logs com ações realizadas.

Diagramas dos Casos de Uso

UC01 — Importar Fotos

U
Usuário
1
Seleciona Fonte
Diretório ou arquivos
→
2
Valida Conteúdo
MIME, extensões
→
3
Processa
EXIF & thumbnails
→
4
Armazena
DB + output/organized
Pré-condições
Fonte acessível; permissão leitura
Pós-condições
Registros e miniaturas criados
Alternativas
Modo `--dry-run`; ignorar corrompidos

UC02 — Detectar Duplicatas

S
Sistema
1
Seleciona Volume
Novas imagens ou coleção
→
2
Calcula Hashes
MD5 + perceptual
→
3
Agrupa
Por score de similaridade
→
4
Apresenta
Dashboard para revisão
Pré-condições
Hashes calculados
Pós-condições
Grupos de duplicatas criados
Alternativas
Ajuste de sensibilidade; execução incremental

UC03 — Organizar Fotos

U
Usuário
1
Seleciona Política
Por data/evento/tags
→
2
Preview
Simula destino (dry-run)
→
3
Executa
Movimentos atômicos
→
4
Audita
Logs e rollback parcial
Pré-condições
Metadados disponíveis
Pós-condições
Arquivos reorganizados
Alternativas
Conflitos → renomeação automática ou prompt

Desenvolvimento

Visão Geral
Esta seção descreve práticas e considerações adotadas durante o desenvolvimento do Photo Organizer. Resume decisões relevantes sobre segurança, desempenho, estrutura do código e testes, complementando as seções de Arquitetura e Tecnologias sem repetir detalhes de implementação.
Segurança
No projeto, a segurança é abordada por validação de caminhos para evitar path traversal, verificação de tipos MIME antes do processamento de arquivos e restrição de operações ao diretório configurado. O dashboard trata entradas de usuário com sanitização e validações, e operações sensíveis realizam verificações de integridade e usam permissões mínimas.
Desempenho
Para coleções grandes, são adotadas estratégias como processamento paralelo (para hashing e geração de miniaturas), batching de I/O e caching de resultados (thumbnails e metadados) para reduzir repetição de trabalho e I/O intenso, melhorando latência e throughput.
Estrutura & Boas Práticas
O código está organizado em pacotes com responsabilidades separadas (`src/core`, `src/organization`, `src/routes`, `src/utils`). Configurações são centralizadas em `config.py`/`config.yaml` e o projeto usa um logger unificado (`src/utils/logger.py`). Operações destrutivas podem ser executadas em modo `--dry-run` para validação prévia.
Testes & CI
A base inclui testes unitários e de integração (arquivos `test_*.py` e diretório `tests/`). Recomenda-se executar a suíte com `pytest` e integrar linting e checagens estáticas no CI (Black, isort, flake8) para manter qualidade e evitar regressões.
Contribuição
Contribuições via PR devem incluir descrição clara e, quando aplicável, testes que cubram a mudança. O `Changelog` deve ser atualizado para registrar alterações relevantes seguindo o padrão datado e categorizado.

Tecnologias Utilizadas

Pillow (PIL)
Biblioteca padrão para manipulação de imagens em Python, escolhida por sua maturidade, performance e suporte completo a formatos comuns, essencial para operações básicas de carregamento, validação e transformação de imagens.
piexif
Especializada em EXIF, selecionada por sua precisão na leitura/escrita de metadados completos incluindo GPS e dados de câmera, superando limitações do Pillow básico para metadados complexos.
imagehash
Implementa algoritmos de hash perceptual (dHash, pHash), crucial para detecção de duplicatas visuais, oferecendo melhor acurácia que hashes tradicionais para imagens similares mas não idênticas.
PyYAML
Para configuração legível por humanos, escolhido por sua simplicidade e suporte a estruturas complexas, facilitando manutenção de configurações sem necessidade de interfaces gráficas.
tqdm
Barras de progresso elegantes, selecionada por sua integração perfeita com iteradores Python e suporte a nested progress bars, melhorando experiência do usuário em operações longas.
python-magic-bin
Detecção robusta de tipos MIME, essencial para validação segura de arquivos em Windows onde libmagic não está disponível nativamente, prevenindo processamento de arquivos maliciosos.
colorama
Coloração de output no terminal Windows, escolhida por sua compatibilidade cross-platform e API simples, tornando logs mais legíveis e profissional.
sqlite-utils
Utilitários leves para SQLite, selecionado por simplificar operações de banco sem adicionar complexidade, mantendo foco em dados relacionais simples.
pytest
Framework de testes moderno, escolhido por sua sintaxe intuitiva, fixtures poderosas e integração com ferramentas de CI/CD, facilitando desenvolvimento orientado a testes.
black
Formatador automático de código, selecionado por suas regras opinativas que garantem consistência, reduzindo debates sobre estilo e melhorando legibilidade do código.
pylint
Linter estático, escolhido por sua análise profunda de qualidade de código, detectando bugs potenciais e enforcing melhores práticas de Python.

Arquitetura e Estrutura Completa

19
Arquivos de Código
8
Pastas Principais
88%
Redução de Código
5
Módulos Refatorados

Estrutura de Diretórios

photo_organizer/ ├── app.py # Aplicação Flask: inicializa app, blueprints, logging e endpoints de saúde ├── main.py # CLI: parseia flags e orquestra o pipeline (scan → process → detect → organize) ├── config.yaml # Configurações do usuário (paths, regras e políticas de processamento) ├── requirements.txt # Dependências Python do projeto ├── .gitignore # Padrões de arquivos e pastas ignoradas pelo Git ├── src/ # Código-fonte principal (módulos organizados por responsabilidade) │ ├── __init__.py │ ├── routes/ # Endpoints web e API que delegam ao `core` │ │ ├── __init__.py │ │ ├── api_routes.py # Endpoints REST: iniciar jobs, status (não há endpoint de download de relatórios) │ │ └── web_routes.py # Rotas do dashboard e páginas web │ ├── processing.py # Worker de background: agendamento e execução de jobs │ ├── utils/ # Utilitários e helpers compartilhados │ │ ├── __init__.py │ │ ├── config.py # Carregamento, validação e normalização de configurações │ │ └── configs/ # Dataclasses de configuração (input/output/detection/etc.) │ │ ├── __init__.py │ │ ├── input_config.py │ │ ├── output_config.py │ │ ├── detection_config.py │ │ ├── db_config.py │ │ ├── processing_config.py │ │ ├── logging_config.py │ │ └── ui_config.py │ ├── core/ # Núcleo: leitores de metadados, scanners e hashing │ │ ├── __init__.py │ │ ├── metadata_reader.py # Fachada de EXIF/GPS: normaliza e expõe metadados para o pipeline │ │ ├── parsers/ # Parsers especializados para EXIF, GPS e datetime │ │ │ ├── __init__.py │ │ │ ├── exif_parser.py │ │ │ ├── gps_parser.py │ │ │ └── datetime_parser.py │ │ ├── file_scanner.py # Varredura de diretórios: detecta imagens e coleta informações básicas │ │ └── scanners/ # Implementações de scanners e helpers de IO │ │ ├── __init__.py │ │ ├── directory_scanner.py │ │ └── file_info.py │ ├── organization/ # Regras e ações para mover/renomear arquivos │ │ ├── __init__.py │ │ ├── file_mover.py # Coordena movimentos atômicos e resolução de conflitos │ │ └── operations/ # Operações especializadas (move, copy, quarantine) │ │ ├── __init__.py │ │ ├── file_operations.py │ │ └── stats.py │ └── detection/ # Módulo de detecção de duplicatas e similares │ ├── __init__.py │ ├── exact_duplicates.py # Duplicatas exatas (MD5) │ ├── similar_detector.py # Duplicatas perceptuais usando imagehash │ └── keep_policy.py # Políticas de retenção e regras de decisão ├── database/ # Código para gerenciar o banco de dados local │ ├── __init__.py │ └── db_manager.py # Gerenciador SQLite: conexões, migrações e queries utilitárias ├── docs/ # Documentação do projeto e guias │ ├── setup.md # Guia de instalação e configuração │ ├── architecture.md # Descrição detalhada da arquitetura e fluxos │ └── version1_documentation.html # Esta documentação interativa ├── scripts/ # Scripts utilitários para manutenção e CI │ ├── export_hashes.py # Exporta/normaliza hashes para análise externa │ ├── generate_reports.py # Gera relatórios CSV/HTML/JSON com thumbnails │ └── package_reports.py # Empacota relatórios para distribuição ou upload ├── data/ # Dados locais não versionados (banco, logs, cache) │ ├── database/ # Arquivos SQLite contendo metadados e índices │ ├── logs/ # Logs de execução e auditoria │ └── cache/ # Miniaturas e artefatos temporários ├── output/ # Resultados do processamento acessíveis para revisão │ ├── organized/ # Fotos reorganizadas por data/evento │ ├── quarantine/ # Duplicatas isoladas para revisão manual │ │ └── groups/ # Grupos de duplicatas │ └── reports/ # Relatórios CSV/HTML/JSON gerados pelo pipeline ├── tests/ # Testes automatizados (unitários e de integração) │ ├── __init__.py │ ├── test_config.py │ ├── test_logger.py │ ├── test_metadata_reader.py │ └── test_photos/ # Dados de teste e fixtures ├── venv/ # Ambiente virtual Python (local) └── .pytest_cache/ # Cache gerado pelo pytest

Raiz do Projeto

app.py
Entrypoint da aplicação Flask: inicializa a app, registra blueprints, configura logging e conexões com o banco, e expõe endpoints de saúde/monitoramento. Gerencia o ciclo de vida da aplicação web e integra os módulos de processamento para exibição e controle via dashboard.
main.py
Interface de linha de comando que parseia argumentos (ex.: --dry-run, --verbose) e orquestra o pipeline completo (scan → process → detect → organize). Gera relatórios em `output/reports`, aplica políticas de retenção e retorna códigos de saída úteis para automação/CI.

Código-Fonte (src/)

routes/
Coleção de blueprints e handlers HTTP que expõem a API e UI: endpoints para iniciar jobs, consultar status, recuperar thumbnails e baixar relatórios. Valida entrada, serializa respostas e delega lógica ao `core` para manter separação de responsabilidades.
core/
Camada de núcleo com leitores de metadados (EXIF), scanners de arquivo, e algoritmos de hashing (MD5 + perceptual). Fornece interfaces testáveis usadas por CLI, web e scripts para detecção, normalização e agregação de resultados.
organization/
Regras e operações que definem como fotos são renomeadas, organizadas e movidas (por data/evento/etiqueta). Implementa movimentos atômicos, resolução de conflitos e políticas de quarentena para duplicatas, incluindo suporte a modo dry-run.

Utilitários e Scripts

scripts/
Scripts utilitários para tarefas offline e CI: `export_hashes.py` para exportar/normalizar hashes, `generate_reports.py` para criar CSV/HTML com estatísticas e `package_reports.py` para empacotar resultados. Executáveis separadamente ou em pipelines automatizados.
docs/
Documentação do projeto com guias de instalação, diagramas de arquitetura, changelog e exemplos de configuração. Esta pasta inclui o HTML interativo, instruções para executar localmente e notas para desenvolvedores que estendem o sistema.

Dados e Output

data/
Dados locais não versionados: banco SQLite com tabelas de caminhos e hashes, diretório de logs para auditoria e um `cache/` para miniaturas e artefatos temporários. Scripts de manutenção controlam rotação e limpeza para evitar crescimento descontrolado.
output/
Resultados do processamento: `organized/` contém a estrutura final de fotos por data/evento, `quarantine/` armazena grupos de duplicatas para revisão e `reports/` guarda CSV/HTML/JSON com resumos e thumbnails para auditoria e exportação.

Erros e Dificuldades Principais

Problemas de Inicialização da Aplicação Flask

Descrição: Durante o desenvolvimento, o comando python app.py falhava repetidamente com erros de importação e inicialização, aparecendo múltiplas vezes no histórico de comandos sem sucesso.

Causa: Dependências circulares entre módulos após refatoração inicial, onde coordenadores tentavam importar módulos especializados que ainda dependiam dos coordenadores.

Solução: Reestruturação completa da arquitetura, criando fachadas limpas e removendo dependências circulares. Implementação de imports lazy e validação incremental de cada módulo.

Quebra de Arquivos Monolíticos

Descrição: Arquivos originais como app.py (336 linhas), config.py (323 linhas), metadata_reader.py (332 linhas), file_mover.py (292 linhas) e file_scanner.py (220 linhas) eram difíceis de manter e entender.

Causa: Acúmulo de responsabilidades múltiplas em arquivos únicos, violando princípio da responsabilidade única e tornando debugging complexo.

Solução: Refatoração incremental em módulos especializados: app.py reduzido para 39 linhas (88% redução), criando subpacotes como routes/, core/, organization/ com responsabilidades claras.

Manutenção de Funcionalidade Durante Refatoração

Descrição: Risco de perder funcionalidades existentes ao dividir código em módulos menores, especialmente em operações complexas como detecção de duplicatas e geração de relatórios.

Causa: Dependências implícitas entre funções que não eram óbvias, e ausência de testes automatizados durante a refatoração inicial.

Solução: Desenvolvimento de testes de integração manuais após cada etapa, verificando imports, instanciação e execução básica. Criação de fachadas que preservam interfaces públicas.

Gerenciamento de Dependências de Importação

Descrição: Após dividir módulos, imports precisavam ser atualizados em múltiplos arquivos, levando a erros de ModuleNotFoundError.

Causa: Mudanças de estrutura de pacotes sem atualização sistemática de todos os pontos de importação, especialmente em __init__.py files.

Solução: Revisão completa de todos os imports usando ferramentas de busca, padronização de imports relativos e criação de __init__.py files que expõem interfaces públicas claras.

Compatibilidade Backward em Interfaces

Descrição: Mudanças na estrutura interna poderiam quebrar código que dependia de funções ou classes públicas dos módulos originais.

Causa: Refatoração focada em estrutura interna sem considerar impacto em consumidores externos dos módulos.

Solução: Manutenção de interfaces públicas estáveis através de fachadas, documentação clara de APIs e testes de integração que validam contratos de interface.

Validação de Integridade Pós-Refatoração

Descrição: Dificuldade em garantir que todas as funcionalidades continuavam funcionando após mudanças estruturais significativas.

Causa: Falta de testes automatizados abrangentes e complexidade de validar pipeline completo (scan → process → detect → organize).

Solução: Implementação de verificações manuais sistemáticas, incluindo testes de importação, instanciação de classes principais e execução de pipeline com dados de teste. Criação de scripts de validação que podem ser executados rapidamente.

Changelog

## [1.0.0] - 2025-12-17

Adicionado (2025-12-17)

  • app.py — entrada principal do aplicativo (APIs e integração com o backend Flask).
  • Dashboard — código HTML/CSS/JS do dashboard para revisão (melhorias de layout aplicadas em atualizações).
  • file_scanner.py — varredura de diretórios e validação de tipos.
  • hash_calculator.py — módulo Hash Calculator (MD5, pHash, dHash, thresholds configuráveis).
  • file_mover.py — utilitário para mover/organizar arquivos conforme políticas.
  • folder_organizer.py — regras de organização por data/evento/tags.
  • Backend web implementado com Flask para servir o dashboard e endpoints de revisão/exportação.
  • Pipeline de organização com modo `--dry-run`. Geração de relatórios: planejada (scripts/offline), sem integração de disparo via dashboard nesta versão.

Modificado

  • Arquitetura refatorada para módulos menores (`core/`, `detection/`, `organization/`) facilitando testes e manutenção.
  • Mensagens de CLI e logs aprimorados para maior clareza em operações longas.

Corrigido

  • Correção de dependências circulares que impediam inicialização em alguns ambientes de dev.
  • Tratamento de imagens corrompidas durante import para não interromper pipelines.
  • Geração de miniaturas para imagens sem EXIF corrigida (evita exceções).

Removido

  • Removidos módulos experimentais não usados do pacote principal (módulos marcados para recriação como plugins).

Segurança

  • Validações adicionais de entrada implementadas para reduzir risco de path traversal em operações de import.

Obsoleto

  • API interna de importação legada marcada como obsoleta; será removida em v2.0.

2025-12-16

Adicionado (2025-12-16)

  • test_metadata.py — testes para validação de extração de metadados.
  • metadata_reader.py — leitor de metadados EXIF.
  • test_scanner.py — testes para o scanner de diretórios.
  • test_config.py — testes de leitura/validação de configuração.
  • config.py — arquivo de configuração centralizada.
  • logger.py — utilitário de logging consistente para o projeto.
  • test_logger.py — testes para o logger.

Observações do processo

  • As atividades de 2025-12-16 focaram em testes e infraestrutura (configurações e logging) para suportar o desenvolvimento de 2025-12-17.