# Plan: Hoja de Ruta por Cobrador + Detalle en Panel Cobrador ## Contexto El supervisor necesita una pantalla en Finanzas para gestionar y generar la hoja de ruta diaria de cada cobrador (lista de clientes a visitar), pudiendo también asignar cobrador a clientes sin asignar. Paralelamente, el Panel Cobrador debe mostrar más detalles por cliente al expandir la tarjeta. ## Decisiones confirmadas | Decisión | Valor | |---|---| | Ubicación supervisor | Tab "Hoja de Ruta" en Finanzas | | Detalle cliente en Panel Cobrador | Expandir tarjeta inline (click) | | Asignación temporal | Solo lista manual de pantalla, sin guardar en BD | | Clientes sin cobrador | Ver lista + asignar cobrador permanente desde ahí | | PDF | Uno por cobrador (A), usando msv-kude | --- ## Campos disponibles en BD | Campo | Fuente | Tabla | |---|---|---| | Nombre / CI | `personas.razon_social`, `nro_documento` | personas | | Dirección | `personas.direccion` + `personas.nro_casa` | personas | | Referencia domicilio | `clientes.referencia_domicilio` | clientes | | Celular / Teléfono | `personas.celular`, `personas.telefono` | personas | | Zona | `clientes.zona` | clientes | | Cobrador asignado | `factura_cab.cobrador_id` / `solicitud_credito.cobrador_id` | ambos | | Día fijo de cobro | `solicitud_credito.dia_fijo_pago` (1-28) | solicitud_credito | | Día semana de cobro | `solicitud_credito.dia_cobro_semana` (1=Lun…7=Dom) | solicitud_credito | | Saldo pendiente | `cuentas_cobrar.saldo_pendiente` | cuentas_cobrar | | Cuotas pendientes | `factura_cuotas` con estado pendiente | factura_cuotas | | Promesa de pago | `promesas_pago.fecha_prometida`, `monto_prometido`, `notas`, `estado` | promesas_pago | | Productos/items | `factura_det.ddesproser`, `dcantproser`, `dmoncuota` | factura_det | | Observación solicitud | `solicitud_credito.observaciones` | solicitud_credito | --- ## Diseño de la Hoja de Ruta (Finanzas) ``` ┌──────────────────────────────────────────────────────────────────┐ │ Finanzas [Caja] [Comisiones] [...] [Hoja de Ruta] │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ Cobrador: [Juan Pérez ▼] Estado: [Todos ▼] │ │ Vence hasta: [30/04/2026] [🖨 Generar PDF] │ │ │ │ ── Clientes asignados (23) ────────────────────────────────── │ │ Cliente CI/RUC Dirección Cel Saldo Día │ │ ───────────────────────────────────────────────────────────── │ │ María López 1234567 Av. España 12 09811 450.000 Lun │ │ Carlos Ruiz 2345678 Calle 5ta 90 09812 230.000 15 │ │ ... │ │ │ │ ── Sin cobrador asignado (8) ──────────────────────────────── │ │ Ana Giménez 3456789 Ruta 2 km 5 09813 180.000 │ │ [Asignar cobrador ▼] │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## Hoja impresa (PDF por cobrador) Una página por cobrador, ordenada por zona/dirección: ``` HOJA DE RUTA — 17/04/2026 Cobrador: Juan Pérez N° Cliente CI Dirección Tel Día Saldo Promesa Obs 1 María López 1234567 Av. España 123 Ref: 09811.. Lun Gs.450.000 20/04 cumplir Portón azul Productos: Samsung A15, Smart TV 55" ───────────────────────────────────────────────────────────────────────────────────────── 2 Carlos Ruiz 2345678 Calle 5ta 90 09812.. Día15 Gs.230.000 Productos: Lavarropas WW18AT ``` --- ## Panel Cobrador — Tarjeta expandida Al hacer click en el nombre del cliente en el Panel Cobrador, la tarjeta se expande mostrando: ``` ┌── María López ───────────────── Al día ─────────────────────┐ │ 📍 Av. España 123 Ref: Portón azul, casa con rejas verdes │ │ 📱 0981-123456 🗓 Cobro: Lunes │ │ │ │ Productos de la cuenta: │ │ • Samsung Galaxy A15 × 1 — Gs. 450.000 │ │ • Smart TV 55" × 1 — Gs. 2.800.000 │ │ │ │ Última promesa: 20/04/2026 — Gs. 150.000 (pendiente) │ │ Nota: "Va a pagar el viernes cuando cobre" │ │ │ │ [Fac. 001-001-000123 c.3 Gs.450.000 29/07/2026] [💰] │ └──────────────────────────────────────────────────────────────┘ ``` --- ## Implementación ### Paso 1 — Backend: nuevos endpoints en CobrosController **Archivo**: `src/cobros/cobros.controller.ts` + `cobros.service.ts` #### 1.1 `GET /cobros/hoja-de-ruta` Parámetros: `cobrador_id`, `estado?` (todos/vencido/al_dia), `fecha_hasta?` Retorna por cobrador una lista de clientes con: - Datos personales (nombre, CI, dirección, referencia, celular, zona) - Cuentas a cobrar con cuotas pendientes y saldo - Última promesa de pago activa (fecha, monto, notas) - Día de cobro (de solicitud_credito: `dia_fijo_pago` o `dia_cobro_semana`) - Productos/items de la factura (primeros 3 del detalle) - Observación de solicitud de crédito #### 1.2 `GET /cobros/clientes-sin-cobrador` Clientes que tienen cuentas_cobrar con estado != 'pagada' pero sin cobrador_id en ninguna factura_cab activa. #### 1.3 `PATCH /clientes/:id/asignar-cobrador` Body: `{ cobrador_id: string }` Actualiza `cobrador_id` en todas las `factura_cab` activas del cliente. #### 1.4 `GET /cobros/hoja-de-ruta/pdf` Parámetros: `cobrador_id`, `tipo?` (view/base64) Arma el payload y llama a msv-kude `/api/hoja-de-ruta/generate-pdf`. ### Paso 2 — Backend: detalle del cliente para Panel Cobrador **Archivo**: `src/cobros/cobros.service.ts` #### 2.1 `GET /cobros/cuentas-cobrar/detalle-cliente/:clienteId` Retorna datos extra del cliente para la tarjeta expandida: - `referencia_domicilio`, `celular`, `telefono`, `direccion` - `dia_fijo_pago`, `dia_cobro_semana` (de última solicitud_credito aprobada) - `ultima_promesa` (promesas_pago más reciente activa) - `productos` (factura_det de las facturas activas del cliente) ### Paso 3 — msv-kude: template hoja de ruta **Directorio nuevo**: `msv-kude/src/hoja-de-ruta/` - `hoja-de-ruta.route.js` — endpoint `POST /api/hoja-de-ruta/generate-pdf` - `hoja-de-ruta.template.js` — template HTML con estilos de impresión - `hoja-de-ruta.controller.js` — lógica de renderizado Template: tabla por cliente con columnas de la hoja impresa descritas arriba. Estilo limpio para impresora (blanco/negro). ### Paso 4 — Frontend: Tab "Hoja de Ruta" en Finanzas **Archivo nuevo**: `pos-ventas/src/components/tesoreria/HojaRutaTab.jsx` **Archivo modificado**: `pos-ventas/src/pages/Tesoreria.jsx` Componente con: - Selector de cobrador con búsqueda (Autocomplete) - Filtro estado + fecha vencimiento hasta - Tabla de clientes asignados (paginada, con columnas del diseño) - Sección "Sin cobrador" con botón asignar por fila - Botón "Generar PDF" → GET al backend → abre en nueva pestaña ### Paso 5 — Frontend: Tarjeta expandible en Panel Cobrador **Archivo**: `pos-ventas/src/pages/PanelCobrador.jsx` (o componente de tarjeta) Al hacer click en el nombre del cliente: - Se dispara query `GET /cobros/cuentas-cobrar/detalle-cliente/:clienteId` - Se expande la tarjeta mostrando las secciones del diseño - Loading skeleton mientras carga - Collapse al volver a clickear --- ## Archivos a modificar | Archivo | Cambio | |---|---| | `src/cobros/cobros.controller.ts` | +4 endpoints | | `src/cobros/cobros.service.ts` | +4 métodos | | `msv-kude/src/hoja-de-ruta/` | **NUEVO** directorio + template + route | | `msv-kude/src/routes/index.js` | Registrar nueva ruta | | `pos-ventas/src/api/cobros.service.js` | +3 funciones API | | `pos-ventas/src/components/tesoreria/HojaRutaTab.jsx` | **NUEVO** | | `pos-ventas/src/pages/Tesoreria.jsx` | +1 tab | | `pos-ventas/src/pages/PanelCobrador.jsx` | Tarjeta expandible | --- ## Orden de implementación 1. Backend: endpoints hoja-de-ruta + clientes-sin-cobrador + detalle-cliente 2. msv-kude: template hoja de ruta 3. Frontend: HojaRutaTab en Finanzas 4. Frontend: tarjeta expandible en Panel Cobrador