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

specs/007-admin-panel/spec.md

@@ -0,0 +1,147 @@
+# Feature Specification: Admin Panel
+
+**Feature Branch**: `[007-admin-panel]`
+**Created**: 2026-04-13
+**Status**: Draft
+**Input**: User description: "Painel administrativo onde o admin pode criar, editar, remover e listar todos os itens do sistema: imóveis, usuários, visitas, boletos, tipos, cidades, bairros, amenidades, etc."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Gerenciar Imóveis (Priority: P1)
+
+O administrador pode criar, editar, remover e listar imóveis, com busca, filtros e paginação.
+
+**Why this priority**: Imóveis são o núcleo do sistema imobiliário; garantir controle total é essencial para o funcionamento do negócio.
+
+**Independent Test**: Testar se um admin consegue realizar todas as operações CRUD em imóveis, com validação e feedback adequado.
+
+**Acceptance Scenarios**:
+
+1. **Given** o admin autenticado, **When** acessa a lista de imóveis, **Then** vê imóveis paginados, pode buscar e filtrar.
+2. **Given** o admin na tela de criação, **When** preenche e submete o formulário, **Then** o imóvel é criado se os dados forem válidos.
+3. **Given** o admin na tela de edição, **When** altera dados e salva, **Then** as mudanças são persistidas.
+4. **Given** o admin na lista, **When** clica para remover um imóvel, **Then** vê confirmação e, ao confirmar, o imóvel é removido (com tratamento para dependências).
+
+---
+
+### User Story 2 - Gerenciar Usuários (Priority: P2)
+
+O administrador pode criar, editar, remover e listar usuários do sistema, com busca, filtros e paginação.
+
+**Why this priority**: Controle de acesso e gestão de usuários são fundamentais para segurança e operação.
+
+**Independent Test**: Testar se um admin consegue realizar todas as operações CRUD em usuários, com validação e feedback adequado.
+
+**Acceptance Scenarios**:
+
+1. **Given** o admin autenticado, **When** acessa a lista de usuários, **Then** vê usuários paginados, pode buscar e filtrar.
+2. **Given** o admin na tela de criação, **When** preenche e submete o formulário, **Then** o usuário é criado se os dados forem válidos.
+3. **Given** o admin na tela de edição, **When** altera dados e salva, **Then** as mudanças são persistidas.
+4. **Given** o admin na lista, **When** clica para remover um usuário, **Then** vê confirmação e, ao confirmar, o usuário é removido (com tratamento para dependências).
+
+---
+
+### User Story 3 - Gerenciar Visitas, Boletos, Tipos, Cidades, Bairros, Amenidades (Priority: P3)
+
+O administrador pode criar, editar, remover e listar visitas, boletos, tipos, cidades, bairros e amenidades, com busca, filtros e paginação.
+
+**Why this priority**: Permite controle total sobre entidades auxiliares e operacionais do sistema.
+
+**Independent Test**: Testar se um admin consegue realizar todas as operações CRUD nessas entidades, com validação e feedback adequado.
+
+**Acceptance Scenarios**:
+
+1. **Given** o admin autenticado, **When** acessa a lista de cada entidade, **Then** vê itens paginados, pode buscar e filtrar.
+2. **Given** o admin na tela de criação, **When** preenche e submete o formulário, **Then** o item é criado se os dados forem válidos.
+3. **Given** o admin na tela de edição, **When** altera dados e salva, **Then** as mudanças são persistidas.
+4. **Given** o admin na lista, **When** clica para remover um item, **Then** vê confirmação e, ao confirmar, o item é removido (com tratamento para dependências).
+
+---
+
+### User Story 4 - Painel Inicial com KPIs (Priority: P4)
+
+O administrador visualiza um painel inicial com indicadores-chave (quantidade de imóveis, usuários, visitas, boletos, etc).
+
+**Why this priority**: Fornece visão rápida do status do sistema e auxilia na tomada de decisão.
+
+**Independent Test**: Testar se o admin vê os KPIs corretos ao acessar o painel inicial.
+
+**Acceptance Scenarios**:
+
+1. **Given** o admin autenticado, **When** acessa o painel inicial, **Then** vê KPIs atualizados e corretos.
+
+---
+
+### User Story 5 - Segurança e Acesso (Priority: P1)
+
+Apenas administradores autenticados podem acessar o painel e suas rotas. Tentativas de acesso não autorizado são bloqueadas e exibem mensagem amigável.
+
+**Why this priority**: Segurança é crítica para evitar acesso indevido a dados sensíveis.
+
+**Independent Test**: Testar se usuários não-admin não conseguem acessar rotas do painel e recebem mensagem adequada.
+
+**Acceptance Scenarios**:
+
+1. **Given** um usuário não-admin, **When** tenta acessar qualquer rota do painel, **Then** o acesso é negado e uma mensagem amigável é exibida.
+2. **Given** um admin não autenticado, **When** tenta acessar o painel, **Then** é redirecionado para login.
+
+---
+
+### User Story 6 - Usabilidade e Navegação (Priority: P2)
+
+O painel possui navegação lateral (sidebar), breadcrumbs e design consistente com o tema Linear dark.
+
+**Why this priority**: Facilita o uso, reduz erros e melhora a experiência do usuário.
+
+**Independent Test**: Testar se a navegação é intuitiva, o tema é aplicado e breadcrumbs refletem a navegação.
+
+**Acceptance Scenarios**:
+
+1. **Given** o admin autenticado, **When** navega entre seções, **Then** a sidebar e breadcrumbs refletem corretamente o contexto.
+2. **Given** o admin autenticado, **When** acessa o painel, **Then** o tema Linear dark é aplicado em todas as telas.
+
+---
+
+## Functional Requirements
+
+1. O painel deve permitir operações CRUD completas para imóveis, usuários, visitas, boletos, tipos, cidades, bairros e amenidades.
+2. Todas as rotas do painel devem ser protegidas e acessíveis apenas por administradores autenticados.
+3. Listagens devem ser paginadas, com busca e filtros por campos relevantes.
+4. Formulários de criação/edição devem validar campos obrigatórios e opcionais, exibindo mensagens de erro amigáveis.
+5. Exclusão de entidades deve exigir confirmação e tratar dependências (ex: não permitir remoção se houver vínculos).
+6. O painel inicial deve exibir KPIs atualizados (quantidade de imóveis, usuários, visitas, boletos, etc).
+7. A interface deve ter navegação lateral (sidebar), breadcrumbs e seguir o tema Linear dark.
+8. Endpoints RESTful devem seguir o padrão /api/v1/admin/* para todas as entidades gerenciadas.
+9. Mensagens de erro devem ser claras e orientar o usuário sobre como corrigir problemas.
+10. Edge cases como tentativas de acesso não autorizado, dados inválidos e remoção de entidades com dependências devem ser tratados com feedback adequado.
+
+## Success Criteria
+
+- Admins conseguem realizar todas as operações CRUD nas entidades listadas, com feedback visual e validação.
+- Apenas admins autenticados acessam o painel; tentativas de acesso não autorizado são bloqueadas e exibem mensagem amigável.
+- Listagens apresentam paginação, busca e filtros funcionais.
+- Formulários exibem mensagens de erro claras para campos obrigatórios/invalidos.
+- Exclusão exige confirmação e previne remoção de entidades com dependências.
+- KPIs do painel inicial refletem dados reais e atualizados.
+- Navegação lateral, breadcrumbs e tema Linear dark estão presentes e funcionais.
+- Todas as rotas e endpoints seguem o padrão RESTful definido.
+- Edge cases são cobertos e testados (acesso, dados inválidos, dependências).
+
+## Key Entities
+
+- Imóvel (Property): id, título, descrição, tipo, localização, preço, status, amenidades, etc.
+- Usuário (User): id, nome, email, papel, status, etc.
+- Visita (Visit): id, imóvel, usuário, data/hora, status, etc.
+- Boleto: id, usuário, valor, status, vencimento, etc.
+- Tipo de imóvel: id, nome, descrição
+- Cidade: id, nome, estado
+- Bairro: id, nome, cidade
+- Amenidade: id, nome, descrição
+
+## Assumptions
+
+- O sistema já possui autenticação JWT e controle de papéis implementados.
+- O tema Linear dark está disponível para uso no frontend.
+- Os endpoints RESTful seguem o padrão /api/v1/admin/*.
+- Campos obrigatórios e opcionais serão definidos conforme regras de negócio já existentes.
+- Mensagens de erro e validação seguem padrões de usabilidade já adotados no sistema.