testes/Modulos Angular/projects/idt_app/docs/README.md

624 lines
19 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 📚 IDT App - Documentação Completa
## Visão Geral
Bem-vindo à documentação oficial do **IDT App**, uma aplicação moderna de gestão de frota desenvolvida em Angular 18+ com **framework CRUD genérico** e design system personalizado.
## 🗂️ Índice de Documentação
### 🎯 **Soluções Críticas** *(NOVO)*
- **[Solução de Sincronização de Formulários](./FORM_SYNCHRONIZATION_SOLUTION.md)** - Correção completa para problemas de edição
- Resolve "segunda tentativa" para editar campos
- Elimina "blinking" e perda de foco
- Corrige loops infinitos no salvamento
- Proteção tripla contra `ngOnChanges()` desnecessário
- Sistema de edição controlada e robusta
### 🚀 **Framework CRUD Universal** *(NOVO)*
- **[Tab System](../src/app/shared/components/tab-system/README.md)** - Sistema completo de abas e formulários
- Sistema genérico para qualquer domínio
- Sub-abas configuráveis dinamicamente
- Salvamento automático escalável
- API universal para CRUD operations
- **[Base Domain Component](../src/app/shared/components/base-domain/base-domain.component.ts)** - Componente base para domínios
- CRUD operations padronizadas
- Herança automática de funcionalidades
- Event handling unificado
- Paginação server-side integrada
- **[API Integration Guide](./API_INTEGRATION_GUIDE.md)** - Guia de integração com API PraFrota
- Orientações para consulta ao Swagger
- Templates para implementação de services
- Mapeamento de schemas para interfaces TypeScript
- Checklist completo para novos domínios
### 📱 Componentes Mobile
- **[Mobile Footer Menu](./mobile/MOBILE_FOOTER_MENU.md)** - Menu de navegação flutuante para dispositivos móveis
- Sistema de notificações em tempo real
- Navegação para Dashboard, Rotas Meli, Veículos e Sidebar
- Design responsivo com tema IDT
### 🃏 Side Card Component
- **[Side Card](../src/app/shared/sidecard/README.md)** - Componente genérico para informações contextuais
- Sistema genérico e reutilizável
- Suporte completo a temas (claro/escuro)
- Design responsivo com collapse automático no mobile
- Hierarquia inteligente de imagens com fallbacks
- Integrado seamlessly com o sistema de tabs
### 🎨 Design System
- **[Typography System](./ui-design/TYPOGRAPHY_SYSTEM.md)** - Sistema de tipografia completo
- **[Logo Relocation Guide](./ui-design/LOGO_RELOCATION_GUIDE.md)** - Guia de posicionamento de logo
- **[Cores e Temas](./DESIGN_SYSTEM.md)** *(em desenvolvimento)*
- Paleta de cores principal: #FFC82E (dourado) e #000000 (preto)
- Suporte a temas claro e escuro
- Variáveis CSS customizadas
### 🏗️ Layout e Estrutura
- **[Layout Restructure Guide](./layout/LAYOUT_RESTRUCTURE_GUIDE.md)** - Guia de reestruturação de layout
- **[Sidebar Styling Guide](./layout/SIDEBAR_STYLING_GUIDE.md)** - Estilização da barra lateral
### 📋 Documentação Geral
- **[Cursor Integration](./general/CURSOR.md)** - Integração e configuração do Cursor
### 🚗 Módulos de Domínio *(Usando Framework Universal)*
- **[Motoristas](./DRIVERS.md)** *(implementado com BaseDomainComponent)*
- CRUD completo automatizado
- Sub-abas: dados, endereço, documentos
- Salvamento genérico integrado
- **[Veículos](./VEHICLES.md)** *(pronto para implementação)*
- Herda automaticamente todas as funcionalidades CRUD
- Configuração declarativa simples
- Sub-abas personalizáveis
### 🛣️ Rotas e Navegação
- **[Mercado Livre](./MERCADO_LIVRE.md)** *(em desenvolvimento)*
- Integração com API do Mercado Livre
- Gestão de rotas de entrega
- Notificações em tempo real
### 📊 Dashboard e Relatórios
- **[Dashboard](./DASHBOARD.md)** *(em desenvolvimento)*
- Widgets personalizáveis
- Métricas em tempo real
- Exportação de dados
## 🚀 Getting Started
### Pré-requisitos
```bash
Node.js >= 18.x
Angular CLI >= 18.x
npm ou yarn
```
### Instalação
```bash
# Clonar repositório
git clone [url-do-repositorio]
# Instalar dependências
cd web/angular
npm install
# Executar em desenvolvimento
npm start
```
### Build para Produção
```bash
# Build otimizado
npm run build:prod
# Build do projeto IDT App
npx ng build idt_app --configuration production
```
## 🌐 **Integração com API PraFrota**
### **📋 Swagger da API**
**URL da API**: [https://prafrota-be-bff-tenant-api.grupopra.tech/swagger#/](https://prafrota-be-bff-tenant-api.grupopra.tech/swagger#/)
### **🎯 Fluxo para Novos Domínios**
Ao implementar um novo domínio usando nosso **Framework CRUD Universal**, siga este processo:
#### **1. Consultar Swagger da API**
```bash
# Acessar a documentação da API
https://prafrota-be-bff-tenant-api.grupopra.tech/swagger#/
# Identificar endpoints para o domínio desejado:
# - GET /api/vehicles (listagem)
# - POST /api/vehicles (criação)
# - PUT /api/vehicles/{id} (atualização)
# - DELETE /api/vehicles/{id} (exclusão)
# - GET /api/vehicles/{id} (detalhes)
```
#### **2. Implementar Service baseado na API**
```typescript
// vehicles.service.ts
@Injectable()
export class VehiclesService implements DomainService<Vehicle> {
private apiUrl = 'https://prafrota-be-bff-tenant-api.grupopra.tech/api';
constructor(private http: HttpClient) {}
// ✅ Método obrigatório para BaseDomainComponent
getEntities(page: number, pageSize: number, filters: any): Observable<{
data: Vehicle[];
totalCount: number;
pageCount: number;
currentPage: number;
}> {
const params = new HttpParams()
.set('page', page.toString())
.set('pageSize', pageSize.toString())
.set('filters', JSON.stringify(filters));
return this.http.get<any>(`${this.apiUrl}/vehicles`, { params });
}
// ✅ Métodos para salvamento genérico
create(vehicle: Partial<Vehicle>): Observable<Vehicle> {
return this.http.post<Vehicle>(`${this.apiUrl}/vehicles`, vehicle);
}
update(id: any, vehicle: Partial<Vehicle>): Observable<Vehicle> {
return this.http.put<Vehicle>(`${this.apiUrl}/vehicles/${id}`, vehicle);
}
delete(id: any): Observable<void> {
return this.http.delete<void>(`${this.apiUrl}/vehicles/${id}`);
}
getById(id: any): Observable<Vehicle> {
return this.http.get<Vehicle>(`${this.apiUrl}/vehicles/${id}`);
}
}
```
#### **3. Implementar Domain Component**
```typescript
// vehicles.component.ts
@Component({
selector: 'app-vehicles',
template: `<app-tab-system [config]="tabConfig" (tableEvent)="onTableEvent($event)"></app-tab-system>`
})
export class VehiclesComponent extends BaseDomainComponent<Vehicle> {
constructor(
private vehiclesService: VehiclesService,
titleService: TitleService,
headerActionsService: HeaderActionsService,
cdr: ChangeDetectorRef
) {
super(titleService, headerActionsService, cdr, vehiclesService);
}
protected getDomainConfig(): DomainConfig {
return {
domain: 'vehicle',
title: 'Veículos',
entityName: 'veículo',
subTabs: ['dados', 'documentos', 'manutencao'],
columns: [
// ✅ Baseado no schema da API no Swagger
{ field: 'plate', header: 'Placa', sortable: true },
{ field: 'model', header: 'Modelo', sortable: true },
{ field: 'year', header: 'Ano', sortable: true },
{ field: 'status', header: 'Status', filterable: true }
]
};
}
// 🎉 PRONTO! CRUD completo integrado com API PraFrota!
}
```
#### **4. Definir Interface baseada no Schema da API**
```typescript
// vehicle.interface.ts
// ✅ Baseado no schema do Swagger
export interface Vehicle {
id: string;
plate: string;
model: string;
year: number;
status: 'ACTIVE' | 'INACTIVE' | 'MAINTENANCE';
brand: string;
color: string;
chassisNumber: string;
renavam: string;
licensePlate: string;
// ... outros campos conforme API
}
```
### **🔧 Vantagens da Integração**
-**Consistência**: Schemas alinhados com a API real
-**Validação**: TypeScript garante tipagem correta
-**Escalabilidade**: Padrão para todos os novos domínios
-**Manutenibilidade**: Mudanças na API refletidas facilmente
-**Documentação**: Swagger como fonte única da verdade
### **📋 Checklist para Novos Domínios**
Ao implementar um novo domínio:
1. **☐ Consultar Swagger** - Identificar endpoints disponíveis
2. **☐ Definir Interface** - Baseada no schema da API
3. **☐ Implementar Service** - Com métodos CRUD padrão
4. **☐ Criar Component** - Estendendo BaseDomainComponent
5. **☐ Configurar Columns** - Baseadas nos campos da API
6. **☐ Testar Integração** - Verificar CRUD completo
### **🎮 Exemplo Prático**
```typescript
// Processo completo para domínio "Drivers":
// 1. Swagger: GET /api/drivers, POST /api/drivers, etc.
// 2. Interface: Driver { id, name, cpf, license, ... }
// 3. Service: DriversService implements DomainService<Driver>
// 4. Component: DriversComponent extends BaseDomainComponent<Driver>
// 5. Resultado: CRUD completo integrado com API PraFrota
```
## 🏗️ Arquitetura do Framework CRUD
### **🎯 Nova Arquitetura Universal**
```
🚀 FRAMEWORK CRUD GENÉRICO:
1⃣ BaseDomainComponent<T> (Genérico)
├── 🔄 CRUD operations padronizadas
├── 📊 Paginação server-side
├── 💾 Sistema de salvamento genérico
└── 🎯 Event handling unificado
2⃣ TabSystemComponent (Interface Universal)
├── 📑 Abas configuráveis
├── 🎨 Sub-abas dinâmicas
├── 💾 Salvamento automático
└── 🔗 Integração com formulários
3⃣ GenericTabFormComponent (Formulários)
├── 📝 Campos configuráveis
├── ✅ Validação automática
├── 💾 Salvamento integrado
└── 🎯 Eventos padronizados
```
### **📂 Estrutura do Projeto (Atualizada)**
```
projects/idt_app/
├── src/
│ ├── app/
│ │ ├── domain/ # Módulos de negócio
│ │ │ ├── drivers/ # ✅ Usa BaseDomainComponent
│ │ │ ├── vehicles/ # 🔄 Pronto para implementar
│ │ │ └── routes/ # 🔄 Pronto para implementar
│ │ ├── shared/ # Componentes compartilhados
│ │ │ ├── components/ # Componentes reutilizáveis
│ │ │ │ ├── base-domain/ # 🚀 NOVO: Componente base CRUD
│ │ │ │ ├── tab-system/ # 🚀 NOVO: Sistema de abas
│ │ │ │ ├── generic-tab-form/ # 🚀 NOVO: Formulários genéricos
│ │ │ │ └── data-table/ # Tabelas com paginação
│ │ │ ├── services/ # Serviços globais
│ │ │ ├── interfaces/ # Tipos TypeScript
│ │ │ └── sidecard/ # 🔄 Side Card reorganizado
│ │ └── core/ # Configurações centrais
│ ├── assets/ # Recursos estáticos
│ └── styles/ # Estilos globais
├── docs/ # 📚 Esta documentação
└── samples_screen/ # Screenshots e exemplos
```
### Tecnologias Utilizadas
#### Frontend
- **Angular 18+**: Framework principal
- **TypeScript**: Linguagem de desenvolvimento
- **RxJS**: Programação reativa
- **Angular Material**: Componentes UI
- **SCSS**: Pré-processador CSS
#### Ferramentas
- **Angular CLI**: Desenvolvimento e build
- **ESLint**: Linting de código
- **Prettier**: Formatação de código
- **Jest**: Testes unitários
## 🎯 Recursos Principais
### ✅ **Implementados (Framework CRUD)**
- [x] **BaseDomainComponent** - CRUD genérico para qualquer domínio
- [x] **TabSystemComponent** - Sistema de abas configuráveis
- [x] **GenericTabFormComponent** - Formulários automáticos
- [x] **Sistema de Salvamento Genérico** - Auto-detecta create/update
- [x] **Sub-abas Dinâmicas** - Configuração declarativa
- [x] **API Universal** - Mesma interface para todos os domínios
- [x] **Event-driven Architecture** - Comunicação padronizada
- [x] **Side Card Integration** - Informações contextuais
### ✅ **Recursos de UI**
- [x] **Mobile Footer Menu** - Navegação mobile otimizada
- [x] **Data Tables** - Tabelas com filtros e paginação
- [x] **Design System** - Cores e temas consistentes
- [x] **Responsive Design** - Adaptação para todos os dispositivos
### 🔄 Em Desenvolvimento
- [ ] Dashboard com widgets
- [ ] Integração completa com APIs
- [ ] Sistema de relatórios
- [ ] Notificações push
- [ ] Modo offline (PWA)
## 📱 Componentes Destacados
### **🚀 Framework CRUD (NOVO)**
#### **Implementar Novo Domínio (APENAS 15 LINHAS)**
```typescript
// ✨ CRUD completo para qualquer entidade em 15 linhas!
@Component({
selector: 'app-clients',
template: `<app-tab-system [config]="tabConfig" (tableEvent)="onTableEvent($event)"></app-tab-system>`
})
export class ClientsComponent extends BaseDomainComponent<Client> {
protected getDomainConfig(): DomainConfig {
return {
domain: 'client',
title: 'Clientes',
entityName: 'cliente',
subTabs: ['dados', 'endereco', 'contratos'],
columns: [
{ field: 'name', header: 'Nome', sortable: true },
{ field: 'email', header: 'Email', filterable: true }
]
};
}
// 🎉 PRONTO! CRUD completo funcionando:
// ✅ Listagem com paginação
// ✅ Criação com formulário
// ✅ Edição com sub-abas
// ✅ Salvamento automático
}
```
#### **API Universal do Tab System**
```typescript
// API genérica - funciona com qualquer entidade
await tabSystemService.openTabWithPreset('driver', 'withDocs', driverData);
await tabSystemService.openTabWithSubTabs('vehicle', vehicleData, ['dados', 'documentos']);
await tabSystemService.openTabWithPreset('client', 'complete', clientData);
// Sistema detecta automaticamente:
// - Se é criação (id === 'new') ou edição
// - Quais sub-abas renderizar
// - Como salvar (create vs update)
```
#### **Salvamento Genérico**
```typescript
// Sistema automático - sem código adicional necessário
// 1. Formulário é submetido
// 2. TabSystem emite evento 'formSubmit'
// 3. BaseDomainComponent recebe e processa
// 4. Auto-detecta createEntity() ou updateEntity()
// 5. Chama callbacks success/error automaticamente
// 6. Atualiza UI e remove modificações
// Customização opcional:
protected createEntity(data: any): Observable<any> {
return this.entityService.createWithValidation(data);
}
```
### **Mobile Footer Menu**
```typescript
// Uso automático - já integrado no layout
// Visível apenas em dispositivos móveis (≤768px)
// Controle programático
import { MobileMenuService } from './services/mobile-menu.service';
// Atualizar notificações
this.mobileMenuService.setMeliNotifications(5);
this.mobileMenuService.setVehicleNotifications(2);
```
### **Data Table (Integrada ao Framework)**
```typescript
// Configuração automática via BaseDomainComponent
protected getDomainConfig(): DomainConfig {
return {
columns: [
{ field: 'name', header: 'Nome', sortable: true },
{ field: 'email', header: 'Email', filterable: true }
],
// Ações automáticas: [Editar] [Novo] já incluídas
};
}
```
## 🎨 Design Guidelines
### Cores Principais
```scss
:root {
--idt-primary: #FFC82E; // Dourado
--idt-secondary: #000000; // Preto
--idt-background: #FFFFFF; // Branco
--idt-surface: #F5F5F5; // Cinza claro
}
```
### Breakpoints
```scss
// Mobile
@media (max-width: 768px) { }
// Tablet
@media (min-width: 769px) and (max-width: 1024px) { }
// Desktop
@media (min-width: 1025px) { }
```
## 🧪 Testes
### **Framework CRUD (NOVO)**
```typescript
// Teste do fluxo completo CRUD
describe('BaseDomainComponent', () => {
it('should auto-detect create operation', async () => {
const component = new ClientsComponent(...);
const mockData = { id: 'new', name: 'João' };
await component.onFormSubmit({
formData: mockData,
isNewItem: true,
onSuccess: jasmine.createSpy(),
onError: jasmine.createSpy()
});
expect(mockService.createClient).toHaveBeenCalledWith(mockData);
});
});
```
### Executar Testes
```bash
# Testes unitários
npm run test
# Testes com cobertura
npm run test:coverage
# Testes end-to-end
npm run e2e
```
## 📦 Deploy
### Ambiente de Desenvolvimento
```bash
# Servidor local
ng serve idt_app
# Acesso: http://localhost:4200
```
### Ambiente de Produção
```bash
# Build otimizado
ng build idt_app --configuration production
# Arquivos gerados em: dist/idt_app/
```
## 🤝 Contribuição
### Workflow
1. **Fork** do repositório
2. **Branch** para feature (`git checkout -b feature/nova-funcionalidade`)
3. **Commit** das mudanças (`git commit -m 'Add: nova funcionalidade'`)
4. **Push** para branch (`git push origin feature/nova-funcionalidade`)
5. **Pull Request** detalhado
### **Padrões do Framework CRUD**
```typescript
// ✅ CORRETO: Usar BaseDomainComponent para novos domínios
export class NewDomainComponent extends BaseDomainComponent<Entity> {
protected getDomainConfig(): DomainConfig { /* configuração */ }
}
// ✅ CORRETO: Usar API genérica para abrir abas
await tabSystemService.openTabWithPreset('entity', 'preset', data);
// ❌ INCORRETO: Reimplementar CRUD manualmente
// export class NewDomainComponent implements OnInit { /* código duplicado */ }
```
### Commits Semânticos
```bash
feat: adiciona nova funcionalidade
fix: corrige bug específico
docs: atualiza documentação
style: melhora estilos
refactor: refatora código
test: adiciona testes
```
## 📞 Suporte
### Canais de Suporte
- **Issues**: Para bugs e feature requests
- **Discussions**: Para dúvidas gerais
- **Wiki**: Para documentação adicional
### FAQ
**Q: Como implementar um novo domínio CRUD?**
```typescript
// Apenas estender BaseDomainComponent e configurar
export class NewDomainComponent extends BaseDomainComponent<T> {
protected getDomainConfig(): DomainConfig { /* config */ }
}
```
**Q: Como personalizar salvamento de um domínio?**
```typescript
// Sobrescrever createEntity/updateEntity conforme necessário
protected createEntity(data: any): Observable<any> {
return this.service.customCreate(data);
}
```
**Q: Como abrir aba com sub-abas específicas?**
```typescript
// Usar API genérica
await tabSystemService.openTabWithSubTabs('driver', data, ['dados', 'endereco']);
```
**Q: Como forçar o mobile menu em desktop?**
```typescript
// Para testes/desenvolvimento
this.mobileMenuService.setVisibility(true);
```
## 📄 Licença
Este projeto está sob licença privada da **Equipe GrupoPRA**.
## 🔄 Changelog
### v2.0.0 (Junho 2025) - **FRAMEWORK CRUD UNIVERSAL**
- 🚀 **BaseDomainComponent**: CRUD genérico para qualquer domínio
- 🚀 **TabSystemComponent**: Sistema de abas configuráveis com sub-abas
- 🚀 **GenericTabFormComponent**: Formulários automáticos
- 🚀 **Sistema de Salvamento Genérico**: Auto-detecta create/update
- 🚀 **API Universal**: Mesma interface para todos os domínios
- 🚀 **Event-driven Architecture**: Comunicação padronizada
-**Backwards Compatible**: Nenhuma funcionalidade removida
### v1.0.0 (Maio 2025)
- ✅ Implementação do Mobile Footer Menu
- ✅ Sistema de notificações em tempo real
- ✅ Design system PraFrota aplicado
- ✅ Integração com layout principal
- ✅ Documentação completa
---
**Última atualização**: Junho 2025
**Versão da documentação**: 2.0.0
**Framework**: CRUD Universal v2.0.0
**Mantido por**: Equipe Grupo PRA