Skip to content

Alcance por microservicio y proyecto base de pagatu-orden-ms y pagatu-cliente-ms

Crear el proyecto base de pagatu-orden-ms

Tabla 1. Configuración del proyecto pagatu-orden-ms en Spring Initializr

Campo Valor
Project Maven Project
Spring Boot 4.1.1
Language Java
Group Id pe.edu.upeu
Artifact Id pagatu-orden-ms
Package name pe.edu.upeu.orden
Packaging Jar
Java 21
Dependencias Las mismas de pagatu-catalogo-ms (S1, Tabla 4): Spring Web, Validation, Lombok, Spring Boot DevTools, SpringDoc OpenAPI WebMvc UI, Spring Boot Actuator, Spring Data JPA, PostgreSQL Driver, Flyway. Agrega también Prometheus (categoría Observability, la ofrece el propio buscador de Spring Initializr — agrega io.micrometer:micrometer-registry-prometheus, scope runtime): si ya tienes obs/ corriendo (Prometheus descubre por Eureka, S3 3.11), el microservicio nuevo queda visible ahí desde que arranca, sin ningún paso adicional. Además, agrega MapStruct a mano en el pom.xml (S1, 3.5.20) — a diferencia de Prometheus, Spring Initializr no lo ofrece como opción, y sin él el proyecto no compila apenas escribas el primer Mapper.
Ubicación sugerente services/pagatu-orden-ms

El puerto de base de datos (15434 DEV / 25434 PROD local) sigue la misma numeración ya reservada para orden_db en la arquitectura del proyecto (docs/index.md), distinta de pagatu_catalogo_db (15432/25432) para que ambos puedan correr al mismo tiempo. El puerto de aplicación en DEV (8082, fijo) sigue el mismo criterio de S1 (puerto fijo, sin argumento) — distinto de 8080, que ya usa pagatu-catalogo-ms.

Puertos de base de datos y de infraestructura (154xx/254xx, 18xxx/28xxx) son exclusivos de pagatu — ningún otro repo del alumno (BomERP/LP2, lambda26/BigData) usa esos rangos, así que no chocan aunque corran al mismo tiempo. Los puertos de aplicación (8080-808x, sin prefijo) sí son un riesgo real: pagatu-catalogo-ms corre en 8080 igual que el backend de BomERP/LP2 (que además usa 8081 para su segunda instancia) — si ambos proyectos corren a la vez en la misma máquina, chocan. Lo mismo va a pasar con el puerto por defecto de Angular (4200) el día que exista pagatu-ng (S11), porque el frontend de LP2 también lo usa. No es un bug que corregir ahora — es una razón concreta para no levantar pagatu y BomERP/LP2 al mismo tiempo en la misma laptop, o para detener uno antes de levantar el otro.

services/pagatu-orden-ms/compose-dev.yml

name: pagatu-orden-dev

services:
  postgres-orden-dev:
    image: postgres:16-alpine
    container_name: pagatu-postgres-orden-dev
    restart: unless-stopped
    environment:
      POSTGRES_DB: pagatu_orden_db
      POSTGRES_USER: pagatu
      POSTGRES_PASSWORD: pagatu
    ports:
      - "15434:5432"
    volumes:
      - pagatu_orden_dev_data:/var/lib/postgresql/data

volumes:
  pagatu_orden_dev_data:

services/pagatu-orden-ms/src/main/resources/application.yml

spring:
  application:
    name: pagatu-orden-ms
  profiles:
    active: dev

services/pagatu-orden-ms/src/main/resources/application-dev.yml

server:
  port: 8082

spring:
  datasource:
    url: jdbc:postgresql://localhost:15434/pagatu_orden_db
    username: pagatu
    password: pagatu
    driver-class-name: org.postgresql.Driver
  flyway:
    enabled: true
    locations: classpath:db/migration
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
    properties:
      hibernate:
        format_sql: true
  devtools:
    restart:
      enabled: true
    livereload:
      enabled: true

springdoc:
  swagger-ui:
    path: /swagger-ui.html

logging:
  level:
    pe.edu.upeu.orden: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: always

services/pagatu-orden-ms/src/main/resources/db/migration/V1__create_orden_tables.sql

CREATE TABLE IF NOT EXISTS ordenes (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY,
    id_cliente BIGINT,
    nombre_cliente VARCHAR(150),
    direccion_cliente VARCHAR(200),
    fecha_creacion TIMESTAMP NOT NULL DEFAULT now(),
    estado VARCHAR(20) NOT NULL DEFAULT 'CARRITO',
    tipo_comprobante VARCHAR(20) NOT NULL DEFAULT 'BOLETA_SIMPLE',
    metodo_pago VARCHAR(20) NOT NULL,
    momento_pago VARCHAR(20) NOT NULL DEFAULT 'ADELANTADO',
    total NUMERIC(10,2),
    expira_en TIMESTAMP,
    PRIMARY KEY (id)
);

CREATE TABLE IF NOT EXISTS orden_detalles (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY,
    id_orden BIGINT NOT NULL REFERENCES ordenes(id),
    id_producto BIGINT NOT NULL,
    nombre_producto VARCHAR(150),
    cantidad INTEGER NOT NULL,
    precio_unitario NUMERIC(10,2),
    PRIMARY KEY (id)
);

id_orden sí es una llave foránea normal (REFERENCES ordenes(id)), porque ordenes y orden_detalles viven en la misma base de datos de pagatu-orden-ms. id_producto e id_cliente, en cambio, no llevan REFERENCES — el producto vive en la base de datos de pagatu-catalogo-ms y el cliente en la de pagatu-cliente-ms (otro microservicio, con su propia base de datos), cada uno un microservicio distinto; validar que existan es responsabilidad del código (una consulta HTTP al microservicio correspondiente), no de una llave foránea entre bases de datos separadas.

id_cliente es NULL-able, no obligatorio: mientras el único cliente sea el cliente de prueba (mostrador, sin autoservicio web), una orden puede registrarse sin identificar a nadie; recién cuando exista autoservicio real (S11) ese valor pasa a ser obligatorio en el punto donde el propio cliente autenticado crea su orden (razonamiento completo en S6, 3.3). nombre_cliente/direccion_cliente quedan declaradas desde ahora, por la misma razón que el resto de columnas de ordenes — una orden es un documento histórico —, pero no se llenan todavía: quedan en NULL hasta que pagatu-orden-ms consulte a pagatu-cliente-ms por Feign, el mismo patrón que ya copia nombre_producto/precio_unitario desde pagatu-catalogo-ms (S6, 3.12-3.13).

precio_unitario y nombre_producto en orden_detalles, igual que total en ordenes, aceptan NULL: una línea (o una orden completa) que no pudo validarse contra pagatu-catalogo-ms queda registrada de todas formas, sin esos datos confirmados, en vez de no registrarse en absoluto — el mismo criterio que protege el Circuit Breaker de S6 (3.3, 3.17). expira_en queda declarada para el futuro carrito con plazo de vencimiento (S6, 3.3-3.4), sin poblarse todavía ni tener un proceso que la revise — eso se retoma cuando exista autoservicio real (S11).

Crear el proyecto base de pagatu-cliente-ms

Tabla 2. Configuración del proyecto pagatu-cliente-ms en Spring Initializr

Campo Valor
Project Maven Project
Spring Boot 4.1.1
Language Java
Group Id pe.edu.upeu
Artifact Id pagatu-cliente-ms
Package name pe.edu.upeu.cliente
Packaging Jar
Java 21
Dependencias Las mismas de pagatu-catalogo-ms (S1, Tabla 4): Spring Web, Validation, Lombok, Spring Boot DevTools, SpringDoc OpenAPI WebMvc UI, Spring Boot Actuator, Spring Data JPA, PostgreSQL Driver, Flyway. Agrega también Prometheus (categoría Observability, la ofrece el propio buscador de Spring Initializr — agrega io.micrometer:micrometer-registry-prometheus, scope runtime): si ya tienes obs/ corriendo (Prometheus descubre por Eureka, S3 3.11), el microservicio nuevo queda visible ahí desde que arranca, sin ningún paso adicional. Además, agrega MapStruct a mano en el pom.xml (S1, 3.5.20) — a diferencia de Prometheus, Spring Initializr no lo ofrece como opción, y sin él el proyecto no compila apenas escribas el primer Mapper.
Ubicación sugerente services/pagatu-cliente-ms

El puerto de base de datos (15433 DEV / 25433 PROD local) es el que ya estaba reservado para cliente_db en la arquitectura del proyecto (docs/index.md) — el hueco entre auth_db (15431) y orden_db (15434). El puerto de aplicación en DEV es 8084, fijo, distinto de 8080 (pagatu-catalogo-ms) y 8082 (pagatu-orden-ms); se deja 8081 y 8083 sin usar, por si se necesitan para segundas instancias o para auth-ms.

services/pagatu-cliente-ms/compose-dev.yml

name: pagatu-cliente-dev

services:
  postgres-cliente-dev:
    image: postgres:16-alpine
    container_name: pagatu-postgres-cliente-dev
    restart: unless-stopped
    environment:
      POSTGRES_DB: pagatu_cliente_db
      POSTGRES_USER: pagatu
      POSTGRES_PASSWORD: pagatu
    ports:
      - "15433:5432"
    volumes:
      - pagatu_cliente_dev_data:/var/lib/postgresql/data

volumes:
  pagatu_cliente_dev_data:

services/pagatu-cliente-ms/src/main/resources/application.yml

spring:
  application:
    name: pagatu-cliente-ms
  profiles:
    active: dev

services/pagatu-cliente-ms/src/main/resources/application-dev.yml

server:
  port: 8084

spring:
  datasource:
    url: jdbc:postgresql://localhost:15433/pagatu_cliente_db
    username: pagatu
    password: pagatu
    driver-class-name: org.postgresql.Driver
  flyway:
    enabled: true
    locations: classpath:db/migration
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
    properties:
      hibernate:
        format_sql: true
  devtools:
    restart:
      enabled: true
    livereload:
      enabled: true

springdoc:
  swagger-ui:
    path: /swagger-ui.html

logging:
  level:
    pe.edu.upeu.cliente: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: always

services/pagatu-cliente-ms/src/main/resources/db/migration/V1__create_cliente_tables.sql

CREATE TABLE IF NOT EXISTS clientes (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY,
    tipo_persona VARCHAR(10) NOT NULL,
    dni VARCHAR(8),
    ruc VARCHAR(11),
    nombre_completo VARCHAR(150),
    razon_social VARCHAR(150),
    direccion VARCHAR(255),
    email VARCHAR(150),
    whatsapp VARCHAR(20),
    PRIMARY KEY (id),
    UNIQUE (dni),
    UNIQUE (ruc)
);

Una persona natural puede tener solo DNI, o DNI y RUC a la vez (un negocio unipersonal, por ejemplo un independiente que emite factura a su propio nombre) — por eso dni y ruc son dos columnas separadas y ambas opcionales, en vez del tipo_documento/numero_documento mutuamente excluyentes de una versión anterior. Una persona jurídica (empresa) solo tiene ruc y razon_social; no tiene dni propio (el DNI de su representante legal es otro dato, fuera de este alcance).

Tabla 3. Reglas de tipo_persona en clientes

tipo_persona Documentos Autocompletado Campo de nombre usado
NATURAL dni obligatorio; ruc opcional RENIEC (por dni); SUNAT (por ruc, si lo tiene) nombre_completo
JURIDICA ruc obligatorio; dni queda NULL SUNAT (por ruc) razon_social

whatsapp (opcional, no lo completa RENIEC/SUNAT — lo escribe el cliente) es el número al que se envía el comprobante de cada orden una vez confirmada; su uso real llega recién con la mensajería de S8, cuando orden-ms publique el evento correspondiente. ordenes.id_cliente apunta al id de esta tabla, sin REFERENCES entre bases de datos.

services/pagatu-cliente-ms/src/main/resources/db/migration/V2__seed_clientes.sql (opcional, datos de prueba)

Flyway también migra datos, no solo estructura — un archivo versionado más, con INSERT en vez de CREATE TABLE. Sirve para no estar registrando clientes a mano cada vez que reinicias la base de datos:

INSERT INTO clientes (tipo_persona, dni, ruc, nombre_completo, razon_social, direccion, email, whatsapp)
VALUES ('NATURAL', '87654321', NULL, 'Maria Torres Quispe', NULL, 'Av. Los Olivos 123, Lima', 'maria.torres@example.com', '999888777');

INSERT INTO clientes (tipo_persona, dni, ruc, nombre_completo, razon_social, direccion, email, whatsapp)
VALUES ('JURIDICA', NULL, '20123456789', NULL, 'Comercial Andina S.A.C.', 'Jr. Comercio 456, Lima', 'contacto@comercialandina.pe', '988777666');

INSERT INTO clientes (tipo_persona, dni, ruc, nombre_completo, razon_social, direccion, email, whatsapp)
VALUES ('NATURAL', '45678912', '10456789123', 'Jose Ramirez Lopez', NULL, 'Calle Las Flores 789, Arequipa', 'jose.ramirez@example.com', '977666555');

INSERT INTO clientes (tipo_persona, dni, ruc, nombre_completo, razon_social, direccion, email, whatsapp)
VALUES ('JURIDICA', NULL, '20567891234', NULL, 'Distribuidora del Sur E.I.R.L.', 'Av. Ejercito 321, Arequipa', 'ventas@distribuidorasur.pe', '966555444');

Este cuarto cliente (NATURAL con dni y ruc) es justo el caso de una persona natural con negocio propio, que puede pedir boleta con su DNI o factura con su RUC según la orden.

Igual que V1, una vez aplicado no se edita — si necesitas ajustar estos datos, agrega un V3 nuevo. pagatu-orden-ms también tiene su propio V2__seed_ordenes.sql, con órdenes de ejemplo referenciando estos id de clientes y los id de productos sembrados en pagatu-catalogo-ms (S1) — sin llave foránea entre microservicios, así que ese V2 de orden-ms solo funciona si los seeds de cliente-ms y catalogo-ms ya se aplicaron antes.

Tipo de comprobante por orden: boleta simple, boleta con DNI o factura

Elegir el comprobante es una decisión de cada orden, no del perfil del cliente — la misma persona puede pedir boleta simple una vez y factura la siguiente. Por eso este campo vive en ordenes (pagatu-orden-ms), no en clientes.

Tabla 4. Tipos de comprobante y qué exigen del cliente

tipo_comprobante Requiere Uso típico
BOLETA_SIMPLE Nada — ni DNI ni RUC Compra rápida, sin identificar al cliente.
BOLETA_CON_DNI El cliente debe tener dni registrado en pagatu-cliente-ms El cliente quiere su DNI impreso en la boleta (garantía, seguimiento).
FACTURA El cliente debe tener ruc registrado en pagatu-cliente-ms El cliente (persona natural con RUC, o persona jurídica) necesita crédito fiscal / gasto deducible.

La columna tipo_comprobante ya está en ordenes (ver V1__create_orden_tables.sql, arriba en este mismo documento). Validar que el cliente realmente tenga dni (para BOLETA_CON_DNI) o ruc (para FACTURA) antes de crear la orden es responsabilidad del código — una consulta a pagatu-cliente-ms — no de una restricción SQL entre bases de datos distintas.

Método de pago por orden

pagatu es comercio electrónico, así que la orden también registra con qué método el cliente eligió pagar — el procesamiento real de ese pago (confirmar, rechazar, reintentar) es trabajo de pago-ms, recién en S8; hoy solo se deja registrado el método elegido en ordenes.metodo_pago.

"Contra entrega" no es un método de pago — es cuándo se paga. El repartidor puede cobrar en efectivo, por Yape/Plin (QR) o incluso por transferencia al momento de la entrega; el medio sigue siendo uno de los mismos de siempre. Por eso pagatu separa dos columnas: con qué se paga (metodo_pago) y cuándo se paga (momento_pago).

Tabla 5. Métodos de pago considerados para pagatu

metodo_pago Descripción Nota
TARJETA Tarjeta de crédito o débito (Visa, Mastercard), vía pasarela de pagos. Es el nodo "Pasarela de pagos externa" que ya está en el C4 nivel 1 y 2 (docs/index.md); en la práctica solo aplica cuando momento_pago = ADELANTADO.
YAPE_PLIN Billetera digital (Yape o Plin) por QR. Funciona tanto adelantado como al momento de la entrega.
TRANSFERENCIA Transferencia bancaria directa. El cliente paga fuera del sistema y sube o registra un comprobante; también puede hacerse al recibir el pedido.
PAGO_EFECTIVO Efectivo — en un agente/punto físico afiliado si es adelantado, o directo al repartidor si es contra entrega. Útil para clientes sin tarjeta ni banca digital.

Tabla 6. momento_pago: cuándo se paga

momento_pago Descripción
ADELANTADO El cliente paga al crear la orden, antes del despacho — pago-ms procesa el pago de inmediato (S8-S9).
CONTRA_ENTREGA El cliente paga cuando recibe el pedido, con cualquiera de los métodos de la Tabla 5 (excepto TARJETA, en la práctica — no suele haber POS físico con el repartidor).

metodo_pago y momento_pago son obligatorios desde el diseño (NOT NULL) porque, a diferencia del comprobante, en comercio electrónico real casi nunca se permite crear una orden sin saber cómo y cuándo se va a pagar. Validar reglas como "TARJETA no aplica a CONTRA_ENTREGA" es trabajo del código en pago-ms (S8), no una restricción SQL de este documento.