Copie TODO esto dentro del archivo:

ALEPH CRM FLOW — Gemelo Comercial

1. Propósito

Definir el flujo operativo del Gemelo Comercial para:

  • gestionar prospectos

  • sincronizar información con ALEPH

  • evitar duplicidades (idempotencia)

  • mantener consistencia entre sistemas

2. Arquitectura del flujo

Prospect Store ↓ company_resolver ↓ company_push ↓ company_writer (dry-run → execute) ↓ crm_sync ↓ crm_push ↓ crm_writer (dry-run → execute) ↓ ALEPH

3. Flujo operativo

3.1 Empresa

  1. Resolver empresa (company_resolver)

  2. Si no existe → CREATE_COMPANY

  3. Generar dry-run

  4. Ejecutar inserción en EMPRESAS

3.2 CRM

  1. Clasificar (crm_sync)

  2. Validar (crm_push)

  3. Generar dry-run (crm_writer)

  4. Ejecutar:

    • PERSONAS

    • PERSONA_PROYECTO

4. Tablas ALEPH

EMPRESAS

  • NIT

  • razon_social

  • id_tipo

  • id_estado

Defaults:

  • id_tipo = 'NA'

  • id_estado = 'OK'

PERSONAS

  • id_persona

  • nombre

  • apellido

  • nombreC

  • e_mail

  • telefono

  • celular

  • NIT

Regla de nombres (Regla 3)

  • 1 palabra → nombre

  • 2 palabras → nombre + apellido

  • 3+ → nombre = todas menos última

Siempre:

nombreC = full_name

PERSONA_PROYECTO

  • id_persona

  • id_proyecto

  • fecha_visita

  • fecha_sig_contacto

  • nota_ultimo_contacto

5. Reglas clave

5.1 Orden jerárquico

EMPRESA → PERSONA → RELACIÓN

5.2 Contacto mínimo

Se requiere:

  • full_name

  • (email o phone)

5.3 Idempotencia

Antes de insertar:

PERSONAS: buscar por email o por (nombre + NIT)

PERSONA_PROYECTO: buscar por (id_persona + id_proyecto)

5.4 Dry-run obligatorio

preview → dry-run → execute

6. Estados del sistema

Estado

Significado

CREATE_CONTACT_AND_ACTIVITY

Crear persona + relación

ENRICH_CONTACTS

Falta contacto

CRM_ALREADY_SYNCED

Ya existe en ALEPH

CREATE_ACTIVITY_ONLY

Falta relación

PENDING_COMPANY_CREATION

Falta empresa

VENDOR_REGISTRATION

Flujo internacional

7. Estado actual

Prospecto

Estado

NAC-0002

✅ CRM_ALREADY_SYNCED

NAC-0001

⛔ PENDING_COMPANY_CREATION

NAC-0003

⛔ PENDING_COMPANY_CREATION

INT-*

⛔ VENDOR_REGISTRATION

8. Archivos del pipeline

data/commercial/

  • prospects.jsonl

  • company_resolution_preview.jsonl

  • company_push_preview.jsonl

  • company_write_dry_run.jsonl

  • crm_sync_preview.jsonl

  • crm_push_preview.jsonl

  • crm_write_dry_run.jsonl

9. Comandos operativos

Empresas

python -m prodisys.comercial.company_resolver
python -m prodisys.comercial.company_push
python -m prodisys.comercial.company_writer
CRM
python -m prodisys.comercial.crm_sync
python -m prodisys.comercial.crm_push
python -m prodisys.comercial.crm_writer
10. Estado del sistema
✔ Escritura en EMPRESAS
✔ Escritura en PERSONAS
✔ Escritura en PERSONA_PROYECTO
✔ Idempotencia funcional
✔ Flujo completo operativo
11. Próximos pasos
Corto plazo
Completar NAC-0001 y NAC-0003
Medio plazo
Normalización de nombres
Validación de teléfonos
Generación automática de contact_id
Largo plazo
Vendor registration (internacional)
Sincronización bidireccional

---

## ✅ Luego guarde y salga

En nano:

```bash
Ctrl + O
Enter
Ctrl + X
🧠 Resultado

Ahora tiene:

documentación persistente
alineada al código real
lista para equipo o escalamiento

### Regla 6 — Proyecto interno obligatorio para CRM operativo

Para crear relación en `PERSONA_PROYECTO` se requiere:

- `internal_commercial_project_id`

Si no existe, el prospecto queda bloqueado con:

- `falta_proyecto_interno`

Razón:
sin proyecto interno comercial no se puede crear la relación CRM operativa en ALEPH.

## Estado actual por prospecto

- `NAC-0002`: sincronizado completamente (`CRM_ALREADY_SYNCED`)
- `NAC-0001`: empresa creada y contacto válido, bloqueado por `falta_proyecto_interno`
- `NAC-0003`: contacto válido, bloqueado por `PENDING_COMPANY_CREATION`
- `INT-0001`, `INT-0002`: bloqueados por `VENDOR_REGISTRATION`

## D-011 — Proyecto interno obligatorio

Para CRM operativo no basta con empresa y contacto.  
También se requiere `internal_commercial_project_id`.

Sin ese dato, el prospecto debe quedar bloqueado como no escribible.

Razón:
`PERSONA_PROYECTO` exige proyecto y el writer CRM depende de esa relación.

## 12. Flujo internacional

A diferencia del flujo nacional, el flujo internacional introduce el concepto de:

- `vendor_registration_required`
- `vendor_registration_status`

### Regla operativa

El vendor registration:

- NO bloquea la creación de contactos ni actividades iniciales
- SÍ afecta la madurez comercial del prospecto

### Interpretación en CRM

| Condición | Acción |
|----------|--------|
| Sin contacto | ENRICH_CONTACTS |
| Con contacto y acción | CREATE_CONTACT_AND_ACTIVITY |
| Con vendor pendiente | se refleja en `reason`, no bloquea |

### Ejemplo

```text
CREATE_CONTACT_AND_ACTIVITY
→ "Prospecto internacional listo para gestión comercial; vendor registration pendiente."