feat: Event Listener — recebe fotos faciais via HTTP Host Notification

Novo módulo core/event_listener.py:
- EventListener: servidor HTTP que recebe eventos dos terminais
- Extrai foto JPEG do multipart do evento de autenticação facial
- Salva automaticamente no _FaceCache (face_cache/{employeeNo}.jpg)
- configure_http_host(): configura terminal para enviar eventos
- Habilita uploadVerificationPic + saveVerificationPic
- Callbacks on_event e on_photo para integração com UI

Testado: configuração aceita pelo DS-K1T672MX (ok=True)
Listener funciona em 172.16.143.55:8889

Bump v4.2.1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Glauber Varjão

build_info.py

@@ -1 +1 @@
-BUILD_TIMESTAMP = "2026-04-01 21:22"
+BUILD_TIMESTAMP = "2026-04-01 21:36"

core/event_listener.py

@@ -0,0 +1,374 @@
+"""
+Protector ISAPI Manager — Event Listener (HTTP Host Mode)
+Recebe eventos em tempo real dos terminais Hikvision via HTTP POST.
+
+Quando o terminal autentica uma face, envia o evento com a foto capturada
+em formato multipart. Este listener extrai a foto e salva no cache local.
+
+Ref: ISAPI AccessControl Protocol — item 4.1 a 4.6
+"""
+
+import json
+import logging
+import os
+import re
+import socket
+import threading
+from datetime import datetime
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Callable, Optional, Dict, Any
+
+logger = logging.getLogger("event_listener")
+
+
+def _extract_jpeg(data: bytes) -> Optional[bytes]:
+    """Extrai JPEG de dados multipart ou raw."""
+    if not data:
+        return None
+    start = data.find(b'\xff\xd8\xff')
+    if start >= 0:
+        end = data.rfind(b'\xff\xd9')
+        if end > start:
+            return data[start:end + 2]
+    return None
+
+
+def _parse_multipart_event(body: bytes, content_type: str) -> Dict[str, Any]:
+    """Parseia evento multipart do terminal Hikvision.
+
+    O terminal envia:
+    - Parte JSON/XML com dados do evento (employeeNo, nome, resultado, etc)
+    - Parte binária com a foto capturada (JPEG)
+
+    Returns:
+        {"event_data": dict, "photo": bytes_or_none, "raw_parts": [...]}
+    """
+    result = {"event_data": {}, "photo": None, "raw_parts": []}
+
+    # Extrair boundary do Content-Type
+    boundary = None
+    if "boundary=" in content_type:
+        boundary = content_type.split("boundary=")[-1].strip().strip('"')
+
+    if boundary:
+        separator = f"--{boundary}".encode()
+        parts = body.split(separator)
+
+        for part in parts:
+            if not part or part.strip() in (b"", b"--", b"--\r\n"):
+                continue
+
+            # Separar headers do body da parte
+            header_end = part.find(b"\r\n\r\n")
+            if header_end < 0:
+                header_end = part.find(b"\n\n")
+            if header_end < 0:
+                continue
+
+            part_headers = part[:header_end].decode("utf-8", errors="replace").lower()
+            part_body = part[header_end + 4:]  # skip \r\n\r\n
+
+            result["raw_parts"].append({
+                "headers": part_headers,
+                "size": len(part_body)
+            })
+
+            # Parte JSON
+            if "application/json" in part_headers:
+                try:
+                    text = part_body.decode("utf-8", errors="replace").strip()
+                    # Remover trailing boundary markers
+                    if text.endswith("--"):
+                        text = text[:-2].strip()
+                    result["event_data"] = json.loads(text)
+                except Exception:
+                    pass
+
+            # Parte XML
+            elif "application/xml" in part_headers or "text/xml" in part_headers:
+                try:
+                    import xml.etree.ElementTree as ET
+                    text = part_body.decode("utf-8", errors="replace").strip()
+                    if text.endswith("--"):
+                        text = text[:-2].strip()
+                    root = ET.fromstring(text)
+                    # Converter XML básico para dict
+                    event_dict = {}
+                    for child in root.iter():
+                        tag = child.tag.split("}")[-1] if "}" in child.tag else child.tag
+                        if child.text and child.text.strip():
+                            event_dict[tag] = child.text.strip()
+                    if event_dict:
+                        result["event_data"] = event_dict
+                except Exception:
+                    pass
+
+            # Parte imagem
+            elif "image/" in part_headers or b"\xff\xd8\xff" in part_body[:10]:
+                img = _extract_jpeg(part_body)
+                if img and len(img) > 100:
+                    result["photo"] = img
+
+    else:
+        # Sem boundary — tentar parsear como JSON puro
+        try:
+            result["event_data"] = json.loads(body.decode("utf-8", errors="replace"))
+        except Exception:
+            pass
+        # Tentar extrair JPEG mesmo sem boundary
+        img = _extract_jpeg(body)
+        if img and len(img) > 100:
+            result["photo"] = img
+
+    return result
+
+
+class EventHandler(BaseHTTPRequestHandler):
+    """Handler HTTP que recebe eventos dos terminais Hikvision."""
+
+    # Referência ao listener (setada pelo EventListener)
+    listener = None
+
+    def do_POST(self, *args, **kwargs):
+        """Recebe evento POST do terminal."""
+        try:
+            content_length = int(self.headers.get("Content-Length", 0))
+            content_type = self.headers.get("Content-Type", "")
+            body = self.rfile.read(content_length) if content_length > 0 else b""
+
+            # Resposta obrigatória: "HTTP/1.1 200 " (com espaço) — ref item 4.4
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain")
+            self.end_headers()
+            self.wfile.write(b"OK")
+
+            # Processar evento em thread separada para não bloquear
+            if body and self.listener:
+                threading.Thread(
+                    target=self.listener._process_event,
+                    args=(body, content_type, self.client_address[0]),
+                    daemon=True
+                ).start()
+
+        except Exception as e:
+            logger.error(f"Erro no handler: {e}")
+            try:
+                self.send_response(200)
+                self.end_headers()
+            except Exception:
+                pass
+
+    def do_GET(self, *args, **kwargs):
+        """Health check."""
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps({
+            "status": "running",
+            "service": "Protector Event Listener",
+            "events_received": self.listener.event_count if self.listener else 0,
+            "photos_cached": self.listener.photo_count if self.listener else 0,
+        }).encode())
+
+    def log_message(self, format, *args):
+        """Silenciar log padrão do HTTPServer."""
+        pass
+
+
+class EventListener:
+    """Servidor HTTP que escuta eventos dos terminais Hikvision.
+
+    Uso:
+        listener = EventListener(port=8888, on_event=callback)
+        listener.start()  # inicia em background thread
+        # ... quando terminar:
+        listener.stop()
+    """
+
+    def __init__(self, port: int = 8888,
+                 on_event: Optional[Callable] = None,
+                 on_photo: Optional[Callable] = None):
+        """
+        Args:
+            port: Porta HTTP para escutar
+            on_event: Callback(event_data: dict, photo: bytes|None, source_ip: str)
+            on_photo: Callback(employee_no: str, jpeg: bytes, source_ip: str)
+        """
+        self.port = port
+        self.on_event = on_event
+        self.on_photo = on_photo
+        self.event_count = 0
+        self.photo_count = 0
+        self._server = None
+        self._thread = None
+        self._running = False
+
+    def start(self):
+        """Inicia o listener em background thread."""
+        if self._running:
+            return
+
+        EventHandler.listener = self
+
+        try:
+            self._server = HTTPServer(("0.0.0.0", self.port), EventHandler)
+            self._running = True
+            self._thread = threading.Thread(
+                target=self._server.serve_forever,
+                daemon=True,
+                name="event-listener"
+            )
+            self._thread.start()
+            logger.info(f"Event Listener iniciado na porta {self.port}")
+        except OSError as e:
+            logger.error(f"Falha ao iniciar listener na porta {self.port}: {e}")
+            raise
+
+    def stop(self):
+        """Para o listener."""
+        self._running = False
+        if self._server:
+            self._server.shutdown()
+            self._server = None
+        logger.info("Event Listener parado")
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    def get_local_ip(self) -> str:
+        """Detecta o IP local da máquina para configurar no terminal."""
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            s.connect(("8.8.8.8", 80))
+            ip = s.getsockname()[0]
+            s.close()
+            return ip
+        except Exception:
+            return "127.0.0.1"
+
+    def _process_event(self, body: bytes, content_type: str, source_ip: str):
+        """Processa evento recebido do terminal."""
+        try:
+            self.event_count += 1
+            parsed = _parse_multipart_event(body, content_type)
+            event_data = parsed.get("event_data", {})
+            photo = parsed.get("photo")
+
+            # Extrair employeeNo do evento
+            emp_no = (
+                event_data.get("employeeNoString")
+                or event_data.get("employeeNo")
+                or event_data.get("EmployeeNo")
+                or ""
+            )
+
+            # Log resumido
+            event_type = event_data.get("eventType", event_data.get("EventType", "?"))
+            name = event_data.get("name", event_data.get("Name", ""))
+            major = event_data.get("majorEventType", "")
+            minor = event_data.get("minorEventType", event_data.get("subEventType", ""))
+
+            logger.info(
+                f"Evento: ip={source_ip} type={event_type} major={major} minor={minor} "
+                f"emp={emp_no} name={name} photo={len(photo) if photo else 0}B"
+            )
+
+            # Salvar foto no cache
+            if photo and emp_no:
+                self.photo_count += 1
+                try:
+                    # Importar cache aqui para evitar circular import
+                    from core.isapi_client import _FaceCache
+                    _FaceCache().save(emp_no, photo)
+                    logger.info(f"Foto salva no cache: {emp_no} ({len(photo)//1024}KB)")
+                except Exception as e:
+                    logger.warning(f"Erro ao salvar foto no cache: {e}")
+
+                # Callback de foto
+                if self.on_photo:
+                    try:
+                        self.on_photo(emp_no, photo, source_ip)
+                    except Exception as e:
+                        logger.warning(f"Erro no callback on_photo: {e}")
+
+            # Callback geral
+            if self.on_event:
+                try:
+                    self.on_event(event_data, photo, source_ip)
+                except Exception as e:
+                    logger.warning(f"Erro no callback on_event: {e}")
+
+        except Exception as e:
+            logger.error(f"Erro ao processar evento: {e}")
+
+
+def configure_http_host(client, listener_ip: str, listener_port: int = 8888,
+                        host_id: int = 1, endpoint: str = "/event") -> Dict[str, Any]:
+    """Configura o terminal para enviar eventos para o listener.
+
+    Args:
+        client: ISAPIClient do terminal
+        listener_ip: IP do servidor que vai receber os eventos
+        listener_port: Porta do listener
+        host_id: ID do host (1-8)
+        endpoint: Path do endpoint no listener
+
+    Returns:
+        {"ok": bool, "error": str}
+    """
+    import xml.etree.ElementTree as ET
+
+    # 1. Configurar HTTP Host Notification
+    xml_host = f"""<?xml version="1.0" encoding="UTF-8"?>
+<HttpHostNotificationList version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
+  <HttpHostNotification>
+    <id>{host_id}</id>
+    <url>{endpoint}</url>
+    <protocolType>HTTP</protocolType>
+    <parameterFormatType>JSON</parameterFormatType>
+    <addressingFormatType>ipaddress</addressingFormatType>
+    <ipAddress>{listener_ip}</ipAddress>
+    <portNo>{listener_port}</portNo>
+    <httpAuthenticationMethod>none</httpAuthenticationMethod>
+  </HttpHostNotification>
+</HttpHostNotificationList>"""
+
+    r = client.put("/ISAPI/Event/notification/httpHosts",
+                   data=xml_host, content_type="application/xml")
+    if not r.get("ok"):
+        return {"ok": False, "error": f"httpHosts falhou: {r.get('error', r.get('status_code'))}"}
+
+    # 2. Habilitar upload de foto de verificação
+    acs_cfg = json.dumps({"AcsCfg": {
+        "uploadVerificationPic": True,
+        "saveVerificationPic": True
+    }})
+    r2 = client.put("/ISAPI/AccessControl/AcsCfg?format=json",
+                    data=acs_cfg, content_type="application/json")
+    if not r2.get("ok"):
+        # Não é erro fatal — pode ser que o terminal já tenha habilitado
+        logger.warning(f"AcsCfg: {r2.get('error', r2.get('status_code'))}")
+
+    # 3. Configurar filtro de eventos (opcional — para receber apenas face events)
+    # minorEvent 0x4b = face authentication completed
+    try:
+        sub_xml = f"""<?xml version="1.0" encoding="UTF-8"?>
+<EventTriggerList version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
+  <EventTrigger>
+    <id>AccessControl</id>
+    <EventTriggerNotificationList>
+      <EventTriggerNotification>
+        <id>{host_id}</id>
+        <notificationMethod>HTTP</notificationMethod>
+        <notificationRecurrence>beginning</notificationRecurrence>
+      </EventTriggerNotification>
+    </EventTriggerNotificationList>
+  </EventTrigger>
+</EventTriggerList>"""
+        client.put("/ISAPI/Event/triggers",
+                   data=sub_xml, content_type="application/xml")
+    except Exception:
+        pass  # Não é crítico
+
+    return {"ok": True, "error": ""}