# 🚀 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**
```bash
git checkout main
git pull origin main
```

### 2. 👤 **Configuração Git (Obrigatório)**
```bash
# 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`

#### 🧭 **Posição no Menu Lateral**
- **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:**
```bash
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):
```typescript
getFormConfig(): TabFormConfig {
  return {
    fields: [ // ❌ Campos aqui = ERRO
      { key: 'name', label: 'Nome', type: 'text' }
    ],
    subTabs: [...]
  };
}
```

✅ **CORRETO** (Estrutura Nova):
```typescript
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**:
```html
<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**
```typescript
// 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**
1. 📚 **Documentação**: `projects/idt_app/docs/`
2. 🎯 **Exemplos**: Componentes `vehicles` e `drivers`
3. 🔧 **MCP Config**: `.mcp/config.json`
4. 💬 **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! 🚀**