# Contrato de base de datos CRM

## Principio general
El CRM usa una base independiente llamada `ventasin_crm_prod`. La base del portal `ventasin_portalvi_prod` se conserva para autenticación, usuarios, roles, permisos y menú.

## Fuente de verdad por dominio

| Dominio | Tabla fuente de verdad CRM | Observación |
|---|---|---|
| Clientes | `crm_clientes` | Unifica prospectos, activos, inactivos y migrados. |
| Contactos | `crm_contactos` | Varios contactos por cliente. |
| Oportunidades | `crm_oportunidades` | Corazón del pipeline comercial. |
| Etapas | `crm_pipeline_etapas` | Configurable. |
| Actividades / agenda | `crm_actividades` | Sustituye cronograma comercial para CRM. |
| Historial actividad | `crm_actividad_historial` | Trazabilidad de cambios y resultados. |
| Cotizaciones | `crm_cotizaciones`, `crm_cotizacion_detalle` | Estructura preparada para etapa 2. |
| Visitas | `crm_visitas` | Estructura preparada para ubicación integrada. |
| Rutas | `crm_rutas` | Inicio/fin de ruta de ejecutivos. |
| Ubicación | `crm_ubicaciones` | Puntos de ruta, visita e hitos. |
| Campañas | `crm_campanias`, `crm_campania_clientes` | Sustituye clientes inactivos como flujo aislado. |
| Importaciones | `crm_importaciones`, `crm_importacion_errores` | Base para archivos planos. |
| API ERP | `crm_api_*` | Base para integración futura. |
| Histórico productos | `crm_cliente_productos_historico` | Conserva histórico importado/migrado. |
| Usuarios | `ventasin_portalvi_prod.usuario/persona` | Se consulta, no se duplica. |
| Roles/permisos | `ventasin_portalvi_prod.rol/opcion/...` | Se consulta y administra en portal. |

## Reglas de continuidad
1. No crear otra tabla de clientes. Usar `crm_clientes`.
2. No crear otra tabla de agenda. Usar `crm_actividades`.
3. No crear otra tabla de visitas sin migrar o relacionar con `crm_visitas`.
4. No guardar usuarios comerciales duplicados en CRM. Guardar únicamente el ID del usuario del portal.
5. Toda información migrada desde el portal debe conservar `legacy_source` y `legacy_id`.
6. Toda información nueva debe quedar en la base CRM.
7. Para importaciones/API desde ERP, actualizar por `codigo_erp` o `nit` para evitar duplicados.

## Relaciones principales
- `crm_contactos.cliente_id` → `crm_clientes.id`
- `crm_oportunidades.cliente_id` → `crm_clientes.id`
- `crm_oportunidades.contacto_id` → `crm_contactos.id`
- `crm_oportunidades.etapa_id` → `crm_pipeline_etapas.id`
- `crm_actividades.cliente_id` → `crm_clientes.id`
- `crm_actividades.oportunidad_id` → `crm_oportunidades.id`
- `crm_visitas.ruta_id` → `crm_rutas.id`
- `crm_visitas.cliente_id` → `crm_clientes.id`
- `crm_ubicaciones.ruta_id` → `crm_rutas.id`
- `crm_ubicaciones.visita_id` → `crm_visitas.id`
- `crm_campania_clientes.campania_id` → `crm_campanias.id`
- `crm_campania_clientes.cliente_id` → `crm_clientes.id`

## Tablas antiguas
Las tablas antiguas quedan como respaldo histórico. En el nuevo CRM no se deben usar como fuente directa de operación diaria:

- `cc_clientes_inactivos`
- `cc_gestiones`
- `cc_productos_historico`
- `cc_agenda`
- `cc_agenda_historial`
- `registrovisitas`
- `rutas_asesor`
- `seguimientos`
- `seguimiento_observaciones`

## Integración entre bases
El código del CRM usa:

- `DatabaseCrm` para la base CRM.
- `Database` para la base del portal.

Cuando se requiere nombre de usuario, responsable o rol, se consulta la base del portal con joins cross-database o con conexión portal.