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
```python
@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
```python
@classmethod
def configure_router(cls, prefix: str, tags: List[str]) -> None
```
Sets the router prefix and OpenAPI tags.

##### Configure Page
```python
@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
```python
@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
```python
@classmethod
def register_method_class(cls, method_class: Type[MethodToEvent]) -> None
```
Registers a MethodToEvent class in the registry.

##### Get All Menu Items
```python
@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
```python
@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
```python
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
```python
# 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
```python
[
    {
        "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