👤 Gestión de Contactos
Administración completa de contactos con acceso basado en roles, fotos y vínculo multi-entidad.
contact_roles. Solo ves los contactos asignados a tu entidad activa.
📋 ¿Qué hace este sistema?
El Gestor de Contactos administra contactos, clientes y miembros de equipo a través de distintas entidades de negocio. Provee:
- Autenticación por sesión + entidad activa (cada usuario pertenece a una o más entidades).
- Ciclo de vida completo del contacto: crear, ver, editar, borrar — con búsqueda y filtros (estado, género, rol, palabra clave).
- Carga de foto/avatar, con valores por defecto razonables.
- Asignación de rol por entidad mediante la tabla pivote
contact_roles(user_id,entity_id,role). - Estadísticas en vivo: totales, activos, verificados, dueños principales.
🖱️ Cómo Usar
Inicio de sesión y contexto de entidad
Después de iniciar sesión, el sistema usa tu selección activa de business_entities. Todo contacto mostrado pertenece a esa entidad.
Ver y filtrar contactos
La tabla muestra foto, nombre, correo, teléfono, rol y estado. Filtra por nombre/correo/teléfono, estado, género o rol.
Agregar un contacto
Llena nombre, apellido, correo (obligatorio), opcionalmente foto y rol. Los contactos nuevos se vinculan a tu entidad vía contact_roles.
Editar / ver / borrar
Borrar solo quita el contacto de tu entidad — el contacto en sí solo se borra por completo si ya no le queda ninguna otra asociación de entidad.
Deduplicación
Agregar un contacto cuyo correo/RFC/CURP ya existe no crea un duplicado — vincula el contacto existente a tu entidad.
⭐ Características Principales
| Característica | Descripción |
|---|---|
| 📤 Foto/Avatar | PNG/JPG, guardadas en /media/platform/img/users/ con nombres basados en el username. |
| 🪪 Validación RFC/CURP | Unicidad reforzada a nivel de aplicación — evita IDs oficiales duplicados entre entidades. |
| 🏢 Arquitectura multi-entidad | Un contacto puede pertenecer a varias entidades, con un rol distinto en cada una, vía contact_roles. |
| 🔑 Hash de contraseña | Los contactos nuevos reciben una contraseña con hash (password_hash()). Editar nunca la muestra ni la resetea por accidente. |
| 📊 Estadísticas en vivo | Conteos agregados (activos/verificados/principales) delimitados a la entidad activa. |
| 🔍 Filtrado dinámico | Búsqueda combinada por nombre/correo/teléfono/apodo más estado/género/rol. |
🔌 Endpoints de la API
Todas las acciones requieren una sesión autenticada y una entidad activa.
GET ?action=get
Contactos paginados con filtros, delimitados a la entidad activa vía contact_roles.
GET ?action=get&id=123
Detalles de un contacto (solo si pertenece a tu entidad activa).
GET ?action=stats
Estadísticas delimitadas a la entidad: total, activos, verificados, principales.
POST Crear contacto
Valida nombre/correo, revisa si el contacto ya existe, y vincula el rol.
PUT Actualizar contacto
Actualiza campos, procesa una foto nueva, actualiza el rol en esa entidad.
DELETE Borrar contacto
Quita el vínculo en contact_roles; solo borra el contacto si no le queda ninguna otra asociación.
contacts (datos personales, foto, is_active), contact_roles (user_id, entity_id, role), business_entities (contexto de entidad).
🛡️ Seguridad y Permisos
- Sesión obligatoria: cada solicitud verifica el usuario autenticado y la entidad activa; las no autorizadas se redirigen al login.
- Aislamiento por entidad: toda consulta pasa por
contact_rolesdelimitada alentity_idactivo — no puedes ver ni editar contactos de otra entidad. - Protección contra inyección SQL: consultas parametrizadas en todo, sin concatenación de cadenas.
- Almacenamiento de contraseñas: los contactos nuevos reciben
password_hash()— nunca texto plano. - Carga de fotos: lista blanca de extensiones, rutas absolutas al guardar para evitar directory traversal.
🔧 Solución de Problemas y Preguntas Frecuentes
"No aparecen contactos" o las estadísticas muestran 0
contact_roles tenga una fila que vincule tu usuario a esa entidad.La foto no se sube o se muestra un avatar por defecto
Error "Invalid business entity"
business_entities. Normalmente se crea automáticamente al registrarte — si falta, contacta a un administrador.Contactos duplicados / comportamiento de vinculación
contact_roles para tu entidad.