9.2 KiB

Raw Blame History

🚀 GUIA DE ONBOARDING - Criação de Novos Domínios

👋 Bem-vindo ao Sistema PraFrota!

Este guia irá te ajudar a criar um novo domínio no sistema de forma fluida e segura. O PraFrota utiliza um framework de geração automática de telas que fornece:

📋 Listagem com filtros, paginação e busca
➕ Cadastro com formulários dinâmicos
✏️ Edição com validação e componentes especializados
🎨 Interface responsiva e profissional

✅ PRÉ-REQUISITOS OBRIGATÓRIOS

1. 🔄 Branch Main Atualizada

git checkout main
git pull origin main

2. 👤 Configuração Git (Obrigatório)

# Configure seu nome e email (DEVE ser @grupopralog.com.br)
git config --global user.name "Seu Nome Completo"
git config --global user.email "seu.email@grupopralog.com.br"

# Verificar configuração
git config --global user.name
git config --global user.email

⚠️ IMPORTANTE: O email DEVE ter domínio @grupopralog.com.br

🎯 ROTEIRO INTERATIVO DE CRIAÇÃO

Passo 1: Informações Básicas do Domínio

📝 Nome do Domínio

Pergunta: Qual o nome do domínio? (ex: contracts, suppliers, employees)
Formato: Singular, minúsculo, sem espaços
Exemplo: contracts → gera ContractsComponent

Pergunta: Onde colocar no menu lateral?
Opções:
- vehicles (após Veículos)
- drivers (após Motoristas)
- routes (após Rotas)
- finances (após Finanças)
- reports (após Relatórios)
- settings (após Configurações)

📸 Sub-aba de Fotos

Pergunta: Terá sub-aba de fotos?
Opções: sim ou não
Se sim: Componente send-image será adicionado automaticamente

🃏 Side Card

Pergunta: Terá Side Card (painel lateral com resumo)?
Opções: sim ou não
Se sim: Configuração automática com campos principais

Passo 2: Campos da API (OBRIGATÓRIO)

⚠️ IMPORTANTE: Consulte a documentação Swagger da API antes de responder!

📋 Campos Básicos da API

Pergunta: A API tem campo "name"? (obrigatório)
Pergunta: A API tem campo "description"?
Pergunta: A API tem campo "status"?
Pergunta: A API tem campo "created_at"?

🎯 Campos Personalizados

Pergunta: Haverá campos específicos da entidade?
Exemplo: Para contratos → contract_number, start_date, end_date
Documentação: Liste todos os campos do Swagger

Passo 3: Componentes Especializados

🛣️ Campo Quilometragem

Pergunta: Terá campo de quilometragem?
Componente: kilometer-input com formatação automática
Formato: 123.456 km

🎨 Campo Cor

Pergunta: Terá campo de cor?
Componente: color-input com seletor visual
Retorno: {name: "Azul", code: "#0000ff"}

📊 Campo Status

Pergunta: Terá campo de status?
Componente: Select com badges coloridos na tabela
Configuração: Status personalizados para o domínio

Passo 4: Integração com APIs

🔍 Campos Remote-Select

Pergunta: Haverá campos para buscar dados de outras APIs?
Exemplos:
- Buscar motoristas em contratos
- Buscar veículos em manutenções
- Buscar fornecedores em compras
Componente: remote-select com autocomplete

🚀 PROCESSO AUTOMATIZADO

1. Pré-requisitos Automáticos ✅

✅ Verificação da branch main atualizada
✅ Configuração Git com email @grupopralog.com.br obrigatório
✅ Estrutura de projeto validada

2. Questionário Interativo 📋

Nome do domínio (singular, lowercase)
Posição no menu sidebar
Inclusão de sub-aba de fotos
Necessidade de side card
Componentes especializados (quilometragem, cor, status)
Campos remote-select para integração com APIs

3. Criação Automática de Branch 🌿

✅ Branch criada automaticamente: feature/domain-[nome]
✅ Verificação de branch existente: Pergunta se quer usar branch existente
✅ Descrição automática: Funcionalidades implementadas documentadas
✅ Checkout automático: Muda para a nova branch criada

Exemplo de branch criada:

git checkout -b feature/domain-products
# Branch: feature/domain-products
# Descrição: Implementação do domínio Produtos
# Funcionalidades: CRUD básico, upload de fotos, painel lateral, campo quilometragem

4. Geração Automática 🔧

Component com BaseDomainComponent + Registry Pattern
Service com integração API
Interface TypeScript
Template HTML otimizado
Styles SCSS
Documentação específica

5. Configuração Automática ⚙️

Registro automático no TabFormConfigService
Integração com sistema de rotas
Configuração do menu sidebar
Atualização do arquivo MCP

🎨 COMPONENTES DISPONÍVEIS

Inputs Básicos

text - Campo de texto simples
number - Campo numérico
date - Seletor de data
select - Lista suspensa

Inputs Especializados

kilometer-input - Quilometragem formatada
color-input - Seletor visual de cores
remote-select - Busca em APIs externas
send-image - Upload de múltiplas imagens

Campos Avançados

multi-select - Seleção múltipla
address-form - Formulário de endereço completo
custom-tabs - Abas personalizadas

📋 CHECKLIST DE VALIDAÇÃO

Antes de Iniciar

Branch main atualizada
Git configurado com email @grupopralog.com.br
Nome do domínio definido
Posição no menu escolhida
Componentes especializados identificados

Durante a Criação

Estrutura de arquivos gerada
Service configurado para API
Interface TypeScript criada
Componente registrado no sistema
Menu lateral atualizado

Após a Criação

Compilação sem erros
Testes básicos funcionando
Documentação atualizada
Branch criada para desenvolvimento
Commit inicial realizado

⚠️ ESTRUTURA CORRETA DE CAMPOS

Campos devem estar DENTRO das Sub-abas

❌ INCORRETO (Estrutura Antiga):

getFormConfig(): TabFormConfig {
  return {
    fields: [ // ❌ Campos aqui = ERRO
      { key: 'name', label: 'Nome', type: 'text' }
    ],
    subTabs: [...]
  };
}

✅ CORRETO (Estrutura Nova):

getFormConfig(): TabFormConfig {
  return {
    fields: [], // ✅ VAZIO
    subTabs: [
      {
        id: 'dados',
        fields: [ // ✅ Campos DENTRO da sub-aba
          { key: 'name', label: 'Nome', type: 'text' }
        ]
      }
    ]
  };
}

Template HTML Obrigatório

✅ Estrutura Correta:

<div class="domain-container">
  <div class="main-content">
    <app-tab-system
      #tabSystem
      [config]="tabConfig"
      [events]="tabEvents"
      (tableEvent)="onTableEvent($event)">
    </app-tab-system>
  </div>
</div>

🚨 REGRAS IMPORTANTES

Nomenclatura

Domínio: Singular, minúsculo (ex: contract)
Componente: PascalCase (ex: ContractComponent)
Service: PascalCase + Service (ex: ContractService)
Interface: PascalCase (ex: Contract)

Estrutura de Dados

ID: Sempre number ou string
Datas: Formato ISO 8601
Status: Enum com valores específicos
Relacionamentos: IDs das entidades relacionadas

Padrões de API

Listagem: GET /api/v1/[dominio]
Criação: POST /api/v1/[dominio]
Edição: PUT /api/v1/[dominio]/{id}
Exclusão: DELETE /api/v1/[dominio]/{id}

🎯 EXEMPLO PRÁTICO

Cenário: Criando domínio "Contratos"

Respostas ao Questionário

Nome do domínio: contracts
Posição no menu: finances
Sub-aba de fotos: sim
Side Card: sim
Campo quilometragem: não
Campo cor: não
Campo status: sim
Campos remote-select: sim (buscar veículos e motoristas)

Resultado Gerado

// contracts.component.ts
@Component({
  selector: 'app-contracts',
  standalone: true,
  imports: [CommonModule, TabSystemComponent],
  templateUrl: './contracts.component.html',
  styleUrl: './contracts.component.scss'
})
export class ContractsComponent extends BaseDomainComponent<Contract> {
  // Configuração automática baseada nas respostas
}

🆘 SUPORTE E AJUDA

Dúvidas Comuns

Erro de compilação: Verificar imports e interfaces
API não funciona: Verificar configuração do service
Menu não aparece: Verificar roteamento e sidebar
Validação incorreta: Verificar campos obrigatórios

Onde Buscar Ajuda

📚 Documentação: projects/idt_app/docs/
🎯 Exemplos: Componentes vehicles e drivers
🔧 MCP Config: .mcp/config.json
💬 Equipe: Canal de desenvolvimento

🎉 CONCLUSÃO

Seguindo este guia, você criará um domínio completo e funcional no sistema PraFrota. O framework automatiza a maior parte do trabalho, deixando você focar na lógica específica do seu domínio.

Próximo passo: Execute o comando de criação e responda às perguntas interativas!

Boa sorte e bem-vindo ao time! 🚀

9.2 KiB Raw Blame History Unescape Escape