F-145 — Architect

Feature

Reporting: payment lines and POS cash-safe capture.

Background

El architecture doc §5.3 (REPORTING_ARCHITECTURE.md) identifica que payments_transactions no tiene método de pago, tienda, terminal ni sesión: no permite filtrar por método ni hacer cuadre de caja POS. El doc pide crear order_payments/orders_payment_lines como líneas de pago inmutables.

Objetivo

Persisitir líneas de pago inmutables por pedido que capturen: método, tienda, terminal, sesión, importe, provider y referencia. Sin datos de tarjeta (PAN/CVV). Estas líneas alimentan GET /reporting/payments y GET /reporting/cash-sessions en F-146/F-148.

Diseño

Nueva tabla: `reporting_payment_lines`

CREATE TABLE reporting_payment_lines (
  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  order_id          uuid NOT NULL REFERENCES orders_orders(id) ON DELETE RESTRICT,
  store_id          uuid NOT NULL REFERENCES pos_stores(id) ON DELETE RESTRICT,
  terminal_id       uuid REFERENCES pos_terminals(id) ON DELETE SET NULL,
  cash_session_id   uuid REFERENCES pos_cash_sessions(id) ON DELETE SET NULL,
  payment_method_id uuid REFERENCES pos_payment_methods(id) ON DELETE SET NULL,
  provider          text NOT NULL,          -- 'stripe', 'cash', 'card', 'bizum'
  amount_cents      integer NOT NULL CHECK (amount_cents != 0),
  currency          text NOT NULL DEFAULT 'EUR' CHECK (currency = 'EUR'),
  status            text NOT NULL CHECK (status IN ('payment', 'refund', 'partial_refund')),
  provider_ref      text,                   -- stripe payment_intent_id / cash receipt
  created_at        timestamptz NOT NULL DEFAULT now(),
  updated_at        timestamptz NOT NULL DEFAULT now()
);

-- reporting por tienda/fecha
CREATE INDEX reporting_payment_lines_store_created_idx
  ON reporting_payment_lines (store_id, created_at);

-- un pago completo = línea payment + posibles líneas refund
CREATE INDEX reporting_payment_lines_order_idx
  ON reporting_payment_lines (order_id);

-- cash-safe: por sesión
CREATE INDEX reporting_payment_lines_session_idx
  ON reporting_payment_lines (cash_session_id) WHERE cash_session_id IS NOT NULL;

Notas de diseño

Inmutable: no hay UPDATE en la tabla; solo INSERT (un refund es una nueva línea con status='refund'). Un updated_at se mantiene por trazabilidad de inserciones desde múltiples procesos (ON INSERT SET updated_at = now()).
provider: distingue Stripe (ecommerce), cash/card (POS). No se guarda PAN ni CVV.
cash_session_id: NULL para ecommerce (no hay caja física). Para POS, la sesión abierta vincula el pago a la caja.
amount_cents != 0: rechaza líneas de 0€ (no tiene sentido). payment o refund siempre tienen importe.
Backfill: la migración no backfillea payments_transactions existente porque faltan store_id/terminal_id/method — los campos necesarios. Los pedidos pre-F-145 sin método de pago explícito quedan con dataAvailability=false en los filtros de pago.
Orden de FK: order_id → orders_orders(id), store_id → pos_stores(id) (ya existe en 048), terminal_id → pos_terminals(id) (existe en 043), cash_session_id → pos_cash_sessions(id) (existe en 043), payment_method_id → pos_payment_methods(id) (existe en 043). Circular: no hay (reporting_payment_lines no tiene FK hacia otra tabla nueva).

Cómo se inserta (contracto para implementación)

El módulo de checkout/orders es responsable de llamar a un nuevo ReportingPaymentLinesRepository.insert(input) tras confirmar el pago:

interface InsertPaymentLineInput {
  orderId: string;
  storeId: string;
  terminalId?: string;
  cashSessionId?: string;
  paymentMethodId?: string;
  provider: string;           // 'stripe' | 'cash' | 'card' | 'bizum'
  amountCents: number;
  status: 'payment' | 'refund' | 'partial_refund';
  providerRef?: string;
}

Para ecommerce: storeId viene del pedido (ya backfillable tras 048); terminalId/cashSessionId son NULL. Provider se determina del webhook (StripePaymentProvider). Para POS: storeId/terminalId/cashSessionId/paymentMethodId se pasan desde el flujo POS en el checkout. Provider = cash o card.

Decisiones rechazadas

No crear order_refunds separada: un refund es una línea con status='refund' en la misma tabla (agrupable por order_id).
No guardar PAN: requisito PCI-DSS mínimo. Provider_ref es el id externo (payment_intent_id), no datos de tarjeta.
No INSERT en payments_transactions: esa tabla es de eventos de provider (Stripe webhooks); reporting_payment_lines es una capa de reporting que existe independientemente de qué provider envió el evento.

Consecuencias

Migration 049 idempotente (ADD TABLE IF NOT EXISTS + DO $$ guard para cada constraint si se re-ejecuta en PG<16).
El servicio de reporting en F-146 puede hacer JOIN reporting_payment_lines con orders_orders para enriquecer métricas de pago por tienda/método/terminal.
F-147/F-148 (dashboard) consumirán estas líneas para el panel de caja y métodos de pago.

Acceptance Criteria

AC1: La tabla reporting_payment_lines existe con las columnas, constraints e índices diseñados (PK, FK validadas, CHECK amount_cents!=0, CHECK status IN, tres índices). AC2: Un INSERT con todos los campos FK válidos se completa sin error. AC3: Un INSERT con amount_cents=0 falla con constraint violation. AC4: Un INSERT sin order_id falla con FK violation. AC5: La migración es idempotente (re-ejecutar up() es no-op) y reversible (down() elimina la tabla y los índices). AC6: El módulo reporting puede consultar la tabla (unittest con mock DB o integración contra migración aplicada). AC7: No hay regresión en los flujos existentes (checkout, POS, payments — no se modifica su comportamiento). AC8: Los gates (reviewer, security, qa) + verify.sh pasan.

5.8 KiB Raw Blame History