sass-imobiliaria/specs/033-video-apresentacao-imovel/spec.md

Feature Specification: Vídeo de Apresentação do Imóvel

Feature Branch: 033-video-apresentacao-imovel Created: 2026-04-22 Status: Draft

---

Contexto

A página de detalhe de imóvel oferece atualmente galeria de fotos, dados técnicos e descrição textual. Não existe suporte a vídeo — um recurso cada vez mais esperado em plataformas imobiliárias, pois vídeos de tour virtual ou apresentação aumentam o engajamento do visitante e reduzem a necessidade de visitas presenciais desnecessárias.

Esta spec cobre a adição de suporte a um vídeo de apresentação por imóvel, com configuração via painel admin e exibição na página pública de detalhe. O administrador pode escolher se o vídeo aparece integrado ao carrossel de fotos (como primeiro slide) ou em uma seção exclusiva logo abaixo do carrossel.

---

User Scenarios & Testing

User Story 1 — Administrador Configura Vídeo em um Imóvel (Priority: P1)

O administrador da imobiliária acessa o painel de edição de um imóvel, informa a URL de um vídeo (YouTube, Vimeo ou arquivo direto), escolhe onde ele será exibido na página pública e salva as alterações.

Why this priority: É o ponto de entrada de toda a feature. Sem a capacidade de configurar o vídeo no admin, nenhuma das outras histórias se torna possível.

Independent Test: Autenticar como administrador, acessar a edição de um imóvel existente, preencher o campo de URL de vídeo com uma URL válida do YouTube (ex.: https://www.youtube.com/watch?v=dQw4w9WgXcQ), selecionar a posição "Seção exclusiva de vídeo" e salvar. Verificar via API que o imóvel retorna video_url preenchido e video_position igual a "section".

Acceptance Scenarios:

1. Given um administrador autenticado na página de edição de um imóvel, When ele informa uma URL válida do YouTube e clica em "Salvar", Then o imóvel é atualizado com a URL informada e a posição padrão aplicada.
2. Given um administrador configurando o vídeo, When ele altera a posição para "No carrossel de fotos", Then o valor salvo reflete a posição selecionada.
3. Given um administrador que deseja remover o vídeo de um imóvel, When ele clica em "Remover vídeo" e confirma, Then a URL e a posição são apagadas e o imóvel volta ao estado sem vídeo.
4. Given um administrador informando uma URL do Vimeo, When ele salva o imóvel, Then a URL é persistida corretamente sem transformação ou truncamento.
5. Given um usuário não autenticado tentando editar um imóvel, When a requisição é enviada, Then o sistema retorna erro de acesso não autorizado (HTTP 401).

---

User Story 2 — Visitante Assiste ao Vídeo na Página de Detalhe (Priority: P1)

Um visitante acessa a página de detalhe de um imóvel que possui vídeo configurado e consegue assistir ao vídeo sem sair da página.

Why this priority: É o produto final entregue ao usuário final do site — a razão de existir de toda a feature. Sem a exibição correta, a configuração feita pelo admin não gera valor.

Independent Test: Acessar diretamente a URL de detalhe de um imóvel que tem video_url e video_position configurados. Verificar que o player de vídeo é exibido no local correto (carrossel ou seção separada) e que o vídeo pode ser iniciado pela interação do visitante.

Acceptance Scenarios:

1. Given um imóvel com video_position igual a "section", When um visitante acessa a página de detalhe, Then uma seção "Vídeo de Apresentação" é exibida após o carrossel de fotos, contendo o player incorporado do vídeo.
2. Given um imóvel com video_position igual a "carousel", When um visitante acessa a página de detalhe, Then o vídeo aparece como primeiro item no carrossel de fotos, antes das imagens.
3. Given um imóvel com URL do YouTube configurada, When o visitante visualiza a página, Then o vídeo é exibido como player incorporado do YouTube, sem redirecionar o visitante para outra aba ou página.
4. Given um imóvel com URL do Vimeo configurada, When o visitante visualiza a página, Then o vídeo é exibido como player incorporado do Vimeo.
5. Given um imóvel com URL de arquivo de vídeo direto (.mp4 ou .webm), When o visitante visualiza a página, Then o vídeo é exibido via player nativo do navegador.
6. Given um visitante em dispositivo móvel, When ele acessa um imóvel com vídeo, Then o player de vídeo se adapta ao layout da tela sem overflow ou quebra de layout.

---

User Story 3 — Administrador Pré-visualiza o Vídeo Antes de Salvar (Priority: P2)

O administrador informa uma URL de vídeo na interface de edição do imóvel e consegue pré-visualizar o player embutido antes de salvar as alterações.

Why this priority: Reduz erros de configuração (URL errada, vídeo equivocado) sem depender de verificação manual na página pública após o salvamento.

Independent Test: Na tela de edição de imóvel no admin, informar uma URL válida do YouTube no campo de vídeo. Verificar que um player de preview é exibido na própria tela de edição, sem necessidade de salvar.

Acceptance Scenarios:

1. Given um administrador digitando uma URL do YouTube no campo de vídeo, When a URL é reconhecida como válida, Then um player de preview é exibido abaixo do campo na mesma tela de edição.
2. Given um administrador com preview ativo, When ele altera a URL por outra URL válida, Then o preview é atualizado para refletir o novo vídeo.
3. Given um administrador digitando uma URL inválida (ex.: texto aleatório), When a URL não pode ser interpretada como vídeo, Then o preview não é exibido e nenhum erro de exceção é lançado na interface.

---

User Story 4 — Visitante Acessa Imóvel Sem Vídeo — Experiência Inalterada (Priority: P3)

Um visitante acessa um imóvel que não possui vídeo configurado e a página de detalhe exibe apenas o carrossel de fotos e as informações textuais, sem espaços vazios ou erros relacionados ao vídeo.

Why this priority: Garante que a nova feature não introduz regressão para a grande maioria dos imóveis que não terão vídeo imediatamente.

Independent Test: Acessar a URL de detalhe de qualquer imóvel que não tenha video_url configurado. Verificar que a página exibe normalmente o carrossel de fotos, dados e descrição, sem seção de vídeo vazia, sem mensagens de erro e sem degradação visual.

Acceptance Scenarios:

1. Given um imóvel sem vídeo configurado, When um visitante acessa sua página de detalhe, Then a seção "Vídeo de Apresentação" não é exibida em nenhuma parte da página.
2. Given um imóvel sem vídeo, When o carrossel de fotos é renderizado, Then o primeiro slide é uma foto (não um slide de vídeo vazio).
3. Given qualquer imóvel existente antes desta feature, When acessado após o deploy, Then sua página de detalhe se comporta exatamente como antes, sem alterações visuais indesejadas.

---

Edge Cases

• O que acontece se o administrador salvar uma URL de vídeo com espaços ou caracteres especiais não codificados? O sistema deve sanitizar a URL antes de persistir.
• O que acontece se o visitante tenta acessar um imóvel cuja URL de vídeo aponta para um vídeo removido ou privado da plataforma? O player do serviço externo (YouTube/Vimeo) exibirá sua própria mensagem de erro; a página do imóvel não deve quebrar.
• O que acontece se o visitante estiver com bloqueador de scripts que impeça o carregamento dos iframes? O layout da página não deve quebrar; o espaço do player pode ser omitido ou substituído por mensagem informativa.
• O que acontece se a URL informada for de um domínio não suportado (nem YouTube, nem Vimeo, nem extensão de vídeo)? O sistema deve ignorar o embed e não exibir o player, sem expor erros técnicos ao visitante.
• O que acontece com imóveis cujo video_url é uma string vazia após um "remover vídeo"? O sistema deve tratar string vazia e null de forma equivalente — nenhum vídeo é exibido.

---

Requirements

Functional Requirements

• FR-001: O sistema DEVE permitir ao administrador associar uma URL de vídeo a um imóvel via painel de edição.
• FR-002: O sistema DEVE aceitar URLs dos formatos: youtube.com/watch?v=, youtu.be/, youtube.com/embed/, vimeo.com/ e URLs diretas terminadas em .mp4 ou .webm.
• FR-003: O sistema DEVE permitir ao administrador selecionar a posição de exibição do vídeo: "no carrossel de fotos" (primeiro slide) ou "seção exclusiva após o carrossel".
• FR-004: O sistema DEVE permitir ao administrador remover o vídeo de um imóvel, retornando o imóvel ao estado sem vídeo.
• FR-005: O campo de vídeo DEVE ser opcional; imóveis sem vídeo configurado não devem ser afetados.
• FR-006: A página de detalhe DEVE exibir o player de vídeo incorporado (embed) quando o imóvel tiver vídeo do YouTube ou Vimeo configurado.
• FR-007: A página de detalhe DEVE exibir um player nativo de vídeo quando a URL for de um arquivo .mp4 ou .webm.
• FR-008: Quando video_position for "carrossel", o vídeo DEVE aparecer como primeiro item no carrossel, antes das fotos.
• FR-009: Quando video_position for "seção", DEVE ser exibida uma seção "Vídeo de Apresentação" após o carrossel de fotos.
• FR-010: Uma URL inválida ou de domínio não suportado NÃO DEVE causar erro de exceção ou quebra visual na página de detalhe.
• FR-011: O painel admin DEVE exibir um preview do player de vídeo em tempo real enquanto o administrador digita uma URL válida.

Key Entities

• Imóvel (Property): Entidade central da plataforma. Recebe dois novos atributos opcionais:
  • video_url: endereço do vídeo de apresentação (pode ser nulo/ausente)
  • video_position: posição de exibição do vídeo na página de detalhe — assume dois valores possíveis ("carrossel" ou "seção exclusiva"); o valor padrão é "seção exclusiva" quando não especificado

---

Success Criteria

Measurable Outcomes

• SC-001: O administrador consegue adicionar ou remover um vídeo de um imóvel em menos de 1 minuto a partir da tela de edição.
• SC-002: 100% dos imóveis com video_url válida exibem o player de vídeo correto na posição configurada, sem erros de renderização.
• SC-003: 100% dos imóveis sem video_url continuam com a página de detalhe idêntica ao estado anterior ao deploy desta feature.
• SC-004: O visitante consegue iniciar a reprodução do vídeo sem sair da página de detalhe do imóvel.
• SC-005: URLs inválidas ou de domínios não suportados não causam erros visíveis ao visitante em 100% dos casos.
• SC-006: O preview do vídeo no painel admin é exibido em menos de 3 segundos após o administrador informar uma URL válida.

---

Assumptions

• Cada imóvel suporta no máximo um vídeo nesta versão; múltiplos vídeos por imóvel estão fora do escopo.
• A validação de disponibilidade do vídeo (verificar se o link não está quebrado) não é realizada em tempo real; a responsabilidade de manter o link ativo é do administrador.
• O embed de vídeo de plataformas externas (YouTube, Vimeo) está sujeito às políticas de privacidade e cookies dessas plataformas; conformidade com LGPD referente a cookies de terceiros pode exigir ação futura independente desta feature.
• A posição padrão do vídeo, quando não especificada, é "seção exclusiva após o carrossel".
• O player de vídeo segue os padrões de responsividade já adotados no projeto (proporção 16:9, largura 100% do contêiner).
• Não há suporte a vídeo hospedado diretamente no servidor da imobiliária nesta versão; apenas links externos ou URLs de arquivos públicos.
• O endpoint admin de edição de imóvel já existente será estendido para aceitar os novos campos; não há criação de novo endpoint.
• As alterações de banco de dados (migration Alembic) seguem o padrão já estabelecido no projeto com reversibilidade garantida (upgrade/downgrade).