Primer commit

docs/PLAYBOOK_DESCUADRE.md

@@ -0,0 +1,284 @@
+# Playbook — Investigación de descuadres Marca vs Sucursales
+
+> Metodología de extremo a extremo para diagnosticar y resolver diferencias de conteo
+> (contactos / oportunidades) entre la cuenta de Marca (Monte Providencia) y la suma de
+> las sucursales, tal como las muestra la **Comparativa** del dashboard.
+>
+> Documenta la operación del **2026-05-29** (descuadre +5/+5 → 0/+2) como caso de estudio
+> y destila el método para casos futuros. Cubre tres niveles: **programación**,
+> **business intelligence** y **análisis de perspectivas** (el porqué de las decisiones).
+>
+> Léelo junto con [AGENTS.md](../AGENTS.md) y las memorias enlazadas al final.
+
+---
+
+## 0. TL;DR — el reflejo correcto
+
+Ante un descuadre, **NO empieces a "arreglar" datos**. Empieza preguntando:
+
+1. **¿El cache está fresco?** La Comparativa lee SQLite, no Bucéfalo en vivo. La causa #1 de un descuadre **positivo** (Marca > sucursales) es cache viejo.
+2. **¿Qué dice el signo?** Negativo (sucursal > Marca) ⇒ faltantes / multi-empeño. Positivo (Marca > sucursal) ⇒ cache viejo, huérfanos creados directo en Marca, o fantasmas.
+3. **¿Existe de verdad en GHL?** Verifica el contacto sospechoso **por id** (`GET /contacts/{id}`) Y por **índice** (`/contacts/search`). El delta entre ambos revela fantasmas.
+
+Solo después de eso, y siempre con **dry-run → snapshot → apply → re-audit**, se toca algo.
+
+---
+
+## 1. De dónde sale el número
+
+La Comparativa del dashboard se calcula con `run_audit()` en
+[`scripts/audit_brand_vs_branches_totals.py`](../scripts/audit_brand_vs_branches_totals.py),
+expuesta vía `GET /api/comparativa/marca-vs-sucursales` (`main.py:856`).
+
+**Regla de oro:** `run_audit()` lee de `generated/data/mp_manager.sqlite` (el **cache**), **no**
+de la API de GHL en vivo. Por lo tanto el número refleja el estado del **último sync por
+location**, no el estado real de Bucéfalo en este instante.
+
+Primer comando de diagnóstico, siempre:
+
+```python
+# ¿cuándo se sincronizó por última vez cada location sospechosa?
+#   sync_log.finished_at  vs  date_added del contacto sospechoso
+# Si el contacto se creó DESPUÉS del último sync de su location -> cache stale, no es huérfano.
+```
+
+El audit es **pesado** (fuzzy matching global). Córrelo en background y vuelca a archivo:
+
+```powershell
+python scripts\audit_brand_vs_branches_totals.py --json | Out-File -Encoding utf8 generated\agent\runs\descuadre_audit.json
+```
+
+(Vía MCP `run_script` con `expect_json=True` puede dar timeout; preferir background + archivo.)
+
+---
+
+## 2. Nivel Business Intelligence — descomponer el descuadre
+
+### 2.1 Identidad de reconciliación
+
+De la memoria `contact_descuadre_reconciliation`:
+
+```
+branch_sum − brand = (A − C multiplicidad) + (B missing-in-brand) − (D solo-Marca)
+```
+
+- **A−C multiplicidad**: un contacto de Marca que matchea con >1 contacto de sucursal (o
+  viceversa) infla un lado sin inflar el otro.
+- **B (missing-in-brand)**: contactos de sucursal que aún no se replican a Marca → bucket
+  `contacts_in_branch_not_in_brand`.
+- **D (solo-Marca)**: contactos que solo viven en Marca → bucket `contacts_in_brand_not_in_any_branch`.
+
+### 2.2 Los 11 buckets de `run_audit()`
+
+El JSON devuelto trae, bajo `missing`, estos buckets (nombres EXACTOS, `audit_…py:1293–1380`):
+
+| Bucket | Qué detecta |
+|---|---|
+| `contacts_in_branch_not_in_brand` | Contacto en sucursal sin contraparte en Marca (ni por CF `id_contacto_sucursal` ni por phone/email/name). |
+| `contacts_in_brand_not_in_assigned_branch` | Contacto de Marca con TIENDA asignada que no está en ESA sucursal. |
+| `contacts_in_brand_present_in_other_branch_not_assigned` | Está en OTRA sucursal, no la asignada por el verificador. |
+| `contacts_in_brand_probable_duplicate` | Marca tiene phone/email, no matchea en sucursal, pero hay homónimo con identificadores fuertes en la asignada ⇒ probable duplicado en Marca. |
+| `contacts_in_brand_without_tienda` | Contacto de Marca sin el CF `TIENDA` poblado. |
+| `contacts_in_brand_with_unknown_tienda` | TIENDA poblada pero no matchea ninguna fila del verificador. |
+| `contacts_in_brand_not_in_any_branch` | No aparece en ninguna sucursal. **Fuente típica del descuadre positivo.** |
+| `opportunities_in_branch_not_in_brand` | Opp de sucursal sin réplica en Marca (ni por CF `id_oportunidad_sucursal` ni vía contacto). |
+| `opportunities_missing_id_field` | Opps con el CF "ID Oportunidad Sucursal" vacío / longitud inválida (calidad de dato, no necesariamente descuadre). |
+| `contacts_missing_id_field` | Contactos con el CF "ID Contacto Sucursal" vacío / inválido. |
+| `intra_brand_duplicates` | Duplicados DENTRO de Marca (mismo nombre normalizado, sin phone NI email). |
+
+### 2.3 El signo del descuadre es un diagnóstico
+
+- **Negativo** (sucursal > Marca): faltantes en Marca (bucket B) o **multi-empeño** no
+  replicado (memoria `opp_multiplicity_replication_gap`, causa del histórico −28).
+- **Positivo** (Marca > sucursal): casi siempre **cache viejo** o contactos creados directo
+  en Marca (Facebook / formulario) que no cascaron. Rara vez son duplicados intra-Marca
+  (verifica `intra_brand_duplicates` para descartarlo de inmediato).
+
+### 2.4 Taxonomía de causas-raíz (observadas en el caso real)
+
+| # | Causa | Cómo se ve | Acción |
+|---|---|---|---|
+| a | **Cache stale** | Contacto creado después del último sync de su location | Re-sync de la location + re-audit |
+| b | **Fantasma de índice GHL** | `/contacts/search` lo devuelve, pero `GET/DELETE /contacts/{id}` da 404 | Esperar a que GHL reconcilie; NO borrar por id |
+| c | **Colisión de identidad** | Dos personas comparten teléfono; un registro queda "Frankenstein" | Jerarquía de resolución + dry-run; a veces UPDATE, no DELETE |
+| d | **Huérfano pre-fix** | Lead viejo (Facebook) que nunca cascó a sucursal | Bajar con la cascada ya arreglada, o aceptar |
+| e | **Sucursal inexistente** | El contacto apunta a una sucursal que no es cuenta MP | Sin arreglo posible; documentar |
+
+---
+
+## 3. Nivel programación — el toolkit y los anclajes
+
+### 3.1 Lectura / diagnóstico (read-only)
+
+- MCP: `get_global_metrics`, `sync_logs`, `error_logs`, `list_accounts`, `get_account_metrics`.
+- El audit completo: background + `Out-File utf8` (ver §1).
+- `error_logs` es oro: cada error trae el `ghl_response_body` real. Ahí apareció el
+  `{"message":"Contact not found for id:…"}` que delató el fantasma de índice.
+
+### 3.2 Entender el matching (clave para leer los buckets)
+
+En `audit_brand_vs_branches_totals.py`:
+
+- `build_contact_index(contacts)` (`:430`) → `(by_phone, by_email, by_name)`.
+- `find_match(contact, by_phone, by_email, by_name=None, …)` (`:458`): cascada
+  **phone+name → email → nombre-solo**.
+- `MATCH_THRESHOLD = 0.80` (`:53`): similitud mínima de nombre cuando el teléfono coincide.
+
+> **Phone solo nunca es match** (memoria `matching_rules`). Si el teléfono coincide pero el
+> nombre diverge < 0.80, es **colisión**, no match. Esta regla es exactamente la que hizo
+> que el audit detectara — correctamente — el caso Rebeca/Maely como huérfano en vez de
+> fusionarlos a ciegas.
+
+### 3.3 Forense n8n (¿la automatización realmente corrió?)
+
+`scripts/n8n_workflow_lib.py::load_credentials()` lee `n8n/n8n credencials.txt`
+(secreto, no imprimir) y devuelve `(api_key, base_url)`. La API se consulta con header
+`X-N8N-API-KEY`:
+
+```python
+GET /api/v1/workflows?limit=100                          # id, name, active
+GET /api/v1/executions?workflowId=<id>&limit=15          # startedAt, status, mode
+GET /api/v1/executions/<execId>?includeData=true         # runData -> camino de nodos
+```
+
+Con `includeData=true` se ve **qué nodos ejecutó** cada corrida: así se confirmó que la
+cascada Marca→Sucursal **sí** creó el contacto en la sucursal (nodo
+`Crear Contacto - Cuenta Objetivo - SUCURSAL` con status success). Workflows clave:
+
+- `4UMRwxJdHFfOGHBp` — `[1604] Crear Contacto - MARCA A SUCURSAL V2` (dispara por **formulario**).
+- `x4DqZ5FtSc43tdzB` — `[1604] Sincronización Sucursal → Marca - Crear Contacto`.
+- `Cfgwp0bOtDW8zuKW` — sync de oportunidades.
+
+El nodo `Obtener Info de cuenta origen - SUCURSAL` expone el `Location_ID` de origen → así se
+ubicó que jorge/fernando venían de **Tampico**.
+
+### 3.4 Verificación en vivo vs cache (cómo cazar fantasmas)
+
+```python
+import sync_engine as se, requests
+tok = {a['location_id']: a['token'] for a in se.parse_accounts_csv()}   # NO usar main.TOKENS_CACHE
+H = {'Authorization': f'Bearer {tok[LOC]}', 'Version': '2021-07-28', 'Accept': 'application/json'}
+
+# (1) por id  -> store principal
+requests.get(f'https://services.leadconnectorhq.com/contacts/{cid}', headers=H)
+# (2) por índice -> lo que ve la sync
+requests.post('https://services.leadconnectorhq.com/contacts/search',
+              headers={**H, 'Content-Type': 'application/json'},
+              json={'locationId': LOC, 'query': '<texto>', 'pageLimit': 20})
+```
+
+> **`main.TOKENS_CACHE` está vacío fuera del startup de FastAPI** (se puebla en el
+> `@app.on_event("startup")`, `main.py:126/141`). Para scripts ad-hoc, cargar tokens con
+> `sync_engine.parse_accounts_csv()`.
+>
+> **Diagnóstico del fantasma:** si (2) lo devuelve pero (1) da 400/404 "Contact not found",
+> el contacto está borrado del store pero el índice de search va con retraso → cada sync lo
+> revive. No se puede borrar (ya no existe por id); se auto-corrige al reconciliar GHL.
+
+### 3.5 Mutación segura
+
+- `ghl_client.update_contact(token, contact_id, data)` → `PUT /contacts/{id}` (`:173`).
+- `ghl_client.delete_contact(token, contact_id, location_id)` → `DELETE` (`:176`).
+- Tags: pasar el array completo deseado en el PUT (el `DELETE …/tags/{name}` por nombre da
+  404 — memoria `ghl_tags_api`).
+- Endpoint del dashboard `delete_comparativa_contact` (`main.py:2095`) respeta **dry-run**
+  vía header `X-Dry-Run` (`is_dry_run_request` `:30`, `dry_run_response` `:44`).
+
+> ⚠️ El endpoint del server usa el token cargado en startup. Si falla con 400 raro, prueba
+> la mutación directa con el token del CSV (probado: el PUT a Rebeca funcionó con el token
+> del CSV cuando el server había dado 400 por el fantasma).
+
+---
+
+## 4. Caso de estudio — la corrida del 2026-05-29
+
+**Estado inicial:** Comparativa marca +5 contactos / +5 opps (Marca de más).
+
+1. **Audit** → `intra_brand_duplicates: 0` (no son duplicados) y `contacts_in_brand_not_in_any_branch: 7`. Los 7 eran el origen del exceso.
+2. **Triage de los 7:**
+   - 4 creados **hoy** (adrian, juan carlos por formulario; jorge, fernando por sucursal).
+   - 1 contacto `qa-test` (test21).
+   - 2 leads viejos de Facebook (rebeca, guco).
+3. **Forense n8n** confirmó que los 4 de hoy **sí** se crearon/replicaron correctamente en
+   su sucursal (executions success). El problema: sus sucursales se habían sincronizado a las
+   **13:58**, antes de las altas (20:10–20:50) → **cache stale**.
+4. **Re-sync** de Villas del Sol, Tulyehualco y Tampico → los 4 matchearon. **Descuadre +5/+5 → 0/+2.**
+5. **Caso Rebeca/Maely** (el `contacts_in_brand_not_in_any_branch` restante con seguimiento):
+   - Un solo contacto en Marca con nombre "Rebeca Gaona" (lead Facebook nov-2025) pero con
+     `ID Contacto Sucursal`, WhatsApp y **opp** de **Maely Linares** (Puebla, abr-2026).
+   - Causa: dos personas comparten el mismo teléfono (+52 222 ··· ····); el autoenlace por teléfono
+     pegó los datos de Maely sobre el contacto de Rebeca → registro "Frankenstein".
+6. **Decisión de negocio (usuario):** conservar el registro reciente con seguimiento (Maely),
+   descartar el viejo sin seguimiento (Rebeca).
+7. **Pivote DELETE → UPDATE:** borrar el contacto de Marca habría borrado también la opp de
+   Maely y la habría dejado huérfana (el registro era, de facto, la réplica de Maely). La
+   acción correcta fue **sobrescribir la identidad** (nombre/email/tags) a Maely, conservando
+   opp y enlace. `snapshot → dry-run (diff) → PUT → re-audit`. Resultado: el par cuadra.
+8. **test21:** resultó ser un **fantasma de índice** — `/contacts/search` lo devolvía
+   (`total:1`) pero `GET/DELETE` por id daban 404. La sync de las 17:10 lo revivió en cache.
+   No accionable; se auto-corrige.
+
+**Estado final:** contactos **0**, opps **+2** (opps auto-creadas en vuelo).
+
+---
+
+## 5. Análisis de perspectivas — por qué funcionó
+
+- **Evidencia sobre inferencia.** Cada hipótesis se confirmó contra datos *antes* de actuar:
+  executions de n8n (¿corrió?), `GET` por id vs search (¿existe?), `sync_log` (¿cache fresco?).
+  Ninguna mutación se hizo "por intuición".
+- **El cache como sospechoso #1.** Tratar el descuadre positivo como problema de cache —no de
+  datos— evitó "arreglar" 4 contactos que ya estaban perfectos en su sucursal. El re-sync
+  resolvió más que cualquier mutación.
+- **El seguimiento del usuario como timón.** La regla de negocio ("quedarse con el registro
+  con seguimiento") la puso el usuario; el rol técnico fue **traducirla a la acción correcta
+  y advertir cuando lo que pidió (borrar) lograba lo contrario**. Esa advertencia evitó
+  orfanar a Maely.
+- **Disciplina dry-run / snapshot.** Convirtió un `PUT` irreversible (sobrescribir identidad)
+  en algo reversible. El snapshot vive en `generated/migrations/`.
+- **Defecto numérico ≠ defecto de integridad.** Rebeca cuadraba a 0 en el contador, pero era
+  corrupción de identidad real. Se arregló por **integridad de datos**, no por mover el número.
+- **Honestidad sobre límites.** test21 (fantasma) y guco (sucursal inexistente) no se forzaron;
+  se documentaron como no-accionables. Mejor "esto no tiene arreglo y aquí está el porqué" que
+  un parche cosmético que reaparece en la siguiente sync.
+
+---
+
+## 6. Checklist de investigación (pégalo y síguelo)
+
+1. **Frescura de cache.** `sync_logs` por location vs `date_added` de sospechosos.
+2. **Corre el audit** (background + JSON) y **lee los buckets por signo** (§2.3).
+3. **Descarta duplicados** intra-Marca (`intra_brand_duplicates`) de entrada.
+4. Para cada huérfano sospechoso: **verifica en vivo** por id vs search (§3.4).
+   - Stale → **re-sync** de la location y **re-audit**.
+   - Fantasma de índice → **esperar / monitorear** (no borrar por id).
+   - Creado en Marca → **forense n8n** (¿cascó? ¿a dónde?).
+5. **Colisión / duplicado real** → jerarquía de resolución (memoria `duplicate_resolution_rules`)
+   + **snapshot → dry-run → apply**. Pregúntate si la acción correcta es UPDATE, no DELETE.
+6. **Re-audit final.** Confirma que el descuadre bajó y que no introdujiste orfandad.
+7. **Reporta en dos registros:** técnico (este nivel) y **no técnico** para el negocio.
+
+---
+
+## 7. Síntomas → causa probable
+
+| Síntoma | Causa probable |
+|---|---|
+| El conteo **subió** tras un re-sync | Altas reales nuevas en GHL (no un error). |
+| Un contacto **reaparece** tras borrarlo del cache | Fantasma de índice GHL (search lo revive). |
+| `GET /contacts/{id}` 404 pero search lo lista | Borrado del store, índice rezagado (fantasma). |
+| Huérfano con tag `sucursal` y sin Sucursal/TIENDA poblada | Vino por Sucursal→Marca con formulario sin ruteo. |
+| Contacto y su opp tienen **nombres distintos** | Colisión por identificador compartido (teléfono/email). |
+| Descuadre positivo con `intra_brand_duplicates: 0` | Cache viejo o huérfanos creados directo en Marca. |
+| Mutación falla 400 vía el server pero el dato existe | Token del server distinto; reintenta con token del CSV. |
+
+---
+
+## Referencias
+
+- [AGENTS.md](../AGENTS.md) · [CLAUDE.md](../CLAUDE.md) · [docs/GUIA_AGENTICA.md](GUIA_AGENTICA.md)
+- Código: `scripts/audit_brand_vs_branches_totals.py`, `ghl_client.py`, `sync_engine.py`,
+  `main.py`, `scripts/n8n_workflow_lib.py`.
+- Memorias: `positive_descuadre_stale_cache`, `contact_descuadre_reconciliation`,
+  `matching_rules`, `duplicate_resolution_rules`, `create_duplicate_phone_contact_marca`,
+  `opp_multiplicity_replication_gap`, `ghl_tags_api`.