External Command Execution

Relevant source files

The following files were used as context for generating this wiki page:

• src/platform/DesktopExternalCommandPort.cpp
• src/platform/DesktopExternalCommandPort.h
• src/presentation/CommandViewModel.cpp
• src/presentation/CommandViewModel.h
• src/ports/IExternalCommandPort.h
• src/presentation/MainViewModel.cpp
• app/desktop/main.cpp

The External Command Execution system provides a structured mechanism for the application to interact with the operating system and external web services. Its primary purpose is to decouple the UI presentation logic from platform-specific implementations, such as opening web browsers or local file paths.

This system is built around the Port-Adapter pattern. The domain logic and ViewModels interact with an abstract interface (IExternalCommandPort), while the platform-specific implementation (DesktopExternalCommandPort) handles the actual execution using Qt's desktop services.
Sources: src/ports/IExternalCommandPort.h, src/platform/DesktopExternalCommandPort.h, src/presentation/MainViewModel.cpp:25-30

Architecture and Component Hierarchy

The system follows a tiered architecture where the user interface triggers actions that flow through a ViewModel to a platform-specific port.

Component Overview

Component	Responsibility
IExternalCommandPort	Abstract interface defining supported external operations.
DesktopExternalCommandPort	Concrete implementation using QDesktopServices to open URLs and files.
CommandViewModel	Qt-compatible wrapper that exposes command port functionality to QML.
MainViewModel	Orchestrates high-level application state and holds the CommandViewModel.

Sources: src/ports/IExternalCommandPort.h:9-21, src/platform/DesktopExternalCommandPort.h:11-20, src/presentation/CommandViewModel.h:15-25, src/presentation/MainViewModel.cpp:55-57

Implementation Diagram

The following class diagram illustrates the relationship between the abstract port, its concrete implementation, and the presentation layer.

Execution Flow

External commands are typically triggered by user interactions in the UI. The flow starts in the MainViewModel, passes through the CommandViewModel, and is finally executed by the DesktopExternalCommandPort.

Opening a Specific SSA

When a user requests to open a specific SSA (Service Selection Advice) record in the external SAM (System of Asset Management) system, the application constructs a URL with specific query parameters.

Command Implementation Details

Desktop Execution

The DesktopExternalCommandPort utilizes QDesktopServices::openUrl to handle different types of external requests:

• Web Navigation: Opens the default browser to the SAM home page or a specific SSA record.
• File System: Opens local paths using the system's default file handler via QUrl::fromLocalFile.
• Generic Commands: The requestCommand method acts as a dispatcher for various operations, such as mapping the open_sam command to specific SSA navigation.

Sources: src/platform/DesktopExternalCommandPort.cpp:12-40

Parameter Mapping

The SAM base URL defaults to https://sam.itaipu.gov.br but is configurable during the construction of the port in the application's entry point.
Sources: app/desktop/main.cpp:64, src/platform/DesktopExternalCommandPort.h:12

// Example of URL construction for SSA lookup
void DesktopExternalCommandPort::openSsa(const std::string& numeroSsa) {
    QUrl url = samBaseUrl_;
    url.setPath("/ssa");
    QUrlQuery query;
    query.addQueryItem("numero", QString::fromStdString(numeroSsa));
    url.setQuery(query);
    QDesktopServices::openUrl(url);
}

Sources: src/platform/DesktopExternalCommandPort.cpp:16-23

Summary

The External Command Execution system ensures that the SSA Consulta Rapida application can interact with external tools and web services while maintaining a clean separation between the UI and the underlying platform. By using the IExternalCommandPort interface, the project facilitates easier testing (through fakes) and portability across different desktop environments.