Initial commit

doc/expansion.md

@@ -0,0 +1,112 @@
+# Guia de Expansão e Desenvolvimento
+
+Este documento explica como adicionar novos recursos (métodos) e suportar novos fabricantes (drivers) na API Zabbix OLT.
+
+## Arquitetura
+A API segue um padrão de **Factory** simplificado:
+1.  **Driver Base (`drivers/__init__.py`)**: Define a interface comum (`OltDriver`).
+2.  **Implementações (`drivers/nokia.py`, etc)**: Classes concretas que herdam de `OltDriver`.
+3.  **API (`app.py`)**: Roteia as requisições para o método correto do driver instanciado.
+
+---
+
+## 1. Adicionar Novo Tipo de Monitoramento (Ex: Interfaces)
+
+Para adicionar uma nova coleta de dados (ex: estatísticas de interface, temperatura, CPU):
+
+### Passo 1: Atualizar o Contrato
+Edite `drivers/__init__.py` e adicione o método abstrato na classe `OltDriver`.
+
+```python
+@abstractmethod
+def get_interface_stats(self):
+    """Retorna estatísticas de interfaces Ethernet/Uplink/PON."""
+    pass
+```
+
+### Passo 2: Implementar nos Drivers
+Atualize **todas** as classes que herdam de `OltDriver` (ex: `drivers/nokia.py`).
+
+```python
+def get_interface_stats(self):
+    connection = self.connect()
+    output = connection.send_command_timing("show interface ...")
+    
+    # Implementar lógica de parsing (regex)
+    stats = self._parse_interfaces(output)
+    
+    connection.disconnect()
+    return stats
+```
+
+### Passo 3: Criar Rota na API
+Edite `app.py` para expor o novo método.
+
+```python
+@app.route('/api/v1/interface_stats', methods=['GET'])
+@cache_response
+def get_interface_stats():
+    # ... (Copiar lógica de instanciação do driver de get_pon_stats) ...
+    
+    try:
+        stats = driver.get_interface_stats()
+        return jsonify({"data": stats, "meta": ...})
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500
+```
+
+---
+
+## 2. Adicionar Novo Fabricante (Vendor)
+
+Para suportar uma nova OLT (ex: Huawei, ZTE):
+
+### Passo 1: Criar o Driver
+Crie um arquivo em `drivers/` (ex: `drivers/huawei.py`).
+
+```python
+from drivers import OltDriver
+import re
+
+class HuaweiDriver(OltDriver):
+    def connect(self):
+        # Configurar conexão Netmiko (device_type='huawei')
+        return ConnectHandler(...)
+
+    def get_pon_stats(self):
+        connection = self.connect()
+        output = connection.send_command("display ont info ...")
+        connection.disconnect()
+        return self._parse_output(output)
+```
+
+### Passo 2: Registrar o Driver
+Edite `app.py` e importe a nova classe.
+
+```python
+from drivers.huawei import HuaweiDriver
+
+DRIVERS = {
+    'nokia': NokiaDriver,
+    'fiberhome': FiberhomeDriver,
+    'huawei': HuaweiDriver  # <--- Novo registro
+}
+```
+
+### Passo 3: Configurar Host
+No `hosts.json`, defina o driver para o IP correspondente.
+
+```json
+"10.10.10.1": {
+    "driver": "huawei",
+    ...
+}
+```
+
+---
+
+## Dicas de Desenvolvimento
+
+- **Netmiko Timing**: Use `send_command_timing` se o equipamento tiver prompts complexos ou lentidão.
+- **Regex**: Teste suas expressões regulares com outputs reais variados para garantir robustez.
+- **Cache**: O decorador `@cache_response` em `utils/cache.py` já trata cache por URL (host distinto = cache distinto).