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

```bash
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."