# 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`).