new api service and logic implemented
This commit is contained in:
229
docs/method_event_system.md
Normal file
229
docs/method_event_system.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user