feat: add full project - backend, frontend, docker, specs and configs

.specify/features/002-docker-setup/spec.md

@@ -0,0 +1,93 @@
+# Feature Specification: Docker Setup
+
+**Feature Branch**: `002-docker-setup`
+**Created**: 2026-04-13
+**Status**: Approved
+
+## User Scenarios & Testing
+
+### User Story 1 — Desenvolvedor sobe todo o ambiente com um comando (Priority: P1)
+
+Um desenvolvedor que acabou de clonar o repositório deve conseguir subir PostgreSQL, backend Flask e frontend React rodando juntos com um único comando, sem instalar Python ou Node localmente.
+
+**Why this priority**: É o bloqueio zero de onboarding. Sem isso, cada dev configura manualmente, gerando ambientes inconsistentes.
+
+**Independent Test**: Executar `docker-compose up --build` na raiz e acessar `http://localhost:5173` deve exibir a homepage carregando dados do backend.
+
+**Acceptance Scenarios**:
+
+1. **Given** o repositório recém-clonado com Docker instalado, **When** o dev roda `docker-compose up --build`, **Then** os três serviços (db, backend, frontend) sobem sem erro e ficam acessíveis.
+2. **Given** o ambiente rodando, **When** o dev acessa `http://localhost:5173`, **Then** a homepage é renderizada com dados reais do banco.
+3. **Given** o ambiente rodando, **When** o dev acessa `http://localhost:5000/api/v1/homepage-config`, **Then** a API retorna JSON 200 com os dados seedados.
+4. **Given** o ambiente rodando, **When** o dev faz uma alteração num arquivo `.tsx`, **Then** o Vite hot-reload atualiza o browser sem reiniciar o container.
+
+---
+
+### User Story 2 — Script de conveniência na raiz (Priority: P1)
+
+Um desenvolvedor Windows deve poder rodar `.\start.ps1` na raiz para ter o ambiente de um clique, sem memorizar comandos Docker.
+
+**Why this priority**: Reduz fricção para devs Windows que são o público principal.
+
+**Independent Test**: `.\start.ps1` executa `docker-compose up --build` e exibe mensagens de status claras.
+
+**Acceptance Scenarios**:
+
+1. **Given** Docker Desktop instalado, **When** o dev roda `.\start.ps1`, **Then** o script valida que Docker está rodando e executa o compose.
+2. **Given** Docker não instalado, **When** o dev roda `.\start.ps1`, **Then** o script exibe mensagem clara pedindo para instalar Docker Desktop.
+
+---
+
+### Edge Cases
+
+- O que acontece se a porta 5432/5000/5173 já estiver em uso? → `docker-compose` retorna erro; o script deve informar.
+- O que acontece se o banco ainda não estiver pronto quando o backend inicializar? → `depends_on` com `healthcheck`; backend deve aguardar ou fazer retry.
+- Como rodar as migrations no primeiro boot? → Entrypoint do backend executa `flask db upgrade` antes de `python run.py`.
+
+## Requirements
+
+### Functional
+- FR1: `docker-compose up --build` na raiz sobe 3 serviços: `db` (PostgreSQL 16), `backend` (Flask), `frontend` (React/Vite)
+- FR2: Backend aguarda PostgreSQL estar saudável antes de inicializar (healthcheck)
+- FR3: Backend executa `flask db upgrade` + seeder automaticamente no primeiro boot
+- FR4: Frontend tem hot-reload via bind mount do código-fonte
+- FR5: Variáveis de ambiente devem estar em `.env` na raiz (não hardcoded no compose)
+- FR6: `.\start.ps1` na raiz é o ponto de entrada único para Windows
+
+### Non-Functional
+- NFR1: `docker-compose up --build` deve completar em menos de 5 min com cache
+- NFR2: Imagens devem usar variantes slim/alpine para minimizar tamanho
+- NFR3: Nenhuma secret hardcoded nas imagens — tudo via env vars
+- NFR4: `.env` não deve ser commitado; `.env.example` deve existir
+
+## Design / Architecture
+
+```
+raiz/
+├── docker-compose.yml       ← orchestração dos 3 serviços
+├── .env.example             ← template de variáveis (db, secret key)
+├── .env                     ← valores locais (gitignored)
+├── start.ps1                ← script Windows de conveniência
+├── backend/
+│   └── Dockerfile           ← python:3.12-slim, uv, flask
+└── frontend/
+    └── Dockerfile           ← node:20-alpine, vite dev server
+```
+
+**Serviços docker-compose:**
+- `db`: postgres:16-alpine, volume persistente, healthcheck
+- `backend`: build ./backend, porta 5000, DATABASE_URL apontando para `db`
+- `frontend`: build ./frontend, porta 5173, bind mount src/ para hot-reload, proxy vite → backend
+
+## Out of Scope
+- Build de produção (multi-stage, nginx servindo static) — feature futura
+- CI/CD pipeline
+- Deploy em cloud
+- HTTPS/TLS local
+
+## Success Criteria
+1. `docker-compose up --build` funciona do zero em máquina limpa
+2. `http://localhost:5173` carrega homepage com dados reais
+3. `http://localhost:5000/api/v1/properties?featured=true` retorna array JSON com imóveis seedados
+4. Alteração em `.tsx` reflete no browser sem restart do container
+5. `.env` está no `.gitignore`; `.env.example` documenta todas as variáveis necessárias