wag-managment-api-service-version-4/docs/method_event_system.md

MethodToEvent System Documentation

Overview

The MethodToEvent system provides a unified way to manage API endpoints and frontend menu structure with built-in permission handling. It uses UUIDs for permission management and supports hierarchical menu structures.

Core Components

1. MethodToEvent Base Class

Base class for defining event methods with API endpoints and frontend page configuration.

Class Variables

• action_key: Unique identifier for the action
• event_type: Type of event (e.g., 'query', 'command')
• event_description: Human-readable description
• event_category: Category for grouping
• __event_keys__: UUID to event name mapping
• __event_validation__: Validation rules
• __endpoint_config__: API endpoint configuration
• __page_info__: Frontend page configuration

Methods

Configure API Endpoints

@classmethod
def register_endpoint(
    cls,
    event_uuid: str,
    path: str,
    method: str = "POST",
    response_model: Optional[Type] = None,
    **kwargs
) -> None

Registers an API endpoint for an event UUID.

Configure Router

@classmethod
def configure_router(cls, prefix: str, tags: List[str]) -> None

Sets the router prefix and OpenAPI tags.

Configure Page

@classmethod
def configure_page(
    cls,
    name: str,
    title: Dict[str, str],
    icon: str,
    url: str,
    component: Optional[str] = None,
    parent: Optional[str] = None
) -> None

Configures frontend page information.

Get Page Info with Permissions

@classmethod
def get_page_info_with_permissions(
    cls,
    user_permission_uuids: Set[str],
    include_endpoints: bool = False
) -> Optional[Dict[str, Any]]

Returns page info if user has required permissions.

2. EventMethodRegistry

Singleton registry for managing all MethodToEvent classes and building menu structures.

Methods

Register Method Class

@classmethod
def register_method_class(cls, method_class: Type[MethodToEvent]) -> None

Registers a MethodToEvent class in the registry.

Get All Menu Items

@classmethod
def get_all_menu_items(
    cls,
    user_permission_uuids: Set[str],
    include_endpoints: bool = False
) -> List[Dict[str, Any]]

Returns complete menu structure based on permissions.

Get Available Endpoints

@classmethod
def get_available_endpoints(
    cls,
    user_permission_uuids: Set[str]
) -> Dict[str, Dict[str, Any]]

Returns all available API endpoints based on permissions.

Example Usage

1. Define Event Methods

class AccountEventMethods(MethodToEvent):
    event_category = "account"
    event_type = "query"
    event_description = "Account management operations"
    __event_keys__ = {
        "uuid1": "view_account",
        "uuid2": "edit_account"
    }

    # Configure API
    configure_router("/api/account", ["Account"])
    register_endpoint(
        "uuid1",
        "/view",
        method="GET",
        response_model=AccountResponse
    )

    # Configure frontend
    configure_page(
        name="AccountPage",
        title={"tr": "Hesaplar", "en": "Accounts"},
        icon="User",
        url="/account"
    )

class AccountDetailsEventMethods(MethodToEvent):
    event_category = "account_details"
    __event_keys__ = {
        "uuid3": "view_details",
        "uuid4": "edit_details"
    }

    configure_page(
        name="AccountDetailsPage",
        title={"tr": "Hesap Detayları", "en": "Account Details"},
        icon="FileText",
        url="/account/details",
        parent="AccountPage"  # Link to parent
    )

2. Register and Use

# Register classes
registry = EventMethodRegistry()
registry.register_method_class(AccountEventMethods)
registry.register_method_class(AccountDetailsEventMethods)

# Get menu structure
user_permissions = {"uuid1", "uuid2", "uuid3"}
menu_items = registry.get_all_menu_items(user_permissions, include_endpoints=True)

Menu Structure Rules

1. Parent-Child Visibility

   • Parent page must have permissions to be visible
   • If parent is not visible, children are never shown
   • If parent is visible, all children are shown

2. Permission Checking

   • Based on UUID intersection
   • Page is visible if user has any of its event UUIDs
   • Endpoints only included if user has specific permission

3. Menu Organization

   • Automatic tree structure based on parent field
   • Sorted by name for consistency
   • Optional endpoint information included

Example Menu Structure

[
    {
        "name": "AccountPage",
        "title": {"tr": "Hesaplar", "en": "Accounts"},
        "icon": "User",
        "url": "/account",
        "category": "account",
        "type": "query",
        "description": "Account management operations",
        "available_endpoints": {
            "uuid1": {"path": "/api/account/view", "method": "GET"},
            "uuid2": {"path": "/api/account/edit", "method": "POST"}
        },
        "items": [
            {
                "name": "AccountDetailsPage",
                "title": {"tr": "Hesap Detayları", "en": "Account Details"},
                "icon": "FileText",
                "url": "/account/details",
                "parent": "AccountPage",
                "available_endpoints": {
                    "uuid3": {"path": "/api/account/details/view", "method": "GET"}
                }
            }
        ]
    }
]

Best Practices

1. UUID Management

   • Use consistent UUIDs across the system
   • Document UUID meanings and permissions
   • Group related permissions under same parent

2. Page Organization

   • Use meaningful page names
   • Provide translations for all titles
   • Keep URL structure consistent with hierarchy

3. API Endpoints

   • Use consistent router prefixes
   • Group related endpoints under same router
   • Use appropriate HTTP methods

4. Permission Structure

   • Design permissions hierarchically
   • Consider access patterns when grouping
   • Document permission requirements