Uso de IA · Facturación y pagos

    @Tool(name = "consultar_comprobante",
          description = "Devuelve un comprobante por su identificador UUID: folio, subtotal, IVA, total, estatus, "
                  + "estatus de cobro, monto pagado, saldo y lista de pagos.")
    public String consultarComprobante(
            @ToolParam(description = "Identificador UUID del comprobante", required = true) String comprobanteId) {
        RegistroHerramientasUsadas.registrar("consultar_comprobante");
        String cuerpo = gateway.get()
                .uri(constructor -> constructor.path(RUTA_BASE + "/comprobantes/{id}")
                        .build(UUID.fromString(comprobanteId.trim())))
                .retrieve()
                .body(String.class);
        return FiltroDatosSensibles.redactar(cuerpo).texto();
    }

    @Tool(name = "registrar_pago_comprobante",
          description = "Prepara el registro de un cobro sobre un comprobante. NO lo registra: devuelve un resumen y un "
                  + "accion_id. El usuario debe confirmarlo en la aplicación. Solo FINANZAS puede usarla.")
    public String registrarPagoComprobante(
            @ToolParam(description = "Identificador UUID del comprobante", required = true) String comprobanteId,
            @ToolParam(description = "Monto mayor a cero, hasta 2 decimales", required = true) String monto,
            @ToolParam(description = "Fecha del pago en formato AAAA-MM-DD; vacío para hoy", required = false) String fechaPago,
            @ToolParam(description = "Referencia bancaria o de transferencia, de hasta 100 caracteres", required = false) String referencia) {
        RegistroHerramientasUsadas.registrar("registrar_pago_comprobante");
        if (acciones == null) {
            return NO_DISPONIBLE;
        }
        UUID id = identificador(comprobanteId);
        if (id == null) {
            return "El identificador del comprobante no es válido.";
        }
        BigDecimal cantidad = decimal(monto);
        if (cantidad == null || cantidad.signum() <= 0) {
            return "El monto debe ser mayor a cero, con hasta 2 decimales.";
        }
        LocalDate fecha = null;
        if (fechaPago != null && !fechaPago.isBlank()) {
            try {
                fecha = LocalDate.parse(fechaPago.trim());
            } catch (DateTimeParseException e) {
                return "La fecha debe tener formato AAAA-MM-DD.";
            }
        }
        if (referencia != null && referencia.trim().length() > 100) {
            return "La referencia no puede tener más de 100 caracteres.";
        }
        try {
            gateway.get().uri(RUTA_BASE + "/comprobantes/{id}", id).retrieve().body(String.class);
        } catch (HttpClientErrorException.NotFound e) {
            return "No encontré ese comprobante.";
        }
        Map<String, Object> cuerpo = new LinkedHashMap<>();
        cuerpo.put("comprobanteId", id.toString());
        cuerpo.put("monto", cantidad);
        if (fecha != null) {
            cuerpo.put("fechaPago", fecha.toString());
        }
        if (referencia != null && !referencia.isBlank()) {
            cuerpo.put("referencia", referencia.trim());
        }
        // Clave única por acción: si el cobro se reintenta, facturación no lo aplica dos veces.
        cuerpo.put("idempotencyKey", java.util.UUID.randomUUID().toString());
        String resumen = "Registrar un cobro de " + cantidad.toPlainString() + " sobre el comprobante " + id
                + (fecha == null ? "" : " con fecha " + fecha);
        AccionPendiente accion = acciones.preparar(usuarioActual(), AccionesPendientes.TIPO_COMPROBANTE_PAGO_REGISTRAR,
                aJson(cuerpo), resumen);
        return FiltroDatosSensibles.redactar("Cobro preparado, no registrado. " + resumen + ". accion_id: "
                + accion.id() + ". Vence en 10 minutos; el usuario debe confirmarlo en la aplicación.").texto();
    }

    static final String RUTA_BASE = "/facturacion-pagos-ms/v1";