# Manual de Desarrollador — Tienda Online Backend + Frontend

## 1) Stack tecnológico

## Backend

- Node.js + Express
- Sequelize ORM
- PostgreSQL
- JWT Auth
- Stripe SDK
- PayPal Checkout Server SDK

## Frontend

- React + Vite
- Axios
- Stripe Elements (`@stripe/react-stripe-js`, `@stripe/stripe-js`)

---

## 2) Estructura principal del proyecto

- `src/server.js`: arranque de API, middlewares, rutas.
- `src/controllers/*`: lógica de negocio.
- `src/routes/*`: definición de endpoints.
- `src/models/*`: modelos Sequelize (convención en español).
- `config/config.json`: configuración de Sequelize CLI.
- `migrations/`, `seeders/`: evolución de BD.
- `frontend/src/*`: cliente React.

> Existe una carpeta duplicada `tienda-online-backend/` con contenido muy similar. Para evitar inconsistencias, trabajar sobre una sola raíz canónica.

---

## 3) Configuración local

## 3.1 Variables de entorno (backend)

Archivo `.env` (ejemplo):

- `PORT`
- `NODE_ENV`
- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
- `JWT_SECRET`, `JWT_EXPIRES_IN`
- `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`
- `PAYPAL_MODE` o `PAYPAL_ENVIRONMENT` (ver nota importante abajo)
- `STRIPE_SECRET_KEY`
- `FRONTEND_URL`, `CORS_ORIGIN`
- `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_DEFAULT_MESSAGE`

## 3.2 Variables de entorno (frontend)

Archivo `frontend/.env`:

- `VITE_STRIPE_PUBLIC_KEY`

---

## 4) Comandos de desarrollo

## Backend

- Instalar: `npm install`
- Ejecutar: `npm run dev` (nodemon) o `npm start`
- Migrar: `npm run migrate`
- Sembrar datos: `npm run seed`
- Reset BD: `npm run db:reset`

## Frontend

- Instalar: `cd frontend && npm install`
- Desarrollo: `npm run dev`
- Build: `npm run build`

---

## 5) Endpoints relevantes

## Salud

- `GET /api/health`

## Auth

- `POST /api/auth/register`
- `POST /api/auth/login`
- `GET /api/auth/profile`

## Productos

- `GET /api/products`
- `GET /api/products/:id`
- `POST /api/products` (admin)
- `PUT /api/products/:id` (admin)
- `DELETE /api/products/:id` (admin)

## Carrito

- `GET /api/cart`
- `POST /api/cart`
- `PUT /api/cart/item/:id_item`
- `DELETE /api/cart/item/:id_item`
- `DELETE /api/cart/clear`
- `GET /api/cart/check-stock`
- `GET /api/cart/summary`

## Pedidos

- `POST /api/orders`
- `GET /api/orders`
- `GET /api/orders/:id`
- `PUT /api/orders/:id/cancel`
- `PUT /api/orders/:id/shipping`

## Pagos

### Stripe

- `POST /api/stripe/create-payment-intent`
- `POST /api/stripe/create-checkout-session`

### PayPal (ruta principal usada por frontend API client)

- `POST /api/paypal/create-order`
- `POST /api/paypal/capture-order`
- `GET /api/paypal/order/:orderId`
- `GET /api/paypal/history`
- `POST /api/paypal/webhook`

### PayPal (ruta alternativa)

- `POST /api/payments/paypal/create`
- `POST /api/payments/paypal/capture`

---

## 6) Flujo de pagos actual (observado en código)

## 6.1 Checkout de carrito con Stripe

1. Frontend solicita `create-payment-intent`.
2. Stripe Elements confirma pago en cliente.
3. Frontend crea pedido (`POST /api/orders`) con `metodo_pago: 'stripe'`.

## 6.2 Contratación de servicios en Home

1. Frontend llama `create-checkout-session` con nombre/precio.
2. Backend devuelve URL de Stripe Checkout.
3. Frontend redirige al usuario a Stripe.

## 6.3 PayPal

- Backend implementa creación/captura y webhook.
- En frontend hay cliente `paypalAPI`, pero no se observó pantalla de checkout PayPal en páginas actuales.

---

## 7) Dictamen técnico sobre la pasarela de pago

## Estado: **No se puede considerar “correctamente operativa” en su estado actual**

Razones verificadas:

1. **Bloqueo de infraestructura local**
   - El backend no logra conectar a PostgreSQL en `localhost:5433` (`ECONNREFUSED`).
   - Sin BD operativa no hay validación end-to-end del checkout.

2. **Incompatibilidad Stripe ↔ modelo de pagos**
   - Frontend envía `metodo_pago: 'stripe'` al crear pedido.
   - Modelo `Payment.metodo` solo acepta `PayPal`, `Tarjeta`, `Transferencia`.
   - Riesgo: error al persistir pago/pedido tras cobro exitoso.

3. **Desalineación de variables PayPal**
   - Parte del código usa `PAYPAL_MODE` y otra `PAYPAL_ENVIRONMENT`.
   - Puede causar selección incorrecta de entorno (sandbox/live), especialmente en producción.

4. **Webhook sin verificación criptográfica**
   - Existe endpoint `/api/paypal/webhook`, pero no se observó verificación de firma.
   - Riesgo de eventos no autenticados.

5. **Persistencia de pago Stripe incompleta**
   - No hay reconciliación robusta por webhook de Stripe para actualizar pedido/pago de forma autoritativa.
   - Se depende de flujo cliente → crear pedido después del `succeeded`.

6. **Cobertura de pruebas insuficiente para pagos**
   - Scripts actuales prueban salud/rutas básicas y flujo general, pero no validan Stripe/PayPal de forma integral con BD real.

---

## 8) Recomendaciones prioritarias

## Prioridad alta (P0)

1. Levantar PostgreSQL accesible en el puerto configurado o ajustar `DB_PORT`.
2. Normalizar método de pago para Stripe:
   - opción A: guardar `metodo_pago: 'Tarjeta'` y mapear Stripe internamente,
   - opción B: ampliar ENUM para incluir `Stripe`.
3. Unificar variable de entorno de PayPal en todo el código (elegir una sola: `PAYPAL_MODE` o `PAYPAL_ENVIRONMENT`).
4. Implementar validación de firma en webhooks (PayPal y Stripe si se agrega).

## Prioridad media (P1)

1. Registrar `paymentIntentId`/`checkoutSessionId` y vincularlos al pedido.
2. Confirmar pago servidor-servidor (webhook) antes de marcar orden como pagada.
3. Consolidar rutas duplicadas (`/api/paypal` vs `/api/payments/paypal/*`).
4. Agregar pruebas automáticas E2E de pagos en sandbox.

## Prioridad baja (P2)

1. Revisar coherencia de estados de pedido entre modelo/controlador/migraciones.
2. Eliminar carpeta duplicada `tienda-online-backend/` o dejarla explícitamente como snapshot.

---

## 9) Plan sugerido de validación (QA de pagos)

## Prueba Stripe (sandbox)

1. Crear usuario y carrito con productos válidos.
2. Ejecutar checkout con tarjeta de prueba Stripe.
3. Verificar:
   - transacción en dashboard Stripe,
   - pedido creado,
   - registro en tabla de pagos,
   - estado de pedido actualizado.

## Prueba PayPal (sandbox)

1. Crear pedido `pendiente`.
2. Crear orden PayPal desde API.
3. Aprobar y capturar.
4. Verificar:
   - registro de `transaction_id`,
   - cambio de estado pago/orden,
   - recepción y validación de webhook.

---

## 10) Observabilidad y soporte técnico

- Logs con Winston en `logs/error.log` y `logs/combined.log`.
- Para incidencias de pago, registrar:
  - usuario,
  - ID de pedido,
  - ID de transacción Stripe/PayPal,
  - timestamp,
  - endpoint y payload sanitizado.

---

## 11) Criterio de “pasarela OK” para producción

Se considera lista cuando cumple todo:

- DB estable y conectada.
- Flujo checkout exitoso en sandbox y producción.
- Reconciliación por webhook con verificación de firma.
- Persistencia consistente de pagos y pedidos.
- Reintentos idempotentes y manejo de fallos transitorios.
- Monitoreo/alertas para pagos fallidos y discrepancias.