Arranque del Gemelo Comercial Prodisys
======================================

Ubicación
---------

El repositorio operativo del Gemelo se encuentra en::

    ~/Documents/Prodisys/prodisys-gemelo

La interfaz comercial principal se ejecuta desde::

    ui_test.ipynb

El repositorio activo utiliza actualmente la rama::

    main


Entorno Python
--------------

La operación validada del Gemelo Comercial utiliza el Python del entorno
Anaconda ``base``::

    /home/prodisys1/anaconda3/bin/python

La versión validada es Python 3.11.

Antes de arrancar puede verificarse con::

    which python
    python --version

Las dependencias operativas comprobadas incluyen:

- pandas
- ipywidgets
- SQLAlchemy
- pyodbc
- python-dotenv
- requests
- BeautifulSoup

El entorno Conda ``prodisys`` existe, pero actualmente no contiene todas las
dependencias requeridas por la interfaz comercial. Por tanto, no debe
considerarse el entorno operativo hasta que sea explícitamente reconstruido
y validado.


Variables de entorno
--------------------

Las conexiones y claves se mantienen en el archivo local::

    .env

Este archivo contiene, entre otras, variables para:

- conexión a ALEPH / SQL Server
- driver ODBC
- Serper API

El archivo ``.env``:

- no debe versionarse en Git
- debe mantener permisos restrictivos
- no debe copiarse a la documentación
- no debe publicarse en HTML


ALEPH y SQL Server
------------------

ALEPH actúa como fuente de información operativa y CRM.

Antes de iniciar la interfaz debe verificarse que la instancia SQL Server
utilizada por ALEPH esté disponible.

La conexión puede comprobarse desde el Gemelo mediante::

    cd ~/Documents/Prodisys/prodisys-gemelo

    python - <<'PY'
    from pathlib import Path
    from dotenv import load_dotenv

    load_dotenv(Path(".env"), override=True)

    from prodisys.ingest.aleph_connection import get_aleph_engine

    engine = get_aleph_engine()

    with engine.connect() as conn:
        value = conn.exec_driver_sql("SELECT 1").scalar()

    print("ALEPH:", "OK" if value == 1 else value)
    PY

La prueba validada debe retornar::

    ALEPH: OK


Serper
------

Serper se utiliza para discovery externo de empresas y fuentes web.

La conectividad puede comprobarse con::

    cd ~/Documents/Prodisys/prodisys-gemelo

    python - <<'PY'
    from pathlib import Path
    from dotenv import load_dotenv

    load_dotenv(Path(".env"), override=True)

    from prodisys.comercial.source_search import _search_serper

    results = _search_serper(
        query="OpenFOAM",
        max_results=2,
        timeout=20,
    )

    print("SERPER resultados:", len(results))
    for r in results:
        print("-", r.title, "|", r.url)
    PY

Una respuesta con resultados confirma que la API está operativa.


JupyterLab
----------

Desde el servidor::

    cd ~/Documents/Prodisys/prodisys-gemelo

    jupyter lab --no-browser --ip=0.0.0.0

El servidor Prodisys se encuentra actualmente en la LAN::

    192.168.2.19

Si el puerto 8888 está ocupado por otra aplicación, JupyterLab seleccionará
automáticamente otro puerto disponible, por ejemplo 8889.

Desde un cliente de la misma red se accede con::

    http://192.168.2.19:<puerto>/lab

Una vez dentro de JupyterLab se debe abrir::

    ui_test.ipynb


Arranque de la interfaz comercial
---------------------------------

La interfaz se construye mediante::

    from prodisys.comercial.ui.app_ui import build_comercial_ui
    build_comercial_ui()

Si después de cambios de código la interfaz no refleja el estado actual::

    Kernel -> Restart Kernel


Módulos principales
-------------------

La interfaz comercial integra actualmente funciones para:

- Actividades
- Lotes
- Empresas
- Contactos
- Prospectos CRM
- scoring y evaluación comercial
- discovery web
- integración CRM con ALEPH

Los datos operativos se encuentran principalmente bajo::

    data/commercial/


Discovery comercial
--------------------

Desde la interfaz::

    Actividades -> Perfil activo -> Ejecutar discovery

El perfil controla, entre otros:

- países
- sectores
- palabras clave incluidas
- palabras clave excluidas
- número máximo de páginas
- número máximo de empresas
- score mínimo

También puede ejecutarse desde terminal::

    python -m prodisys.comercial.prospect_discovery


Pipeline comercial
------------------

Los comandos principales son::

    python -m prodisys.comercial.pipeline_runner --help

    python -m prodisys.comercial.pipeline_runner discover
    python -m prodisys.comercial.pipeline_runner continue
    python -m prodisys.comercial.pipeline_runner integrate
    python -m prodisys.comercial.pipeline_runner push-crm
    python -m prodisys.comercial.pipeline_runner crm-dry-run
    python -m prodisys.comercial.pipeline_runner crm-execute --confirm
    python -m prodisys.comercial.pipeline_runner summary


Precauciones CRM
----------------

Las operaciones de escritura real en ALEPH deben ejecutarse únicamente de
forma deliberada.

En particular::

    crm-execute --confirm

realiza operaciones reales y no debe utilizarse como prueba de arranque.

Para validación funcional se recomienda utilizar primero:

- lectura de datos
- preview
- dry-run
- validación de prospectos


Secuencia recomendada de arranque
---------------------------------

1. Entrar a ``~/Documents/Prodisys/prodisys-gemelo``.
2. Verificar que Python sea el entorno ``base`` validado.
3. Confirmar disponibilidad de SQL Server / ALEPH.
4. Ejecutar una prueba ``SELECT 1`` contra ALEPH.
5. Verificar Serper si se utilizará discovery.
6. Iniciar JupyterLab.
7. Acceder desde el cliente al puerto asignado.
8. Abrir ``ui_test.ipynb``.
9. Ejecutar ``build_comercial_ui()``.
10. Validar navegación y lectura de información antes de ejecutar escrituras CRM.


Cierre
------

JupyterLab se detiene con ``Ctrl+C`` en la terminal donde fue iniciado.

No se recomienda detener servicios SQL compartidos sin verificar previamente
si otras aplicaciones dependen de ellos.