Saltar a contenido

ADR-004 — Dev bench: separate municipal emulator with three panels

  • Status: accepted (2026-11-16)

Context

The municipal sandbox simulator can only mark a charge as paid; it cannot produce insufficient balance, latency, 5xx responses or the cancel-vs-pay race. The team needs a visual bench to tune the gateway and its use cases before connecting the real CYRE POS. GatewayPrismaQR already has an emulator module (prisma-emulator) with scenarios and a fault injector.

Alternatives

  • Separate emulator module with its own bench UI. Chosen.
  • Bench inside the gateway cockpit. Rejected: test code would ship in the product installed on the CYRE server.
  • Municipal sandbox only. Rejected: it cannot reproduce failure modes.

Decision

A muni-emulator module (runnable jar) implements the full municipal API (create, query, cancel, /pagar, movements, balance) with in-memory state. It serves a React bench UI with three panels:

  1. Simulated POS: speaks the PAGOQR contract to the real gateway, renders the QR, shows statuses as the cashier would see them.
  2. Payer app: "scans" a QR from the POS panel and chooses an outcome: pay, insufficient balance, pay at second X, or do nothing.
  3. Municipal backend: charges and their statuses, plus fault knobs (latency, 5xx, timeouts, 409 on the cancel-vs-pay race).

The gateway runs exactly as in production with its own cockpit; only its municipal base URL changes (emulator, sandbox or production). Phase 2: the real CYRE POS points at the gateway, and panel 1 stays for regression.

Consequences

  • The emulator must track the municipal contract; corpus captured from the sandbox (RISKS R-01) is used to check the emulator's responses against reality.
  • The emulator is never deployed to CYRE servers.

Implementation Plan

  • Copy the prisma-emulator module layout (scenarios, FaultInjector, runnable jar) from C:/Work/AI/GatewayPrismaQR.
  • Bench UI: React 19 + Vite 8, served by the emulator jar.

Verification

  • [ ] An end-to-end payment runs from panel 1 → gateway → emulator → panel 2 → back to panel 1.
  • [ ] Each fault knob produces the expected gateway behavior (ADR-003 scenarios).
  • [ ] The gateway artifact contains no emulator classes.