dengun_ai-admin-client/INTEGRATION_SETUP.md

Cliente simples para integração com o AI Admin Dashboard - Plug and Play

# 🚀 Setup Completo de Integração - AI Admin Dashboard

## 📋 Resumo das Implementações

Este documento detalha todas as implementações realizadas para criar um sistema completo de integração entre aplicações externas e o AI Admin Dashboard.

## 🎯 Funcionalidades Implementadas

### 1. **Setup Automático Completo**
- ✅ Comando `npx ai-admin-init` aprimorado
- ✅ Detecção automática de tipo de projeto (Next.js, Express, Standalone)
- ✅ Criação de arquivos de configuração completos
- ✅ Templates específicos por framework
- ✅ Arquivo .env com todas as configurações necessárias

### 2. **Comando de Solicitação de Conexão**
- ✅ Comando `npx ai-admin-request` implementado
- ✅ Envio automático de solicitação ao dashboard
- ✅ Validação de dados obrigatórios
- ✅ Salva informações da solicitação localmente
- ✅ Atualiza arquivo .env automaticamente

### 3. **Endpoints do Dashboard Criados/Atualizados**
- ✅ `/api/bots/auth` - Autenticação de bots externos
- ✅ `/api/bots/ping` - Heartbeat para manter conexão
- ✅ `/api/bots/validate-user` - Validar acesso de usuário ao bot
- ✅ `/api/bots/usage` - Receber dados de uso de tokens
- ✅ `/api/bots/errors` - Receber relatórios de erros (atualizado)
- ✅ `/api/bots/request` - Solicitar registro de bot (já existia)

### 4. **Melhorias no Package**
- ✅ Atualização do `ConnectionManager` para usar endpoints corretos
- ✅ Suporte a autenticação JWT com bot secret
- ✅ Envio em lotes de dados de uso e erros
- ✅ Reconexão automática em falhas
- ✅ Validação de usuários no dashboard

### 5. **Estrutura de Banco Atualizada**
- ✅ Adicionada coluna `bot_secret` na tabela `bots`
- ✅ Migração automática para gerar secrets únicos
- ✅ Índices de performance adicionados

## 🔄 Fluxo Completo de Integração

### Passo 1: Inicialização
```bash
# Instalar package
npm install dengun_ai-admin-client

# Criar setup completo
npx ai-admin-init
```

**Arquivos criados:**
- `ai-admin-config/.env` - Configurações de ambiente
- `ai-admin-config/client.ts` - Cliente configurado
- `ai-admin-config/exemplo.ts` - Exemplo de uso
- `ai-admin-config/express-server.ts` - Servidor Express (se detectado)
- `ai-admin-config/app/api/` - API Routes Next.js (se detectado)
- `ai-admin-config/package.json` - Dependências específicas
- `ai-admin-config/README.md` - Documentação

### Passo 2: Solicitação de Conexão
```bash
# Solicitar registro no dashboard
npx ai-admin-request \
  --name "Meu Bot" \
  --email "admin@exemplo.com" \
  --website "http://localhost:3001" \
  --description "Bot de atendimento"
```

**O que acontece:**
1. Envia solicitação para `/api/bots/request`
2. Cria notificação no dashboard para admin
3. Salva informações em `bot-request.json`
4. Atualiza arquivo `.env` com dados do bot

### Passo 3: Aprovação no Dashboard
1. Administrador recebe notificação
2. Analisa dados do bot
3. Aprova ou rejeita solicitação
4. Bot é criado e associado a todos os tenants ativos
5. Bot secret é gerado automaticamente

### Passo 4: Configuração Final
```bash
# Editar .env com bot_id e bot_secret recebidos
# BOT_ID=bot-id-gerado
# BOT_SECRET=secret-gerado-pelo-dashboard

# Instalar dependências
cd ai-admin-config
npm install

# Executar aplicação
npm start
```

## 📊 Dados Enviados Automaticamente

### 1. **Dados de Uso de Tokens**
```typescript
await client.reportUsage({
  sessionId: 'session_123',
  userId: 'user_456',
  tenantId: 'tenant_789',
  action: 'chat_message',
  tokensUsed: 150,
  metadata: {
    messageLength: 50,
    responseTime: 1200
  }
});
```

**Enviado para:** `/api/bots/usage`
**Armazenado em:** Tabela `token_usage` e `usage_stats`

### 2. **Relatórios de Erros**
```typescript
await client.reportError({
  sessionId: 'session_123',
  userId: 'user_456',
  tenantId: 'tenant_789',
  error: 'Rate limit exceeded',
  errorCode: 'RATE_LIMIT_ERROR',
  stack: 'Error stack trace...',
  context: { limit: 100, current: 150 }
});
```

**Enviado para:** `/api/bots/errors`
**Armazenado em:** Tabela `bot_errors`

### 3. **Monitoramento de Conexão**
- Autenticação inicial em `/api/bots/auth`
- Ping a cada 30 segundos em `/api/bots/ping`
- Validação de usuários em `/api/bots/validate-user`

## 🔧 Configurações Automáticas

### Arquivo .env Completo
```env
# ========================================
# AI ADMIN DASHBOARD - CONFIGURAÇÃO
# ========================================

# 🔗 CONEXÃO COM DASHBOARD (Obrigatório)
DASHBOARD_URL=http://localhost:3000
BOT_ID=seu-bot-id
BOT_SECRET=seu-bot-secret

# ⚙️ CONFIGURAÇÕES AUTOMÁTICAS (Opcional)
AUTO_REPORT_USAGE=true
AUTO_REPORT_ERRORS=true
REPORT_INTERVAL=30000
DEBUG=false

# 🔐 CONFIGURAÇÕES DE SEGURANÇA
JWT_SECRET=your-jwt-secret-here
API_TIMEOUT=10000
MAX_RETRIES=3

# 📊 CONFIGURAÇÕES DE TELEMETRIA
TELEMETRY_ENABLED=true
ERROR_REPORTING=true
ANALYTICS_ENABLED=true

# 🌐 CONFIGURAÇÕES DA APLICAÇÃO
NODE_ENV=development
PORT=3001
```

### Cliente Singleton
```typescript
// client.ts - Configuração automática
export const aiAdminClient = new AiAdminClient({
  dashboardUrl: process.env.DASHBOARD_URL!,
  botId: process.env.BOT_ID!,
  botSecret: process.env.BOT_SECRET!,
  options: {
    autoReportUsage: process.env.AUTO_REPORT_USAGE === 'true',
    autoReportErrors: process.env.AUTO_REPORT_ERRORS === 'true',
    reportInterval: parseInt(process.env.REPORT_INTERVAL || '30000'),
    timeout: parseInt(process.env.API_TIMEOUT || '10000'),
    maxRetries: parseInt(process.env.MAX_RETRIES || '3'),
    debug: process.env.DEBUG === 'true'
  }
});
```

## 🛠️ Integrações por Framework

### Express.js
```typescript
// express-server.ts - Gerado automaticamente
app.post('/api/chat', async (req, res) => {
  const { message, userId, tenantId } = req.body;
  
  await withAiAdmin(async (client) => {
    const session = await client.createUserSession(userId, tenantId);
    
    // Sua lógica de processamento aqui
    const response = await processMessage(message);
    
    // Relatório automático de uso
    await client.reportUsage({
      sessionId: session.sessionId,
      userId,
      tenantId,
      action: 'chat_message',
      tokensUsed: response.tokensUsed
    });
    
    res.json(response);
  });
});
```

### Next.js
```typescript
// app/api/chat/route.ts - Gerado automaticamente
export async function POST(request: NextRequest) {
  const { message, userId, tenantId } = await request.json();
  
  const result = await withAiAdmin(async (client) => {
    const session = await client.createUserSession(userId, tenantId);
    
    // Sua lógica aqui
    const response = await processMessage(message);
    
    // Relatório automático
    await client.reportUsage({
      sessionId: session.sessionId,
      userId,
      tenantId,
      action: 'chat_message',
      tokensUsed: response.tokensUsed
    });
    
    return response;
  });
  
  return NextResponse.json(result);
}
```

## 🔒 Segurança Implementada

### 1. **Autenticação de Bots**
- Bot ID único por aplicação
- Bot Secret gerado automaticamente (32 bytes)
- Tokens JWT com expiração
- Renovação automática de tokens

### 2. **Validação de Usuários**
- Verificação de permissões no tenant
- Validação de acesso ao bot específico
- Controle de tokens disponíveis
- Isolamento de dados por tenant

### 3. **Interceptação de Erros**
- Captura automática de erros não tratados
- Retry automático em falhas de rede
- Filas resilientes para não perder dados
- Categorização de erros por gravidade

## 📈 Analytics e Monitoramento

### Dados Coletados Automaticamente
1. **Uso de Tokens**
   - Por usuário, tenant e ação
   - Timestamp e duração
   - Metadata customizável

2. **Erros e Falhas**
   - Stack traces completos
   - Context da aplicação
   - Categorização automática

3. **Sessões de Usuários**
   - Duração das sessões
   - Ações realizadas
   - Performance metrics

4. **Status de Conexão**
   - Heartbeat contínuo
   - Latência de rede
   - Reconexões automáticas

## 🎯 Comandos Disponíveis

### Inicialização
```bash
npx ai-admin-init          # Setup completo
npx ai-admin-init --help   # Ajuda
```

### Solicitação de Conexão
```bash
npx ai-admin-request --name "Bot" --email "admin@exemplo.com"
npx ai-admin-request --help  # Ver todas as opções
```

### No Projeto Criado
```bash
npm start     # Executar aplicação
npm run dev   # Modo desenvolvimento
npm run test  # Executar exemplo
```

## ✅ Checklist de Implementação

- [x] Setup automático completo por tipo de projeto
- [x] Comando de solicitação de conexão
- [x] Todos os endpoints necessários no dashboard
- [x] Autenticação segura com bot secrets
- [x] Envio automático de dados de uso
- [x] Relatório automático de erros
- [x] Validação de usuários e permissões
- [x] Monitoramento de conexão
- [x] Reconexão automática
- [x] Templates para Express e Next.js
- [x] Documentação completa
- [x] Estrutura de banco atualizada

## 🚀 Resultado Final

Com essas implementações, qualquer desenvolvedor pode:

1. **Instalar o package** em 1 comando
2. **Criar setup completo** em 1 comando
3. **Solicitar conexão** em 1 comando
4. **Configurar credenciais** em 1 arquivo
5. **Executar aplicação** integrada em 1 comando

**Total: 5 comandos para integração completa!**

O sistema automaticamente:
- ✅ Conecta com o dashboard
- ✅ Valida usuários e permissões
- ✅ Reporta uso de tokens
- ✅ Reporta erros e falhas
- ✅ Mantém conexão ativa
- ✅ Reconecta em falhas
- ✅ Isola dados por tenant
- ✅ Monitora performance

**🎉 Integração 100% plug-and-play implementada com sucesso!**