besper-frontend-site-dev-main/src/pages/account-management/DEVELOPER_GUIDE.md

Professional B-esper Frontend Site - Site-wide integration toolkit for full website bot deployment

# Account Management Page - Developer Guide

## Overview

Centralized account management functionality with comprehensive workspace management, user impersonation, and APIM integration.

## Architecture

### Core Components

- **AccountManagementPage**: Main page class with bulletproof loading pattern
- **WorkspaceManagementSystem**: Comprehensive workspace management with hierarchy support
- **Authentication Integration**: Smart token coordination with multiple fallback mechanisms
- **APIM Integration**: Full integration with administrative APIs

## Business Context References

### Workspace Management Business Logic

For detailed business requirements and context:

- **Source**: `infra/besper_site_serversite/storage/account-management/BUSINESS_CONTEXT.md`
- **Developer Guide**: `infra/besper_site_serversite/storage/account-management/DEVELOPER_GUIDE.md`
- **Migration Guide**: `infra/besper_site_serversite/storage/account-management/MIGRATION_GUIDE.md`

## Key Features

### Workspace Hierarchy Management

- **Parent-Child Relationships**: Full workspace hierarchy with circular reference prevention
- **User Impersonation**: Administrative operations with proper user context
- **Related Entity Management**: Comprehensive management of users, licenses, and cost pools
- **Real-time Statistics**: Live aggregation of workspace metrics and statistics

### Authentication & Security

- **Smart Token Coordination**: Multi-layer authentication with fallback mechanisms
- **APIM Integration**: Secure integration with internal administrative endpoints
- **User Permission Management**: Proper permission validation and user context handling

### Data Management

- **Background Loading**: Non-blocking data loading with immediate UI rendering
- **Demo Data Fallback**: Development-friendly fallback data when APIs are unavailable
- **Export Functionality**: Comprehensive data export with workspace hierarchy
- **Real-time Updates**: Live statistics and data synchronization

## API Integration

### Administrative Endpoints

- `POST /api/admin/administrative/workspace/list` - Workspace listing with hierarchy
- Individual workspace detail endpoints for comprehensive management
- User impersonation endpoints for administrative operations

### Authentication Flow

1. **Smart Token Coordination**: Attempt to get token from global coordination system
2. **Fallback Authentication**: Use tokenAuth service as secondary option
3. **Error Handling**: Graceful degradation with user-friendly error messages

## Implementation Notes

### Page Structure

```javascript
class AccountManagementPage {
  // Bulletproof initialization
  constructor(options = {})
  async initialize(data = {})

  // Workspace management integration
  initializeWorkspaceManagement()
  async loadWorkspacesWithHierarchy()
  openWorkspaceDetails(workspaceId, editMode)

  // Data management
  async loadAccountDataFromAPIM()
  exportWorkspaceData()
}
```

### Key Methods

- **initializeWorkspaceManagement()**: Sets up comprehensive workspace management
- **loadWorkspacesWithHierarchy()**: Loads workspace data with parent-child relationships
- **openWorkspaceDetails()**: Opens detailed workspace view with management capabilities
- **exportWorkspaceData()**: Exports comprehensive workspace data including hierarchy

## Development Guidelines

### Error Handling

- All API calls include comprehensive error handling
- Fallback to demo data when APIs are unavailable
- User-friendly error messages with actionable guidance

### Performance Optimization

- Immediate UI rendering without blocking on authentication
- Background data loading with progressive enhancement
- Efficient DOM updates with minimal reflow

### Internationalization

- German and English language support
- Dynamic language switching with persistent preferences
- Localized date and number formatting

## Testing Notes

### Demo Data Structure

The page includes comprehensive demo data that mirrors production data structure:

- Hierarchical workspace relationships
- User, license, and cost pool associations
- Realistic statistics and performance metrics

### API Mocking

For development and testing:

- Automatic fallback to demo data when APIs are unavailable
- Comprehensive error simulation for testing error handling
- Development-friendly logging and debugging information