first commit

2025-08-08 10:22:27 -03:00
commit d0d99063e2
@@ -0,0 +1,326 @@
+# Funcionalidade: Adicionar ONU
+
+## Descrição
+Nova funcionalidade implementada para adicionar ONUs automaticamente nas OLTs, incluindo descoberta de slot, determinação de ONU ID disponível, configuração de VLAN e criação de service-port.
+
+## Como Usar
+
+### Comando de Texto
+```
+adicionar onu SERIAL_DA_ONU
+add onu SERIAL_DA_ONU
+cadastrar onu SERIAL_DA_ONU
+criar onu SERIAL_DA_ONU
+registrar onu SERIAL_DA_ONU
+```
+
+### Exemplos
+- `adicionar onu FHTT12345678`
+- `add onu DACM91569513`
+- `cadastrar onu ABCD12345678`
+
+## Fluxo de Operação
+
+### 1. Comando Inicial
+O usuário digita o comando com o serial da ONU que deseja adicionar.
+
+### 2. Seleção da OLT
+O bot apresenta uma lista das OLTs disponíveis para o usuário escolher onde adicionar a ONU.
+
+### 3. Descoberta do Slot
+O sistema executa `show interface gpon discovered-onus` para encontrar o slot onde a ONU foi descoberta.
+
+### 4. Análise de ONU IDs
+O sistema executa `show interface gpon SLOT onu | nomore` para descobrir quais ONU IDs (0-127) estão em uso.
+
+### 5. Determinação da VLAN
+Com base na OLT e slot, o sistema determina automaticamente o VLAN ID usando o mapeamento pré-configurado.
+
+### 6. Confirmação
+Antes de adicionar, o bot exibe todas as informações e pede confirmação:
+- Serial da ONU
+- Slot descoberto
+- ONU ID que será usado
+- VLAN ID
+- Configurações que serão aplicadas
+
+### 7. Adição Automática
+Após confirmação, o sistema executa automaticamente todos os comandos necessários.
+
+## Comandos SSH Executados
+
+### Descoberta do Slot
+```bash
+show interface gpon discovered-onus
+```
+
+### Verificação de ONU IDs em Uso
+```bash
+show interface gpon 1/1/3 onu | nomore
+```
+
+### Configuração da ONU
+```bash
+config
+interface gpon 1/1/3          # Slot descoberto
+onu 42                        # Próximo ID disponível
+line-profile DM986-100
+serial-number FHTT12345678
+ethernet 1
+native vlan vlan-id 603       # VLAN baseada na OLT/slot
+top
+service-port new
+gpon 1/1/3 onu 42 gem 1 match vlan vlan-id 603 action vlan replace vlan-id 603
+commit
+top
+exit
+exit
+```
+
+## Mapeamento de VLANs
+
+### OLT DITO
+| Slot | VLAN |
+|------|------|
+| 1/1/1 | 601 |
+| 1/1/2 | 602 |
+| 1/1/3 | 603 |
+| 1/1/4 | 604 |
+
+### OLT COLMEIA
+| Slot | VLAN |
+|------|------|
+| 1/1/1 | 605 |
+| 1/1/2 | 606 |
+| 1/1/3 | 607 |
+| 1/1/4 | 608 |
+| 1/1/5 | 609 |
+| 1/1/6 | 610 |
+| 1/1/7 | 611 |
+| 1/1/8 | 612 |
+| 1/1/9 | 613 |
+| 1/1/10 | 614 |
+| 1/1/11 | 608 |
+| 1/1/12 | 616 |
+| 1/1/13 | 617 |
+| 1/1/14 | 618 |
+| 1/1/15 | 619 |
+| 1/1/16 | 620 |
+
+### OLT CANAA
+| Slot | VLAN |
+|------|------|
+| 1/1/1 | 605 |
+| 1/1/2 | 606 |
+| 1/1/3 | 607 |
+| 1/1/4 | 608 |
+| 1/1/5 | 609 |
+| 1/1/6 | 610 |
+| 1/1/7 | 611 |
+| 1/1/8 | 612 |
+
+### OLT CANAA 2
+| Slot | VLAN |
+|------|------|
+| 1/1/1 | 621 |
+| 1/1/2 | 622 |
+| 1/1/3 | 623 |
+| 1/1/4 | 624 |
+| 1/1/5 | 625 |
+| 1/1/6 | 626 |
+| 1/1/7 | 627 |
+| 1/1/8 | 628 |
+
+### OLT PEDRO AFONSO 1
+| Slot | VLAN |
+|------|------|
+| 1/1/1 | 301 |
+| 1/1/2 | 302 |
+| 1/1/3 | 303 |
+| 1/1/4 | 304 |
+| 1/1/5 | 305 |
+| 1/1/6 | 306 |
+| 1/1/7 | 307 |
+| 1/1/8 | 308 |
+| 1/1/9 | 309 |
+| 1/1/10 | 310 |
+| 1/1/11 | 311 |
+| 1/1/12 | 312 |
+| 1/1/13 | 313 |
+| 1/1/14 | 314 |
+| 1/1/15 | 315 |
+| 1/1/16 | 316 |
+
+### OLT CANAVIEIRAS
+| Slot | VLAN |
+|------|------|
+| 1/1/1 | 601 |
+| 1/1/2 | 602 |
+| 1/1/3 | 603 |
+| 1/1/4 | 604 |
+| 1/1/5 | 605 |
+| 1/1/6 | 606 |
+| 1/1/7 | 607 |
+| 1/1/8 | 608 |
+| 1/1/9 | 609 |
+| 1/1/10 | 610 |
+| 1/1/11 | 611 |
+| 1/1/12 | 612 |
+| 1/1/13 | 613 |
+| 1/1/14 | 614 |
+| 1/1/15 | 615 |
+| 1/1/16 | 616 |
+
+## Recursos de Segurança
+
+### Confirmação Obrigatória
+- Sistema exige confirmação explícita antes de adicionar
+- Exibe todas as configurações que serão aplicadas
+- Mostra ONU IDs já em uso no slot
+
+### Validação de Dados
+- Verifica se a ONU está na lista de discovered-onus
+- Encontra automaticamente o próximo ONU ID disponível
+- Valida se existe VLAN configurada para a OLT/slot
+
+### Processo Controlado
+- Usa shell interativo para manter contexto
+- Timeout de segurança (90 segundos)
+- Logging detalhado de todas as operações
+
+## Tratamento de Erros
+
+### ONU Não Descoberta
+- Mensagem clara informando que a ONU não está na lista discovered-onus
+- Sugestão para verificar se a ONU está ligada
+
+### Slot Lotado
+- Informa quando todos os ONU IDs (0-127) estão em uso
+- Sugere usar outro slot ou remover ONUs não utilizadas
+
+### VLAN Não Configurada
+- Alerta quando não há VLAN mapeada para a OLT/slot
+- Informa as configurações necessárias
+
+### Timeout
+- Processo é interrompido após 90 segundos
+- Conexão é fechada adequadamente
+
+## Resultados
+
+### Sucesso
+```
+✅ ONU Adicionada com Sucesso!
+
+📱 Serial: FHTT12345678
+📍 Localização: Slot 1/1/3, ONU 42
+🏷️ VLAN: 603
+🔌 Service-port: 1234
+🏢 OLT: DITO
+
+✅ Configurações aplicadas:
+• Line-profile: DM986-100
+• Serial number: FHTT12345678
+• Ethernet: porta 1
+• Native VLAN: 603
+• Service-port: criado e configurado
+• Configuração commitada
+
+🎉 A ONU está pronta para uso!
+```
+
+### Erro
+```
+❌ Não foi possível adicionar a ONU
+
+📱 Serial: FHTT12345678
+🏢 OLT: DITO
+
+❌ Erro: ONU FHTT12345678 não encontrada na lista de discovered-onus
+
+💡 Dica: Verifique se a ONU está ligada e descoberta pela OLT.
+Use o comando: show interface gpon discovered-onus
+```
+
+## Arquivos Modificados
+
+### 1. `src/ssh/manager.js`
+- `getVlanMapping()` - Mapeamento de VLANs por OLT/slot
+- `discoverOnuSlot()` - Descobre slot da ONU na lista discovered-onus
+- `getUsedOnuIds()` - Lista ONU IDs já em uso em um slot
+- `findNextAvailableOnuId()` - Encontra próximo ID disponível
+- `addOnu()` - Adiciona ONU completa (shell interativo)
+- `addOnuBySerial()` - Processo completo por serial
+
+### 2. `src/nlp/processor.js`
+- Adicionado 'adicionar_onu' aos actionSynonyms
+- Novos padrões regex para comandos de adição
+- Suporte para variações de comando (add, criar, cadastrar, registrar)
+
+### 3. `src/bot/handler.js`
+- `handleAdicionarOnu()` - Interface para comando adicionar
+- `handleAddOnuCallback()` - Callback para seleção de OLT e análise
+- `handleConfirmAddCallback()` - Callback para confirmação e execução
+- Atualização da mensagem de help
+
+## Considerações Técnicas
+
+### Performance
+- Processo otimizado em etapas bem definidas
+- Uso de shell interativo para operações complexas
+- Timeout de 90 segundos para operações da OLT
+
+### Confiabilidade
+- Validação em todas as etapas
+- Descoberta automática de configurações
+- Logs detalhados para troubleshooting
+
+### Usabilidade
+- Interface intuitiva com botões
+- Mensagens claras e informativas
+- Confirmação visual antes da ação
+
+## Limitações
+
+1. **Dependência de Discovered-onus**: ONU deve estar na lista discovered-onus
+2. **Mapeamento Fixo**: VLANs são pré-configuradas no código
+3. **Timeout**: Operações longas podem exceder 90s
+4. **Dependência SSH**: Requer conectividade estável
+
+## Próximas Melhorias
+
+1. **VLAN Configurável**: Permitir definir VLAN customizada
+2. **Line-profile Dinâmico**: Detectar modelo da ONU automaticamente
+3. **Validação Pós-adição**: Verificar se ONU subiu corretamente
+4. **Adição em Lote**: Adicionar múltiplas ONUs de uma vez
+
+## Teste da Funcionalidade
+
+### Cenário de Teste
+1. Certifique-se que há uma ONU na lista discovered-onus
+2. Digite: `adicionar onu SERIAL_DA_ONU`
+3. Selecione uma OLT na lista
+4. Verifique as informações exibidas
+5. Confirme a adição
+6. Aguarde conclusão da operação
+
+### Comandos de Teste
+- `adicionar onu TESTE123456`
+- `add onu TESTE123456`
+- `cadastrar onu TESTE123456`
+- `criar TESTE123456`
+
+### Verificação Manual
+```bash
+# Verificar se ONU está discovered
+show interface gpon discovered-onus
+
+# Verificar ONU IDs em uso
+show interface gpon 1/1/3 onu | nomore
+
+# Após adição, verificar se ONU subiu
+show interface gpon 1/1/3 onu ONUID
+
+# Verificar service-port criado
+show running-config service-port
+```