Payment order platform - v0 by Vercel

Aquí están las tareas formateadas como tickets de Jira: --- ## EPIC: GEST-001 - Sistema de Gestión de Pedidos de Pago **Descripción:** Desarrollo del módulo de gestión de pedidos de pago para facturas por pagar, incluyendo selección de facturas, generación de pedidos y consulta de órdenes de pago emitidas. --- ### GEST-002 | Backend | Diseño y creación de modelo de datos **Tipo:** Tarea Técnica **Componente:** Backend / Base de Datos **Prioridad:** Highest **Story Points:** 5 **Descripción:** Diseñar e implementar el modelo de datos necesario para soportar el módulo de gestión de pedidos de pago. **Tareas:** - Crear tabla `clientes` (id, codigo, razon_social, cuit, direccion, activo, timestamps) - Crear tabla `cuentas_bancarias` (id, cliente_id, banco, tipo_cuenta, cbu, alias, moneda, activo) - Crear tabla `facturas` (id, numero_factura, cliente_id, producto, cosecha, contrato, monto, fecha_emision, fecha_vencimiento, status) - Crear tabla `pedidos_pago` (id, numero_pedido, cliente_id, metodo_pago, cuenta_bancaria_id, monto_total, descontar_gastos, para_cobrar_insumos, observaciones, status, fecha_pedido, usuario_creacion) - Crear tabla `pedidos_pago_detalle` (id, pedido_pago_id, factura_id, monto_factura, monto_a_pagar) - Crear tabla `facturas_gestion` (id, factura_id, pedido_pago_id, metodo_pago, monto_pedido, observaciones, fecha_gestion, usuario) - Crear tabla `ordenes_pago` (estructura según sistema contable existente) - Crear índices de performance en campos de búsqueda frecuente - Crear foreign keys y constraints necesarios **Criterios de Aceptación:** - [ ] Todas las tablas creadas en ambiente de desarrollo - [ ] Foreign keys implementadas correctamente - [ ] Índices creados en: facturas.status, facturas.cliente_id, facturas.fecha_emision, pedidos_pago.cliente_id, pedidos_pago.fecha_pedido - [ ] Script de migración documentado y versionado - [ ] Datos de prueba insertados para testing **Notas Técnicas:** - Status de facturas: 'pendiente', 'tomado', 'pagado' - Status de pedidos: 'pendiente', 'procesado', 'anulado' - Métodos de pago: 'transferencia', 'cheque', 'echeq', 'cuenta' - Monedas: 'ARS', 'USD' --- ### GEST-003 | Backend | API Listar Facturas con Filtros **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Highest **Story Points:** 3 **Descripción:** Como usuario del sistema, necesito consultar el listado de facturas con filtros y paginación para visualizar las facturas pendientes de pago. **Endpoint:** `GET /api/facturas` **Parámetros Query:** | Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | status | string | No | Filtro: pendiente, tomado, pagado, todos | | cliente_id | int | No | Filtro por cliente | | search | string | No | Búsqueda en cliente, producto, contrato | | fecha_desde | date | No | Filtro fecha emisión desde | | fecha_hasta | date | No | Filtro fecha emisión hasta | | page | int | No | Página (default: 1) | | limit | int | No | Registros por página (default: 50) | **Response esperado:** ```json { "data": [{ "id": "FAC-001", "cliente": "Agrícola San Martín S.A.", "clienteId": 1, "producto": "Soja", "cosecha": "2024/25", "contrato": "CT-2024-0156", "monto": 125000.00, "fechaEmision": "2024-11-15", "fechaVencimiento": "2025-01-15", "status": "pendiente", "metodoPago": null, "montoPedido": null, "fechaGestion": null, "observaciones": null }], "pagination": { "page": 1, "limit": 50, "total": 150, "totalPages": 3 }, "summary": { "totalPendientes": 85, "montoPendiente": 4500000.00, "totalTomados": 45, "montoTomado": 2100000.00, "totalPagados": 20, "montoPagado": 980000.00 } } ``` **Criterios de Aceptación:** - [ ] Endpoint responde con listado de facturas - [ ] Filtro por status funciona correctamente - [ ] Filtro por cliente_id funciona correctamente - [ ] Búsqueda por texto funciona en cliente, producto y contrato - [ ] Filtros de fecha funcionan correctamente - [ ] Paginación implementada y funcionando - [ ] Summary con totales por estado incluido en response - [ ] JOIN con tabla facturas_gestion para datos de gestión - [ ] Ordenamiento por fecha_emision DESC por defecto - [ ] Tiempo de respuesta < 500ms **Notas Técnicas:** - Realizar LEFT JOIN con facturas_gestion para obtener datos de gestión - Implementar búsqueda con LIKE case-insensitive - Validar parámetros de entrada --- ### GEST-004 | Backend | API Obtener Detalle de Factura **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** High **Story Points:** 2 **Descripción:** Como usuario del sistema, necesito consultar el detalle completo de una factura incluyendo información de gestión si existe. **Endpoint:** `GET /api/facturas/:id` **Parámetros Path:** | Parámetro | Tipo | Descripción | |-----------|------|-------------| | id | int | ID de la factura | **Response esperado:** ```json { "data": { "id": 1, "numeroFactura": "FAC-001", "cliente": { "id": 1, "razonSocial": "Agrícola San Martín S.A.", "cuit": "30-12345678-9" }, "producto": "Soja", "cosecha": "2024/25", "contrato": "CT-2024-0156", "monto": 125000.00, "fechaEmision": "2024-11-15", "fechaVencimiento": "2025-01-15", "status": "tomado", "gestion": { "metodoPago": "transferencia", "montoPedido": 100000.00, "fechaGestion": "2024-12-10T14:30:00", "observaciones": "Pago parcial", "numeroPedido": "PP-20241210-0005" } } } ``` **Criterios de Aceptación:** - [ ] Endpoint responde con detalle de factura - [ ] Incluye datos del cliente (razon_social, cuit) - [ ] Incluye datos de gestión si existen (LEFT JOIN) - [ ] Incluye número de pedido de pago asociado - [ ] Retorna 404 si factura no existe - [ ] Tiempo de respuesta < 200ms --- ### GEST-005 | Backend | API Listar Cuentas Bancarias por Cliente **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Highest **Story Points:** 2 **Descripción:** Como usuario del sistema, al seleccionar transferencia bancaria como método de pago, necesito ver las cuentas bancarias disponibles del cliente para seleccionar una. **Endpoint:** `GET /api/clientes/:clienteId/cuentas-bancarias` **Parámetros Path:** | Parámetro | Tipo | Descripción | |-----------|------|-------------| | clienteId | int | ID del cliente | **Response esperado:** ```json { "data": [ { "id": 1, "banco": "Banco Nación", "tipoCuenta": "Cuenta Corriente", "cbu": "0110012345678901234567", "alias": "AGRICOLA.SANMARTIN.BNA", "moneda": "ARS" }, { "id": 2, "banco": "Banco Galicia", "tipoCuenta": "Caja de Ahorro", "cbu": "0070012345678901234567", "alias": "AGRICOLA.SM.USD", "moneda": "USD" } ] } ``` **Criterios de Aceptación:** - [ ] Endpoint responde con listado de cuentas bancarias del cliente - [ ] Solo retorna cuentas con activo = 1 - [ ] Ordenado por banco, tipo_cuenta - [ ] Retorna array vacío si cliente no tiene cuentas - [ ] Retorna 404 si cliente no existe - [ ] Tiempo de respuesta < 200ms --- ### GEST-006 | Backend | API Crear Pedido de Pago **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Highest **Story Points:** 8 **Descripción:** Como usuario del sistema, necesito crear un pedido de pago seleccionando facturas de un mismo cliente, método de pago y monto a pagar para iniciar el proceso de pago. **Endpoint:** `POST /api/pedidos-pago` **Request Body:** ```json { "clienteId": 1, "metodoPago": "transferencia", "cuentaBancariaId": 2, "montoTotal": 125000.00, "descontarGastos": true, "paraCobrarInsumos": false, "observaciones": "Pago parcial según acuerdo", "facturas": [ { "facturaId": 1, "montoFactura": 125000.00, "montoAPagar": 100000.00 }, { "facturaId": 5, "montoFactura": 92150.00, "montoAPagar": 25000.00 } ] } ``` **Response esperado (201):** ```json { "success": true, "data": { "id": 45, "numeroPedido": "PP-20241215-0012", "clienteId": 1, "cliente": "Agrícola San Martín S.A.", "metodoPago": "transferencia", "cuentaBancaria": { "banco": "Banco Galicia", "cbu": "0070012345678901234567" }, "montoTotal": 125000.00, "cantidadFacturas": 2, "fechaPedido": "2024-12-15T14:30:00" } } ``` **Validaciones de Negocio:** 1. Todas las facturas deben pertenecer al mismo clienteId enviado 2. Todas las facturas deben tener status = 'pendiente' 3. Si metodoPago = 'transferencia', cuentaBancariaId es obligatorio 4. La cuenta bancaria debe pertenecer al cliente 5. montoAPagar no puede ser mayor a montoFactura en cada factura 6. La suma de montoAPagar debe coincidir con montoTotal 7. Al menos una factura debe ser incluida **Operaciones Transaccionales:** 1. Generar número de pedido único (PP-YYYYMMDD-XXXX) 2. Insertar registro en `pedidos_pago` 3. Insertar registros en `pedidos_pago_detalle` por cada factura 4. Actualizar status de facturas a 'tomado' 5. Insertar registros en `facturas_gestion` por cada factura **Criterios de Aceptación:** - [ ] Endpoint crea pedido de pago correctamente - [ ] Número de pedido se genera automáticamente con formato PP-YYYYMMDD-XXXX - [ ] Valida que todas las facturas pertenecen al mismo cliente - [ ] Valida que todas las facturas tienen status 'pendiente' - [ ] Valida cuenta bancaria obligatoria si método es transferencia - [ ] Valida que montoAPagar <= montoFactura - [ ] Valida que suma de montoAPagar = montoTotal - [ ] Actualiza status de facturas a 'tomado' - [ ] Registra gestión en tabla facturas_gestion - [ ] Toda la operación es transaccional (rollback si falla) - [ ] Retorna 400 con mensaje descriptivo si validación falla - [ ] Registra usuario que crea el pedido - [ ] Tiempo de respuesta < 1000ms **Errores esperados:** ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Las facturas seleccionadas no pertenecen al mismo cliente", "details": [ { "facturaId": 5, "clienteId": 2, "clienteEsperado": 1 } ] } } ``` --- ### GEST-007 | Backend | API Listar Pedidos de Pago **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Medium **Story Points:** 3 **Descripción:** Como usuario del sistema, necesito consultar el listado de pedidos de pago generados para dar seguimiento a los mismos. **Endpoint:** `GET /api/pedidos-pago` **Parámetros Query:** | Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | status | string | No | pendiente, procesado, anulado | | cliente_id | int | No | Filtro por cliente | | metodo_pago | string | No | transferencia, cheque, echeq, cuenta | | fecha_desde | date | No | Desde fecha pedido | | fecha_hasta | date | No | Hasta fecha pedido | | page | int | No | Página (default: 1) | | limit | int | No | Registros por página (default: 50) | **Criterios de Aceptación:** - [ ] Endpoint responde con listado de pedidos de pago - [ ] Todos los filtros funcionan correctamente - [ ] Incluye datos del cliente en cada registro - [ ] Incluye cantidad de facturas asociadas - [ ] Paginación implementada - [ ] Ordenado por fecha_pedido DESC --- ### GEST-008 | Backend | API Detalle de Pedido de Pago **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Medium **Story Points:** 2 **Descripción:** Como usuario del sistema, necesito ver el detalle completo de un pedido de pago incluyendo todas las facturas asociadas. **Endpoint:** `GET /api/pedidos-pago/:id` **Response esperado:** ```json { "data": { "id": 45, "numeroPedido": "PP-20241215-0012", "cliente": { "id": 1, "razonSocial": "Agrícola San Martín S.A." }, "metodoPago": "transferencia", "cuentaBancaria": { "banco": "Banco Galicia", "tipoCuenta": "Caja de Ahorro", "cbu": "0070012345678901234567", "alias": "AGRICOLA.SM.USD", "moneda": "USD" }, "montoTotal": 125000.00, "descontarGastos": true, "paraCobrarInsumos": false, "observaciones": "Pago parcial según acuerdo", "status": "pendiente", "fechaPedido": "2024-12-15T14:30:00", "usuarioCreacion": "jperez", "facturas": [ { "facturaId": 1, "numeroFactura": "FAC-001", "producto": "Soja", "cosecha": "2024/25", "contrato": "CT-2024-0156", "fechaEmision": "2024-11-15", "fechaVencimiento": "2025-01-15", "montoFactura": 125000.00, "montoAPagar": 100000.00 } ] } } ``` **Criterios de Aceptación:** - [ ] Endpoint responde con detalle completo del pedido - [ ] Incluye datos del cliente - [ ] Incluye datos de cuenta bancaria si aplica - [ ] Incluye listado de facturas con detalle - [ ] Retorna 404 si pedido no existe --- ### GEST-009 | Backend | API Listar Órdenes de Pago Emitidas **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** High **Story Points:** 3 **Descripción:** Como usuario del sistema, necesito consultar las órdenes de pago emitidas (importadas del sistema contable) para verificar los pagos realizados. **Endpoint:** `GET /api/ordenes-pago` **Parámetros Query:** | Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | search | string | No | Búsqueda en N° doc, operación, proveedor | | fecha_desde | date | No | Desde fecha contabilización | | fecha_hasta | date | No | Hasta fecha contabilización | | metodo_pago | string | No | efectivo, cheques, transferencia, tarjeta | | page | int | No | Página (default: 1) | | limit | int | No | Registros por página (default: 50) | **Response esperado:** ```json { "data": [{ "id": 1, "numeroDocumento": "OP-2024-001234", "numeroOperacion": "TRF-98765", "fechaContabilizacion": "2024-12-10", "codigoProveedor": "P001", "nombreProveedor": "Agrícola San Martín S.A.", "efectivo": 0, "cheques": 0, "transferencia": 125000.00, "tarjeta": 0, "importeRetencion": 5000.00, "tipoCambio": 1, "total": 120000.00, "totalDocumento": 125000.00, "metodoPrincipal": "transferencia" }], "pagination": {...}, "summary": { "totalOrdenes": 35, "montoTotal": 15840000.00, "totalEfectivo": 450000.00, "totalCheques": 2100000.00, "totalTransferencias": 12500000.00, "totalTarjeta": 150000.00, "totalRetenciones": 640000.00 } } ``` **Criterios de Aceptación:** - [ ] Endpoint responde con listado de órdenes de pago - [ ] Búsqueda funciona en número documento, operación y proveedor - [ ] Filtros de fecha funcionan correctamente - [ ] Filtro por método de pago funciona (busca en columna correspondiente > 0) - [ ] Campo metodoPrincipal calculado según prioridad: transferencia > cheques > efectivo > tarjeta - [ ] Summary con totales por método incluido - [ ] Paginación implementada - [ ] Ordenado por fecha_contabilizacion DESC --- ### GEST-010 | Backend | API Detalle de Orden de Pago **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Medium **Story Points:** 1 **Descripción:** Como usuario del sistema, necesito ver el detalle completo de una orden de pago emitida. **Endpoint:** `GET /api/ordenes-pago/:id` **Criterios de Aceptación:** - [ ] Endpoint responde con detalle completo de la orden - [ ] Incluye todos los campos de la orden - [ ] Retorna 404 si orden no existe --- ### GEST-011 | Backend | API Exportar Facturas **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Medium **Story Points:** 3 **Descripción:** Como usuario del sistema, necesito exportar el listado de facturas a CSV o Excel para utilizar en procesos externos. **Endpoint:** `GET /api/facturas/export` **Parámetros Query:** | Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | format | string | Sí | csv o xlsx | | status | string | No | Filtro por estado | | cliente_id | int | No | Filtro por cliente | | ids | string | No | Lista de IDs separados por coma | **Criterios de Aceptación:** - [ ] Endpoint genera archivo CSV correctamente - [ ] Endpoint genera archivo XLSX correctamente - [ ] Headers de respuesta configurados para descarga - [ ] Nombre de archivo incluye fecha: facturas_YYYYMMDD.csv/xlsx - [ ] Filtros aplicados al export - [ ] Incluye todos los campos relevantes - [ ] Encoding UTF-8 para caracteres especiales - [ ] Separador punto y coma para CSV (compatibilidad Excel español) --- ### GEST-012 | Backend | API Exportar Órdenes de Pago **Tipo:** Historia de Usuario **Componente:** Backend / API **Prioridad:** Medium **Story Points:** 2 **Descripción:** Como usuario del sistema, necesito exportar el listado de órdenes de pago a CSV o Excel. **Endpoint:** `GET /api/ordenes-pago/export` **Criterios de Aceptación:** - [ ] Endpoint genera archivo CSV correctamente - [ ] Endpoint genera archivo XLSX correctamente - [ ] Headers de respuesta configurados para descarga - [ ] Incluye todos los campos relevantes - [ ] Encoding UTF-8 --- ### GEST-013 | Backend | Seguridad y Auditoría **Tipo:** Tarea Técnica **Componente:** Backend / Seguridad **Prioridad:** High **Story Points:** 3 **Descripción:** Implementar capa de seguridad y auditoría en todos los endpoints del módulo. **Tareas:** - Implementar autenticación JWT en todos los endpoints - Validar permisos por rol de usuario - Sanitizar todos los inputs para prevenir SQL injection - Implementar logs de auditoría en operaciones de escritura - Configurar rate limiting **Criterios de Aceptación:** - [ ] Todos los endpoints requieren token JWT válido - [ ] Endpoints de escritura validan permisos de usuario - [ ] Inputs sanitizados con parametrización de queries - [ ] Log de auditoría registra: usuario, acción, timestamp, datos anteriores/nuevos - [ ] Rate limiting configurado (100 req/min por usuario) - [ ] Respuesta 401 si token inválido/expirado - [ ] Respuesta 403 si usuario sin permisos --- ### GEST-014 | Backend | Tests Unitarios e Integración **Tipo:** Tarea Técnica **Componente:** Backend / Testing **Prioridad:** High **Story Points:** 5 **Descripción:** Desarrollar suite de tests para el módulo de gestión de pagos. **Tareas:** - Tests unitarios para validaciones de negocio - Tests de integración para cada endpoint - Tests de transacciones (rollback en error) - Mocks de base de datos **Criterios de Aceptación:** - [ ] Cobertura mínima 80% en lógica de negocio - [ ] Tests para todos los endpoints (happy path + error cases) - [ ] Test de transacción verifica rollback en error - [ ] Tests ejecutables en CI/CD pipeline - [ ] Documentación de casos de prueba --- ### GEST-015 | Backend | Integración con Sistema Contable **Tipo:** Spike / Investigación **Componente:** Backend / Integración **Prioridad:** Medium **Story Points:** 3 **Descripción:** Investigar y documentar la integración con el sistema contable existente para importación de órdenes de pago emitidas. **Tareas:** - Definir mecanismo de importación de OP (API, archivo, BD compartida) - Definir formato de datos de OP - Definir frecuencia de sincronización - Definir mapeo de campos - Documentar proceso de integración **Criterios de Aceptación:** - [ ] Documento técnico de integración elaborado - [ ] Formato de intercambio definido - [ ] Mapeo de campos documentado - [ ] Proceso de sincronización diseñado - [ ] Estimación de desarrollo de integración --- ## Resumen de Story Points | Ticket | Descripción | SP | |--------|-------------|---:| | GEST-002 | Modelo de datos | 5 | | GEST-003 | API Listar Facturas | 3 | | GEST-004 | API Detalle Factura | 2 | | GEST-005 | API Cuentas Bancarias | 2 | | GEST-006 | API Crear Pedido Pago | 8 | | GEST-007 | API Listar Pedidos | 3 | | GEST-008 | API Detalle Pedido | 2 | | GEST-009 | API Listar OP | 3 | | GEST-010 | API Detalle OP | 1 | | GEST-011 | API Export Facturas | 3 | | GEST-012 | API Export OP | 2 | | GEST-013 | Seguridad y Auditoría | 3 | | GEST-014 | Tests | 5 | | GEST-015 | Spike Integración | 3 | | **TOTAL** | | **45** | --- **Dependencias sugeridas:** - GEST-002 (Modelo) debe completarse primero - GEST-003, GEST-004, GEST-005 pueden desarrollarse en paralelo después de GEST-002 - GEST-006 depende de GEST-003 y GEST-005 - GEST-013 puede desarrollarse en paralelo - GEST-014 al final de cada endpoint