Feat/sprint 23 ux certification

.github/workflows/ci.yml

@@ -16,12 +16,13 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: "3.11"
+        cache: 'pip'
 
     - name: Instalar Dependências
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
-        pip install pytest-mock
+        pip install pytest-mock pytest-qt
 
     - name: Executar Testes Unitários
       run: |
@@ -30,3 +31,11 @@ jobs:
     - name: Executar Testes de Integração
       run: |
         pytest tests/integration
+
+    - name: Executar Testes de Interface (GUI)
+      run: |
+        pytest tests/gui
+
+    - name: Executar Testes BDD
+      run: |
+        pytest tests/bdd

.github/workflows/release.yml

@@ -21,6 +21,7 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: "3.11"
+        cache: 'pip'
 
     - name: Extrair e Validar Versão (Centro de Verdade)
       id: version_check

.gitignore

@@ -1,72 +1,64 @@
-# Python
+# --- Python & Environment ---
 __pycache__/
 *.py[cod]
 *$py.class
 *.so
 .Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# Virtual Environments
-.env
 .venv
-env/
 venv/
+env/
 ENV/
-env.bak/
-venv.bak/
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
+*.bak/
+.env
 
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
+# --- Build & Distribution ---
+build/
+dist/
+out/
+foton.spec
+foton_v1.0.0.spec
+*.egg-info/
+.eggs/
+*.egg
 
-# IDEs and Editors
-.obsidian/
-.idea/
+# --- IDEs & Editors ---
 .vscode/
+.idea/
+.obsidian/
 *.swp
 *.swo
 *~
 .directory
-
-# Operating System
 Thumbs.db
 Desktop.ini
 .DS_Store
-.AppleDouble
-.LSOverride
-._*
 
-# Project specific
+# --- Logs & Test Artifacts ---
 *.log
-tmp/
-.obsidian/workspace.json
+logs/
+build_log.txt
+.coverage
+.coverage.*
+coverage.xml
+coverage_report.txt
+htmlcov/
+.pytest_cache/
+pytest_*.txt
+test_results.*
+tests_failed*.txt
+output.log
+pytest_output.txt
+pytest_full_output.txt
+pytest_final_output.txt
+
+# --- Project Specific Artifacts ---
+stage_state.db
+# Manter PDFs de teste manuais fora do repo para evitar volume desnecessário
+manual_test*.pdf
+test_complex.pdf
+test_layers.pdf
+test_multi_page.pdf
+
+# --- Documentation ---
+# Permitir docs mas ignorar capturas pesadas se necessário
+docs/visuals/captures/

CONTRIBUTING.md

@@ -48,6 +48,9 @@ Siga os padrões do projeto ([[docs/DEVELOPMENT|Guia de Desenvolvimento]]).
 
 ```bash
 pytest                        # Todos os testes
+# Recomendado (com PYTHONPATH):
+# $env:PYTHONPATH = ".;src"; pytest
+
 pytest tests/unit            # Apenas unitários
 pytest --cov=src             # Com cobertura
 ```
@@ -88,7 +91,7 @@ mypy src/
 
 ### Estrutura de Commits
 
-```
+```text
 tipo(escopo): descrição curta
 
 Descrição detalhada do que foi feito e por quê.
@@ -110,8 +113,12 @@ Closes #123
 ### Estrutura
 
 - `tests/unit/`: Testes rápidos, sem I/O
-- `tests/integration/`: Testes com bibliotecas reais
-- `tests/e2e/`: Testes de ponta a ponta
+- `tests/integration/`: Testes com bibliotecas reais e integração de adaptadores
+- `tests/gui/`: Testes de unidade e integridade para widgets PyQt6
+- `tests/e2e/`: Testes de ponta a ponta (instalação e fluxos do SO)
+
+> [!NOTE]
+> Testes de GUI que dependem de renderização complexa (como Shadow Effects) são ignorados automaticamente em ambientes **Headless** (CI/CD) para evitar deadlocks, mas devem ser validados localmente.
 
 ### Exemplo de Teste
 

LLM_CONTEXT.md

@@ -16,10 +16,12 @@ Este arquivo serve como a "Memória de Longo Prazo" para qualquer IA assistente
 4. **I/O Assíncrono:** Todas as operações de processamento de PDF devem ser executadas em threads separadas para não bloquear a UI.
 5. **Resiliência de UI (Boundaries):** Todas as callbacks críticas do Qt na `MainWindow` ou widgets complexos devem ser decoradas com `@safe_ui_callback` para garantir que exceções locais não derrubem o processo principal.
 6. **Filosofia Senior (Obrigatório):**
-   - **DRY (Don't Repeat Yourself):** Reutilize código, centralize lógicas comuns nos domínios.
-   - **CLEAN Code:** Código legível, nomes auto-explicativos e funções com responsabilidade única.
-   - **SOLID:** Princípios de design para garantir escalabilidade e facilitar manutenção.
-   - **Centros de Verdade:** Centralize definições e lógicas críticas em locais únicos. Exemplo: `src/__init__.py` é o único centro de verdade para a versão da aplicação, validado pelo pipeline de CD.
+    - **DRY (Don't Repeat Yourself):** Reutilize código, centralize lógicas comuns nos domínios.
+    - **CLEAN Code:** Código legível, nomes auto-explicativos e funções com responsabilidade única.
+    - **SOLID:** Princípios de design para garantir escalabilidade e facilitar manutenção.
+    - **Centros de Verdade:** Centralize definições e lógicas críticas em locais únicos. Exemplo: `src/__init__.py` é o único centro de verdade para a versão da aplicação, validado pelo pipeline de CD.
+    - **Precisão Geométrica (AEC):** Todas as medidas visíveis ao usuário devem ser processadas em Milímetros (mm). O `GeometryService` é o mediador obrigatório entre coordenadas de PDF (Points) e a interface.
+    - **Identidade de Marca (UI/UX):** O branding (Solar Gold, Deep Space) e o uso proeminente da logo (`docs/brand/logo.svg`) devem ser reforçados em todos os componentes principais de interface (Top Toolbar, Splash Screen).
 
 ## 📝 Documentação e Rastreamento (Crucial)
 
@@ -37,6 +39,7 @@ Sempre que gerar um commit, siga este template rigorosamente:
 2. **Base:** Analise o output de `git status` e `git diff`.
 3. **Detalhamento:** Liste as alterações relevantes.
 4. **Sincronização de Docs:** Sempre após o commit de desenvolvimento do código, realize uma verificação da documentação para registrar, compatibilizar e documentar o avanço do trabalho (ROADMAP, SPRINTS, DASHBOARD).
+5. **Workflow IA-UI (AIAD):** Para tarefas de interface, siga rigorosamente o [[docs/guides/AIAD_WORKFLOW|Guide de Workflow AIAD]], utilizando loops de snapshot e validação via hot-reload.
 
 **Formato:**
 
@@ -58,14 +61,21 @@ Arquivos alterados:
 - **Tipagem:** Python Type Hints são OBRIGATÓRIOS em todas as funções públicas.
 - **Logs:** Usar o módulo `logging` estruturado (JSON format).
 
-## 📂 Estrutura de Diretórios
+- `scripts/`: Ferramentas auxiliares (Build, Icons, Signing, UI Capture).
+- `scripts/hot_reload.py`: **Ferramenta Primária de Dev**. Use para validar mudanças na GUI.
+- `scripts/dev_gui_view.py` e `scripts/dev_mocks.py`: Infraestrutura de design e testes visuais (Mocks).
+- `scripts/capture_concept.py`: Utilitário para capturar screenshots do mockup HTML.
 
-- `src/domain`: Entidades puras e protocolos (Portas).
-- `src/application`: Casos de uso e orquestração (ex: `UpdateService`).
-- `src/infrastructure`: Implementações concretas (Adapters de Registro, Notificação e PDF).
-- `src/interfaces`: UI, CLI e integração com Menu de Contexto (Setup e Uninstall Wizards).
+## 🚀 Como Executar e Validar (Para LLMs)
 
-## 🔗 Navegação e Referências
+Para testar mudanças na interface ou lógica, use sempre o hot-reload:
+
+1. **Validar Design/UI:** `python scripts/hot_reload.py --mode mock`
+2. **Validar Fluxo Real:** `python scripts/hot_reload.py --mode app`
+3. **Capturar Referência Visual (Mockup):** `python scripts/capture_concept.py`
+
+> [!IMPORTANT]
+> O hot-reload abre a interface imediatamente e reinicia ao detectar mudanças. Sempre use esta ferramenta para comprovar que suas alterações não quebraram a renderização ou o comportamento da MainWindow.
 
 - **🗺️ Mapa da Documentação:** [[docs/MAP|MAP.md]] (MOC Central)
 - **🏗️ Arquitetura Detalhada:** [[docs/ARCHITECTURE|ARCHITECTURE.md]]

README.md

@@ -39,6 +39,9 @@ Se você deseja apenas usar o software e não é desenvolvedor, acesse:
 - **Integração Nativa:** Menus organizados com prefixo `fotonPDF ▸` para PDFs.
 - **Operações Inteligentes:** Girar, Juntar e Separar com **timestamps automáticos** para evitar sobrescritas.
 - **Visualizador Fóton:** Janela de pré-visualização ultrarrápida (PyQt6) com suporte a abertura direta via CLI.
+- **Navegação Universal:** `ModernNavBar` com transparência dinâmica, submenus colapsáveis e atalhos estilo Okular.
+- **Mesa de Luz Profissional:** Visualização de páginas como objetos físicos com zoom focado no mouse e renderização Hi-Res.
+- **Suporte A0/A1:** Tiling inteligente para grandes formatos de engenharia sem travar a memória.
 - **Resiliência Industrial:** Infraestrutura de "Error Boundaries" que mantém o app estável mesmo sob falhas críticas de UI.
 - **Estabilidade:** Distribuição otimizada em modo diretório para performance máxima.
 

docs/00_Start/DASHBOARD.md

@@ -0,0 +1,100 @@
+# 🎛️ Dashboard do Projeto
+
+> **Central de Comando**: Visão executiva do estado atual do **fotonPDF**
+
+## 📊 Status Geral
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#4CAF50'}}}%%
+pie title Cobertura da Documentação
+    "Completos" : 25
+    "Pendentes (Fase 4)" : 1
+```
+
+## 🚦 Semáforo de Progresso
+
+| Fase | Status | Progresso | Deadline |
+| --- | --- | --- | --- |
+| **Fase 1: Fundação** | 🟢 Completo | ████████████ 100% | Finalizada ✅ |
+| **Fase 2: Interface & Func.** | 🟢 Completo | ████████████ 100% | 20/01/2026 ✅ |
+| **Fase 3: Ecossistema** | 🟢 Completo | ████████████ 100% | 23/01/2026 ✅ |
+| **Fase 3.5: Navegação Premium** | 🟢 Completo | ████████████ 100% | 27/01/2026 ✅ |
+| **Fase 4: Plugins** | 🏗️ Em Progresso | [██░░░░░░░░░░░░░░░░░░] 10% | Prev. Fev/2026 |
+| **Q&A: Cobertura 90%** | 🟢 Completo | ████████████ 100% | 24/01/2026 ✅ |
+
+### Sprint 22 (Concluído) ✅
+
+- [x] Menu Lúdico v2 🎨
+- [x] Extração Pro (Assíncrona) 📄
+- [x] Reordenação Espacial na Mesa de Luz 📐
+- [x] Viewport Dinâmica (Fix Rotação) 🔄
+- [x] Resolução de Identidade Virtual (Fix de Reordenação) 🔗
+- [x] Correção de Visibilidade da Sidebar e Batch Loading (Fix Crítico) 🛠️
+- [x] Lógica de Limpeza de Estado UI (Fix TabContainer / Single-Document V4) 🧹
+- [x] Zoom por Área (RubberBand) 🔍
+- [x] Renderização Assíncrona da Primeira Página ⚡
+- [x] Testes E2E e Robustez para Navegação 🧪
+- [x] Estabilidade 100% e Preparação para Merge `develop` 🚀
+
+### Sprint 23 (Concluído) ✅
+
+- [x] Testes de Física Interativa (Drag-and-Drop, RubberBand) 🎯
+- [x] Zoom Cirúrgico e Recuperação de Qualidade Pós-Zoom 🔍
+- [x] Navegação por Teclado na Mesa de Luz ⌨️
+- [x] Validação da Command Palette (Filtragem, Estrutura) 🎨
+- [x] 40 Testes Automatizados Premium UX 🧪
+- [x] 0 RuntimeError de C++ nas simulações de mouse 🛡️
+
+### Sprint 21 (Concluído) ✅
+
+- [x] ModernNavBar com Transparência Dinâmica 🎨
+- [x] NavHub (Volante de Controle) 🎮
+- [x] Atalhos Estilo Okular ⌨️
+- [x] Zoom Focado no Mouse 🎯
+- [x] Mesa de Luz Hi-Res 📐
+- [x] Suporte A0/A1 (Tiling) 🏗️
+
+### Sprint 20 (Concluído) ✅
+
+- [x] Stabilized Test Infrastructure 🧪
+- [x] Windows Registry Mock Adapter 🛠️
+- [x] UI Widget Unit Tests (TopBar, Canvas) 🎨
+- [x] 90%+ Coverage Achievement 🚀
+
+### Sprint 10 (Concluído) ✅
+
+- [x] Settings Service (Persistência) 💾
+- [x] Modos de Leitura (Sépia/Noite/Invertido) 👁️
+- [x] Dual-View Layout 📖
+- [x] Anotações Básicas (Highlight) ✍️
+- [x] Refinamento Estético & Glow Effects ✨
+
+### Sprint 7 (Concluído) ✅
+
+- [x] Detecção inteligente de PDFs sem camada de texto 🔍
+- [x] Aplicação de OCR Tesseract em documento completo 📄
+- [x] Extração interativa de área via mouse (On-demand) ✂️
+- [x] Banner proativo de sugestão de OCR 🔔
+
+## 🧩 Módulos Implementados
+
+```mermaid
+gantt
+    title Cronograma de Implementação de Módulos
+    dateFormat  YYYY-MM-DD
+    section Core
+    Domain Entities       :a1, 2026-01-18, 3d
+    PyMuPDF Adapter       :a2, after a1, 4d
+    OCR & Tesseract       :a3, 2026-01-20, 2d
+    section UI
+    Navigation Sidebar    :c1, 2026-01-19, 2d
+    Reading Modes & Dual-View :c2, 2026-01-20, 1d
+    Settings & Persistence :c3, 2026-01-20, 1d
+```
+
+---
+
+**Última atualização:** 2026-02-21  
+**Próxima revisão:** Início da Fase 4
+
+[[MAP|← Voltar ao Mapa]] | [[REPORT|📊 Ver Relatório Completo]]