# Factronics USA — Blueprint Operativo de Agentes IA
**Proyecto:** Ecosistema Hermes para Factronics USA / FACCA  
**Stack base:** Hostinger VPS → Coolify → n8n → Hermes (Claude API) → QuickBooks Desktop Bridge  
**Versión QB:** QuickBooks Desktop 2024 Manufacturing Edition  
**Fecha:** Junio 2026

---

## 1. Visión General de la Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                        HOSTINGER VPS                            │
│                     (Coolify orquesta todo)                     │
│                                                                 │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐   │
│  │   n8n        │   │  Hermes API  │   │   RAG Service    │   │
│  │ (Workflows)  │──▶│ (Orchestrator│──▶│ (Conocimiento    │   │
│  │              │   │  + Agents)   │   │  Factronics)     │   │
│  └──────┬───────┘   └──────┬───────┘   └──────────────────┘   │
│         │                  │                                     │
│  ┌──────▼───────┐   ┌──────▼───────┐   ┌──────────────────┐   │
│  │  PostgreSQL  │   │    Redis     │   │  Control Panel   │   │
│  │  (Estado,    │   │  (Colas,     │   │  (Dashboard      │   │
│  │   logs)      │   │   sessions)  │   │   Jovan)         │   │
│  └──────────────┘   └──────────────┘   └──────────────────┘   │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTPS / Cloudflare Tunnel
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              INFRAESTRUCTURA LOCAL FACTRONICS (Medley, FL)      │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │           QB BRIDGE SERVICE (Python + QBFC SDK)          │  │
│  │   QuickBooks Desktop 2024 Manufacturing Edition          │  │
│  │   Puerto local: 8765  │  Auth: token rotativo            │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
    Gmail API           HubSpot API          Slack API
  (accounting@       (CRM sync,           (Notificaciones
   jovan.gutic@)      pipelines)           al equipo)
```

---

## 2. Stack Tecnológico — Configuración por Componente

### 2.1 Hostinger VPS — Specs Recomendadas

```
Plan:    KVM 2 o superior
RAM:     8 GB mínimo (16 GB ideal)
CPU:     4 vCPUs
Storage: 100 GB SSD
OS:      Ubuntu 22.04 LTS
IP:      IP estática (obligatorio para tunnel QB)
```

### 2.2 Coolify — Plataforma de Despliegue

**Instalación:**
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```

**Servicios a desplegar en Coolify:**

| Servicio | Tipo | Puerto interno | Dominio sugerido |
|---|---|---|---|
| n8n | Docker container | 5678 | n8n.factronic-ops.com |
| Hermes API | Docker container | 8000 | api.factronic-ops.com |
| RAG Service | Docker container | 8001 | rag.factronic-ops.com |
| Control Panel | Docker container | 3000 | ops.factronic-ops.com |
| PostgreSQL | Database | 5432 | interno |
| Redis | Database | 6379 | interno |

**Variables de entorno globales en Coolify:**
```env
ANTHROPIC_API_KEY=sk-ant-...
GMAIL_CLIENT_ID=...
GMAIL_CLIENT_SECRET=...
GMAIL_REFRESH_TOKEN_JOVAN=...
GMAIL_REFRESH_TOKEN_ACCOUNTING=...
SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_OPS=#ops-agentes
HUBSPOT_API_KEY=...
QB_BRIDGE_URL=https://qb-bridge.factronics-internal.com
QB_BRIDGE_TOKEN=...
POSTGRES_URL=postgresql://hermes:xxx@postgres:5432/hermes
REDIS_URL=redis://redis:6379
```

---

### 2.3 QuickBooks Desktop Bridge — Componente Crítico

**Qué es:** Un servicio Python que corre en la misma máquina (o servidor Windows local) donde está instalado QuickBooks Desktop. Expone una API REST que Hermes puede llamar desde el VPS.

**Stack del Bridge:**
```
Python 3.11
FastAPI (HTTP server)
pywin32 (comunicación con QBXMLRP2 COM object)
Cloudflare Tunnel (exposición segura sin abrir puertos)
```

**Endpoints que expone el Bridge:**

```
GET  /health                    → Ping (QuickBooks está abierto y responde)
GET  /customers                 → Lista clientes con ID interno QB
GET  /customers/{id}            → Detalle de cliente + términos de pago
GET  /items                     → Lista de productos/items con precio vigente
GET  /items/{item_code}         → Precio unitario y descripción
POST /sales-orders/draft        → Crear Sales Order en estado Draft
POST /invoices/draft            → Crear Invoice en estado Draft
GET  /sales-orders/{id}         → Ver Sales Order existente
GET  /tax-exemptions            → Certificados de reventa activos
PUT  /tax-exemptions/{cust_id}  → Actualizar certificado de reventa
```

**Configuración del Bridge (bridge_config.yaml):**
```yaml
server:
  host: "127.0.0.1"
  port: 8765
  auth_token: "${QB_BRIDGE_TOKEN}"

quickbooks:
  company_file: "C:/QB_DATA/Factronics2024.QBW"  # ajustar ruta real
  qbxml_version: "16.0"
  timeout_seconds: 30

tunnel:
  provider: "cloudflare"
  tunnel_name: "factronics-qb-bridge"
  public_url: "https://qb-bridge.factronics-internal.com"

logging:
  level: "INFO"
  file: "C:/QB_Bridge/logs/bridge.log"
  max_size_mb: 50
  backup_count: 5
```

**Setup en la máquina local de Factronics:**
```bash
# 1. Instalar Python 3.11 en Windows
# 2. Instalar dependencias
pip install fastapi uvicorn pywin32 pyyaml requests

# 3. Instalar Cloudflare Tunnel
# Descargar cloudflared.exe desde Cloudflare
cloudflared tunnel login
cloudflared tunnel create factronics-qb-bridge
cloudflared tunnel route dns factronics-qb-bridge qb-bridge.factronics-internal.com

# 4. Registrar como servicio Windows para arranque automático
cloudflared service install
python -m uvicorn bridge:app --host 127.0.0.1 --port 8765 &
# Usar NSSM para registrar el bridge como servicio Windows
```

**CRÍTICO — QuickBooks debe estar abierto** para que el bridge funcione. Se recomienda que la computadora donde corre QB esté siempre encendida durante horas laborales, o considerar un servidor Windows dedicado.

---

### 2.4 Hermes API — El Orquestador Central

**Descripción:** Hermes es el cerebro del sistema. Es una API FastAPI en Python que recibe instrucciones de n8n, decide qué agente activar, llama a Claude API con el contexto correcto, y devuelve acciones estructuradas.

**Estructura de archivos:**
```
hermes-api/
├── main.py                  # FastAPI app, rutas principales
├── agents/
│   ├── accounting.py        # Agente Contable (PO → QB)
│   ├── inbox.py             # Agente de Inbox (triaje + borradores)
│   ├── operations.py        # Agente Operativo (tareas FACCA)
│   └── tax_exemptions.py    # Agente Certificados de Reventa
├── tools/
│   ├── qb_bridge.py         # Cliente del QB Bridge
│   ├── gmail.py             # Cliente Gmail API
│   ├── hubspot.py           # Cliente HubSpot
│   ├── slack.py             # Notificaciones Slack
│   └── pdf_extractor.py     # Extracción de PDFs via Claude
├── knowledge/
│   ├── rag_client.py        # Consultas al RAG Service
│   └── prompts/             # Prompts por agente
│       ├── accounting.txt
│       ├── inbox.txt
│       └── operations.txt
├── models/
│   ├── purchase_order.py    # Schema PO extraída
│   ├── sales_order.py       # Schema Sales Order QB
│   └── email_triage.py      # Schema clasificación inbox
├── db/
│   ├── audit_log.py         # Log inmutable de acciones
│   └── job_queue.py         # Cola de trabajos
├── Dockerfile
├── requirements.txt
└── config.py
```

**Endpoints principales de Hermes:**
```
POST /agents/accounting/process-po    → Procesar PO adjunta
POST /agents/inbox/triage             → Clasificar email entrante
POST /agents/inbox/draft-reply        → Generar borrador de respuesta
POST /agents/operations/update-tasks  → Actualizar estado de tareas
POST /agents/tax/validate             → Validar certificado de reventa
GET  /jobs/{job_id}                   → Estado de trabajo asíncrono
GET  /audit-log                       → Log de todas las acciones
GET  /health                          → Health check
```

---

### 2.5 RAG Service — Base de Conocimiento Factronics

**Descripción:** Servicio de recuperación de información que alimenta a Hermes con contexto técnico, comercial y operativo de Factronics cuando lo necesita para redactar respuestas o tomar decisiones.

**Fuentes de conocimiento a indexar:**
```
Prioridad 1 (indexar en semana 1):
- PDFs de productos Linx (9800, 9000, Iris, SureClean)
- Case Studies Portfolio (los 19 casos)
- Listas de precios vigentes QB (exportación CSV)
- Términos de pago por cliente

Prioridad 2 (indexar en semana 2-3):
- Marketing Brain (brand voice, positioning)
- Email sequences de las 15 industrias
- Historial de cotizaciones (últimos 12 meses de QB)
- FAQs técnicas de equipos Anritsu, Variovac, JMK

Prioridad 3 (ongoing):
- Nuevos emails respondidos por Jovan (feedback loop)
- Nuevas cotizaciones cerradas
- Actualizaciones de precios de proveedores
```

**Stack del RAG:**
```
Framework: LlamaIndex o LangChain
Vector DB: pgvector (en el mismo PostgreSQL)
Embeddings: text-embedding-3-small (OpenAI) o claude embeddings
Chunk size: 512 tokens con 50 tokens de overlap
```

---

### 2.6 n8n — Capa de Orquestación de Workflows

**Descripción:** n8n es la capa que conecta los triggers del mundo real (email nuevo, PO recibida, tarea vencida) con los agentes de Hermes. No contiene lógica de negocio — solo enruta eventos.

**Variables de entorno n8n en Coolify:**
```env
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=...
EXECUTIONS_DATA_SAVE_ON_ERROR=all
EXECUTIONS_DATA_SAVE_ON_SUCCESS=all
N8N_LOG_LEVEL=info
WEBHOOK_URL=https://n8n.factronic-ops.com
```

---

### 2.7 Control Panel — Dashboard para Jovan

**Descripción:** Una interfaz web simple (Next.js o HTML estático) que muestra en tiempo real lo que hicieron los agentes, con acceso directo a cada borrador.

**Vistas del panel:**
```
/               → Resumen del día (POs procesadas, emails triados, alertas)
/borradores     → Lista de Sales Orders y facturas en Draft en QB
/inbox          → Borradores de email pendientes de revisión
/alertas        → Discrepancias de precio, certificados vencidos
/audit          → Log completo de acciones de todos los agentes
/config         → Activar/desactivar agentes (Kill Switch)
```

---

## 3. Los 4 Agentes — Definición Completa

---

### AGENTE 1: Contador (QB Accounting Agent)
**Prioridad:** CRÍTICA — Este es el POC  
**Tiempo estimado de build:** 3-4 semanas

**Función:** Leer POs en PDF que llegan al inbox de `accounting@factronicsusa.com`, extraer los datos, cruzarlos con QB, y crear Sales Orders o Invoices en estado Draft.

**Trigger en n8n:**
```
Gmail Trigger → accounting@factronicsusa.com
Filtro: tiene adjunto PDF con palabras "Purchase Order" o "PO" en subject o cuerpo
Frecuencia de polling: cada 5 minutos
```

**Flujo completo:**
```
1. n8n detecta email con PDF adjunto
2. n8n llama POST /agents/accounting/process-po con:
   - email_id (Gmail)
   - pdf_base64
   - sender_email
   - email_subject

3. Hermes / Agente Contable:
   a. Llama a Claude API con el PDF y prompt de extracción
   b. Claude extrae: {customer_id_or_name, po_number, items[], quantities[], unit_prices[], 
                      payment_terms, ship_to, requested_date}
   c. Valida customer_id contra QB Bridge GET /customers
   d. Para cada item, valida precio unitario contra QB Bridge GET /items/{code}
   
   SI precios coinciden (tolerancia ±2%):
     → Crea Sales Order Draft vía QB Bridge POST /sales-orders/draft
     → Slack: "✅ Sales Order Draft creada para [Cliente] | PO# [X] | $[Monto]"
     → Log en PostgreSQL: success
   
   SI hay discrepancia de precio:
     → NO crea la Sales Order
     → Genera borrador de email aclaratorio al cliente en Gmail Drafts
     → Slack: "⚠️ DISCREPANCIA en PO de [Cliente] | Precio PO: $X vs QB: $Y | Requiere autorización"
     → Log en PostgreSQL: pending_review

4. Actualiza Control Panel con resultado
```

**Prompt del Agente Contable (prompts/accounting.txt):**
```
Eres el asistente contable de Factronics USA, especialista en procesar 
órdenes de compra de clientes industriales.

Tu tarea es extraer con PRECISIÓN ABSOLUTA los siguientes campos del PDF de PO:

CAMPOS OBLIGATORIOS:
- customer_name: Nombre exacto del cliente como aparece en el documento
- po_number: Número de orden de compra
- po_date: Fecha de la orden (formato YYYY-MM-DD)
- requested_delivery_date: Fecha de entrega solicitada (si aplica)
- line_items: Lista de items con:
  * item_code: Código de producto (si existe)
  * description: Descripción del producto
  * quantity: Cantidad (número exacto)
  * unit_price: Precio unitario (número exacto, sin símbolo $)
  * total_line: Total de la línea
- subtotal: Subtotal antes de impuestos
- tax_amount: Monto de impuestos (si aplica)  
- total_amount: Total de la orden
- ship_to_address: Dirección de envío completa
- billing_contact: Contacto de facturación si aparece
- special_instructions: Cualquier nota especial o instrucción

REGLAS CRÍTICAS:
- NUNCA inventes o estimes un precio. Si no está claro, reporta null.
- Si el documento está en inglés, devuelve los valores en su idioma original.
- Los precios son siempre en USD.
- Si hay múltiples páginas, procesa TODAS.
- Responde ÚNICAMENTE en JSON válido, sin texto adicional.

FORMATO DE RESPUESTA:
{
  "customer_name": "",
  "po_number": "",
  "po_date": "",
  "requested_delivery_date": null,
  "line_items": [
    {
      "item_code": null,
      "description": "",
      "quantity": 0,
      "unit_price": 0.00,
      "total_line": 0.00
    }
  ],
  "subtotal": 0.00,
  "tax_amount": 0.00,
  "total_amount": 0.00,
  "ship_to_address": "",
  "billing_contact": null,
  "special_instructions": null,
  "confidence_score": 0.0
}

El campo confidence_score va de 0 a 1. Si es menor a 0.85, incluye 
"uncertainty_notes" explicando qué campos no pudiste extraer con certeza.
```

**Casos de clientes principales a configurar en QB mapping:**
```python
KNOWN_CUSTOMERS = {
    "National Steak Processors": "NSP",
    "NSP Quality Meats": "NSP",
    "Bauducco Foods": "BAUDUCCO",
    "Nestlé": "NESTLE",
    "B. Braun Medical": "BBRAUN",
    "Armor Iimak": "ARMOR",
    "Liberty Express": "LIBERTY",
    # Agregar todos los clientes recurrentes de QB
}
```

---

### AGENTE 2: Inbox Copilot (Email Intelligence Agent)
**Prioridad:** ALTA — Build después del POC  
**Tiempo estimado de build:** 2-3 semanas adicionales

**Función:** Leer emails entrantes en `jovan.gutic@factronicsusa.com`, clasificarlos por urgencia y tipo, y generar borradores de respuesta técnicamente precisos que queden en Gmail Drafts.

**Trigger en n8n:**
```
Gmail Trigger → jovan.gutic@factronicsusa.com
Polling: cada 10 minutos
Excluir: newsletters, spam, notificaciones automáticas
Incluir: emails de dominios de clientes conocidos o con palabras clave técnicas
```

**Clasificación de emails (taxonomy):**
```
TIPO A — Técnico-Comercial:
  Subcategorías: cotización, comparación_competencia, soporte_técnico, viabilidad_equipo
  Acción: Borrador técnico usando RAG con knowledge base de productos
  Prioridad asignada: ALTA si menciona cliente enterprise (Nestlé, NSP, B.Braun)

TIPO B — Administrativo-Operativo:
  Subcategorías: seguimiento_orden, estatus_entrega, factura, certificado_reventa
  Acción: Borrador administrativo + consulta QB Bridge para datos reales
  Prioridad asignada: MEDIA

TIPO C — Soporte Post-Venta:
  Subcategorías: falla_equipo, repuesto, mantenimiento, inkjet_consumible
  Acción: Borrador de soporte + búsqueda en historial de equipos del cliente
  Prioridad asignada: ALTA (tiempo de respuesta crítico)

TIPO D — Marketing/Prospecto:
  Subcategorías: lead_nuevo, solicitud_demo, cotización_inicial
  Acción: Borrador de bienvenida + crear contacto en HubSpot
  Prioridad asignada: MEDIA

TIPO X — No requiere respuesta del agente:
  Subcategorías: notificación_interna, confirmación_envío, newsletter
  Acción: Solo clasificar y archivar, no generar borrador
```

**Prompt del Agente Inbox — Clasificación (prompts/inbox_triage.txt):**
```
Eres el asistente de Jovan Gutic, CEO de Factronics USA, empresa especializada 
en equipos de codificación, marcado, inspección y empaque industrial en el 
sureste de EE.UU.

Analiza el siguiente email y devuelve ÚNICAMENTE JSON con esta estructura:

{
  "type": "A|B|C|D|X",
  "subtype": "",
  "priority": "HIGH|MEDIUM|LOW",
  "sender_is_client": true/false,
  "client_name": null,
  "summary_one_line": "",
  "key_questions": [],
  "requires_technical_knowledge": true/false,
  "requires_qb_lookup": true/false,
  "suggested_response_language": "es|en",
  "confidence": 0.0
}

CONTEXTO DE FACTRONICS:
- Clientes enterprise: Nestlé, NSP (National Steak Processors), B. Braun Medical, Bauducco Foods
- Productos: Linx CIJ/TTO/Laser, Anritsu X-Ray/Metal Detector/Checkweigher, 
  Variovac Thermoformer, JMK VFFS/Case Sealer
- Competidores principales: Tecnifar, Markem-Imaje, Videojet, Domino
- El CEO habla español e inglés; con clientes latinoamericanos siempre en español
```

**Prompt del Agente Inbox — Generación de Borrador (prompts/inbox_draft.txt):**
```
Eres el asistente ejecutivo de Jovan Gutic, CEO de Factronics USA.
Tu rol es redactar borradores de respuesta que Jovan revisará y enviará.

ESTILO DE COMUNICACIÓN DE JOVAN:
- Directo, técnico y confiable
- Nunca hace promesas que no puede cumplir
- Usa frases cortas en conversaciones cotidianas
- En propuestas técnicas, es detallado y preciso
- Tono cálido con clientes de largo plazo
- Nunca critica directamente a la competencia — muestra superioridad técnica con datos

REGLAS ABSOLUTAS:
- NUNCA envíes el email — solo crea el BORRADOR en Gmail Drafts
- NUNCA inventes especificaciones técnicas. Si no lo sabes, deja [VERIFICAR] en rojo
- NUNCA menciones precios sin consultar la base de datos actualizada
- Si el email es de un cliente enterprise (Nestlé, B. Braun, NSP), el borrador 
  debe ser más formal y revisado dos veces antes de sugerir envío
- Siempre termina el borrador con la firma estándar de Jovan

FIRMA ESTÁNDAR:
---
Jovan Gutic
CEO | Factronics USA
📞 [teléfono]
📧 jovan.gutic@factronicsusa.com
🌐 factronicsusa.com
Medley, FL 33178
---

CONTEXTO TÉCNICO DISPONIBLE:
{rag_context}

EMAIL A RESPONDER:
{email_thread}

CLASIFICACIÓN PREVIA:
{triage_result}

Genera el borrador de respuesta completo, listo para que Jovan lo revise.
```

---

### AGENTE 3: Operations Supervisor (Internal Task Agent)
**Prioridad:** MEDIA — Build en Mes 2-3  
**Tiempo estimado de build:** 2 semanas

**Función:** Monitorear el avance de tareas del equipo de ingeniería (JMK Robotics) y administración regional (FACCA Caracas), enviar alertas cuando hay cuellos de botella, y generar resumen diario para Jovan.

**Fuentes de datos:**
```
- Google Sheets: Tareas_Caracas.xlsx (actualmente manual)
- Google Drive: Reportes de campo JMK
- Slack: Canal #operaciones
- HubSpot: Deals en etapa de instalación/servicio
```

**Trigger en n8n:**
```
Schedule Trigger: 
  - Lunes-Viernes 8:00 AM: Resumen de estado del día
  - Lunes-Viernes 5:00 PM: Reporte de cierre del día
  - Cada hora: Scan de tareas vencidas o en riesgo
```

**Flujo del resumen diario:**
```
1. n8n trigger a las 8 AM
2. Hermes / Agente Operativo:
   a. Consulta Google Sheets: tareas con fecha_limite <= hoy
   b. Consulta HubSpot: deals en stage "Installation" o "Service" activos
   c. Consulta Slack: mensajes sin respuesta en #operaciones de las últimas 24h
   d. Genera resumen con Claude
3. Slack: Envía resumen al canal #ops-jovan con:
   - ✅ Tareas completadas ayer
   - 🔴 Tareas vencidas hoy
   - ⚠️ Tareas en riesgo (vencen en 48h)
   - 📋 Deals activos en campo
```

**Estructura de Tareas_Caracas (migración sugerida a Google Sheets estructurado):**
```
Columnas obligatorias:
- task_id (auto)
- description
- assigned_to (nombre o email)
- team (JMK | FACCA | Medley)
- deal_id (HubSpot, si aplica)
- due_date
- status (pending | in_progress | blocked | done)
- priority (high | medium | low)
- notes
- last_updated
```

**Prompt del Agente Operativo:**
```
Eres el supervisor de operaciones de Factronics USA. Tu trabajo es analizar 
el estado actual de las tareas del equipo y generar un reporte ejecutivo 
claro para el CEO Jovan Gutic.

El reporte debe ser conciso, accionable y en español.
Formato: mensaje de Slack (máximo 500 caracteres por sección).

Usa estos emojis para el status:
✅ Completado  🔴 Vencido/Bloqueado  ⚠️ En riesgo  🔵 En progreso  📋 Pendiente

DATA:
{task_data}
{hubspot_active_deals}
{slack_pending_messages}
```

---

### AGENTE 4: Tax Exemption Manager (Resale Certificate Agent)
**Prioridad:** BAJA — Build en Mes 3  
**Tiempo estimado de build:** 1 semana

**Función:** Monitorear los certificados de reventa de clientes en Florida, alertar cuando están próximos a vencer, generar el email de solicitud de renovación, y actualizar QB cuando se recibe el nuevo certificado.

**Trigger en n8n:**
```
Schedule Trigger: Primer día de cada mes, 9:00 AM
```

**Flujo:**
```
1. Consultar QB Bridge GET /tax-exemptions
2. Para cada certificado:
   - Si vence en < 60 días: crear alerta MEDIA
   - Si vence en < 30 días: crear alerta ALTA + borrador de email al cliente
   - Si ya venció: crear alerta CRÍTICA + bloquear generación de órdenes exentas
3. Slack: Reporte mensual de certificados
4. Al recibir nuevo PDF de certificado por email:
   - Extraer: número, fecha_vencimiento, estado, cliente
   - Actualizar QB Bridge PUT /tax-exemptions/{cust_id}
   - Confirmar por Slack: "✅ Certificado actualizado para [Cliente]"
```

---

## 4. Workflows de n8n — Configuración Detallada

### WF-001: PO Processing (Trigger → Accounting Agent)

```
[Gmail Trigger]
  ↓ Filtro: has_attachment=true AND (subject CONTAINS "PO" OR "Purchase Order")
  ↓ Get attachment (PDF base64)
[HTTP Request]
  ↓ POST https://api.factronic-ops.com/agents/accounting/process-po
  ↓ Headers: Authorization: Bearer {QB_BRIDGE_TOKEN}
  ↓ Body: {email_id, pdf_base64, sender, subject}
[IF: response.status = "success"]
  ↓ TRUE → Slack: "✅ Sales Order Draft creada | {customer} | ${amount}"
  ↓ FALSE → IF: response.status = "price_discrepancy"
              ↓ Slack: "⚠️ Discrepancia de precio | {customer} | Requiere revisión"
              ↓ HTTP: Crear Gmail Draft con borrador aclaratorio
[Postgres: Insert audit_log]
```

### WF-002: Inbox Triage (Trigger → Inbox Agent)

```
[Gmail Trigger] → jovan.gutic@factronicsusa.com
  ↓ Filtro: NOT from:noreply* AND NOT label:processed-by-hermes
[HTTP Request] → POST /agents/inbox/triage
  ↓ Body: {email_id, from, subject, body_preview, has_attachment}
[IF: triage.type != "X"]
  ↓ HTTP Request → POST /agents/inbox/draft-reply
  ↓ Body: {email_id, triage_result, thread_context}
[Gmail: Create Draft]
  ↓ draft_id, reply_to_thread_id
[Gmail: Add label "processed-by-hermes"]
[IF: triage.priority = "HIGH" AND triage.sender_is_client = true]
  ↓ Slack: "📧 Email ALTO de {sender} | {summary} | Borrador listo en Gmail"
[Postgres: Insert audit_log]
```

### WF-003: Daily Operations Report

```
[Schedule: 8:00 AM Mon-Fri]
[Google Sheets: Read Tareas_Caracas]
[HubSpot: Get deals in stage "Installation", "Service Active"]
[HTTP Request] → POST /agents/operations/daily-summary
[Slack: Post to #ops-jovan]
```

### WF-004: Tax Certificate Monitor

```
[Schedule: 1st of month, 9 AM]
[HTTP Request] → GET {QB_BRIDGE}/tax-exemptions
[Code Node: Filter expiring certificates]
[IF: any_critical = true]
  ↓ Gmail: Create draft renewal request emails
  ↓ Slack: "🚨 Certificados vencidos: {list}"
[IF: any_warning = true]
  ↓ Slack: "⚠️ Certificados próximos a vencer en 60 días: {list}"
[Postgres: Insert audit_log]
```

### WF-005: Kill Switch (Emergency Stop)

```
[Webhook Trigger: POST /killswitch]
  ↓ Auth: admin token requerido
[Code Node: Set all agents status = DISABLED in PostgreSQL]
[Remove Gmail Triggers (deactivate WF-001 y WF-002)]
[Slack: "🛑 Sistema Hermes DETENIDO por {user} a las {time}"]
```

---

## 5. Base de Datos — Esquema PostgreSQL

```sql
-- Tabla principal de audit log (inmutable)
CREATE TABLE audit_log (
    id              BIGSERIAL PRIMARY KEY,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    agent           VARCHAR(50) NOT NULL,  -- 'accounting'|'inbox'|'operations'|'tax'
    workflow        VARCHAR(50) NOT NULL,
    action          VARCHAR(100) NOT NULL,
    input_ref       TEXT,                  -- email_id, pdf_filename, etc.
    output_ref      TEXT,                  -- qb_sales_order_id, gmail_draft_id, etc.
    status          VARCHAR(20) NOT NULL,  -- 'success'|'error'|'pending_review'|'discrepancy'
    confidence      DECIMAL(3,2),
    error_message   TEXT,
    metadata        JSONB
);

-- Cola de trabajos pendientes de revisión humana
CREATE TABLE pending_review (
    id              BIGSERIAL PRIMARY KEY,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    reviewed_at     TIMESTAMPTZ,
    reviewed_by     VARCHAR(100),
    agent           VARCHAR(50) NOT NULL,
    review_type     VARCHAR(50) NOT NULL,  -- 'price_discrepancy'|'low_confidence'|'unknown_customer'
    input_data      JSONB NOT NULL,
    suggested_action JSONB,
    status          VARCHAR(20) DEFAULT 'pending',  -- 'pending'|'approved'|'rejected'
    notes           TEXT
);

-- Estado de agentes (para kill switch y monitoring)
CREATE TABLE agent_status (
    agent_name      VARCHAR(50) PRIMARY KEY,
    enabled         BOOLEAN DEFAULT TRUE,
    last_run        TIMESTAMPTZ,
    last_success    TIMESTAMPTZ,
    error_count_24h INTEGER DEFAULT 0,
    updated_at      TIMESTAMPTZ DEFAULT NOW()
);

-- Certificados de reventa (sincronizados desde QB)
CREATE TABLE tax_exemptions (
    customer_id     VARCHAR(50) PRIMARY KEY,
    customer_name   VARCHAR(200),
    certificate_num VARCHAR(100),
    state           VARCHAR(2) DEFAULT 'FL',
    issue_date      DATE,
    expiry_date     DATE,
    status          VARCHAR(20),  -- 'active'|'expiring_soon'|'expired'
    pdf_gdrive_url  TEXT,
    last_synced     TIMESTAMPTZ DEFAULT NOW()
);

-- Cache de clientes QB (sincronizado diariamente)
CREATE TABLE qb_customers_cache (
    qb_id           VARCHAR(50) PRIMARY KEY,
    name            VARCHAR(200),
    email           VARCHAR(200),
    payment_terms   VARCHAR(50),
    tax_exempt      BOOLEAN DEFAULT FALSE,
    last_synced     TIMESTAMPTZ DEFAULT NOW()
);

-- Cache de items/productos QB (sincronizado diariamente)
CREATE TABLE qb_items_cache (
    qb_id           VARCHAR(50) PRIMARY KEY,
    item_code       VARCHAR(50),
    description     TEXT,
    unit_price      DECIMAL(12,2),
    sales_price     DECIMAL(12,2),
    is_active       BOOLEAN DEFAULT TRUE,
    last_synced     TIMESTAMPTZ DEFAULT NOW()
);
```

---

## 6. Plan de Ejecución por Semanas

```
SEMANA 1-2: FOUNDATION (No hay agente sin esto)
────────────────────────────────────────────────
□ Hostinger VPS: Ubuntu 22.04, IP estática configurada
□ Coolify instalado y funcionando
□ PostgreSQL desplegado en Coolify con esquemas creados
□ Redis desplegado en Coolify
□ Cloudflare configurado (dominio factronic-ops.com o similar)
□ QB Bridge instalado en PC de Factronics (Medley)
□ QB Bridge: prueba de GET /customers → recibe lista real de QB
□ QB Bridge: prueba de GET /items → recibe lista real de precios
□ Cloudflare Tunnel configurado y funcionando (QB Bridge accesible desde VPS)
□ n8n desplegado en Coolify, accesible en dominio
□ Gmail API: OAuth configurado para accounting@ y jovan.gutic@
□ Slack API: Bot creado, token activo, canal #ops-agentes creado

ENTREGABLE SEMANA 2: Jovan puede llamar GET /health en el QB Bridge 
desde internet y ver "QuickBooks: connected"

SEMANA 3-4: POC CONTABLE (El agente más crítico)
─────────────────────────────────────────────────
□ Hermes API: estructura base desplegada en Coolify
□ Agente Contable: extracción de PDF con Claude API
□ Test con 5 POs históricas reales de NSP, Bauducco, otros clientes
□ Validación de precios contra QB Cache
□ Creación de Sales Order Draft en QB (modo test)
□ Workflow n8n WF-001 completo
□ Notificación Slack funcionando
□ Audit log en PostgreSQL
□ Control Panel: vista básica de borradores creados

ENTREGABLE SEMANA 4: Demostración a Jovan — PO de NSP llega 
por email → en 3 minutos hay un Draft en QB + mensaje en Slack

SEMANA 5-6: INBOX COPILOT
─────────────────────────
□ RAG Service: indexar PDFs de productos Linx y Anritsu
□ RAG Service: indexar Case Studies Portfolio
□ Agente Inbox: clasificación de emails (triage)
□ Agente Inbox: generación de borradores (draft)
□ Test con 20 emails reales del inbox de Jovan (histórico)
□ Workflow n8n WF-002 completo
□ Gmail: label "processed-by-hermes" funcionando
□ Control Panel: vista de borradores de email pendientes

ENTREGABLE SEMANA 6: 10 emails del inbox de Jovan procesados 
automáticamente, borradores en Gmail para su revisión

SEMANA 7-8: OPERATIONS + TAX AGENT
────────────────────────────────────
□ Migrar Tareas_Caracas.xlsx a estructura estándar en Google Sheets
□ Agente Operativo: resumen diario
□ Agente Operativo: alertas de tareas vencidas
□ Workflow n8n WF-003
□ Agente Tax: scan de certificados de reventa en QB
□ Workflow n8n WF-004
□ WF-005 Kill Switch
□ Control Panel: vistas completas de todas las secciones
□ Documentación de operación para el equipo de Factronics

ENTREGABLE SEMANA 8: Sistema completo en staging, demo con 
Jovan y equipo contable, aprobación para pasar a producción

SEMANA 9-10: PRODUCCIÓN + AJUSTE
──────────────────────────────────
□ Deploy a producción con datos reales
□ Monitoreo intensivo los primeros 5 días
□ Ajuste de prompts según feedback de Jovan
□ Ajuste de umbrales de confianza (si confidence < 0.85 → pending_review)
□ Sesión de capacitación: Jovan y equipo contable aprenden a usar el panel
□ Documentación final entregada
□ Retainer mensual activado
```

---

## 7. Seguridad y Compliance

### Variables sensibles — Gestión
```
NUNCA en código fuente. Siempre en:
- Coolify: Environment Variables (encriptadas en reposo)
- QB Bridge local: archivo .env en carpeta protegida
- Rotación de tokens: cada 90 días

Tokens a rotar periódicamente:
- QB_BRIDGE_TOKEN (generado con uuid4, 128 chars)
- ANTHROPIC_API_KEY (monitorear uso en dashboard Anthropic)
- GMAIL_REFRESH_TOKENS (revocar y regenerar si hay incidente)
- SLACK_BOT_TOKEN
```

### Logs de auditoría — Política
```
- Cada acción de cada agente se escribe en audit_log (inmutable, no hay DELETE)
- Retención: 2 años
- Backup automático de PostgreSQL: diario a Google Drive de Factronics
- Los logs incluyen: qué PO procesó, con qué confianza, qué creó en QB, cuándo
```

### Kill Switch — Protocolo
```
Activar en: https://ops.factronic-ops.com/config
Requiere: password de admin (solo Jovan y Pablo tienen acceso)
Efecto inmediato:
1. Todos los triggers de n8n se desactivan
2. Hermes API rechaza nuevas peticiones (HTTP 503)
3. QB Bridge sigue respondiendo (lectura, no escritura)
4. Slack alerta al equipo

Tiempo estimado de reactivación tras kill switch: 2 minutos
```

### Política de NO-ENVÍO autónomo
```
REGLA ABSOLUTA: Ningún agente puede enviar emails por cuenta propia.
Todo email generado va a Gmail DRAFTS.
La Sales Order va a QB como DRAFT.
El humano (Jovan o contabilidad) da clic de aprobación.

La única excepción: notificaciones internas de Slack (no es comunicación externa).
```

---

## 8. Estimado de Costos Operativos Mensuales

| Concepto | Costo mensual estimado |
|---|---|
| Hostinger VPS (KVM 2) | ~$15-20 USD |
| Claude API (estimado: 215 POs + 500 emails) | ~$150-250 USD |
| Cloudflare (Tunnel + dominio) | ~$10 USD |
| Gmail API | Gratis (dentro de límites) |
| n8n (self-hosted en Coolify) | $0 |
| PostgreSQL + Redis (self-hosted) | $0 |
| **Total infraestructura** | **~$175-280 USD/mes** |

*Nota: El costo de Claude API escala con el volumen. Con 215 POs/mes y ~500 emails, usando claude-sonnet-4-6 (modelo recomendado por balance precio/calidad), el estimado conservador es $150/mes. Si el volumen crece o se usan documentos largos, puede llegar a $400/mes.*

---

## 9. KPIs de Éxito — Cómo medir el valor

| KPI del RFP | Línea base | Meta | Cómo medirlo |
|---|---|---|---|
| Tiempo en procesamiento QB | 17.92 horas / 5 meses | < 2.5 horas revisión | audit_log: tiempo promedio por PO |
| Triaje de inbox | 7.67 horas / 5 meses | Reducción 75% | n8n: emails procesados automáticamente |
| Redacción de respuestas | 4.25 horas / 5 meses | 90% automatizado | Gmail Drafts generados vs enviados |
| Precisión contable | Variable (error humano) | 98% borradores correctos | pending_review: aprobados vs rechazados |
| Tiempo PO → QB Draft | ~7 minutos manual | < 3 minutos automático | audit_log: created_at vs po_received_at |

---

## 10. Próximos Pasos Inmediatos

```
HOY / ESTA SEMANA:
□ Confirmar con Jovan: ¿QB Desktop está en una sola PC o en servidor? 
  ¿Esa PC está siempre encendida durante horas laborales?
□ Confirmar dominio para los servicios (factronic-ops.com u otro)
□ Jovan crea: App en Google Cloud Console para Gmail API
□ Jovan crea: App en Slack para el Bot
□ Jovan comparte: 5-10 POs históricas de NSP / Bauducco para pruebas
□ Confirmar: ¿Tienen Cloudflare account existente?

SEMANA 1 — TU EQUIPO:
□ Provisionar VPS Hostinger
□ Instalar Coolify
□ Setup PostgreSQL con esquemas
□ Comenzar QB Bridge en ambiente de desarrollo
□ Primera reunión de kick-off técnico con equipo de Factronics (30 min)
```

---

*Blueprint elaborado por Coordenadas — Junio 2026*  
*Versión 1.0 — Para uso interno del equipo de ejecución*