AgrSis Docs
Referência Histórica

PLANO DE DESENVOLVIMENTO - FRONTEND ADMIN AGRSIS

Data: 2025-01-12 Versão: 1.0 Objetivo: Documento completo de planejamento para desenvolvimento do frontend administrativo do AgrSis

PLANO DE DESENVOLVIMENTO - FRONTEND ADMIN AGRSIS

Data: 2025-01-12 Versão: 1.0 Objetivo: Documento completo de planejamento para desenvolvimento do frontend administrativo do AgrSis

📋 ÍNDICE

  1. Visão Geral
  2. Stack Tecnológica
  3. Estrutura de Pastas
  4. Componentes Reutilizáveis
  5. Módulos Funcionais
  6. Sistema de Autenticação
  7. Dashboard Principal
  8. Gestão de Usuários
  9. Gestão de Produtores
  10. Gestão de Fornecedores
  11. Gestão de Licitações
  12. Gestão de Propostas
  13. Gestão de Produtos
  14. Relatórios e Analytics
  15. Sistema de Logs
  16. Configurações do Sistema
  17. Permissões e ACL
  18. Roadmap de Implementação

1. VISÃO GERAL

1.1 Objetivo

O Frontend Admin é a interface administrativa do AgrSis onde os administradores gerenciam toda a plataforma:

  • 👥 Gestão de usuários (produtores, fornecedores, admins)
  • 📊 Dashboards e relatórios completos
  • 🔍 Auditoria e logs de sistema
  • ⚙️ Configurações gerais da plataforma
  • 📦 Gestão de licitações e propostas
  • 🏷️ Catálogo de produtos (hierarquia N1-N2-N3)
  • 🔐 Controle de permissões e ACL

1.2 Personas

Admin Master:

  • Acesso total ao sistema
  • Gerencia outros admins
  • Configura parâmetros globais
  • Visualiza todos os logs

Admin Operacional:

  • Gerencia produtores e fornecedores
  • Acompanha licitações
  • Gera relatórios
  • Suporte aos usuários

Admin Financeiro:

  • Visualiza transações
  • Aprova pagamentos
  • Gera relatórios financeiros

2. STACK TECNOLÓGICA

2.1 Framework e Bibliotecas

{
  "nuxt": "^4.2.1",
  "vue": "^3.5.25",
  "@pinia/nuxt": "^0.11.3",
  "pinia": "^3.0.4",
  "pinia-plugin-persistedstate": "^4.7.1",
  "@heroicons/vue": "^2.2.0",
  "@vueuse/core": "^14.1.0",
  "@tanstack/vue-table": "^8.11.3",
  "@tanstack/vue-virtual": "^3.13.18",
  "date-fns": "^4.1.0",
  "chart.js": "^4.4.7",
  "vue-chartjs": "^5.3.3",
  "apexcharts": "^3.61.0",
  "vue3-apexcharts": "^1.6.3"
}

2.2 Decisões de Arquitetura

✅ Base no Frontend Supplier:

  • Estrutura mais madura (Pinia, composables organizados)
  • Sistema de toast e error handler
  • Melhor padrão de API consumption (useApi)

✅ Componentes de Ambos:

  • StatusBadge, ToastContainer (supplier)
  • TopNav, StateCitySelect (producer)
  • Design System unificado

✅ Novos Recursos:

  • Tabelas avançadas (TanStack Table)
  • Charts (ApexCharts)
  • Export para Excel/PDF
  • Bulk operations
  • Advanced filters

3. ESTRUTURA DE PASTAS

apps/admin/
├── assets/
│   └── css/
│       └── main.css                    # Design system + utilities
├── components/
│   ├── layout/
│   │   ├── AdminSidebar.vue           # Sidebar navigation
│   │   ├── AdminTopNav.vue            # Top navigation bar
│   │   ├── AdminBreadcrumb.vue        # Breadcrumb trail
│   │   └── AdminFooter.vue            # Footer
│   ├── dashboard/
│   │   ├── MetricCard.vue             # Cards de métricas
│   │   ├── RevenueChart.vue           # Gráfico de receita
│   │   ├── OrdersChart.vue            # Gráfico de licitações
│   │   ├── UsersChart.vue             # Gráfico de usuários
│   │   ├── ActivityTimeline.vue       # Timeline de atividades
│   │   └── QuickActions.vue           # Ações rápidas
│   ├── users/
│   │   ├── UserTable.vue              # Tabela de usuários
│   │   ├── UserFilters.vue            # Filtros
│   │   ├── UserForm.vue               # Formulário CRUD
│   │   ├── UserDetailsModal.vue       # Modal de detalhes
│   │   └── UserStatusBadge.vue        # Badge de status
│   ├── producers/
│   │   ├── ProducerTable.vue
│   │   ├── ProducerFilters.vue
│   │   ├── ProducerForm.vue
│   │   ├── ProducerDetailsModal.vue
│   │   └── ProducerAddressList.vue
│   ├── suppliers/
│   │   ├── SupplierTable.vue
│   │   ├── SupplierFilters.vue
│   │   ├── SupplierForm.vue
│   │   ├── SupplierDetailsModal.vue
│   │   └── SupplierProductsList.vue
│   ├── orders/
│   │   ├── OrderTable.vue
│   │   ├── OrderFilters.vue
│   │   ├── OrderDetailsCard.vue
│   │   ├── OrderTimeline.vue
│   │   └── OrderItemsList.vue
│   ├── proposals/
│   │   ├── ProposalTable.vue
│   │   ├── ProposalFilters.vue
│   │   ├── ProposalDetailsCard.vue
│   │   └── ProposalComparison.vue
│   ├── products/
│   │   ├── ProductTypeTable.vue       # N1
│   │   ├── ProductSubtypeTable.vue    # N2
│   │   ├── ProductTable.vue           # N3
│   │   ├── ProductForm.vue
│   │   └── ProductHierarchy.vue       # Visualização hierárquica
│   ├── reports/
│   │   ├── ReportBuilder.vue
│   │   ├── ReportFilters.vue
│   │   ├── ReportChart.vue
│   │   └── ExportButtons.vue
│   ├── logs/
│   │   ├── LogTable.vue
│   │   ├── LogFilters.vue
│   │   └── LogDetailsModal.vue
│   ├── settings/
│   │   ├── GeneralSettings.vue
│   │   ├── EmailSettings.vue
│   │   ├── PaymentSettings.vue
│   │   └── NotificationSettings.vue
│   └── ui/
│       ├── DataTable.vue              # Tabela reutilizável
│       ├── SearchInput.vue
│       ├── DateRangePicker.vue
│       ├── StatusBadge.vue
│       ├── LoadingSpinner.vue
│       ├── EmptyState.vue
│       ├── ConfirmDialog.vue
│       ├── ToastContainer.vue
│       ├── ToastItem.vue
│       ├── Pagination.vue
│       ├── BulkActions.vue
│       └── ExportButton.vue
├── composables/
│   ├── useAuth.ts                     # Autenticação admin
│   ├── useApi.ts                      # API wrapper
│   ├── useToast.ts                    # Sistema de notificações
│   ├── useErrorHandler.ts             # Tratamento de erros
│   ├── useFormValidation.ts           # Validação
│   ├── usePermissions.ts              # Controle de permissões
│   ├── useExport.ts                   # Export Excel/PDF
│   ├── useDashboard.ts                # Dashboard data
│   ├── useUsers.ts                    # Gestão de usuários
│   ├── useProducers.ts                # Gestão de produtores
│   ├── useSuppliers.ts                # Gestão de fornecedores
│   ├── useOrders.ts                   # Gestão de licitações
│   ├── useProposals.ts                # Gestão de propostas
│   ├── useProducts.ts                 # Gestão de produtos
│   ├── useLogs.ts                     # Logs do sistema
│   └── useSettings.ts                 # Configurações
├── layouts/
│   ├── default.vue                    # Layout principal (sidebar + content)
│   └── auth.vue                       # Layout de login
├── middleware/
│   ├── auth.ts                        # Middleware de autenticação
│   └── permissions.ts                 # Middleware de permissões
├── pages/
│   ├── index.vue                      # Redirect para /dashboard
│   ├── login.vue                      # Login admin
│   ├── dashboard.vue                  # Dashboard principal
│   ├── users/
│   │   ├── index.vue                  # Lista de usuários
│   │   ├── [id].vue                   # Detalhes do usuário
│   │   └── new.vue                    # Criar usuário
│   ├── producers/
│   │   ├── index.vue
│   │   ├── [id].vue
│   │   └── new.vue
│   ├── suppliers/
│   │   ├── index.vue
│   │   ├── [id].vue
│   │   └── new.vue
│   ├── orders/
│   │   ├── index.vue
│   │   └── [id].vue
│   ├── proposals/
│   │   ├── index.vue
│   │   └── [id].vue
│   ├── products/
│   │   ├── types/
│   │   │   ├── index.vue              # Lista N1
│   │   │   └── [id].vue               # Editar N1
│   │   ├── subtypes/
│   │   │   ├── index.vue              # Lista N2
│   │   │   └── [id].vue               # Editar N2
│   │   └── index.vue                  # Lista N3
│   ├── reports/
│   │   ├── index.vue                  # Dashboard de relatórios
│   │   ├── orders.vue                 # Relatório de licitações
│   │   ├── proposals.vue              # Relatório de propostas
│   │   ├── users.vue                  # Relatório de usuários
│   │   └── financial.vue              # Relatório financeiro
│   ├── logs/
│   │   ├── index.vue                  # Lista de logs
│   │   └── [id].vue                   # Detalhes do log
│   └── settings/
│       ├── index.vue                  # Dashboard de configurações
│       ├── general.vue
│       ├── email.vue
│       ├── payment.vue
│       └── notifications.vue
├── stores/
│   ├── auth.ts                        # Store de autenticação
│   ├── dashboard.ts                   # Store de dashboard
│   ├── users.ts                       # Store de usuários
│   ├── producers.ts                   # Store de produtores
│   ├── suppliers.ts                   # Store de fornecedores
│   ├── orders.ts                      # Store de licitações
│   ├── proposals.ts                   # Store de propostas
│   ├── products.ts                    # Store de produtos
│   └── settings.ts                    # Store de configurações
├── types/
│   ├── auth.ts
│   ├── user.ts
│   ├── producer.ts
│   ├── supplier.ts
│   ├── order.ts
│   ├── proposal.ts
│   ├── product.ts
│   ├── log.ts
│   └── settings.ts
├── utils/
│   ├── formatters.ts                  # Formatação (CPF, CNPJ, moeda, data)
│   ├── validators.ts                  # Validações
│   ├── helpers.ts                     # Helpers gerais
│   └── constants.ts                   # Constantes
├── plugins/
│   ├── toast.client.ts
│   ├── error-handler.client.ts
│   └── permissions.client.ts
├── nuxt.config.ts
├── tailwind.config.js
└── package.json

4. COMPONENTES REUTILIZÁVEIS

4.1 Componentes de UI Base

DataTable.vue

Funcionalidades:

  • Sorting (ASC/DESC)
  • Pagination (client/server-side)
  • Filtering
  • Bulk selection (checkbox)
  • Bulk actions
  • Column visibility toggle
  • Export (CSV/Excel/PDF)
  • Responsive (mobile-first)
  • Virtual scrolling (listas grandes)

Props:

interface DataTableProps {
  columns: ColumnDef[]
  data: any[]
  loading?: boolean
  pagination?: PaginationConfig
  sortable?: boolean
  filterable?: boolean
  selectable?: boolean
  bulkActions?: BulkAction[]
  exportable?: boolean
}

StatusBadge.vue

Mapeamento Completo:

const statusMap = {
  // Usuários
  ativo: { color: 'green', label: 'Ativo' },
  inativo: { color: 'red', label: 'Inativo' },
  pendente: { color: 'yellow', label: 'Pendente' },
  bloqueado: { color: 'red', label: 'Bloqueado' },

  // Licitações
  rascunho: { color: 'gray', label: 'Rascunho' },
  publicada: { color: 'blue', label: 'Publicada' },
  em_andamento: { color: 'yellow', label: 'Em Andamento' },
  encerrada: { color: 'green', label: 'Encerrada' },
  cancelada: { color: 'red', label: 'Cancelada' },
  suspensa: { color: 'orange', label: 'Suspensa' },

  // Propostas
  enviada: { color: 'blue', label: 'Enviada' },
  em_analise: { color: 'yellow', label: 'Em Análise' },
  vencedora: { color: 'green', label: 'Vencedora' },
  aceita: { color: 'green', label: 'Aceita' },
  rejeitada: { color: 'red', label: 'Rejeitada' },

  // Pagamentos
  pago: { color: 'green', label: 'Pago' },
  vencido: { color: 'red', label: 'Vencido' }
}

ToastContainer & ToastItem

Tipos:

  • success (verde)
  • error (vermelho)
  • warning (amarelo)
  • info (azul)
  • loading (spinner)

API:

const toast = useToast()

toast.success('Operação realizada com sucesso!')
toast.error('Erro ao processar')
toast.loading('Carregando...')
toast.promise(promise, {
  loading: 'Processando...',
  success: 'Concluído!',
  error: 'Erro ao processar'
})

4.2 Componentes de Layout

AdminSidebar.vue

Navegação:

const navigation = [
  {
    name: 'Dashboard',
    icon: HomeIcon,
    href: '/dashboard',
    badge: null
  },
  {
    name: 'Usuários',
    icon: UsersIcon,
    href: '/users',
    badge: '12'
  },
  {
    name: 'Produtores',
    icon: UserGroupIcon,
    href: '/producers'
  },
  {
    name: 'Fornecedores',
    icon: BuildingStorefrontIcon,
    href: '/suppliers'
  },
  {
    name: 'Licitações',
    icon: ClipboardDocumentListIcon,
    href: '/orders',
    children: [
      { name: 'Todas', href: '/orders' },
      { name: 'Ativas', href: '/orders?status=ativa' },
      { name: 'Encerradas', href: '/orders?status=encerrada' }
    ]
  },
  {
    name: 'Propostas',
    icon: DocumentTextIcon,
    href: '/proposals'
  },
  {
    name: 'Produtos',
    icon: CubeIcon,
    href: '/products',
    children: [
      { name: 'Tipos (N1)', href: '/products/types' },
      { name: 'Subtipos (N2)', href: '/products/subtypes' },
      { name: 'Produtos (N3)', href: '/products' }
    ]
  },
  {
    name: 'Relatórios',
    icon: ChartBarIcon,
    href: '/reports'
  },
  {
    name: 'Logs',
    icon: DocumentMagnifyingGlassIcon,
    href: '/logs'
  },
  {
    name: 'Configurações',
    icon: Cog6ToothIcon,
    href: '/settings'
  }
]

AdminTopNav.vue

Elementos:

  • Logo AgrSis
  • Breadcrumb
  • Search global (⌘K)
  • Notificações (dropdown)
  • Menu de usuário (dropdown)
    • Perfil
    • Configurações
    • Logout

5. MÓDULOS FUNCIONAIS

5.1 Módulo: Dashboard Principal

Métricas Principais:

interface DashboardMetrics {
  totalUsers: number
  activeUsers: number
  totalProducers: number
  totalSuppliers: number
  totalOrders: number
  activeOrders: number
  totalProposals: number
  acceptedProposals: number
  revenue: number
  revenueGrowth: number
}

Gráficos:

  1. Receita Mensal (Line Chart)
    • Últimos 12 meses
    • Comparação com ano anterior
  2. Licitações por Status (Pie Chart)
    • Ativas, Encerradas, Canceladas
  3. Novos Cadastros (Bar Chart)
    • Produtores vs Fornecedores
    • Últimos 30 dias
  4. Top Produtos (Bar Chart)
    • Produtos mais solicitados
    • Top 10

Timeline de Atividades:

  • Últimas 20 ações no sistema
  • Filtro por tipo de ação
  • Filtro por usuário

5.2 Módulo: Gestão de Usuários

Funcionalidades:

  • ✅ Listar todos os usuários (produtores + fornecedores + admins)
  • ✅ Filtros: tipo, status, data de cadastro
  • ✅ Busca: nome, email, CPF/CNPJ
  • ✅ Ordenação: nome, email, data
  • ✅ Criar novo usuário (produtor/fornecedor/admin)
  • ✅ Editar usuário
  • ✅ Ativar/Desativar usuário
  • ✅ Bloquear/Desbloquear usuário
  • ✅ Visualizar detalhes completos
  • ✅ Histórico de ações do usuário
  • ✅ Export para Excel/CSV

Endpoints da API:

GET    /api/v1/admin/users              # Listar (com filtros)
GET    /api/v1/admin/users/{id}         # Detalhes
POST   /api/v1/admin/users              # Criar
PUT    /api/v1/admin/users/{id}         # Editar
PATCH  /api/v1/admin/users/{id}/status  # Alterar status
DELETE /api/v1/admin/users/{id}         # Deletar (soft delete)
GET    /api/v1/admin/users/{id}/logs    # Histórico

Campos do Formulário:

interface UserForm {
  // Básico
  name: string
  email: string
  phone: string
  user_type: 'produtor' | 'fornecedor' | 'admin'

  // Documento
  document_type: 'cpf' | 'cnpj'
  document_number: string

  // Status
  status: 'ativo' | 'inativo' | 'bloqueado'
  email_verified: boolean

  // Senha (somente criação)
  password?: string
  password_confirmation?: string

  // Endereço (produtor/fornecedor)
  addresses?: Address[]
}

Validações:

  • Email único
  • CPF/CNPJ único e válido
  • Senha forte (8+ chars, número, maiúscula)
  • Telefone válido
  • Pelo menos 1 endereço (produtor/fornecedor)

5.3 Módulo: Gestão de Produtores

Funcionalidades:

  • ✅ Listar todos os produtores
  • ✅ Filtros: status, cidade, estado, data cadastro
  • ✅ Busca: nome, email, CPF/CNPJ, propriedade
  • ✅ Ordenação: nome, data, licitações criadas
  • ✅ Visualizar detalhes completos
  • ✅ Editar informações
  • ✅ Gerenciar endereços
  • ✅ Visualizar licitações criadas
  • ✅ Histórico de ações
  • ✅ Export para Excel/CSV

Endpoints da API:

GET    /api/v1/admin/producers              # Listar
GET    /api/v1/admin/producers/{id}         # Detalhes
PUT    /api/v1/admin/producers/{id}         # Editar
GET    /api/v1/admin/producers/{id}/orders  # Licitações
GET    /api/v1/admin/producers/{id}/logs    # Histórico

Informações Específicas:

interface ProducerDetails extends User {
  // Propriedade
  property_name: string
  property_size: number // hectares

  // Culturas
  cultures: Culture[]

  // Endereços
  addresses: Address[]
  primary_address: Address

  // Estatísticas
  stats: {
    totalOrders: number
    activeOrders: number
    totalSpent: number
    avgOrderValue: number
  }

  // Licitações
  orders: Order[]
}

5.4 Módulo: Gestão de Fornecedores

Funcionalidades:

  • ✅ Listar todos os fornecedores
  • ✅ Filtros: status, cidade, estado, data cadastro
  • ✅ Busca: nome, email, CPF/CNPJ, empresa
  • ✅ Ordenação: nome, data, propostas enviadas
  • ✅ Visualizar detalhes completos
  • ✅ Editar informações
  • ✅ Gerenciar endereços
  • ✅ Gerenciar produtos oferecidos
  • ✅ Visualizar propostas enviadas
  • ✅ Histórico de ações
  • ✅ Export para Excel/CSV

Endpoints da API:

GET    /api/v1/admin/suppliers                # Listar
GET    /api/v1/admin/suppliers/{id}           # Detalhes
PUT    /api/v1/admin/suppliers/{id}           # Editar
GET    /api/v1/admin/suppliers/{id}/proposals # Propostas
GET    /api/v1/admin/suppliers/{id}/products  # Produtos oferecidos
GET    /api/v1/admin/suppliers/{id}/logs      # Histórico

Informações Específicas:

interface SupplierDetails extends User {
  // Empresa
  company_name: string
  company_document: string // CNPJ

  // Endereços
  addresses: Address[]
  primary_address: Address

  // Produtos Oferecidos
  productTypes: ProductType[]  // N1

  // Estatísticas
  stats: {
    totalProposals: number
    acceptedProposals: number
    totalRevenue: number
    avgProposalValue: number
    winRate: number // % de propostas aceitas
  }

  // Propostas
  proposals: Proposal[]
}

5.5 Módulo: Gestão de Licitações

Funcionalidades:

  • ✅ Listar todas as licitações
  • ✅ Filtros: status, produtor, data, valor, localização
  • ✅ Busca: ID, título, produtor
  • ✅ Ordenação: data, valor, status
  • ✅ Visualizar detalhes completos
  • ✅ Timeline de eventos
  • ✅ Visualizar itens solicitados
  • ✅ Visualizar propostas recebidas
  • ✅ Comparação de propostas
  • ✅ Histórico de alterações
  • ✅ Export para Excel/CSV/PDF

Endpoints da API:

GET    /api/v1/admin/orders                  # Listar
GET    /api/v1/admin/orders/{id}             # Detalhes
GET    /api/v1/admin/orders/{id}/items       # Itens
GET    /api/v1/admin/orders/{id}/proposals   # Propostas
GET    /api/v1/admin/orders/{id}/timeline    # Timeline
GET    /api/v1/admin/orders/{id}/logs        # Histórico

Detalhes da Licitação:

interface OrderDetails {
  // Básico
  id: number
  title: string
  description: string
  status: OrderStatus

  // Produtor
  producer: Producer

  // Datas
  created_at: string
  published_at: string
  deadline: string
  closed_at: string

  // Itens
  items: OrderItem[]
  total_items: number

  // Propostas
  proposals: Proposal[]
  total_proposals: number
  accepted_proposal?: Proposal

  // Localização
  delivery_address: Address
  delivery_radius: number

  // Timeline
  events: TimelineEvent[]
}

Status da Licitação:

enum OrderStatus {
  RASCUNHO = 'rascunho',
  PUBLICADA = 'publicada',
  EM_ANDAMENTO = 'em_andamento',
  ENCERRADA = 'encerrada',
  CANCELADA = 'cancelada',
  SUSPENSA = 'suspensa'
}

Timeline de Eventos:

  • Criada
  • Publicada
  • Primeira proposta recebida
  • Deadline alcançado
  • Proposta aceita
  • Encerrada
  • Cancelada/Suspensa

5.6 Módulo: Gestão de Propostas

Funcionalidades:

  • ✅ Listar todas as propostas
  • ✅ Filtros: status, fornecedor, licitação, data
  • ✅ Busca: ID, fornecedor, licitação
  • ✅ Ordenação: data, valor, status
  • ✅ Visualizar detalhes completos
  • ✅ Comparar propostas da mesma licitação
  • ✅ Visualizar itens e preços
  • ✅ Histórico de alterações
  • ✅ Export para Excel/CSV/PDF

Endpoints da API:

GET    /api/v1/admin/proposals              # Listar
GET    /api/v1/admin/proposals/{id}         # Detalhes
GET    /api/v1/admin/proposals/{id}/items   # Itens
GET    /api/v1/admin/proposals/{id}/logs    # Histórico
GET    /api/v1/admin/proposals/compare      # Comparar (query: ids[])

Detalhes da Proposta:

interface ProposalDetails {
  // Básico
  id: number
  order_id: number
  supplier_id: number
  status: ProposalStatus

  // Fornecedor
  supplier: Supplier

  // Licitação
  order: Order

  // Datas
  created_at: string
  submitted_at: string
  accepted_at: string
  rejected_at: string

  // Valores
  items: ProposalItem[]
  subtotal: number
  discount_percent: number
  discount_value: number
  total: number

  // Observações
  notes: string
  rejection_reason?: string

  // Documentos
  attachments: Attachment[]
}

Status da Proposta:

enum ProposalStatus {
  RASCUNHO = 'rascunho',
  ENVIADA = 'enviada',
  EM_ANALISE = 'em_analise',
  VENCEDORA = 'vencedora',
  ACEITA = 'aceita',
  REJEITADA = 'rejeitada',
  CANCELADA = 'cancelada'
}

Comparação de Propostas:

  • Tabela lado a lado
  • Destaque de melhor preço por item
  • Total comparativo
  • Prazo de entrega
  • Condições de pagamento

5.7 Módulo: Gestão de Produtos

Hierarquia de Produtos:

N1 - ProductType (Tipo)
  └─ N2 - ProductSubtype (Subtipo)
       └─ N3 - Product (Produto)

Exemplo:

Defensivos Agrícolas (N1)
  └─ Herbicidas (N2)
       ├─ Glifosato 480g/L (N3)
       ├─ Atrazina 500g/L (N3)
       └─ 2,4-D 670g/L (N3)
  └─ Inseticidas (N2)
       ├─ Lambda-Cialotrina 50g/L (N3)
       └─ Imidacloprido 200g/L (N3)

5.7.1 Gestão de Tipos (N1)

Funcionalidades:

  • ✅ Listar todos os tipos
  • ✅ Criar novo tipo
  • ✅ Editar tipo
  • ✅ Deletar tipo (se não tiver subtipos)
  • ✅ Visualizar subtipos vinculados
  • ✅ Ordenação alfabética

Endpoints:

GET    /api/v1/product-types
POST   /api/v1/product-types
GET    /api/v1/product-types/{id}
PUT    /api/v1/product-types/{id}
DELETE /api/v1/product-types/{id}

Campos:

interface ProductType {
  id: number
  name: string
  description: string
  active: boolean
  subtypes_count: number
  created_at: string
  updated_at: string
}

5.7.2 Gestão de Subtipos (N2)

Funcionalidades:

  • ✅ Listar todos os subtipos
  • ✅ Filtrar por tipo (N1)
  • ✅ Criar novo subtipo
  • ✅ Editar subtipo
  • ✅ Deletar subtipo (se não tiver produtos)
  • ✅ Visualizar produtos vinculados

Endpoints:

GET    /api/v1/product-subtypes
GET    /api/v1/product-types/{id}/subtypes
POST   /api/v1/product-subtypes
GET    /api/v1/product-subtypes/{id}
PUT    /api/v1/product-subtypes/{id}
DELETE /api/v1/product-subtypes/{id}

Campos:

interface ProductSubtype {
  id: number
  product_type_id: number
  name: string
  description: string
  active: boolean
  products_count: number
  type: ProductType  // Relacionamento
  created_at: string
  updated_at: string
}

5.7.3 Gestão de Produtos (N3)

Funcionalidades:

  • ✅ Listar todos os produtos
  • ✅ Filtrar por tipo (N1) e subtipo (N2)
  • ✅ Busca: nome, marca, princípio ativo
  • ✅ Criar novo produto
  • ✅ Editar produto
  • ✅ Deletar produto
  • ✅ Ativar/Desativar produto
  • ✅ Import em massa (CSV/Excel)
  • ✅ Export para Excel/CSV

Endpoints:

GET    /api/v1/products
GET    /api/v1/product-subtypes/{id}/products
POST   /api/v1/products
GET    /api/v1/products/{id}
PUT    /api/v1/products/{id}
DELETE /api/v1/products/{id}
POST   /api/v1/products/import

Campos:

interface Product {
  id: number
  product_subtype_id: number
  name: string
  description: string
  brand: string
  active_ingredient: string
  concentration: string
  unit: 'L' | 'KG' | 'UN'
  active: boolean
  subtype: ProductSubtype  // Relacionamento
  type: ProductType        // Relacionamento via subtype
  created_at: string
  updated_at: string
}

Visualização Hierárquica:

  • Tree view com expansão/collapse
  • Navegação breadcrumb
  • Filtros em cada nível

5.8 Módulo: Relatórios e Analytics

Tipos de Relatórios:

5.8.1 Relatório de Licitações

  • Total de licitações (período)
  • Por status
  • Por produtor
  • Por região (estado/cidade)
  • Ticket médio
  • Tempo médio de fechamento
  • Taxa de conversão (propostas/licitações)

Gráficos:

  • Licitações por mês (line chart)
  • Licitações por status (pie chart)
  • Top 10 produtores (bar chart)
  • Licitações por região (map chart)

5.8.2 Relatório de Propostas

  • Total de propostas (período)
  • Por status
  • Por fornecedor
  • Taxa de aceitação
  • Ticket médio
  • Desconto médio

Gráficos:

  • Propostas por mês (line chart)
  • Taxa de aceitação (line chart)
  • Top 10 fornecedores (bar chart)

5.8.3 Relatório de Usuários

  • Total de usuários (produtores + fornecedores)
  • Novos cadastros (período)
  • Usuários ativos
  • Taxa de ativação
  • Churn rate
  • Por região

Gráficos:

  • Crescimento de usuários (line chart)
  • Usuários por tipo (pie chart)
  • Usuários por região (bar chart)

5.8.4 Relatório Financeiro

  • Receita total (período)
  • Receita por mês
  • Receita por tipo de plano
  • Ticket médio
  • LTV (Lifetime Value)
  • Churn

Gráficos:

  • Receita mensal (line chart)
  • MRR (Monthly Recurring Revenue) (line chart)
  • Receita por plano (pie chart)

Filtros Globais:

  • Período (data inicial/final)
  • Produtor/Fornecedor específico
  • Região (estado/cidade)
  • Status

Export:

  • Excel (.xlsx)
  • CSV (.csv)
  • PDF (.pdf)

5.9 Módulo: Sistema de Logs

Tipos de Logs:

5.9.1 Logs de Autenticação

  • Login/Logout
  • Falhas de login
  • Alteração de senha
  • Redefinição de senha

5.9.2 Logs de Ações

  • CRUD de usuários
  • CRUD de licitações
  • CRUD de propostas
  • CRUD de produtos
  • Alterações de status
  • Uploads de arquivos

5.9.3 Logs de Sistema

  • Erros de API
  • Jobs/Queues
  • Webhooks
  • Integrações externas

Estrutura do Log:

interface Log {
  id: number
  user_id: number
  user: User
  action: string          // 'created', 'updated', 'deleted', 'status_changed'
  resource_type: string   // 'User', 'Order', 'Proposal', 'Product'
  resource_id: number
  old_values: any         // JSON
  new_values: any         // JSON
  ip_address: string
  user_agent: string
  created_at: string
}

Funcionalidades:

  • ✅ Listar todos os logs
  • ✅ Filtros: usuário, ação, recurso, data
  • ✅ Busca: IP, user agent
  • ✅ Visualizar detalhes (diff de valores)
  • ✅ Export para CSV

Endpoints:

GET    /api/v1/admin/logs                # Listar
GET    /api/v1/admin/logs/{id}           # Detalhes
GET    /api/v1/admin/users/{id}/logs     # Logs de um usuário
GET    /api/v1/admin/orders/{id}/logs    # Logs de uma licitação

5.10 Módulo: Configurações do Sistema

Categorias de Configurações:

5.10.1 Configurações Gerais

  • Nome do sistema
  • Logo
  • Favicon
  • Timezone
  • Idioma padrão
  • Moeda

5.10.2 Configurações de Email

  • Servidor SMTP
  • Porta
  • Usuário/Senha
  • De (nome e email)
  • Templates de email

5.10.3 Configurações de Pagamento

  • Banco Inter (credenciais)
  • Webhook URL
  • Dias para vencimento
  • Multa/Juros

5.10.4 Configurações de Notificações

  • WhatsApp (Z-API)
    • Ativo/Inativo
    • Número de teste
    • Templates

5.10.5 Configurações de Integrações

  • OpenRouteService (geocoding)
  • HubDev (validação CPF/CNPJ)
  • ViaCEP

Estrutura:

interface SystemSettings {
  // Gerais
  app_name: string
  app_logo: string
  app_favicon: string
  timezone: string
  locale: string
  currency: string

  // Email
  mail_host: string
  mail_port: number
  mail_username: string
  mail_password: string
  mail_from_name: string
  mail_from_address: string

  // Pagamento
  inter_active: boolean
  inter_client_id: string
  inter_client_secret: string
  inter_account: string
  payment_due_days: number
  payment_fine_percent: number
  payment_interest_percent: number

  // WhatsApp
  whatsapp_active: boolean
  whatsapp_test_mode: boolean
  whatsapp_test_number: string

  // Outras
  [key: string]: any
}

Endpoints:

GET    /api/v1/admin/settings            # Obter todas
PUT    /api/v1/admin/settings            # Atualizar
GET    /api/v1/admin/settings/{key}      # Obter uma
PUT    /api/v1/admin/settings/{key}      # Atualizar uma

6. SISTEMA DE AUTENTICAÇÃO

6.1 Login Admin

Diferenças do Login Normal:

  • User type: admin
  • Verificação de permissões
  • Não permite registro público

Campos:

interface LoginForm {
  email: string
  password: string
  user_type: 'admin'
}

Endpoint:

POST /api/v1/login
{
  "email": "admin@agrsis.com",
  "password": "senha123",
  "user_type": "admin"
}

Resposta:

interface LoginResponse {
  user: User
  token: string
  permissions: string[]
}

6.2 Middleware de Autenticação

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const authStore = useAuthStore()

  if (!authStore.isAuthenticated) {
    return navigateTo('/login')
  }

  if (authStore.user?.user_type !== 'admin') {
    return navigateTo('/unauthorized')
  }
})

6.3 Refresh Token

Configuração:

  • Token expira em 24h
  • Refresh automático em 401
  • Logout em caso de falha
const refreshAuthToken = async () => {
  try {
    const { data } = await api.post<AuthResponse>('/refresh')
    if (data) {
      authStore.setToken(data.token)
      return true
    }
  } catch (error) {
    authStore.clear()
    navigateTo('/login')
    return false
  }
}

7. DASHBOARD PRINCIPAL

7.1 Layout

<template>
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mb-8">
    <!-- Métricas -->
    <MetricCard
      v-for="metric in metrics"
      :key="metric.key"
      :title="metric.title"
      :value="metric.value"
      :change="metric.change"
      :icon="metric.icon"
    />
  </div>

  <div class="grid grid-cols-1 lg:grid-cols-2 gap-6 mb-8">
    <!-- Gráfico de Receita -->
    <RevenueChart :data="revenueData" />

    <!-- Gráfico de Licitações -->
    <OrdersChart :data="ordersData" />
  </div>

  <div class="grid grid-cols-1 lg:grid-cols-3 gap-6">
    <!-- Timeline de Atividades -->
    <div class="lg:col-span-2">
      <ActivityTimeline :activities="recentActivities" />
    </div>

    <!-- Ações Rápidas -->
    <QuickActions />
  </div>
</template>

7.2 Métricas

const metrics = [
  {
    key: 'users',
    title: 'Total de Usuários',
    value: 1234,
    change: +12.5,
    icon: UsersIcon
  },
  {
    key: 'orders',
    title: 'Licitações Ativas',
    value: 45,
    change: -5.3,
    icon: ClipboardDocumentListIcon
  },
  {
    key: 'proposals',
    title: 'Propostas Este Mês',
    value: 189,
    change: +23.1,
    icon: DocumentTextIcon
  },
  {
    key: 'revenue',
    title: 'Receita (MRR)',
    value: 'R$ 45.890,00',
    change: +8.2,
    icon: CurrencyDollarIcon
  }
]

7.3 Timeline de Atividades

interface Activity {
  id: number
  type: 'user' | 'order' | 'proposal' | 'payment'
  action: string
  user: User
  resource: any
  created_at: string
}

// Exemplo:
{
  id: 1,
  type: 'order',
  action: 'Licitação criada',
  user: { name: 'João Silva', avatar: '...' },
  resource: { id: 123, title: 'Compra de Fertilizantes' },
  created_at: '2025-01-12T10:30:00Z'
}

8. GESTÃO DE USUÁRIOS

8.1 Listagem

Filtros:

interface UserFilters {
  user_type?: 'produtor' | 'fornecedor' | 'admin'
  status?: 'ativo' | 'inativo' | 'bloqueado'
  email_verified?: boolean
  created_from?: string
  created_to?: string
  search?: string  // nome, email, documento
}

Colunas da Tabela:

  • Avatar
  • Nome
  • Email
  • Tipo
  • Documento (CPF/CNPJ)
  • Telefone
  • Status
  • Email Verificado
  • Data de Cadastro
  • Ações

Bulk Actions:

  • Ativar selecionados
  • Desativar selecionados
  • Enviar email
  • Export selecionados

8.2 Detalhes do Usuário

Abas:

  1. Informações Básicas
    • Dados pessoais
    • Documento
    • Contato
    • Status
  2. Endereços
    • Lista de endereços
    • Endereço principal
    • Adicionar/Editar/Remover
  3. Licitações (produtor)
    • Lista de licitações criadas
    • Estatísticas
  4. Propostas (fornecedor)
    • Lista de propostas enviadas
    • Estatísticas
  5. Histórico
    • Timeline de ações
    • Logs de auditoria

9. GESTÃO DE PRODUTORES

9.1 Informações Específicas

Dados da Propriedade:

  • Nome da propriedade
  • Tamanho (hectares)
  • Culturas plantadas
  • Área por cultura

Estatísticas:

  • Total de licitações criadas
  • Licitações ativas
  • Total gasto em compras
  • Valor médio por licitação

9.2 Gráficos

  1. Licitações por Mês (últimos 12 meses)
  2. Gastos por Categoria (defensivos, fertilizantes, sementes)
  3. Top Fornecedores (propostas aceitas)

10. GESTÃO DE FORNECEDORES

10.1 Informações Específicas

Dados da Empresa:

  • Razão social
  • CNPJ
  • Inscrição estadual
  • Produtos oferecidos (tipos N1)

Estatísticas:

  • Total de propostas enviadas
  • Propostas aceitas
  • Receita total
  • Valor médio por proposta
  • Win rate (%)

10.2 Gráficos

  1. Propostas por Mês (últimos 12 meses)
  2. Taxa de Aceitação (%)
  3. Receita por Categoria (tipos de produtos)

11. GESTÃO DE LICITAÇÕES

11.1 Listagem

Filtros Avançados:

interface OrderFilters {
  status?: OrderStatus[]
  producer_id?: number
  state?: string
  city?: string
  value_min?: number
  value_max?: number
  created_from?: string
  created_to?: string
  deadline_from?: string
  deadline_to?: string
  has_proposals?: boolean
  search?: string  // ID, título
}

Colunas:

  • ID
  • Título
  • Produtor
  • Status
  • Valor Total
  • Propostas Recebidas
  • Prazo
  • Data de Criação
  • Ações

11.2 Detalhes da Licitação

Página Completa:

<template>
  <div class="space-y-6">
    <!-- Header com Status e Ações -->
    <OrderDetailsHeader :order="order" />

    <!-- Informações Básicas -->
    <OrderBasicInfo :order="order" />

    <!-- Itens Solicitados -->
    <OrderItemsList :items="order.items" />

    <!-- Propostas Recebidas -->
    <ProposalsTable :proposals="order.proposals" />

    <!-- Comparação de Propostas -->
    <ProposalComparison :proposals="order.proposals" />

    <!-- Timeline de Eventos -->
    <OrderTimeline :events="order.timeline" />

    <!-- Histórico de Alterações -->
    <OrderAuditLog :logs="order.logs" />
  </div>
</template>

11.3 Comparação de Propostas

Tabela Comparativa:

┌──────────────┬─────────────┬─────────────┬─────────────┐
│ Produto      │ Fornec. A   │ Fornec. B   │ Fornec. C   │
├──────────────┼─────────────┼─────────────┼─────────────┤
│ Glifosato    │ R$ 45,00 ✓  │ R$ 48,00    │ R$ 50,00    │
│ Atrazina     │ R$ 65,00    │ R$ 62,00 ✓  │ R$ 68,00    │
│ Lambda       │ R$ 85,00    │ R$ 82,00 ✓  │ R$ 90,00    │
├──────────────┼─────────────┼─────────────┼─────────────┤
│ SUBTOTAL     │ R$ 195,00   │ R$ 192,00   │ R$ 208,00   │
│ Desconto     │ R$ 0,00     │ R$ 10,00    │ R$ 0,00     │
│ TOTAL        │ R$ 195,00   │ R$ 182,00 ✓ │ R$ 208,00   │
└──────────────┴─────────────┴─────────────┴─────────────┘

Legenda:

  • ✓ = Melhor preço
  • Destaque verde para vencedor geral

12. GESTÃO DE PROPOSTAS

12.1 Listagem

Filtros:

interface ProposalFilters {
  status?: ProposalStatus[]
  supplier_id?: number
  order_id?: number
  value_min?: number
  value_max?: number
  created_from?: string
  created_to?: string
  search?: string
}

Colunas:

  • ID
  • Licitação
  • Fornecedor
  • Status
  • Valor Total
  • Desconto
  • Data de Envio
  • Ações

12.2 Detalhes da Proposta

Seções:

  1. Informações da proposta
  2. Itens e preços
  3. Dados do fornecedor
  4. Dados da licitação
  5. Observações
  6. Documentos anexados
  7. Histórico

13. GESTÃO DE PRODUTOS

13.1 Interface de Tipos (N1)

Tabela Simples:

  • ID
  • Nome
  • Descrição
  • Nº de Subtipos
  • Status
  • Ações (Editar/Deletar/Ver Subtipos)

13.2 Interface de Subtipos (N2)

Tabela com Filtro:

  • Filtro por Tipo (N1)
  • ID
  • Tipo (N1)
  • Nome
  • Descrição
  • Nº de Produtos
  • Status
  • Ações

13.3 Interface de Produtos (N3)

Tabela Completa:

  • ID
  • Nome
  • Marca
  • Tipo (N1)
  • Subtipo (N2)
  • Princípio Ativo
  • Concentração
  • Unidade
  • Status
  • Ações

Import em Massa:

  • Upload CSV/Excel
  • Mapeamento de colunas
  • Validação
  • Preview
  • Importar

Template CSV:

nome,marca,principio_ativo,concentracao,unidade,tipo,subtipo
"Glifosato 480g/L","Marca A","Glifosato","480g/L","L","Defensivos","Herbicidas"

14. RELATÓRIOS E ANALYTICS

14.1 Dashboard de Relatórios

Cards de Acesso Rápido:

  • Relatório de Licitações
  • Relatório de Propostas
  • Relatório de Usuários
  • Relatório Financeiro

14.2 Report Builder

Componente Dinâmico:

<template>
  <div class="report-builder">
    <!-- Seleção de Tipo -->
    <ReportTypeSelector v-model="reportType" />

    <!-- Filtros Dinâmicos -->
    <ReportFilters
      :type="reportType"
      v-model="filters"
    />

    <!-- Visualização -->
    <ReportView
      :type="reportType"
      :filters="filters"
      :data="reportData"
    />

    <!-- Export -->
    <ExportButtons
      :formats="['excel', 'csv', 'pdf']"
      @export="handleExport"
    />
  </div>
</template>

14.3 Gráficos com ApexCharts

Line Chart:

<apexchart
  type="line"
  :options="chartOptions"
  :series="series"
/>

Bar Chart:

<apexchart
  type="bar"
  :options="chartOptions"
  :series="series"
/>

Pie Chart:

<apexchart
  type="pie"
  :options="chartOptions"
  :series="series"
/>

15. SISTEMA DE LOGS

15.1 Listagem de Logs

Filtros:

  • Usuário
  • Ação (created, updated, deleted, status_changed)
  • Recurso (User, Order, Proposal, Product)
  • Data (de/até)
  • IP Address

Colunas:

  • Data/Hora
  • Usuário
  • Ação
  • Recurso
  • IP
  • User Agent
  • Ver Detalhes

15.2 Detalhes do Log

Visualização Diff:

<template>
  <div class="log-details">
    <div class="log-header">
      <h3>{{ log.action }} em {{ log.resource_type }}</h3>
      <p>{{ log.user.name }} - {{ formatDate(log.created_at) }}</p>
    </div>

    <div class="log-diff">
      <div class="log-old">
        <h4>Valores Antigos</h4>
        <pre>{{ JSON.stringify(log.old_values, null, 2) }}</pre>
      </div>

      <div class="log-new">
        <h4>Valores Novos</h4>
        <pre>{{ JSON.stringify(log.new_values, null, 2) }}</pre>
      </div>
    </div>
  </div>
</template>

16. CONFIGURAÇÕES DO SISTEMA

16.1 Interface de Configurações

Layout em Abas:

<template>
  <div class="settings">
    <TabGroup>
      <TabList>
        <Tab>Gerais</Tab>
        <Tab>Email</Tab>
        <Tab>Pagamento</Tab>
        <Tab>Notificações</Tab>
        <Tab>Integrações</Tab>
      </TabList>

      <TabPanels>
        <TabPanel><GeneralSettings /></TabPanel>
        <TabPanel><EmailSettings /></TabPanel>
        <TabPanel><PaymentSettings /></TabPanel>
        <TabPanel><NotificationSettings /></TabPanel>
        <TabPanel><IntegrationSettings /></TabPanel>
      </TabPanels>
    </TabGroup>
  </div>
</template>

16.2 Formulário de Configurações

Pattern:

  • Carrega configurações existentes
  • Edita inline
  • Botão "Salvar" geral ou por seção
  • Validação de campos
  • Feedback visual (toast)

17. PERMISSÕES E ACL

17.1 Sistema de Permissões

Níveis:

enum AdminRole {
  MASTER = 'master',
  OPERACIONAL = 'operacional',
  FINANCEIRO = 'financeiro'
}

Permissões por Módulo:

interface Permissions {
  users: {
    view: boolean
    create: boolean
    edit: boolean
    delete: boolean
  }
  producers: { ... }
  suppliers: { ... }
  orders: { ... }
  proposals: { ... }
  products: { ... }
  reports: { ... }
  logs: { ... }
  settings: { ... }
}

17.2 Middleware de Permissões

// middleware/permissions.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const authStore = useAuthStore()
  const requiredPermission = to.meta.permission as string

  if (requiredPermission && !authStore.hasPermission(requiredPermission)) {
    return navigateTo('/unauthorized')
  }
})

17.3 Uso nos Componentes

<template>
  <button
    v-if="can('users.create')"
    @click="createUser"
  >
    Criar Usuário
  </button>
</template>

<script setup>
const { can } = usePermissions()
</script>

18. ROADMAP DE IMPLEMENTAÇÃO

Fase 1: Setup e Base (1-2 semanas)

Semana 1:

  • ✅ Criar estrutura de pastas
  • ✅ Copiar design system (Tailwind + CSS)
  • ✅ Configurar Nuxt + Pinia + plugins
  • ✅ Criar layouts (default, auth)
  • ✅ Implementar componentes UI base
    • DataTable
    • StatusBadge
    • ToastContainer
    • LoadingSpinner
    • EmptyState
    • ConfirmDialog

Semana 2:

  • ✅ Implementar autenticação admin
  • ✅ Criar middleware (auth, permissions)
  • ✅ Criar composables base
    • useAuth
    • useApi
    • useToast
    • useErrorHandler
    • usePermissions
  • ✅ Criar layout admin (sidebar + topnav)

Fase 2: Dashboard e Usuários (2 semanas)

Semana 3:

  • ✅ Dashboard principal
    • Métricas
    • Gráficos (ApexCharts)
    • Timeline de atividades
  • ✅ Gestão de usuários
    • Listagem com filtros
    • Criação/Edição
    • Detalhes

Semana 4:

  • ✅ Gestão de produtores
    • Listagem com filtros
    • Detalhes completos
    • Endereços
    • Licitações do produtor
  • ✅ Gestão de fornecedores
    • Listagem com filtros
    • Detalhes completos
    • Endereços
    • Propostas do fornecedor

Fase 3: Licitações e Propostas (2 semanas)

Semana 5:

  • ✅ Gestão de licitações
    • Listagem com filtros avançados
    • Detalhes completos
    • Timeline de eventos
    • Comparação de propostas

Semana 6:

  • ✅ Gestão de propostas
    • Listagem com filtros
    • Detalhes completos
    • Comparação lado a lado
    • Export PDF

Fase 4: Produtos e Relatórios (2 semanas)

Semana 7:

  • ✅ Gestão de produtos
    • Tipos (N1)
    • Subtipos (N2)
    • Produtos (N3)
    • Visualização hierárquica
    • Import em massa

Semana 8:

  • ✅ Sistema de relatórios
    • Report Builder
    • Relatório de licitações
    • Relatório de propostas
    • Relatório de usuários
    • Relatório financeiro
    • Export (Excel, CSV, PDF)

Fase 5: Logs e Configurações (1 semana)

Semana 9:

  • ✅ Sistema de logs
    • Listagem com filtros
    • Detalhes (diff)
    • Export CSV
  • ✅ Configurações do sistema
    • Gerais
    • Email
    • Pagamento
    • Notificações
    • Integrações

Fase 6: Testes e Refinamentos (1 semana)

Semana 10:

  • ✅ Testes de integração
  • ✅ Testes de permissões
  • ✅ Refinamentos de UI/UX
  • ✅ Otimizações de performance
  • ✅ Documentação final
  • ✅ Deploy

TOTAL: 10 SEMANAS (2,5 MESES)

19. CHECKLIST DE DESENVOLVIMENTO

Setup Inicial

  • Criar pasta apps/admin/
  • Configurar package.json
  • Configurar nuxt.config.ts
  • Configurar tailwind.config.js
  • Copiar assets/css/main.css
  • Instalar dependências

Componentes UI

  • DataTable
  • StatusBadge
  • ToastContainer/ToastItem
  • LoadingSpinner
  • EmptyState
  • ConfirmDialog
  • Pagination
  • SearchInput
  • DateRangePicker
  • BulkActions
  • ExportButton

Layout

  • AdminSidebar
  • AdminTopNav
  • AdminBreadcrumb
  • AdminFooter
  • Layout default
  • Layout auth

Composables

  • useAuth
  • useApi
  • useToast
  • useErrorHandler
  • useFormValidation
  • usePermissions
  • useExport
  • useDashboard
  • useUsers
  • useProducers
  • useSuppliers
  • useOrders
  • useProposals
  • useProducts
  • useLogs
  • useSettings

Stores

  • auth
  • dashboard
  • users
  • producers
  • suppliers
  • orders
  • proposals
  • products
  • settings

Pages - Autenticação

  • /login

Pages - Dashboard

  • /dashboard

Pages - Usuários

  • /users
  • /users/new
  • /users/id

Pages - Produtores

  • /producers
  • /producers/new
  • /producers/id

Pages - Fornecedores

  • /suppliers
  • /suppliers/new
  • /suppliers/id

Pages - Licitações

  • /orders
  • /orders/id

Pages - Propostas

  • /proposals
  • /proposals/id

Pages - Produtos

  • /products/types
  • /products/types/id
  • /products/subtypes
  • /products/subtypes/id
  • /products

Pages - Relatórios

  • /reports
  • /reports/orders
  • /reports/proposals
  • /reports/users
  • /reports/financial

Pages - Logs

  • /logs
  • /logs/id

Pages - Configurações

  • /settings
  • /settings/general
  • /settings/email
  • /settings/payment
  • /settings/notifications

Funcionalidades

  • Autenticação admin
  • Refresh token automático
  • Sistema de permissões
  • Export Excel/CSV/PDF
  • Import em massa (produtos)
  • Comparação de propostas
  • Timeline de eventos
  • Sistema de logs
  • Gráficos (ApexCharts)
  • Notificações (toast)
  • Error handling

Testes

  • Testes de integração
  • Testes de permissões
  • Testes de componentes
  • Testes de composables

Deploy

  • Build de produção
  • Deploy no servidor
  • Configuração de variáveis de ambiente
  • Testes em produção

20. OBSERVAÇÕES FINAIS

Boas Práticas

  1. Componentização:
    • Criar componentes pequenos e reutilizáveis
    • Separar lógica de apresentação
    • Usar composables para lógica compartilhada
  2. Performance:
    • Lazy loading de rotas
    • Virtual scrolling em listas grandes
    • Debounce em buscas
    • Cache de requisições
  3. UX:
    • Loading states em todas as operações
    • Feedback visual (toast)
    • Confirmação em ações destrutivas
    • Empty states
    • Error states
  4. Segurança:
    • Validação client-side e server-side
    • Proteção contra XSS
    • Sanitização de inputs
    • Controle de permissões
  5. Código:
    • TypeScript strict mode
    • ESLint + Prettier
    • Commits semânticos
    • Code review

Recursos Necessários

Desenvolvedor:

  • 1 Full-stack (Vue 3 + Laravel)
  • Experiência com Nuxt 3, Pinia, Tailwind CSS
  • Conhecimento de charts (ApexCharts)
  • Familiaridade com TanStack Table

Design:

  • Reutilizar design system existente
  • Ajustes pontuais de UI

Backend:

  • API já existe (documentada com Scribe)
  • Possíveis novos endpoints para admin

21. ENDPOINTS NECESSÁRIOS NA API

Novos Endpoints para Admin

# Usuários
GET    /api/v1/admin/users
GET    /api/v1/admin/users/{id}
POST   /api/v1/admin/users
PUT    /api/v1/admin/users/{id}
DELETE /api/v1/admin/users/{id}
PATCH  /api/v1/admin/users/{id}/status
GET    /api/v1/admin/users/{id}/logs

# Produtores
GET    /api/v1/admin/producers
GET    /api/v1/admin/producers/{id}
PUT    /api/v1/admin/producers/{id}
GET    /api/v1/admin/producers/{id}/orders
GET    /api/v1/admin/producers/{id}/logs

# Fornecedores
GET    /api/v1/admin/suppliers
GET    /api/v1/admin/suppliers/{id}
PUT    /api/v1/admin/suppliers/{id}
GET    /api/v1/admin/suppliers/{id}/proposals
GET    /api/v1/admin/suppliers/{id}/products
GET    /api/v1/admin/suppliers/{id}/logs

# Licitações
GET    /api/v1/admin/orders
GET    /api/v1/admin/orders/{id}
GET    /api/v1/admin/orders/{id}/items
GET    /api/v1/admin/orders/{id}/proposals
GET    /api/v1/admin/orders/{id}/timeline
GET    /api/v1/admin/orders/{id}/logs

# Propostas
GET    /api/v1/admin/proposals
GET    /api/v1/admin/proposals/{id}
GET    /api/v1/admin/proposals/{id}/items
GET    /api/v1/admin/proposals/{id}/logs
GET    /api/v1/admin/proposals/compare?ids[]=1&ids[]=2

# Dashboard
GET    /api/v1/admin/dashboard
GET    /api/v1/admin/dashboard/metrics
GET    /api/v1/admin/dashboard/charts/revenue
GET    /api/v1/admin/dashboard/charts/orders
GET    /api/v1/admin/dashboard/charts/users
GET    /api/v1/admin/dashboard/activities

# Relatórios
GET    /api/v1/admin/reports/orders
GET    /api/v1/admin/reports/proposals
GET    /api/v1/admin/reports/users
GET    /api/v1/admin/reports/financial

# Logs
GET    /api/v1/admin/logs
GET    /api/v1/admin/logs/{id}

# Configurações
GET    /api/v1/admin/settings
PUT    /api/v1/admin/settings
GET    /api/v1/admin/settings/{key}
PUT    /api/v1/admin/settings/{key}

# Import/Export
POST   /api/v1/admin/products/import
GET    /api/v1/admin/export/{resource}

22. CONSIDERAÇÕES DE DESIGN

Tema de Cores

Paleta Admin:

colors: {
  admin: {
    50: '#f0f9ff',
    100: '#e0f2fe',
    200: '#bae6fd',
    300: '#7dd3fc',
    400: '#38bdf8',
    500: '#0ea5e9',  // Primary
    600: '#0284c7',
    700: '#0369a1',
    800: '#075985',
    900: '#0c4a6e',
  }
}

Ícones (Heroicons)

Módulos:

  • Dashboard: HomeIcon
  • Usuários: UsersIcon
  • Produtores: UserGroupIcon
  • Fornecedores: BuildingStorefrontIcon
  • Licitações: ClipboardDocumentListIcon
  • Propostas: DocumentTextIcon
  • Produtos: CubeIcon
  • Relatórios: ChartBarIcon
  • Logs: DocumentMagnifyingGlassIcon
  • Configurações: Cog6ToothIcon

CONCLUSÃO

Este documento serve como guia completo para o desenvolvimento do frontend administrativo do AgrSis.

A arquitetura proposta é:

  • ✅ Escalável
  • ✅ Reutilizável
  • ✅ Performática
  • ✅ Segura
  • ✅ Moderna

Seguindo este plano, teremos um admin completo, profissional e funcional em aproximadamente 10 semanas.

Próximos Passos:

  1. ✅ Revisar e aprovar este plano
  2. ✅ Definir prioridades (se houver)
  3. ✅ Começar pela Fase 1 (Setup e Base)

Documento criado em: 2025-01-12 Última atualização: 2025-01-12 Versão: 1.0

Migração de Nomenclatura: Português → Inglês

Status: ✅ CONCLUÍDA Data Início: 2025-12-18 Data Conclusão: 2025-12-18 Tempo Total: ~1h30min Impacto: Alto - API + Frontend Producer migrados com sucesso

Backlog pendente - Projeto AgrSis

Data de geração: 2026-03-09

Copyright © 2026