Registro de CRM (CrmRecord)

Modulo: CRM Tipo: Resource Estado: Implementado Fecha: 2026-02-02

---

Descripcion

El recurso CrmRecord (Registro de CRM) es la entidad central del modulo, representando cada interaccion, seguimiento o caso gestionado. Es el recurso mas complejo del modulo con soporte para tipos dinamicos, campos personalizados, derivaciones entre usuarios y relaciones entre registros.

Valor de negocio:

• Centraliza el seguimiento de todas las interacciones con contactos
• Permite trazabilidad completa de cada caso o oportunidad
• Soporta flujos de trabajo con derivaciones entre usuarios
• Habilita relacionar registros para casos complejos
• Mantiene historial completo incluyendo cancelaciones
• Admite datos extendidos segun el tipo de CRM

---

Frontend (Perspectiva de Usuario)

Vistas

1. Listado de Registros

   • Tabla paginada con filtros avanzados
   • Indicadores visuales de estado (cancelado, con derivaciones)
   • Acceso rapido a detalle, edicion y acciones
   • Filtros por fecha, operador, estado, tipo de consulta

2. Formulario de Alta/Modificacion

   • Datos basicos (fecha, contacto, titulo, detalle)
   • Campos personalizados dinamicos segun tipo de CRM
   • Datos extendidos segun tipo (ventas, servicio tecnico)
   • Pestanas para derivaciones y relaciones

3. Panel de Derivaciones

   • Historial de derivaciones del registro
   • Agregar nueva derivacion
   • Visualizar quien derivo a quien

4. Panel de Relaciones

   • Registros relacionados (origen y destino)
   • Agregar nueva relacion
   • Tipo de relacion (seguimiento, duplicado, derivado)

5. Modales de Cancelacion

   • Seleccion de motivo de cancelacion
   • Opcion para cancelar registros relacionados
   • Confirmacion de accion

Interacciones del Usuario

Accion	Descripcion
Crear registro	El usuario crea un nuevo registro de CRM
Editar registro	El usuario modifica los datos de un registro
Cancelar registro	El usuario cancela un registro con motivo
Recuperar registro	El usuario revierte la cancelacion
Cancelar por rango	El usuario cancela multiples registros por fecha
Derivar registro	El usuario deriva el registro a otro operador
Relacionar registros	El usuario vincula dos registros
Eliminar relacion	El usuario elimina una relacion existente
Filtrar registros	El usuario aplica filtros de busqueda
Ver derivaciones	El usuario consulta historial de derivaciones
Ver relaciones	El usuario consulta registros relacionados

Filtros Disponibles

Filtro	Descripcion
Fecha desde	Fecha minima del registro
Fecha hasta	Fecha maxima del registro
Titulo	Busqueda por texto en titulo
Detalle	Busqueda por texto en detalle
Contacto	Filtro por contacto especifico
Operador	Filtro por usuario que creo el registro
Estado cancelacion	Todas / Solo canceladas / Solo activas
Campos extendidos	Filtros segun tipo de CRM (estado, categoria, etc.)

Permisos

• Visualizar registros
• Crear registros
• Modificar registros
• Cancelar registros
• Recuperar registros cancelados
• Derivar registros
• Gestionar relaciones

Estados de UI

Estado	Descripcion
Registro activo	Estado normal sin cancelacion
Registro cancelado	Muestra fecha y motivo de cancelacion
Con derivaciones	Indicador de que tiene derivaciones
Con relaciones	Indicador de registros relacionados
Cargando	Indicador durante operaciones
Error	Mensajes de error contextuales

---

Backend (Perspectiva de Datos de Negocio)

Entidad de Negocio: Registro de CRM

Representa una interaccion, seguimiento o caso dentro del CRM.

Datos Necesarios

Dato	Descripcion	Requerido	Restricciones
Identificador	UUID unico del registro	Auto	Formato UUID v4
Tipo CRM	Tipo de CRM al que pertenece	Si	Referencia valida
Fecha	Fecha y hora del registro	Si	Timestamp
Contacto	Contacto asociado al registro	Si	Referencia valida
Titulo	Titulo descriptivo del registro	Si	100 caracteres
Detalle	Descripcion extendida	No	Texto libre
Usuario	Operador que creo el registro	Si	Referencia a usuario
Fecha creacion	Momento de creacion	Auto	Timestamp
Fecha cancelacion	Momento de cancelacion	No	Timestamp
Motivo cancelacion	Razon de la cancelacion	No	Referencia valida

Datos Extendidos (ext_data)

Segun el tipo de CRM, se almacenan datos adicionales:

CRM Ventas:

• Categoria
• Subcategoria
• Tipo de origen
• Estado de llamada
• Prioridad
• Concesionario
• Modelo de interes

CRM Servicio Tecnico:

• Numero de serie
• Descripcion del problema
• Estado del servicio

Relaciones de Negocio

Relacion	Descripcion
Tipo CRM	Cada registro pertenece a un tipo de CRM
Contacto	Cada registro esta asociado a un contacto
Usuario	El registro tiene un operador creador
Motivo cancelacion	Si esta cancelado, tiene un motivo
Campos personalizados	El registro puede tener valores de campos dinamicos
Derivaciones	El registro puede tener multiples derivaciones
Relaciones	El registro puede estar relacionado con otros registros

Validaciones de Negocio

Validacion	Descripcion
Tipo CRM existente	El tipo de CRM debe existir y estar activo
Contacto existente	El contacto debe existir en el sistema
Titulo requerido	El titulo es obligatorio (5-100 caracteres)
Fecha valida	La fecha debe tener formato valido
Motivo requerido	Al cancelar, el motivo es obligatorio
Campos requeridos	Los campos personalizados marcados como requeridos deben tener valor
Relacion no duplicada	No pueden existir relaciones duplicadas entre registros
Relacion bidireccional	Las relaciones se validan en ambas direcciones

---

Reglas de Negocio

RN-REC-001: Identificador UUID

• Condicion: Al crear un nuevo registro
• Accion: El sistema genera automaticamente un UUID v4
• Nota: El UUID permite sincronizacion entre sistemas

RN-REC-002: Registro de Usuario

• Condicion: Al crear o modificar un registro
• Accion: El sistema registra el usuario que realiza la operacion
• Nota: El usuario se obtiene del token de autenticacion

RN-REC-003: Cancelacion con Motivo

• Condicion: Al cancelar un registro
• Accion: Se requiere fecha de cancelacion y motivo
• Nota: La cancelacion es reversible

RN-REC-004: Cancelacion en Cascada

• Condicion: Al cancelar con opcion "cancelar relacionados"
• Accion: El sistema cancela recursivamente todos los registros relacionados
• Nota: Todos reciben el mismo motivo de cancelacion

RN-REC-005: Recuperacion de Registro

• Condicion: Al recuperar un registro cancelado
• Accion: Se eliminan fecha y motivo de cancelacion
• Nota: No se recuperan automaticamente los registros relacionados

RN-REC-006: Cancelacion Masiva por Rango

• Condicion: Al cancelar por rango de fechas
• Accion: Se cancelan todos los registros en el rango (excepto ya cancelados)
• Nota: Opcionalmente incluye registros relacionados

RN-REC-007: Relaciones Bidireccionales

• Condicion: Al crear una relacion entre registros
• Accion: La relacion se puede ver desde ambos registros
• Nota: Se valida que no exista relacion duplicada en ninguna direccion

RN-REC-008: Datos Extendidos por Tipo

• Condicion: Al crear registro de tipo especifico
• Accion: Se almacenan datos extendidos segun el tipo de CRM
• Nota: Los datos se guardan en tabla separada

RN-REC-009: Campos Personalizados

• Condicion: Al crear/editar registro con campos definidos
• Accion: Se almacenan los valores de campos personalizados
• Nota: Los campos requeridos se validan segun configuracion

RN-REC-010: Inclusion de Relaciones

• Condicion: Al solicitar registro con includes
• Accion: Se incluyen las relaciones solicitadas (fields, derivations, relations, contact)
• Nota: Evita multiples consultas

---

Casos de Uso

Caso 1: Crear Registro de CRM

Actor: Usuario del modulo CRM

Precondiciones:

• El usuario debe estar autenticado
• El tipo de CRM debe existir y estar activo
• Debe existir al menos un contacto

Flujo principal:

1. El usuario accede al listado de registros
2. El usuario presiona "Nuevo Registro"
3. El sistema muestra el formulario de alta
4. El usuario selecciona la fecha y hora
5. El usuario selecciona el contacto
6. El usuario ingresa el titulo (5-100 caracteres)
7. El usuario opcionalmente ingresa detalle
8. El usuario completa campos personalizados segun el tipo
9. El usuario completa datos extendidos segun el tipo
10. El usuario presiona "Guardar"
11. El sistema valida los datos
12. El sistema crea el registro con UUID y usuario
13. El sistema muestra notificacion de exito

Postcondiciones:

• El registro queda almacenado con UUID unico
• El contador del tipo CRM incrementa
• El registro aparece en el listado

---

Caso 2: Cancelar Registro con Relacionados

Actor: Usuario del modulo CRM

Precondiciones:

• El registro debe existir y no estar cancelado
• El registro puede tener registros relacionados

Flujo principal:

1. El usuario accede al detalle del registro
2. El usuario presiona "Cancelar"
3. El sistema muestra modal de cancelacion
4. El usuario selecciona el motivo de cancelacion
5. El usuario marca la opcion "Cancelar registros relacionados"
6. El usuario confirma la operacion
7. El sistema cancela el registro principal
8. El sistema obtiene todos los registros relacionados recursivamente
9. El sistema cancela cada registro relacionado
10. El sistema muestra notificacion con cantidad de registros cancelados

Postcondiciones:

• El registro y todos sus relacionados quedan cancelados
• Todos tienen el mismo motivo de cancelacion
• Los registros permanecen visibles como cancelados

Flujos alternativos:

• Sin relacionados: Solo se cancela el registro principal

---

Caso 3: Derivar Registro a Otro Usuario

Actor: Usuario del modulo CRM

Precondiciones:

• El registro debe existir
• Debe haber otros usuarios disponibles

Flujo principal:

1. El usuario accede al detalle del registro
2. El usuario accede a la pestana "Derivaciones"
3. El usuario presiona "Nueva Derivacion"
4. El sistema muestra modal de derivacion
5. El usuario selecciona el usuario destino
6. El usuario opcionalmente ingresa una nota
7. El usuario confirma la derivacion
8. El sistema registra la derivacion con fecha actual
9. El sistema muestra notificacion de exito

Postcondiciones:

• La derivacion queda registrada con usuarios origen y destino
• El registro muestra indicador de derivacion
• El historial de derivaciones se actualiza

---

Caso 4: Relacionar Dos Registros

Actor: Usuario del modulo CRM

Precondiciones:

• Ambos registros deben existir
• No debe existir relacion previa entre ellos

Flujo principal:

1. El usuario accede al detalle de un registro
2. El usuario accede a la pestana "Relaciones"
3. El usuario presiona "Agregar Relacion"
4. El sistema muestra modal de busqueda
5. El usuario busca y selecciona el registro destino
6. El usuario selecciona el tipo de relacion (seguimiento, duplicado, derivado)
7. El usuario opcionalmente ingresa una nota
8. El usuario confirma la relacion
9. El sistema valida que no exista relacion duplicada
10. El sistema crea la relacion bidireccional
11. El sistema muestra notificacion de exito

Postcondiciones:

• La relacion queda registrada
• Ambos registros muestran la relacion
• Se puede navegar entre registros relacionados

Flujos alternativos:

• Relacion existente: El sistema muestra error indicando duplicado
• Direccion invertida: El usuario puede elegir invertir origen/destino

---

Caso 5: Filtrar Registros por Multiples Criterios

Actor: Usuario del modulo CRM

Precondiciones:

• Deben existir registros en el sistema

Flujo principal:

1. El usuario accede al listado de registros
2. El usuario abre el panel de filtros
3. El usuario ingresa fecha desde y hasta
4. El usuario selecciona un operador
5. El usuario selecciona estado "Solo activos"
6. El usuario aplica filtros adicionales segun tipo (categoria, estado llamada)
7. El sistema filtra los resultados
8. El listado muestra solo registros que cumplen todos los criterios
9. La paginacion se ajusta a los resultados

Postcondiciones:

• El listado muestra registros filtrados
• Los contadores reflejan los filtros aplicados

---

Caso 6: Cancelar Registros por Rango de Fechas

Actor: Usuario del modulo CRM

Precondiciones:

• Deben existir registros en el rango de fechas
• El usuario debe tener permiso de cancelacion masiva

Flujo principal:

1. El usuario accede a la funcion de cancelacion masiva
2. El usuario ingresa fecha desde
3. El usuario ingresa fecha hasta
4. El usuario selecciona motivo de cancelacion
5. El usuario opcionalmente marca "Incluir relacionados"
6. El sistema muestra previsualizacion de registros afectados
7. El usuario confirma la operacion
8. El sistema cancela todos los registros en el rango
9. El sistema retorna cantidad de registros cancelados

Postcondiciones:

• Todos los registros en el rango quedan cancelados
• Se excluyen registros ya cancelados
• Los IDs cancelados se retornan para trazabilidad

---

Consideraciones

Seguridad

• Solo usuarios autenticados pueden crear registros
• La cancelacion puede requerir permisos especiales
• Los datos del contacto requieren proteccion
• Las derivaciones registran quien realiza la accion

Auditoria

• Se registra quien crea cada registro
• Se registra quien cancela y cuando
• Las derivaciones mantienen historial completo
• Las relaciones registran quien las crea

Rendimiento

• El listado usa paginacion del lado del servidor
• Los filtros se aplican en la base de datos
• Las relaciones incluidas evitan N+1 queries
• El UUID permite indexacion eficiente

---

Dependencias

Funcionalidades Relacionadas

• Tipos de CRM: Define el contexto del registro
• Contactos: Persona asociada al registro
• Campos Personalizados: Datos adicionales configurables
• Usuarios: Operadores que crean y derivan
• Motivos de Cierre: Catalogo de razones de cancelacion

Subrecursos

• Derivaciones: Historial de derivaciones del registro
• Relaciones: Vinculos con otros registros
• Valores de Campos: Datos de campos personalizados

---

Criterios de Aceptacion

• [ ] AC-001: El usuario puede crear un registro con fecha, contacto y titulo
• [ ] AC-002: El sistema genera automaticamente un UUID para cada registro
• [ ] AC-003: El sistema registra el usuario creador automaticamente
• [ ] AC-004: El usuario puede completar campos personalizados segun el tipo
• [ ] AC-005: El usuario puede completar datos extendidos segun el tipo
• [ ] AC-006: El usuario puede editar registros existentes
• [ ] AC-007: El usuario puede cancelar un registro con motivo
• [ ] AC-008: El usuario puede cancelar registros relacionados en cascada
• [ ] AC-009: El usuario puede recuperar un registro cancelado
• [ ] AC-010: El usuario puede cancelar registros por rango de fechas
• [ ] AC-011: El usuario puede derivar un registro a otro usuario
• [ ] AC-012: El usuario puede ver historial de derivaciones
• [ ] AC-013: El usuario puede relacionar dos registros
• [ ] AC-014: El sistema previene relaciones duplicadas
• [ ] AC-015: Las relaciones son bidireccionales
• [ ] AC-016: El usuario puede eliminar relaciones
• [ ] AC-017: El listado soporta paginacion
• [ ] AC-018: El listado soporta multiples filtros simultaneos
• [ ] AC-019: Los filtros incluyen campos de datos extendidos
• [ ] AC-020: El usuario puede incluir datos relacionados (fields, derivations, relations, contact)

---

Notas Adicionales

• El UUID permite sincronizacion con sistemas externos
• Los datos extendidos (ext_data) varian segun el tipo de CRM
• Las derivaciones no cambian la propiedad del registro, solo documentan el flujo
• Las relaciones permiten navegar casos relacionados sin estructura jerarquica
• La cancelacion en cascada es util para grupos de registros relacionados
• Los filtros por datos extendidos usan batch loading para rendimiento
• El conteo de registros se calcula eficientemente para paginacion
• Los registros cancelados permanecen visibles pero claramente marcados