Comentários em Documentos

Introdução

O Sutram oferece um poderoso sistema de comentários em documentos que permite às equipes de projeto colaborar diretamente nos documentos, posicionando comentários em locais específicos. Os comentários são ancorados em posições precisas dentro de PDFs, imagens, documentos Office, arquivos markdown e modelos CAD/BIM, possibilitando discussões contextuais sem sair da plataforma.

Principais Funcionalidades

Ancoragem Contextual: Três métodos diferentes de ancoragem dependendo do tipo de arquivo
Discussões em Threads: Responda a comentários para criar conversas encadeadas
Colaboração em Tempo Real: Veja comentários de outros usuários instantaneamente via PubSub
Suporte a Múltiplos Formatos: Funciona com PDFs, imagens, documentos Office (Word, Excel, PowerPoint), markdown e arquivos CAD/BIM
Resolução de Comentários: Marque comentários como resolvidos quando as questões forem tratadas
Marcadores Visuais: Marcadores numerados em formato de balão mostram a localização dos comentários diretamente nos documentos
Painel de Comentários: Painel inferior com filtros (Todos/Abertos/Resolvidos) para navegar e localizar comentários
Navegação: Clique nos marcadores ou itens do painel para ir até comentários específicos
Suporte a 6 Idiomas: Internacionalização completa (Inglês, Português, Espanhol, Francês, Alemão, Italiano)

Métodos de Ancoragem por Tipo de Arquivo

O sistema utiliza três métodos distintos de ancoragem dependendo do tipo de arquivo, cada um otimizado para a forma como os usuários interagem com aquele tipo de conteúdo:

1. Ancoragem Posicional (PDF e Imagens)

Usado para: Arquivos PDF, Imagens, documentos Office (convertidos para PDF)

Como funciona: O usuário clica em qualquer lugar do documento e o comentário é ancorado em coordenadas relativas (0.0-1.0).

Tipo de Arquivo	Tipo de Posição	Armazenamento	Interação do Usuário
PDF	`pdf_page`	`pdf_page_number` + `pdf_relative_x/y` (0.0-1.0)	Clique em qualquer lugar da página
Imagens	`image`	`pdf_relative_x/y` (0.0-1.0)	Clique em qualquer lugar da imagem
Office	`pdf_page`	Convertido para PDF primeiro, mesmo que PDF	Clique no PDF convertido

Vantagens:

Funciona independentemente do nível de zoom ou tamanho da janela
Posicionamento preciso em conteúdo visual
Simples e intuitivo para os usuários

Texto do botão: "Clique para adicionar..." (traduzido para 6 idiomas)

2. Ancoragem por Visualização da Câmera (CAD/BIM)

Usado para: Desenhos CAD 2D (DWG, DXF), Modelos CAD 3D (IFC, RVT, etc.)

Como funciona: O usuário clica no modelo e o comentário captura tanto as coordenadas do mundo quanto o estado da câmera (posição da vista, zoom, rotação).

Tipo de Arquivo	Tipo de Posição	Armazenamento	Interação do Usuário
CAD 3D	`aps_3d`	`aps_world_coordinates` {x,y,z} + `aps_db_id` + `aps_camera_state`	Clique na superfície do modelo 3D
CAD 2D	`aps_2d`	`aps_world_coordinates` {x,y,z} + `aps_sheet_guid` + `aps_camera_state`	Clique no desenho 2D

Vantagens:

Os marcadores acompanham o modelo durante zoom/pan/rotação
"Ir para localização" restaura exatamente a vista que o autor do comentário viu
Funciona com vistas explodidas e planos de corte
ID do elemento capturado para integrações futuras

Texto do botão: "Clique para adicionar..." (traduzido para 6 idiomas)

3. Comentários Ancorados em Texto (markdown)

Usado para: Arquivos markdown (no visualizador e no editor)

Como funciona: O usuário seleciona texto (em vez de clicar) e o comentário é ancorado ao texto selecionado com contexto circundante para resiliência contra edições.

Tipo de Arquivo	Tipo de Posição	Armazenamento	Interação do Usuário
markdown	`markdown`	`text_anchor` {exact_text, prefix, suffix} + `pdf_relative_y` (fallback)	Selecione texto para comentar

Estrutura do Text Anchor:

{
  "exact_text": "o texto selecionado",
  "prefix": "50 caracteres antes da seleção",
  "suffix": "50 caracteres após a seleção",
  "selection_length": 18
}

Vantagens:

Comentários sobrevivem a edições no documento (busca baseada em texto, não posição em pixel)
O contexto de prefixo/sufixo ajuda a encontrar o texto mesmo se a correspondência exata mudar de lugar
Destaque visual do texto comentado no visualizador
Suporte mobile com botão flutuante "Comentar"

Texto do botão: "Selecione texto..." (traduzido para 6 idiomas)

Experiência Mobile:

Dispositivo touch detectado automaticamente
O usuário faz toque longo para selecionar texto
Botão flutuante "Comentar" aparece abaixo da seleção (evita conflito com o menu nativo)
Debounce de 600ms permite que o usuário ajuste as alças de seleção antes do botão aparecer

Como Funciona

Ativando o Modo de Comentários

Abra a pré-visualização de um documento (PDF, imagem, markdown, Office ou arquivo CAD)
Clique no botão de comentários na barra de ferramentas da pré-visualização
A sobreposição é ativada e os marcadores aparecem para os comentários existentes
O Painel de Comentários aparece na parte inferior com opções de filtro

Adicionando um Comentário

A interação difere por tipo de arquivo:

PDF, Imagens, Office, CAD

Com o modo de comentários ativado, clique em Adicionar no Painel de Comentários
Clique no documento na localização desejada
Um modal aparece com um campo de texto
Digite o texto do seu comentário
Clique em Publicar Comentário para criar o comentário
Um marcador numerado aparece na localização clicada

markdown

Com o modo de comentários ativado, clique em Adicionar no Painel de Comentários
Selecione texto clicando e arrastando (desktop) ou toque longo e arraste as alças (mobile)
No desktop: o modal abre imediatamente após a seleção
No mobile: toque no botão flutuante "Comentar" que aparece abaixo da seleção
Digite o texto do seu comentário
Clique em Publicar Comentário para criar o comentário
Um marcador numerado aparece na margem esquerda, alinhado com o texto selecionado

Visualizando Comentários Existentes

Marcadores: Marcadores numerados em formato de balão mostram a localização dos comentários
- Marcadores roxos: Comentários abertos
- Marcadores verdes: Comentários resolvidos
- Badge laranja: Número de respostas
Clique no marcador: Abre o modal da thread do comentário
Painel de Comentários: Painel inferior mostrando todos os comentários
- Expandir/recolher clicando no cabeçalho
- Filtrar por status: Todos / Abertos / Resolvidos
- Clique em qualquer comentário para navegar até sua localização
Navegação: Use "Ir para localização" ou o painel para ir até os comentários

Respondendo a Comentários

Clique em um marcador de comentário existente (ou selecione no Painel de Comentários)
O modal da thread abre mostrando o comentário original e quaisquer respostas
Digite sua resposta no campo de texto
Clique em Publicar resposta para adicionar sua resposta

Resolvendo Comentários

Abra uma thread de comentário
Clique em Marcar como resolvido (botão acima da área de resposta)
O marcador fica verde para indicar a resolução
Comentários resolvidos podem ser Reabertos nas ações do modal

Excluindo Comentários

Abra uma thread de comentário
Clique no botão Excluir (visível apenas para o autor do comentário ou administrador do projeto)
Confirme a exclusão
O marcador é removido do documento

Documentos Office (Word, Excel, PowerPoint)

Arquivos Office requerem tratamento especial porque os comentários precisam de uma superfície estática para posicionamento.

Como Funciona

Configuração do projeto: "Permitir comentários em arquivos Office" deve estar habilitado
Primeira ativação: Ao clicar no botão de comentários em um arquivo Office:
- Se o PDF estiver em cache: Muda para o visualizador de PDF imediatamente
- Se não estiver em cache: Mostra o estado de carregamento "Convertendo documento..."
Conversão: O LibreOffice converte o arquivo Office para PDF (executado uma vez, cache permanente)
Resultado: O visualizador de PDF com sobreposição de comentários aparece
Badge: O badge "Modo de comentários" aparece no cabeçalho ao visualizar o PDF convertido

Configuração

Os proprietários do projeto podem habilitar comentários em arquivos Office nas Configurações do Projeto:

Navegue até Configurações > Configurações de Arquivo
Habilite "Permitir comentários em arquivos Office"
Salve as configurações

Limitações

Os comentários são posicionados na conversão PDF, não no arquivo Office original
Formatações complexas podem ser renderizadas de forma diferente no PDF
Fórmulas do Excel mostram apenas os valores calculados
Animações/transições do PowerPoint são perdidas

Arquivos CAD/BIM (Autodesk APS)

O sistema de comentários se integra completamente com o Autodesk Viewer para arquivos CAD e BIM.

Modelos 3D (IFC, RVT, etc.)

Para modelos 3D, os comentários são ancorados usando:

Coordenadas do Mundo: O ponto 3D onde o usuário clicou
ID do Elemento: O elemento específico do modelo (se o hit test for bem-sucedido)
Estado da Câmera: A posição exata da vista quando o comentário foi criado

Comportamento:

Os marcadores atualizam a posição em tempo real conforme você rotaciona/aproxima o modelo
"Ir para localização" restaura exatamente a vista da câmera de quando o comentário foi criado
Funciona com vistas explodidas e planos de corte

Desenhos 2D (DWG, DXF)

Para desenhos 2D, os comentários utilizam:

Coordenadas do Modelo: Posição em unidades do desenho (não pixels da tela)
GUID da Folha: Identifica em qual folha o comentário está

Comportamento:

Os marcadores permanecem fixos aos pontos do desenho durante zoom/pan
Eventos de mudança de câmera disparam a re-renderização dos marcadores
Funciona em diferentes níveis de zoom e posições de pan

Detalhes Técnicos

O sistema utiliza métodos do Autodesk Viewer SDK:

Operação	Método
Obter posição do clique (3D)	`viewer.impl.hitTest()`
Obter posição do clique (2D)	`viewer.clientToWorld()`
Renderizar posição do marcador	`viewer.impl.worldToClient()`
Navegar até comentário	`viewer.restoreState()`
Rastrear mudanças de câmera	Listener `CAMERA_CHANGE_EVENT`

Colaboração em Tempo Real

Os comentários são sincronizados em tempo real entre todos os usuários conectados.

Tópicos PubSub

Formato do tópico: document_comments:{content_item_id}

Eventos

Evento	Descrição
`comment_added`	Novo comentário criado por outro usuário
`comment_updated`	Comentário editado, resposta adicionada ou status alterado
`comment_deleted`	Comentário removido por outro usuário

Comportamento

Novos marcadores aparecem instantaneamente quando outros usuários adicionam comentários
Contadores de respostas são atualizados em tempo real
O status de resolução é sincronizado entre todos os visualizadores
Se estiver visualizando um comentário excluído, o modal fecha automaticamente

Interface do Usuário

Marcadores de Comentário

Os marcadores usam um design de balão de chat com um ponteiro:

   ┌───────┐
   │  1.2  │  ← Número (página.índice ou apenas índice)
   └───┬───┘
       ▽     ← Ponteiro indica a posição exata

Estilo:

Fundo: Índigo (#6366f1) para abertos, Verde (#22c55e) para resolvidos
Badge de respostas: Laranja (#f97316) círculo no canto superior direito
Efeito hover: Leve aumento de escala (1.1x)
Sombra: Sombra projetada para visibilidade em qualquer fundo

Modal de Comentário

O modal exibe:

Cabeçalho:

Nome e avatar do autor do comentário
Timestamp (relativo, ex.: "há 2 horas")
Informação de posição (ex.: "Página 3" ou "Ponto 3D")

Corpo:

Texto do comentário
Respostas (em thread, cronológicas)
Campo de texto para resposta

Ações (visualização da thread):

Marcar como resolvido: Botão acima do formulário de resposta (verde, destacado)
Publicar resposta: Botão de enviar resposta
Excluir: Ícone de lixeira (apenas autor/administrador)
Reabrir: Disponível quando o comentário está resolvido
Fechar: Dispensar modal

Arquitetura

Esquema do Banco de Dados

Tabela: document_comments

Coluna	Tipo	Descrição
`id`	UUID	Chave primária
`content`	Text	Texto do comentário
`content_item_id`	UUID	FK para content_items
`user_id`	UUID	FK para users (autor)
`project_id`	UUID	FK para projects
`parent_id`	UUID	FK para document_comments (para respostas)
`position_type`	String	`pdf_page`, `image`, `markdown`, `aps_3d`, `aps_2d`
`pdf_page_number`	Integer	Número da página (apenas PDF)
`pdf_relative_x`	Float	Posição X 0.0-1.0 (ou pixels para markdown)
`pdf_relative_y`	Float	Posição Y 0.0-1.0 (ou pixels para markdown)
`aps_world_coordinates`	Map	`{x, y, z}` para CAD
`aps_db_id`	Integer	ID do elemento Autodesk
`aps_camera_state`	Map	Estado do viewer para navegação
`aps_sheet_guid`	String	Identificador da folha 2D
`resolved`	Boolean	Status de resolução
`resolved_at`	DateTime	Quando foi resolvido
`resolved_by_id`	UUID	FK para users
`inserted_at`	DateTime	Timestamp de criação
`updated_at`	DateTime	Última modificação

Módulos Backend

Módulo	Finalidade
`Sutram.Content.DocumentComment`	Schema Ecto com validações
`Sutram.Content`	Funções CRUD para comentários
`SutramWeb.ProjectLive.Content.CommentHandler`	Handlers de eventos LiveView
`SutramWeb.ProjectLive.Components.CommentModal`	LiveComponent do modal
`SutramWeb.ProjectLive.Components.CommentsPanel`	Painel inferior com filtros
`SutramWeb.ProjectLive.Components.PreviewModal`	Pré-visualização com sobreposição

Frontend (JavaScript)

Arquivo	Finalidade
`assets/js/hooks/comment_overlay.js`	Hook principal da sobreposição
`assets/js/viewers/pdf_viewer.js`	Visualizador de PDF com rastreamento de página
`assets/js/viewers/autodesk_viewer.js`	Visualizador CAD com `getViewerInstance()`

Funções Principais

Hook CommentOverlay:

calculatePdfPosition(): Converter clique em coordenadas PDF
calculateImagePosition(): Converter clique em coordenadas de imagem
calculateMarkdownPosition(): Converter clique em coordenadas de pixel markdown
calculateApsPosition(): Converter clique em coordenadas do mundo CAD
calculateScreenPosition(): Converter posição armazenada em pixels de tela
renderMarkers(): Desenhar todos os marcadores visíveis
navigateToComment(): Rolar/ampliar até a localização do comentário

Configuração

Configurações do Projeto

Configuração	Padrão	Descrição
`allow_office_comments`	`false`	Habilitar comentários em arquivos Office

Configurações da Aplicação

Os comentários são habilitados por padrão para:

Arquivos PDF
Arquivos de imagem
Arquivos CAD (quando o APS está configurado)

Arquivos Office requerem opt-in explícito no nível do projeto devido à necessidade de conversão para PDF.

Solução de Problemas

Comentários Não Aparecem

Causa: Modo de comentários não ativado

Solução:

Clique no botão de comentários na barra de ferramentas da pré-visualização
Aguarde os marcadores serem renderizados
Verifique o console do navegador em busca de erros

Marcadores na Posição Errada

Causa: Redimensionamento ou zoom alterado após os marcadores serem renderizados

Solução:

Os marcadores se reposicionam automaticamente ao redimensionar/aplicar zoom
Se ainda estiverem errados, feche e reabra a pré-visualização

Comentários em CAD Não Salvam

Causa: Visualizador APS não totalmente carregado

Solução:

Aguarde o modelo 3D carregar completamente
Tente clicar em uma superfície visível
Verifique se o visualizador responde à navegação

Botão de Comentário em Office Ausente

Causa: Configuração do projeto não habilitada

Solução:

Vá para Configurações do Projeto > Configurações de Arquivo
Habilite "Permitir comentários em arquivos Office"
Salve e atualize a página

Referência da API

Eventos LiveView (Cliente para Servidor)

Evento	Payload	Descrição
`position_selected`	Dados de posição	Usuário clicou para adicionar comentário
`marker_clicked`	`{comment_id, marker_number}`	Usuário clicou em marcador existente
`create_comment`	`{content}`	Salvar novo comentário
`create_reply`	`{content, parent_id}`	Adicionar resposta à thread
`resolve_comment`	`{comment_id}`	Marcar como resolvido
`reopen_comment`	`{comment_id}`	Reabrir comentário resolvido
`delete_comment`	`{comment_id}`	Remover comentário
`navigate_to_comment`	`{comment_id}`	Ir para localização
`request_markers`	`{content_item_id}`	Solicitar marcadores iniciais

Eventos Push (Servidor para Cliente)

Evento	Payload	Descrição
`render_markers`	`{markers: [...]}`	Lista completa de marcadores
`add_marker`	`{marker: {...}}`	Novo marcador individual
`update_marker`	`{marker: {...}}`	Dados atualizados do marcador
`remove_marker`	`{comment_id}`	Excluir marcador
`navigate_to_comment`	`{comment: {...}}`	Disparar navegação

Histórico de Versões

Versão	Data	Alterações
v0.58.0	22/12/2025	Comentários iniciais em PDF com threads
v0.59.0	23/12/2025	Comentários no contexto do Chat
v0.60.0	24/12/2025	Suporte a comentários em imagens
v0.61.0	24/12/2025	Comentários em arquivos Office (via PDF)
v0.61.1	24/12/2025	Comentários em CAD/APS (2D e 3D)
v0.62.0	24/12/2025	Dica de onboarding em toast
v0.63.0	25/12/2025	Painel de Comentários (V3) - painel inferior com filtros e navegação
v0.64.0	26/12/2025	Suporte a comentários em markdown
v0.64.1	26/12/2025	Melhorias na interface: ações do modal reorganizadas, dica em toast removida
v0.65.0	26/12/2025	Modo de comentários no editor markdown com ajuste manual de posição
v0.65.1	29/12/2025	Suporte a seleção de texto mobile para comentários em markdown
v0.65.2	29/12/2025	Melhorias de UX: botão flutuante posicionado abaixo da seleção para evitar menu nativo
v0.65.3	29/12/2025	Internacionalização: botão flutuante "Comentar" traduzido para 6 idiomas

Painel de Comentários (V3)

O Painel de Comentários é um painel inferior que lista todos os comentários do documento, proporcionando uma experiência de navegação unificada para mobile e desktop.

Layout

O painel usa um design de painel inferior (unificado para mobile e desktop):

┌─────────────────────────────────────────────────┐
│                                                 │
│           Visualizador (PDF/Imagem/CAD)         │
│                                                 │
│                       📍                        │
│                                                 │
├─────────────────────────────────────────────────┤
│ 💬 4 comentários                            ▼  │  ← Clique expande
├─────────────────────────────────────────────────┤
│ ◉ Todos   ○ Abertos   ○ Resolvido              │  ← Filtros
├─────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ 🗨️1 👤 João · há 2h                         │ │
│ │     Verificar se a cota está correta...     │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 🗨️2 👤 Maria · há 1d                    ✅  │ │
│ │     Conflito com a estrutura existente      │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Estados

Estado	Descrição
Minimizado	Mostra apenas o cabeçalho com contagem de comentários (altura de 48px)
Expandido	Mostra filtros e lista rolável (máximo 50vh)

Funcionalidades

Alternância: Clique no cabeçalho para expandir/recolher
Filtros: Todos / Abertos / Resolvidos (botões de rádio)
Lista de Comentários: Lista rolável com marcadores em balão no mesmo estilo do canvas
Navegação: Clique em qualquer comentário para ir até sua localização (mudança de página para PDF, restauração de câmera para CAD)
Tempo real: Atualiza automaticamente via PubSub existente

Estilo do Marcador

Os comentários na lista usam o mesmo estilo de marcador em balão do canvas:

   ┌───────┐
   │   1   │  ← Número (ordem de inserção)
   └───┬───┘
       ▽     ← Ponteiro (cauda do balão de chat)

Fundo: Índigo (#6366f1) para abertos, Verde (#22c55e) para resolvidos
Badge de respostas: Laranja (#f97316) no canto superior direito
Sombra projetada: Para visibilidade

Detalhes Técnicos

Novo Componente: SutramWeb.ProjectLive.Components.CommentsPanel

Props:

comments - Lista de structs DocumentComment
expanded - Boolean (estado do painel)
filter - Atom (:all, :open, :resolved)

Eventos (enviados ao pai via send/2):

{:comments_panel, :toggle} - Alternar expandir/recolher
{:comments_panel, :filter, filter} - Mudar filtro
{:comments_panel, :go_to_comment, comment_id} - Navegar até comentário

Gerenciamento de Estado (no Content LiveView):

comments_panel_expanded - Boolean
comments_panel_filter - Atom

Modo de Comentários no Editor markdown (v0.65.0)

O editor markdown inclui um modo dedicado de comentários que permite aos usuários visualizar e reposicionar marcadores de comentário durante a edição. Isso resolve o problema em que os marcadores ficam desalinhados após editar o conteúdo markdown (já que o markdown usa coordenadas absolutas em pixels).

Dois Modos

Modo	Descrição
Edição (padrão)	Editor WYSIWYG Milkdown normal, sem marcadores visíveis
Comentários	Pré-visualização renderizada com sobreposição de comentários e painel lateral

Layout (Modo de Comentários)

┌─────────────────────────────────────────────────────────────────┐
│  ← Voltar    [Edição] [Comentários 📍3]        Upload   │ Cabeçalho │
├─────────────────────────────────────┬───────────────────────────┤
│                                     │ 💬 3 comentários           │
│   Pré-visualização markdown         │ ─────────────────────────│
│   Renderizada (somente leitura)     │ ◉ Todos ○ Abertos ○ Resolvidos │
│                                     │ ─────────────────────────│
│        📍 Marcador 1                │ [1] João · há 2h          │
│                                     │     Verificar esta seção  │
│        📍 Marcador 2                │     [Ajustar] [Ir para]   │
│                                     │ ─────────────────────────│
│                                     │ [2] Maria · há 1d    ✅   │
│                                     │     Corrigido             │
└─────────────────────────────────────┴───────────────────────────┘

Ajuste Manual de Posição

Quando o conteúdo markdown é editado, os marcadores de comentário podem ficar desalinhados porque usam coordenadas absolutas em pixels. Os usuários podem reposicionar manualmente os marcadores:

Entre no modo de Comentários no editor markdown
Encontre o comentário desalinhado no painel lateral
Clique no botão "Ajustar posição"
O cursor muda para mira, o painel lateral mostra "Clique na nova posição"
Clique na localização correta na pré-visualização
O marcador se move para a nova posição e é salvo

Restrição Mobile

Aviso: O modo de comentários não está disponível em dispositivos mobile (viewport < 768px). Uma dica no botão desabilitado explica: "Use um computador desktop para gerenciar comentários".

Detalhes Técnicos

Novos Assigns (em markdown_editor.ex):

editor_mode - Atom (:editing | :comments)
comments - Lista de structs DocumentComment
comments_panel_expanded - Boolean
comments_panel_filter - Atom (:all | :open | :resolved)
repositioning_comment_id - UUID ou nil

Novos Eventos:

toggle_editor_mode - Alternar entre os modos de edição e comentários
start_reposition - Entrar no modo de reposicionamento para um comentário específico
cancel_reposition - Sair do modo de reposicionamento
update_marker_position - Salvar nova posição a partir do clique de reposicionamento
go_to_comment - Navegar/rolar até a localização do comentário

Alterações no JavaScript (comment_overlay.js):

Adicionado estado repositioningCommentId
Adicionados handlers de evento enter_reposition_mode / exit_reposition_mode
Handler de clique modificado para detectar modo de reposicionamento e enviar update_marker_position
Seletores de elementos markdown atualizados para funcionar tanto no visualizador quanto no editor

Versão do Documento: 1.3 Última Atualização: 29 de dezembro de 2025 Autor: Equipe de Desenvolvimento Sutram