Guías de tareas¶

Recetas concretas para tareas puntuales del ecosistema. A diferencia de la Referencia (que describe qué hay) o de Entender el sistema (que explica por qué), acá el foco es cómo hago X, paso a paso.

Backend¶

Agregar o tocar un módulo sin romper el guardrail¶

1. Poné el código nuevo en el paquete del módulo correcto (com.tipre.autocompras.<modulo>).
2. Lo que sea API pública va en la raíz del paquete; lo interno, en subpaquetes.
3. Si tu módulo necesita algo de otro, llamá sólo su API pública — nunca una clase de un subpaquete ajeno. Si te tienta cruzar la frontera, replanteá: probablemente la dependencia va al revés (que tickets orqueste) o por evento (@ApplicationModuleListener).
4. Corré el guardrail:

   mvn test
   

   Si ModularityTests.verify() falla, no toques el test: revisá el diseño. Ver El monolito modular.

Refrescar una cache (catálogo o promos)¶

Con seguridad activa hace falta rol admin:

curl -X POST http://localhost:8080/autocompras/v1/catalogo/cache/refresh \
  -H "Authorization: Bearer <jwt-admin>"

curl -X POST http://localhost:8080/autocompras/v1/cache/refresh \
  -H "Authorization: Bearer <jwt-admin>"

Con app.security.enabled=false (dev) no hace falta el token, pero recordá el riesgo del toggle.

Diagnosticar el parque de terminales en el Cockpit¶

1. Abrí /autocompras/v1/cockpit/, panel Terminals.
2. Una terminal offline no se borró: no pingeó dentro de la ventana de ~90 s. Revisá su conectividad y su último heartbeat.
3. Para salud por terminal (pinpad/Point), mirá lo que reporta el header X-Device-Health. Ver Cockpit.

Terminal (TiprePOS)¶

Configurar una terminal nueva contra un backend¶

1. Arrancá la app: el router te manda a /configuration (no hay config).
2. Cargá server, port, ssl y el código de terminal.
3. En /register la terminal se registra y baja su TerminalConfig.
4. Verificá en el Cockpit que aparezca online.

Detalle en Setup del entorno.

Apuntar el pago con tarjeta a otro daemon ApiCard¶

Por defecto la terminal pega a localhost:50001. Es configurable (fix TPOS-016): apicardServer / apicardPort / apicardSsl en IsarConnectionConfig. Ver Pagos → Tarjeta.

Entender por qué un pago Point Smart quedó "incierto"¶

Si ves el estado action_required o expired, el dinero puede estar cobrado aunque la UI no lo confirme. No asumas: conciliá por payment_id contra MercadoPago antes de dar la venta por perdida o por hecha. Ver la máquina de estados de Point Smart.

Pruebas de carga (StressBench)¶

Correr un load-test del backend¶

Para verificar que el sistema aguanta carga realista (200 terminales vendiendo a la vez), usá StressBench:

1. Creá las DBs lt_ aisladas y sembrá los 200 POS (seed/).
2. Levantá el backend con el profile loadtest (apunta los pagos al gateway falso y los datasources a las DBs lt_).
3. cd pos-swarm && npm install && npm start (gateway falso :9090 + cockpit :4000).
4. Abrí http://localhost:4000, cargá el modelo de venta con EANs reales, elegí el escenario de pago y subí el slider a 200.

Antes del enjambre, corré el smoke de 1 POS: npx tsx scripts/smoke-one-pos.ts. Detalle completo en StressBench.

Forzar (y validar) el drenado de pagos indeterminados¶

Es la prueba más valiosa. En el cockpit de StressBench, poné el escenario de pago en "no responde" o "muy lento" (delayMs > timeout). Eso fuerza pagos INDETERMINADO. Después confirmá en el panel "Backend (monitoring)" que reconciliador.indeterminado baja (el reconciliador del backend los resuelve), y en el log del backend: Reconciliador: ... resuelto a APROBADO. Ver El ciclo de pago y fiscalización.

Documentación¶

Correr esta doc en local¶

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
mkdocs serve

Abrí http://127.0.0.1:8000. Validá links antes de pushear:

mkdocs build --strict

Exportar la doc a PDF¶

pip install -r requirements.txt
python -m playwright install chromium
$env:PDF_EXPORT = "true"; mkdocs build

El PDF queda en site/pdf/autocompramod-documentacion.pdf. Detalle en el README del repo (sección Exportar a PDF).