Arquitectura ControlPro: Socios de negocios

Este documento describe la arquitectura, estructura de datos y funcionalidad del módulo de «Socios de Negocios» (Business Partners) en el sistema ControlPro.

1. Visión General

El módulo de Socios de Negocios actúa como el directorio centralizado para gestionar todas las relaciones externas de la empresa. Un «Socio de Negocio» puede ser un Cliente, Proveedor o Prospecto. Este módulo es fundamental ya que alimenta a otros módulos críticos como Ventas, Compras y Contratos. Esta catalogado dentro de los Documentos Maestros del sistema.

2. Arquitectura de Datos

Entidad Principal: partners

La tabla partners es el núcleo del módulo.

• Identificación: id (PK), company_id (Multi-tenancy).
• Clasificación: type (proveedor, cliente, prospecto), category_id (FK partner_categories).
• Datos Generales: nombre, nombre_comercial, nombre_alias, nit, descripcion.
• Datos de Contacto: email, telefono, url.
• Datos Financieros: price_list_id (Lista de Precios), currency (Moneda default), payment_terms_id (Condiciones de Pago), payment_method_id (Forma de Pago).
• Ubicación: direccion, pais, ciudad, state, postal_code.
• Redes Sociales: Almacenado en columnas individuales (facebook, instagram, tiktok, whatsapp_business) o campos redes_sociales (dependiendo de la versión de migración).

Entidades Relacionadas (Tablas Satélite)

Estas tablas tienen una relación 1:N con partners.

1. Contactos (partner_contacts): Personas de contacto dentro de la organización del socio.
   • Campos: name, position, email, phone, photo, is_default.
2. Direcciones (partner_addresses): Múltiples direcciones de envío o facturación.
   • Campos: address, city, state, country, location_name (ej. Bodega Central), phone, email.
3. Cuentas Bancarias (partner_bank_accounts): Información bancaria para pagos (principalmente proveedores).
   • Campos: bank_name, account_number, account_type, currency, is_default.
4. Enlaces Extras (partner_urls): URLs adicionales relevantes.
   • Campos: url, description, username.
5. Notas Internas (partner_notes): Bitácora de notas o comentarios internos sobre el socio.
   • Campos: note, created_by, created_at.
6. Documentos (partner_documents): Archivos adjuntos (ej. RTU, Patente).
   • Campos: filename, path, file_type.
7. Relaciones (partner_relationships): Vincula dos socios (ej. «Subsidiaria de»).
   • Campos: partner_a_id, partner_b_id, relationship_type_id.

Diagrama Entidad-Relación (Simplificado)

3. Estructura del módulo (Archivos)

El módulo se encuentra en modules/partners/ y sigue un patrón MVC simple (sin clases estrictas de controlador, lógica procedural en archivos PHP).

Controladores de Vista

• index.php: Listado principal. Maneja filtros (tipo, categoría, búsqueda), paginación y ordenamiento.
• profile.php: Perfil detallado «360 grados» del socio. Muestra dashboard con gráficos de ingresos, historial de transacciones, contactos, etc.

Lógica de negocio (CRUD)

• save.php: Crea y actualiza la entidad principal partners.
• save_contact.php, save_address.php, save_*.php: Manejan la creación/edición de entidades satélite vía AJAX.
• delete.php: Elimina un socio (validando dependencias previas).
• delete_*.php: Eliminación de registros satélite.

Componentes de datos (Getters)

• get.php: Obtiene datos de un socio (JSON) para edición rápida.
• get_contacts.php, get_addresses.php: Obtiene listas para renderizado dinámico o modales.

4. Funcionalidades clave

4.1 Gestión de Perfil 360°

La vista de perfil (profile.php) agrega toda la información relevante:

• Métricas: Gráfico de ingresos generados (último año/mes).
• Historial Transaccional:
  • Cotizaciones
  • Órdenes de Venta
  • Órdenes de Compra (si es Proveedor)
  • Contratos vigentes y pasados
• Productos Relacionados: Lista de productos más comprados/vendidos a este socio.

4.2 Validaciones y reglas

• Borrado Seguro: No permite borrar socios que tengan transacciones vinculadas (cotizaciones, órdenes, etc.) (dependency_count).
• Permisos: Verifica permisos de usuario (Socios de Negocio -> view, create, edit, delete) y nivel de webadmin.
• Multi-empresa: Aísla estricta por company_id.

5. Integraciones

El módulo exporta datos para ser consumidos por:

• Módulo de Ventas: Selección de cliente en Cotizaciones/Órdenes. Hereda condiciones de pago y listas de precios.
• Módulo de Compras: Selección de proveedor.
• Módulo de Contratos: Asignación de contraparte legal.
• Módulo de Inventarios: Proveedores de productos.

6. Futuras mejoras recomendadas

• Validación de NIT: Integración con API de SAT para validar datos fiscales automáticamente.
• Límites de Crédito: Implementar campo de límite de crédito y validación en Órdenes de Venta.
• Portal de Autoservicio: Permitir que ciertos contactos del socio («Portal User») inicien sesión para ver sus facturas/pedidos.