Sistema de Cobranza de SEDAPAL

Sistema de Cobranza de SEDAPAL

Documentacio´n T´ecnica de Implementacio´n

Calidad de Software 11 de noviembre de 2025

1. Resumen Ejecutivo

El Sistema de Cobranza de SEDAPAL (SCS) es una aplicaci´on full-stack disen˜ada para gestionar el ciclo completo de facturaci´on, pagos, morosidad y atenci´on al cliente del servicio de agua potable. El sistema implementa 22 historias de usuario distribuidas en 5 m´odulos funcionales: Pagos (6 HU), Autenticaci´on (6 HU), Morosidad (7 HU), Integraci´on (2 HU) y Administraci´on (1 HU).

1. Tecnolog´ıas Implementadas

[pic 1] Backend: Node.js 18+, Express.js 4.18, TypeScript 5.3, Prisma ORM 5.22

[pic 2] Frontend: React 18, Vite, TypeScript, TailwindCSS, Zustand

[pic 3] Base de Datos: PostgreSQL 17 (19 tablas)

[pic 4] Seguridad: JWT, bcrypt, Helmet, validaci´on con express-validator

[pic 5] Pagos: Stripe (modo test), arquitectura de adaptadores para mu´ltiples pasarelas

[pic 6] Procesos Batch: node-cron para tareas programadas

1. Estado del Proyecto

[pic 7] Funcionalidad: 22/22 historias de usuario implementadas (100 % verificado)

[pic 8] Cobertura de Pruebas: 8/8 tests automatizados aprobados (verificado)

[pic 9] Despliegue: Producci´on en Render.com (backend, frontend, base de datos)

[pic 10] Nota: Los indicadores de calidad incluyen tanto m´etricas verificadas en c´odigo como objetivos propuestos

1. Casos de Uso Implementados

1. M´odulo de Pagos (HU-PAG)

1. HU-PAG-001: Consulta de Facturas Pendientes

Implementaci´on: src/routes/invoices.ts:12-43, src/services/invoiceService.ts:15-42

El cliente autenticado obtiene sus facturas mediante JWT en el header Authorization. El sistema extrae el userId, busca el cliente asociado y filtra facturas por estado:

router.get(’/’, authenticateToken, async (req, res) => {

const customerId = await getCustomerIdByUserId(req.user!.userId); const invoices = await prisma.invoice.findMany({

where: { customerId, status: { in: [’PENDIENTE’, ’VENCIDO’] } }, orderBy: { issueDate: ’desc’ }

});

return res.json(invoices);

});

Validaciones: Autenticaci´on obligatoria, paginaci´on configurable, filtrado por estado.

1. HU-PAG-002: Pago con Tarjeta de Cr´edito/D´ebito

Implementaci´on: src/routes/payments.ts:28-91, src/services/stripeAdapter.ts:42-118

Utiliza el patr´on Adapter para abstraer la integraci´on con Stripe. El flujo completo incluye:

1. Validaci´on de monto y factura (express-validator)
2. Creaci´on de PaymentIntent en Stripe
3. Confirmaci´on de pago con m´etodo tokenizado
4. Actualizaci´on transaccional de estado de factura
5. Registro de auditor´ıa

const paymentIntent = await stripe.paymentIntents.create({ amount: Math.round(amount * 100),

currency: ’pen’,

payment_method: paymentMethodToken, confirm: true,

metadata: { invoiceId, customerId }

});

Seguridad: Tokenizaci´on PCI DSS compliant, no se almacenan datos de tarjetas reales.

1. HU-PAG-003: Pago con Yape/Plin

Implementaci´on: src/services/yapeAdapter.ts, src/services/plinAdapter.ts

Simulaci´on de integraci´on con APIs de billeteras digitales mediante adaptadores espec´ıficos. En producci´on se reemplazar´ıan con credenciales reales.

1. HU-PAG-004: Historial de Pagos Implementaci´on: src/routes/payments.ts:15-26

Consulta con JOIN entre Payment, Invoice y Customer para obtener detalles completos. Incluye filtros por rango de fechas y m´etodo de pago.

1. HU-PAG-005: Descarga de Comprobante Implementaci´on: src/routes/payments.ts:93-112

Generaci´on de PDF mediante metadata en JSON. En producci´on se integrar´ıa con biblioteca de generaci´on de PDFs (pdfkit/puppeteer).

1. HU-PAG-006: Pago Autom´atico

Implementaci´on: src/services/autoPaymentService.ts:12-85, src/jobs/autoPaymentJob.ts

Proceso batch diario (cron: 0 2 * * *) que:

1. Identifica clientes con autopago activo
2. Busca facturas pr´oximas a vencer (3 d´ıas antes)
3. Ejecuta cargo autom´atico con m´etodo de pago guardado
4. Env´ıa notificaci´on de resultado

1. M´odulo de Autenticaci´on (HU-AUT)

1. HU-AUT-001: Registro de Cliente

Implementaci´on: src/routes/auth.ts:24-87, backend/prisma/schema.prisma:24-40

Registro con validaci´on de email u´nico, hash de contrasen˜a (bcrypt rounds=10), creaci´on transac- cional de User y Customer:

const hashedPassword = await bcrypt.hash(password, 10); const user = await prisma.user.create({

data: {

email, password: hashedPassword, role: ’CLIENTE’, customer: {

create: { firstName, lastName, documentType, documentNumber, phone, address, district }

}

}

});

Validaciones: Email u´nico, DNI/RUC v´alido (8/11 d´ıgitos), contrasen˜a segura (m´ın. 8 caracteres).

1. HU-AUT-002: Inicio de Sesi´on Implementaci´on: src/routes/auth.ts:89-128

Autenticaci´on con JWT (expiraci´on: 7 d´ıas), comparaci´on segura con bcrypt, generaci´on de token con payload userId/role:

const isValid = await bcrypt.compare(password, user.password); const token = jwt.sign({ userId: user.id, role: user.role },