👤 Clientes

---

1. 🧩 Descripción General

El módulo de Clientes permite registrar, clasificar y gestionar la información de los compradores de la empresa, así como sus condiciones comerciales, historial de compras, estado de cuenta y direcciones de entrega. Su integración es clave con Ventas, Facturación, Cuentas por Cobrar y CRM.

---

2. 🧱 Modelos del Módulo

a. Client

• id: integer (PK)
• name: string
• rfc: string
• email: string
• phone: string
• credit_limit: decimal
• payment_terms: integer (días)
• currency: string
• price_list: string (opcional)
• is_active: boolean

b. ClientAddress

• id: integer (PK)
• client_id: FK → Client
• type: enum (fiscal, envío)
• street, city, state, zip, country: strings

c. ClientContact

• id: integer (PK)
• client_id: FK → Client
• name: string
• email: string
• phone: string
• position: string

d. ClientNote

• id: integer (PK)
• client_id: FK → Client
• note: text
• created_by: FK → User
• created_at: datetime

---

3. 🔁 Funciones del Controlador

• index(): Listar todos los clientes.
• store(): Crear nuevo cliente.
• show($id): Ver detalles del cliente.
• update($id): Editar datos.
• destroy($id): Desactivar cliente.
• addAddress(): Agregar dirección.
• addContact(): Agregar contacto.
• addNote(): Registrar nota interna.

---

4. 🌐 Endpoints detallados y justificados

Método	Ruta	Descripción	Justificación
GET	/api/clients	Listado de clientes	Consulta general
POST	/api/clients	Crear cliente	Alta para venta o factura
GET	/api/clients/{id}	Ver detalle	Info completa para pedidos
PUT	/api/clients/{id}	Editar cliente	Cambios comerciales
DELETE	/api/clients/{id}	Desactivar	Mantenimiento
POST	/api/clients/{id}/addresses	Agregar dirección	Facturación o entrega
POST	/api/clients/{id}/contacts	Agregar contacto	Punto de contacto
POST	/api/clients/{id}/notes	Agregar nota interna	Observaciones internas

---

5. 🖥️ Diseño UX sugerido (flujo de usuario)

Página: "Listado de Clientes"

• Tabla con nombre, RFC, límite de crédito, correo
• Filtros: por estado, moneda, vendedor asignado
• Acciones: Ver, Editar, Desactivar

Página: "Ficha del Cliente"

• Datos fiscales y comerciales
• Direcciones y contactos
• Notas internas
• Botón: Crear pedido, Generar factura

---

6. 📄 Vistas sugeridas (tipo wireframe)

Vista	Campos sugeridos	Acciones
Listado	Nombre, RFC, correo, teléfono, estado	Ver, Editar, Desactivar
Formulario	Nombre, RFC, correo, teléfono, moneda, límite	Guardar
Contactos	Nombre, email, teléfono, puesto	Añadir, Editar, Eliminar
Direcciones	Tipo, ciudad, calle, CP	Añadir, Editar, Eliminar

---

7. 🔗 Conexión Frontend ↔ API JSON:API

Acción en Frontend	Método/API	Resultado esperado
Ver clientes	GET /api/clients	Mostrar tabla
Ver cliente	GET /api/clients/{id}	Ficha de cliente
Crear cliente	POST /api/clients	Registro nuevo
Editar cliente	PUT /api/clients/{id}	Actualización
Añadir dirección	POST /api/clients/{id}/addresses	Agregada
Añadir contacto	POST /api/clients/{id}/contacts	Agregado
Añadir nota	POST /api/clients/{id}/notes	Guardada

---

📦 Este módulo permite una gestión integral de los clientes con enfoque comercial, contable y logístico, formando una base esencial para los módulos de ventas, facturación y cobranza del ERP.