docs: documenta telemetria (tabla events, EVENTS_PERSIST, endpoints)

.env.example

@@ -57,6 +57,14 @@ MODEL_ARCHITECTURE=yolo26n                # yolo26n | rfdetr_nano (define el ada
 HF_MODEL_REPO=<org>/agrovision-plantcount
 HF_TOKEN=
 
+# -----------------------------------------------------------------------------------
+# 6) Telemetría de UI (Fase 9)
+#    Los eventos siempre se loguean en stdout y se guardan en un buffer en memoria
+#    (GET /api/events/recent). EVENTS_PERSIST=true además los persiste en la tabla
+#    `events` de Supabase (best-effort; requiere DATABASE_URL). Nunca contiene secretos.
+# -----------------------------------------------------------------------------------
+EVENTS_PERSIST=false                      # true para volcar la telemetría a la tabla events
+
 # -----------------------------------------------------------------------------------
 # 6) Supabase (BD PostGIS + Storage + Queues) — PLATAFORMA COMPLETA
 #    Project Settings -> API / Database. SERVICE_ROLE es SECRETO (solo backend, nunca UI).

docs/db/diseno_db.md

@@ -141,6 +141,19 @@ erDiagram
 
 ---
 
+### 3.5 Tabla: `events` (Telemetría de UI — Fase 9, persistencia **opcional**)
+*   **Descripción:** Traza de acciones de la UI para depurar. Se escribe **solo** si `EVENTS_PERSIST=true` (best-effort; un fallo de BD nunca rompe la UI). El backend **redacta** `meta` antes de insertar: **nunca** contiene secretos. Por defecto la telemetría vive solo en stdout + un ring buffer en memoria (`GET /api/events/recent`).
+
+| Campo | Tipo de Dato | Modificadores | Descripción / Regla de Negocio |
+| :--- | :--- | :--- | :--- |
+| `id` | `BIGSERIAL` | `PK` | Identificador secuencial. |
+| `action` | `TEXT` | `NOT NULL` | Acción (`nav`, `creds_set`, `parcel_create`, `chart_view`, `api_error`…). |
+| `session_id` | `TEXT` | `NOT NULL` | Correlación por sesión de UI. |
+| `meta` | `JSONB` | `NOT NULL DEFAULT '{}'` | Contexto **ya redactado** (contadores, pestaña, status…). |
+| `created_at` | `TIMESTAMP` | `DEFAULT now()` | Orden temporal. |
+
+---
+
 ## 4. Matriz de Accesos y CRUD por Componente
 
 | Tabla | Gateway (FastAPI) | Worker Asíncrono | UI (Shiny) | Permisos | Notas de Diseño |
@@ -149,6 +162,7 @@ erDiagram
 | `ndvi_timeseries` | `RemoteSensingService` (write, mensual) | *Ninguno* | lectura vía API (*Teledetección*, *Resumen*) | `API: Read/Write` | Escritura tras estadística zonal + agregación mensual; idempotente por `UNIQUE(field_id,date)`. |
 | `plant_counts` | `CountService` (read) | `InferenceWorker` (write) | lectura vía API | `API: Read` <br> `Worker: Write` | **En desarrollo:** sin escrituras hasta `COUNTING_ENABLED=true`. |
 | `chat_messages` | `AgentService` | *Ninguno* | lectura vía API (*Asistente*) | `API: Read/Write` | Memoria del agente (Memory Buffer). |
+| `events` | `events` router (write best-effort) | *Ninguno* | escritura vía `POST /api/events` (telemetría) | `API: Write` <br> (opcional) | **Opcional** (`EVENTS_PERSIST=true`). Sin secretos (redactado). Por defecto solo buffer en memoria. |
 | `pgmq.count_tasks` (cola) | `CountService` (produce) | `InferenceWorker` (consume) | — | `API: send` <br> `Worker: read/archive` | **En desarrollo:** cola creada pero inactiva hasta activar el conteo. |
 
 > **NDVI raster / heatmap:** el endpoint `POST /api/ndvi/raster` genera un PNG colorizado **on-demand** (no escribe en BD ni en Storage; se regenera). No aparece en la matriz por no tocar persistencia.
@@ -164,6 +178,7 @@ erDiagram
 *   **`ndvi_field_date_idx`** en `ndvi_timeseries (field_id, date)` — optimiza filtros de fecha del agente.
 *   **`plant_counts_json_gin_idx`** en `plant_counts USING gin (result_json)` — búsquedas/agregaciones sobre el JSONB de detecciones.
 *   **`chat_session_history_idx`** en `chat_messages (session_id, created_at)` — recuperación ordenada del historial.
+*   **`events_session_created_idx`** en `events (session_id, created_at)` — traza de una sesión ordenada (depuración; tabla opcional).
 
 ### 5.2 Control de Concurrencia y Seguridad
 *   **Row Level Security (RLS):** políticas `auth.uid() = user_id` en todas las tablas para aislar usuarios dentro del mismo proyecto Supabase.

docs/ejecucion.md

@@ -128,7 +128,9 @@ Abre **http://localhost:4321/**. *(UI Shiny legacy, opcional: `.\scripts\run_ui.
 5. [ ] (Con `DATABASE_URL` + Copernicus configurados) **Creación de Parcelas**: dibujar un polígono, nombrarlo y *Guardar* → aparece en la lista; tras unos segundos, en **Teledetección** se ve la serie NDVI de 5 años.
 6. [ ] (Con Groq) **Asistente**: preguntar *"¿cómo evolucionó el NDVI de \<parcela\>?"* → responde citando la herramienta usada.
 
-> **Pruebas en vivo del backend** (sin la UI): `http://127.0.0.1:8000/docs` (Swagger) lista `/api/fields`, `/api/ndvi`, `/api/ndvi/raster`, `/api/weather`, `/api/chat`. Recuerda aplicar migraciones (`uv run python -m backend.db.migrate`) antes de usar parcelas.
+> **Pruebas en vivo del backend** (sin la UI): `http://127.0.0.1:8000/docs` (Swagger) lista `/api/fields`, `/api/ndvi`, `/api/ndvi/raster`, `/api/weather`, `/api/chat` y `/api/events` (telemetría: `POST /api/events`, `GET /api/events/recent?session_id=`). Recuerda aplicar migraciones (`uv run python -m backend.db.migrate`) antes de usar parcelas.
+>
+> **Telemetría (Fase 9):** cada acción de la UI emite un evento (sin secretos) que se loguea en stdout y se guarda en un buffer en memoria, consultable en `GET /api/events/recent`. Para depurar una sesión: `GET /api/events/recent?session_id=<id>`. La persistencia en la tabla `events` es **opcional** (`EVENTS_PERSIST=true`).
 
 ### 3.5 (Opcional) Demostrar el Conteo con Datos Mock