# Implementation Plan: Vídeo de Apresentação do Imóvel

**Branch**: `033-video-apresentacao-imovel` | **Data**: 2026-04-22 | **Spec**: [spec.md](spec.md)  
**Input**: [specs/033-video-apresentacao-imovel/spec.md](spec.md)

## Summary

Adicionar suporte a um vídeo de apresentação por imóvel: o administrador configura a URL (YouTube, Vimeo ou arquivo direto) e escolhe se o vídeo aparece integrado ao carrossel de fotos ou em seção exclusiva abaixo dele. A implementação consiste em uma migration Alembic (+2 colunas), extensões mínimas nos schemas Pydantic e no handler de update existente no backend, e três artefatos novos no frontend (`getEmbedUrl`, `VideoPlayer`, modificação do `PhotoCarousel`).

---

## Technical Context

**Language/Version**: Python 3.12 (backend) · TypeScript 5.5 (frontend)  
**Primary Dependencies**: Flask 3.x, SQLAlchemy 2.x, Pydantic v2, Alembic (backend) · React 18, Tailwind CSS 3.4 (frontend) — **sem novas dependências**  
**Storage**: PostgreSQL 16 — tabela `properties` recebe `video_url VARCHAR(512) NULL` e `video_position VARCHAR(20) NOT NULL DEFAULT 'section'`  
**Testing**: pytest (backend) · testes manuais via browser (frontend)  
**Target Platform**: Web SPA (React) + REST API (Flask)  
**Project Type**: Web application — SaaS imobiliária  
**Performance Goals**: Preview do vídeo no admin ≤ 3s (SC-006); página de detalhe não deve sofrer regressão de performance (vídeo só carrega quando configurado)  
**Constraints**: Sem novas dependências npm; sem ENUM SQL (usar VARCHAR + validação Pydantic); `iframe` com `loading="lazy"` para não bloquear LCP  
**Scale/Scope**: Feature aditiva — 1 migration, 1 utilitário, 1 componente, modificações pontuais em 6 arquivos existentes

---

## Constitution Check

| Princípio | Status | Notas |
|-----------|--------|-------|
| **I. Design-First** | ✅ PASSA | `VideoPlayer` usa `aspect-[16/9]`, `rounded-xl`, cores `bg-panel border border-white/5` do design system; nenhum estilo inline fora do sistema |
| **II. Separation of Concerns** | ✅ PASSA | Backend persiste URL bruta; parse/transform de embed é 100% client-side; contrato REST documentado em `contracts/api.md` |
| **III. Spec-Driven** | ✅ PASSA | spec.md aprovado → plan.md → tasks.md → implementação; ordem respeitada |
| **IV. Data Integrity** | ✅ PASSA | Migration Alembic com `upgrade`/`downgrade`; campos declarados com nullable explícito; Pydantic `Literal` para `video_position`; sanitização de URL antes de persistir |
| **V. Security** | ✅ PASSA | Endpoint admin protegido por `@require_admin`; sem secrets no frontend; `video_url` é dado público sem impacto de segurança; `iframe` com `allow` explícito |
| **VI. Simplicity First** | ✅ PASSA | Sem novas dependências; helper puro sem estado; modificação do carrossel existente em vez de criar novo; YAGNI respeitado (1 vídeo por imóvel) |

---

## Project Structure

### Documentation (esta feature)

```text
specs/033-video-apresentacao-imovel/
├── plan.md          ← este arquivo
├── research.md      ← decisões técnicas documentadas
├── data-model.md    ← modelo de dados e migration
├── quickstart.md    ← guia de setup e teste
├── contracts/
│   └── api.md       ← contratos REST + utilitários frontend
└── tasks.md         ← gerado por /speckit.tasks (próximo passo)
```

### Source Code — Arquivos Afetados

```text
backend/
├── migrations/versions/
│   └── k3l4m5n6o7p8_add_video_to_properties.py    [NOVO]
├── app/
│   ├── models/
│   │   └── property.py                              [MODIFICADO]
│   ├── schemas/
│   │   └── property.py                              [MODIFICADO]
│   └── routes/
│       └── admin.py                                 [MODIFICADO]

frontend/src/
├── utils/
│   └── getEmbedUrl.ts                               [NOVO]
├── components/
│   └── PropertyDetail/
│       ├── VideoPlayer.tsx                          [NOVO]
│       └── PhotoCarousel.tsx                        [MODIFICADO]
├── pages/
│   ├── PropertyDetailPage.tsx                       [MODIFICADO]
│   └── admin/
│       └── PropertyForm.tsx                         [MODIFICADO]
└── types/
    └── property.ts                                  [MODIFICADO]
```

---

## Implementation Phases

### Fase 1 — Backend (sem frontend)

#### 1.1 Migration Alembic

**Arquivo**: `backend/migrations/versions/k3l4m5n6o7p8_add_video_to_properties.py`

```python
"""add video to properties

Revision ID: k3l4m5n6o7p8
Revises: j2k3l4m5n6o7
Create Date: 2026-04-22
"""
from alembic import op
import sqlalchemy as sa

revision = 'k3l4m5n6o7p8'
down_revision = 'j2k3l4m5n6o7'
branch_labels = None
depends_on = None

def upgrade() -> None:
    op.add_column('properties',
        sa.Column('video_url', sa.String(512), nullable=True))
    op.add_column('properties',
        sa.Column('video_position', sa.String(20),
                  nullable=False, server_default='section'))

def downgrade() -> None:
    op.drop_column('properties', 'video_position')
    op.drop_column('properties', 'video_url')
```

#### 1.2 Model — `backend/app/models/property.py`

Adicionar após `created_at`:

```python
video_url = db.Column(db.String(512), nullable=True)
video_position = db.Column(db.String(20), nullable=False, server_default='section')
```

#### 1.3 Schema público — `backend/app/schemas/property.py`

Adicionar campos em `PropertyDetailOut`:

```python
class PropertyDetailOut(PropertyOut):
    address: str | None = None
    code: str | None = None
    description: str | None = None
    video_url: str | None = None
    video_position: Literal['carousel', 'section'] = 'section'
```

#### 1.4 Schema admin + handler — `backend/app/routes/admin.py`

**`PropertyAdminOut`** — adicionar campos:
```python
video_url: str | None = None
video_position: Literal['carousel', 'section'] = 'section'
```

**`PropertyAdminOut.from_prop`** — adicionar no `return cls(...)`:
```python
video_url=p.video_url,
video_position=p.video_position,
```

**`admin_update_property`** — adicionar `'video_position'` em `_SCALAR_FIELDS` e, fora do loop, o tratamento de `video_url`:

```python
# Após o loop de _SCALAR_FIELDS:
if 'video_url' in body:
    raw = body['video_url']
    prop.video_url = raw.strip() if raw and raw.strip() else None
```

> **Nota**: `video_position` entra em `_SCALAR_FIELDS` normalmente. `video_url` precisa de tratamento fora do loop para sanitização (strip + string vazia → None).

---

### Fase 2 — Frontend Utilitário + Componente Base

#### 2.1 `frontend/src/utils/getEmbedUrl.ts` — NOVO

```ts
export type VideoType = 'youtube' | 'vimeo' | 'direct' | 'unknown'

export interface EmbedResult {
  type: VideoType
  embedUrl: string | null
}

export function getEmbedUrl(url: string): EmbedResult {
  const trimmed = url.trim()
  if (!trimmed) return { type: 'unknown', embedUrl: null }

  // YouTube — watch, youtu.be, embed
  const ytWatch = trimmed.match(
    /(?:youtube\.com\/watch\?(?:.*&)?v=|youtu\.be\/)([A-Za-z0-9_-]{11})/
  )
  if (ytWatch) {
    return { type: 'youtube', embedUrl: `https://www.youtube.com/embed/${ytWatch[1]}` }
  }
  if (/youtube\.com\/embed\/[A-Za-z0-9_-]{11}/.test(trimmed)) {
    return { type: 'youtube', embedUrl: trimmed }
  }

  // Vimeo
  const vimeoMatch = trimmed.match(/vimeo\.com\/(\d+)/)
  if (vimeoMatch) {
    return { type: 'vimeo', embedUrl: `https://player.vimeo.com/video/${vimeoMatch[1]}` }
  }
  if (/player\.vimeo\.com\/video\/\d+/.test(trimmed)) {
    return { type: 'vimeo', embedUrl: trimmed }
  }

  // Arquivo direto
  if (/\.(mp4|webm)(\?.*)?$/i.test(trimmed)) {
    return { type: 'direct', embedUrl: trimmed }
  }

  return { type: 'unknown', embedUrl: null }
}
```

#### 2.2 `frontend/src/components/PropertyDetail/VideoPlayer.tsx` — NOVO

```tsx
import { getEmbedUrl } from '../../utils/getEmbedUrl'

interface VideoPlayerProps {
  url: string
  className?: string
}

export default function VideoPlayer({ url, className = '' }: VideoPlayerProps) {
  const { type, embedUrl } = getEmbedUrl(url)

  if (!embedUrl) return null

  const wrapperClass =
    `relative w-full aspect-[16/9] rounded-xl overflow-hidden bg-panel border border-white/5 ${className}`

  if (type === 'direct') {
    return (
      <div className={wrapperClass}>
        <video
          src={embedUrl}
          controls
          className="absolute inset-0 w-full h-full"
          title="Vídeo de apresentação do imóvel"
        />
      </div>
    )
  }

  return (
    <div className={wrapperClass}>
      <iframe
        src={embedUrl}
        className="absolute inset-0 w-full h-full"
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
        allowFullScreen
        loading="lazy"
        title="Vídeo de apresentação do imóvel"
      />
    </div>
  )
}
```

---

### Fase 3 — Frontend Integração

#### 3.1 `frontend/src/types/property.ts`

Adicionar em `PropertyDetail`:
```ts
export interface PropertyDetail extends Property {
  address: string | null
  code: string | null
  description: string | null
  video_url: string | null                      // NOVO
  video_position: 'carousel' | 'section'        // NOVO
}
```

#### 3.2 `frontend/src/components/PropertyDetail/PhotoCarousel.tsx`

**Mudanças necessárias**:

1. Importar `VideoPlayer` e `getEmbedUrl`.
2. Adicionar `videoUrl?: string | null` em `PhotoCarouselProps`.
3. Calcular `hasVideo = !!videoUrl && getEmbedUrl(videoUrl).type !== 'unknown'`.
4. `totalSlides = hasVideo ? photos.length + 1 : photos.length`.
5. Ajustar `prev`/`next` para usar `totalSlides`.
6. No slot de renderização do slide ativo: se `hasVideo && activeIndex === 0` → `<VideoPlayer url={videoUrl} />`; caso contrário → `<img>` atual com índice ajustado `photos[hasVideo ? activeIndex - 1 : activeIndex]`.
7. No strip de thumbnails: inserir no início (quando `hasVideo`) um botão com ícone de play para o slide de vídeo.
8. Contador `{activeIndex + 1} / {totalSlides}`.

> **Garantia de regressão**: quando `videoUrl` é `null`/`undefined`, `hasVideo = false` e nenhuma lógica nova é exercida — comportamento idêntico ao atual.

#### 3.3 `frontend/src/pages/PropertyDetailPage.tsx`

Substituir o uso atual do carrossel:

```tsx
{/* Carousel + vídeo integrado (posição carousel) */}
<PhotoCarousel
  photos={property.photos}
  videoUrl={property.video_position === 'carousel' ? property.video_url : null}
/>

{/* Seção de vídeo (posição section) */}
{property.video_url && property.video_position === 'section' && (
  <div>
    <h2 className="text-base font-semibold text-textPrimary mb-3">
      Vídeo de Apresentação
    </h2>
    <VideoPlayer url={property.video_url} />
  </div>
)}
```

> Adicionar import de `VideoPlayer` no topo do arquivo.

#### 3.4 `frontend/src/pages/admin/PropertyForm.tsx`

No formulário de edição, após o campo `description`, adicionar bloco de configuração de vídeo:

1. **Campo URL**: `<input type="url">` — label "URL do vídeo", placeholder `https://youtube.com/watch?v=...`
2. **Select posição**: `<select>` — opções "Seção exclusiva (após carrossel)" (`section`) e "Integrado ao carrossel" (`carousel`); desabilitado quando `video_url` está vazio
3. **Botão remover**: visível apenas quando `video_url` tem valor; zera `video_url` e reseta `video_position` para `'section'`
4. **Preview inline**: debounce de 600ms; quando `getEmbedUrl(debouncedUrl).type !== 'unknown'`, renderiza `<VideoPlayer url={debouncedUrl} className="mt-3" />`

**Campos adicionados ao estado/payload do form**:
```ts
video_url: string        // '' = sem vídeo
video_position: 'carousel' | 'section'
```

---

## Complexity Tracking

Nenhuma violação da constituição detectada. Sem justificativas necessárias.

---

## Checklist de Verificação Pré-Merge

- [ ] `alembic upgrade head` executa sem erro; `alembic downgrade -1` reverte sem erro
- [ ] Imóveis existentes (sem `video_url`) continuam com página de detalhe inalterada
- [ ] URL do YouTube: player embed exibido na posição correta
- [ ] URL do Vimeo: player embed exibido na posição correta
- [ ] URL `.mp4`: player nativo exibido
- [ ] URL inválida/desconhecida: sem seção de vídeo, sem erro no console
- [ ] String vazia via admin → `video_url = null` na API
- [ ] `video_position = 'carousel'`: vídeo como slide 0 no carrossel
- [ ] `video_position = 'section'`: seção "Vídeo de Apresentação" após carrossel
- [ ] Preview admin exibe player com ≤ 600ms de debounce
- [ ] Layout mobile (< 768px) sem overflow
- [ ] Nenhuma nova dependência npm adicionada