chore: seed sample video data, add spec 033 and update instructions

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

@@ -0,0 +1,144 @@
+# 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`).