> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingoai.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia dev completo

> Manual de onboarding tecnico para desenvolver em qualquer area do ExclusiveDay.

## Objetivo desta pagina

Se um dev novo pegar apenas esta documentacao, ele deve conseguir:

* subir o ambiente
* entender a arquitetura
* localizar qualquer parte do codigo
* implementar features em backend, channel e frontend
* criar migration/seed com seguranca
* debugar erro de request, socket, fila e integracao

## 1) Mapa do monorepo

Raiz: `C:\Users\guilh\crm`

* `Backend-1`: API principal, auth, regras de negocio, socket, event bus e workers.
* `channel-2`: integracoes de canais (Baileys/Meta), consumers/producers Rabbit e bus de eventos.
* `frontend`: app React com rotas, paginas, hooks, contextos e componentes.
* `deploy`: infraestrutura Docker (Traefik, Postgres, Redis, RabbitMQ, MinIO, backend, channel, frontend, transcricao).
* `scripts`: instaladores automatizados para deploy.

## 2) Fluxo completo da aplicacao

1. Usuario aciona tela no frontend.
2. Frontend chama endpoint HTTP no backend.
3. Backend executa regra de negocio (service/model) e pode publicar em Rabbit.
4. Channel consome eventos/fila e conversa com canal externo.
5. Channel devolve resposta/notificacao para backend.
6. Backend emite evento via Socket.IO.
7. Frontend atualiza interface em tempo real no ExclusiveDay.

## 3) Como navegar no backend (`Backend-1`)

Arquitetura principal:

* `src/server.ts`: bootstrap do servidor, fila, crons, socket init.
* `src/app.ts`: middlewares globais, CORS, erro global, registro de rotas.
* `src/routes/index.ts`: agregador de todos os modulos de rota.
* `src/controllers`: camada HTTP.
* `src/services`: regra de negocio.
* `src/models`: entidades Sequelize.
* `src/middleware/isAuth.ts`: validacao de token.
* `src/libs/socket.ts`: namespaces e eventos Socket.IO.

Padrao de implementacao de endpoint:

1. Criar service em `src/services/<Dominio>Services`.
2. Criar/ajustar controller em `src/controllers`.
3. Criar rota em `src/routes/<dominio>Routes.ts`.
4. Registrar no `src/routes/index.ts`.
5. Se precisar realtime, emitir via `getIO()` (socket).

## 4) Como navegar no channel (`channel-2`)

Arquitetura principal:

* `src/server.ts`: bootstrap do channel, start do bus e inicializacao dos consumers.
* `src/bus-rabbitmq/bus-rabbitmq.ts`: registro dos handlers de comandos/eventos.
* `src/bus-rabbitmq/rabbitmq-transport.ts`: retry, DLQ, bind exchange/queue.
* `src/handlers`: handlers de comandos (baileys/meta/schedule/campaign).
* `src/consumers`: consumers RPC diretos.
* `src/producers`: envio direto para filas.
* `src/services/flow`: logica de flow builder no channel.

Padrao para nova integracao:

1. Criar command/event + handler em `src/handlers`.
2. Registrar handler no `bus-rabbitmq.ts`.
3. Se for RPC direto, criar consumer em `src/consumers` e iniciar no `server.ts`.
4. Criar producer em `src/producers` para chamadas de outros servicos.

## 5) Como navegar no frontend (`frontend`)

Arquitetura principal:

* `src/routes/index.js`: rotas publicas e privadas.
* `src/layout/MainListItems.js`: menu lateral e visibilidade por permissao/plano.
* `src/pages`: telas por modulo.
* `src/components`: componentes reutilizaveis.
* `src/hooks`: acesso a API e estado de dominio.
* `src/context`: auth, tickets, whatsapp etc.
* `src/services/api.js`: cliente HTTP.
* `src/services/socket.js`: cliente Socket.IO.

Padrao para nova tela/modulo:

1. Criar pagina em `src/pages/<NovaTela>/index.js`.
2. Adicionar rota em `src/routes/index.js`.
3. Adicionar item no menu em `src/layout/MainListItems.js`.
4. Criar hook de dados em `src/hooks`.
5. Integrar endpoints via `src/services/api.js`.

## 6) Migrations e seeds (backend + channel)

Backend:

* Migrations: `Backend-1/src/database/migrations`
* Seeds: `Backend-1/src/database/seeds`
* Comandos: `npm run db:migrate` e `npm run db:seed`

Channel:

* Migrations: `channel-2/src/database/migrations`
* Seeds: `channel-2/src/database/seeds`
* Comandos: `npm run db:migrate` e `npm run db:seed`

Observacao importante:

* O `channel-2/package.json` chama `copy:migrations` antes do migrate. Validar esse passo no ambiente antes de pipeline.

## 7) Mensageria (RabbitMQ) para dev

Filas de RPC entre backend e channel:

* `check-contact-number-queue`
* `get-profile-picture-queue`
* `create-or-update-contact-queue`
* `notification-queue`

Filas de event bus (por servico):

* `backend-event-bus-queue`
* `channel-event-bus-queue`

Referencia detalhada:

* `essentials/eventos-rabbitmq`

## 8) Como adicionar um modulo novo (fim a fim)

Checklist rapido:

1. Definir dominio (ex.: `smart-campaigns`).
2. Backend: rota + controller + service + model (se necessario).
3. Channel: producer/consumer/handler (se houver integracao externa).
4. Frontend: pagina + rota + menu + hook + componentes.
5. Banco: migration e seed quando aplicavel.
6. Tempo real: evento socket se a UI precisar de atualizacao imediata.
7. Docs: atualizar `modulos-crm` e este guia.

## 9) Debug por camada

### Backend

* verificar `src/server.ts` e `src/app.ts`
* confirmar token em `isAuth.ts`
* inspecionar erro de service/controller nos logs
* validar emissao socket em `libs/socket.ts`

### Channel

* confirmar start do bus em `channel-2/src/server.ts`
* validar `RABBITMQ_URI` e `RABBITMQ_QUEUE_NAME`
* checar handlers registrados no `bus-rabbitmq.ts`
* acompanhar retries/DLQ no transport custom

### Frontend

* confirmar `REACT_APP_BACKEND_URL`
* checar interceptors/login em `hooks/useAuth.js`
* validar rota e permissao em `routes/index.js` e `MainListItems.js`
* checar assinatura de socket no hook do modulo

## 10) Convencoes de codigo observadas

* Controllers em `PascalCaseController.ts`.
* Services em pastas por dominio com sufixo `Service`.
* Rotas em `camelCaseRoutes.ts`.
* Models em `PascalCase.ts`.
* Uso de `isAuth` para proteger endpoints privados.
* Uso de `companyId` como particionamento funcional em varios fluxos.

## 11) Roteiro de onboarding para dev novo (1 dia)

1. Subir stack (`quickstart`) ou ambiente local (`development`).
2. Rodar migrations e seeds.
3. Login admin e navegar modulos principais.
4. Ler `arquitetura-backend-frontend`.
5. Ler `eventos-rabbitmq`.
6. Implementar uma alteracao pequena em um modulo (backend + frontend).
7. Validar fluxo com socket/mensageria quando aplicavel.

Com isso, o dev ja consegue evoluir qualquer area do ExclusiveDay com autonomia.