feat(employees): implement automatic system user creation for employees

- Add `is_system_user` boolean field to employee model, schemas, and database
- Implement `_create_employee_system_user` method to generate system users with temporary passwords
- Map employee designations to system user roles (ASM, SALES_EXECUTIVE, etc.)
- Generate system usernames from employee codes with automatic formatting
- Store employee metadata in system user records for relationship tracking
- Add comprehensive documentation for employee-system user integration workflow
- Include error handling to prevent system user creation failures from blocking employee creation
- Add test script to verify system user creation functionality
- System user creation is triggered when `is_system_user=True` during employee creation

EMPLOYEE_SYSTEM_USER_INTEGRATION.md

@@ -0,0 +1,153 @@
+# Employee System User Integration
+
+## Overview
+
+This document describes the implementation of automatic system user creation when an employee is created with the `is_system_user` flag set to `true`.
+
+## Implementation Details
+
+### 1. Schema Changes
+
+#### Employee Create Schema (`EmployeeCreate`)
+- Added `is_system_user: bool` field with default value `False`
+- When set to `True`, triggers system user creation after employee creation
+
+#### Employee Update Schema (`EmployeeUpdate`)
+- Added `is_system_user: Optional[bool]` field for updates
+
+#### Employee Response Schema (`EmployeeResponse`)
+- Added `is_system_user: bool` field to include in responses
+
+#### Employee Model (`EmployeeModel`)
+- Added `is_system_user: bool` field for database storage
+
+### 2. Service Layer Changes
+
+#### Employee Service (`EmployeeService`)
+
+**Modified `create_employee` method:**
+- After successful employee creation, checks if `is_system_user` is `True`
+- If true, calls `_create_employee_system_user` method
+- System user creation failure doesn't fail employee creation (logged as error)
+
+**Added `_create_employee_system_user` method:**
+- Creates a system user in the `SCM_SYSTEM_USERS` collection
+- Generates username from employee code (lowercase, hyphens → underscores)
+- Creates temporary password with format `Temp@{random_token}`
+- Maps employee designation to role_id
+- Stores employee metadata in system user record
+
+### 3. System User Creation Logic
+
+When `is_system_user=True`, the following system user is created:
+
+```python
+{
+    "username": "emp_test_001",  # from employee_code
+    "email": "employee@company.com",  # same as employee
+    "password": "Temp@{random}",  # temporary password
+    "full_name": "First Last",  # from employee name
+    "role_id": "role_asm",  # from designation
+    "merchant_id": "created_by_value",  # from created_by
+    "metadata": {
+        "employee_user_id": "usr_xxx",
+        "employee_code": "EMP-TEST-001",
+        "designation": "ASM",
+        "created_from": "employee_creation"
+    }
+}
+```
+
+### 4. Role Mapping
+
+Employee designations are mapped to system user roles:
+- `ASM` → `role_asm`
+- `SALES_EXECUTIVE` → `role_sales_executive`
+- etc.
+
+### 5. Error Handling
+
+- System user creation errors are logged but don't fail employee creation
+- Employee record is always created successfully
+- System user creation can be retried separately if needed
+
+## Usage Examples
+
+### Creating Employee with System User
+
+```python
+employee_data = EmployeeCreate(
+    employee_code="EMP-MUM-001",
+    first_name="John",
+    last_name="Doe",
+    email="john.doe@company.com",
+    phone="+919876543210",
+    designation=Designation.ASM,
+    base_city="Mumbai",
+    base_state="Maharashtra",
+    doj=date.today(),
+    emergency_contact={
+        "name": "Jane Doe",
+        "relation": "Spouse",
+        "phone": "+919876543211"
+    },
+    is_system_user=True,  # This triggers system user creation
+    created_by="admin_001"
+)
+
+employee = await EmployeeService.create_employee(employee_data)
+```
+
+### Creating Employee without System User
+
+```python
+employee_data = EmployeeCreate(
+    # ... same fields ...
+    is_system_user=False,  # No system user created
+    created_by="admin_001"
+)
+
+employee = await EmployeeService.create_employee(employee_data)
+```
+
+## API Response
+
+The employee response now includes the `is_system_user` field:
+
+```json
+{
+    "user_id": "usr_01HZQX5K3N2P8R6T4V9W",
+    "employee_code": "EMP-MUM-001",
+    "first_name": "John",
+    "last_name": "Doe",
+    "email": "john.doe@company.com",
+    "designation": "ASM",
+    "is_system_user": true,
+    "status": "onboarding",
+    "created_by": "admin_001",
+    "created_at": "2023-01-10T08:00:00Z"
+}
+```
+
+## Testing
+
+Use the provided test script to verify the functionality:
+
+```bash
+cd cuatrolabs-scm-ms
+python test_employee_system_user_creation.py
+```
+
+## Security Considerations
+
+1. **Temporary Passwords**: System users are created with temporary passwords that should be changed on first login
+2. **Role Mapping**: Ensure proper role mapping for security permissions
+3. **Metadata Tracking**: Employee-system user relationship is tracked via metadata
+4. **Error Isolation**: System user creation failures don't affect employee creation
+
+## Future Enhancements
+
+1. **Email Notifications**: Send temporary password via secure email
+2. **Role Customization**: Allow custom role assignment during employee creation
+3. **Bulk Operations**: Support bulk employee creation with system users
+4. **Audit Trail**: Enhanced logging for system user creation events

app/employees/models/model.py

@@ -139,6 +139,12 @@ class EmployeeModel(BaseModel):
         description="Application access configuration"
     )
     
+    # System user flag
+    is_system_user: bool = Field(
+        default=False,
+        description="Whether this employee has a corresponding system user"
+    )
+    
     # Location tracking
     location_settings: LocationSettingsModel = Field(
         default_factory=LocationSettingsModel,

app/employees/schemas/schema.py

@@ -261,6 +261,12 @@ class EmployeeCreate(BaseModel):
         description="Application access configuration"
     )
     
+    # System user flag
+    is_system_user: bool = Field(
+        default=False,
+        description="Whether to create a system user for this employee"
+    )
+    
     # Location tracking
     location_settings: LocationSettingsSchema = Field(
         default_factory=LocationSettingsSchema,
@@ -433,6 +439,7 @@ class EmployeeCreate(BaseModel):
                     "precision_level": "MEDIUM",
                     "location_retention_days": 90
                 },
+                "is_system_user": False,
                 "created_by": "admin_001"
             }
         }
@@ -457,6 +464,7 @@ class EmployeeUpdate(BaseModel):
     status: Optional[EmployeeStatus] = None
     app_access: Optional[AppAccessSchema] = None
     location_settings: Optional[LocationSettingsSchema] = None
+    is_system_user: Optional[bool] = None
     metadata: Optional[Dict[str, Any]] = None
 
     @field_validator("phone")
@@ -529,6 +537,7 @@ class EmployeeResponse(BaseModel):
     status: EmployeeStatus
     app_access: Dict[str, Any]
     location_settings: Dict[str, Any]
+    is_system_user: bool
     created_by: str
     created_at: str
     updated_at: Optional[str]
@@ -578,6 +587,7 @@ class EmployeeResponse(BaseModel):
                     "precision_level": "MEDIUM",
                     "location_retention_days": 90
                 },
+                "is_system_user": False,
                 "created_by": "admin_001",
                 "created_at": "2023-01-10T08:00:00Z",
                 "updated_at": "2024-11-24T10:00:00Z",

app/employees/services/service.py

@@ -18,6 +18,8 @@ from app.constants.employee_types import (
 )
 from app.employees.models.model import EmployeeModel
 from app.employees.schemas.schema import EmployeeCreate, EmployeeUpdate, EmployeeResponse
+from app.system_users.services.service import SystemUserService
+from app.system_users.schemas.schema import CreateUserRequest
 
 logger = get_logger(__name__)
 
@@ -291,6 +293,16 @@ class EmployeeService:
                 }
             )
             
+            # Create system user if is_system_user flag is true
+            if payload.is_system_user:
+                try:
+                    await EmployeeService._create_employee_system_user(user_id, payload)
+                    logger.info(f"Created system user for employee {user_id}")
+                except Exception as e:
+                    logger.error(f"Failed to create system user for employee {user_id}: {str(e)}")
+                    # Note: We don't fail the employee creation if system user creation fails
+                    # The employee record will still be created successfully
+            
             # Return response
             return EmployeeResponse(**employee_dict)
             
@@ -679,3 +691,65 @@ class EmployeeService:
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error fetching widget data"
             )
+
+    @staticmethod
+    async def _create_employee_system_user(employee_user_id: str, employee_payload: EmployeeCreate):
+        """
+        Create a system user for the newly created employee.
+        
+        Args:
+            employee_user_id: The employee's user_id
+            employee_payload: The employee creation payload
+        """
+        try:
+            # Initialize system user service
+            system_user_service = SystemUserService(get_database())
+            
+            # Generate username from employee code (lowercase, replace hyphens with underscores)
+            username = employee_payload.employee_code.lower().replace('-', '_')
+            
+            # Generate a temporary password (employee should change this on first login)
+            temp_password = f"Temp@{secrets.token_urlsafe(8)}"
+            
+            # Determine role_id based on designation (you may want to customize this mapping)
+            role_id = f"role_{employee_payload.designation.value.lower().replace(' ', '_')}"
+            
+            # Create system user request
+            system_user_request = CreateUserRequest(
+                username=username,
+                email=employee_payload.email,
+                merchant_id=employee_payload.created_by,  # Using created_by as merchant_id for now
+                password=temp_password,
+                full_name=f"{employee_payload.first_name} {employee_payload.last_name or ''}".strip(),
+                role_id=role_id,
+                is_active=True,
+                metadata={
+                    "employee_user_id": employee_user_id,
+                    "employee_code": employee_payload.employee_code,
+                    "designation": employee_payload.designation.value,
+                    "created_from": "employee_creation"
+                }
+            )
+            
+            # Create the system user
+            system_user = await system_user_service.create_user(
+                system_user_request, 
+                employee_payload.created_by
+            )
+            
+            logger.info(
+                f"System user created for employee",
+                extra={
+                    "employee_user_id": employee_user_id,
+                    "system_user_id": system_user.user_id,
+                    "username": username,
+                    "temp_password": temp_password  # In production, this should be sent via secure channel
+                }
+            )
+            
+        except Exception as e:
+            logger.error(
+                f"Error creating system user for employee {employee_user_id}",
+                exc_info=e
+            )
+            raise

test_employee_system_user_creation.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Test script to demonstrate employee creation with system user functionality.
+"""
+import asyncio
+import json
+from datetime import date
+from app.employees.services.service import EmployeeService
+from app.employees.schemas.schema import EmployeeCreate
+from app.constants.employee_types import Designation, EmployeeStatus
+from app.nosql import get_database
+from app.system_users.services.service import SystemUserService
+
+
+async def test_employee_with_system_user():
+    """Test creating an employee with is_system_user=True"""
+    
+    print("🧪 Testing Employee Creation with System User")
+    print("=" * 50)
+    
+    # Sample employee data with is_system_user=True
+    employee_data = EmployeeCreate(
+        employee_code="EMP-TEST-001",
+        first_name="John",
+        last_name="Doe",
+        email="john.doe@company.com",
+        phone="+919876543210",
+        designation=Designation.ASM,
+        base_city="Mumbai",
+        base_state="Maharashtra",
+        doj=date.today(),
+        emergency_contact={
+            "name": "Jane Doe",
+            "relation": "Spouse",
+            "phone": "+919876543211"
+        },
+        is_system_user=True,  # This will trigger system user creation
+        created_by="admin_001"
+    )
+    
+    try:
+        # Create employee (this should also create a system user)
+        print("📝 Creating employee with system user flag...")
+        employee = await EmployeeService.create_employee(employee_data)
+        
+        print(f"✅ Employee created successfully!")
+        print(f"   - User ID: {employee.user_id}")
+        print(f"   - Employee Code: {employee.employee_code}")
+        print(f"   - Name: {employee.first_name} {employee.last_name}")
+        print(f"   - Is System User: {employee.is_system_user}")
+        
+        # Check if system user was created
+        system_user_service = SystemUserService(get_database())
+        
+        # Look for system user with matching metadata
+        db = get_database()
+        system_user_doc = await db["scm_system_users"].find_one({
+            "metadata.employee_user_id": employee.user_id
+        })
+        
+        if system_user_doc:
+            print(f"✅ System user created successfully!")
+            print(f"   - System User ID: {system_user_doc['user_id']}")
+            print(f"   - Username: {system_user_doc['username']}")
+            print(f"   - Email: {system_user_doc['email']}")
+            print(f"   - Role ID: {system_user_doc['role_id']}")
+            print(f"   - Full Name: {system_user_doc['full_name']}")
+        else:
+            print("❌ System user was not created")
+            
+    except Exception as e:
+        print(f"❌ Error: {str(e)}")
+
+
+async def test_employee_without_system_user():
+    """Test creating an employee with is_system_user=False"""
+    
+    print("\n🧪 Testing Employee Creation without System User")
+    print("=" * 50)
+    
+    # Sample employee data with is_system_user=False (default)
+    employee_data = EmployeeCreate(
+        employee_code="EMP-TEST-002",
+        first_name="Alice",
+        last_name="Smith",
+        email="alice.smith@company.com",
+        phone="+919876543212",
+        designation=Designation.SALES_EXECUTIVE,
+        base_city="Delhi",
+        base_state="Delhi",
+        doj=date.today(),
+        emergency_contact={
+            "name": "Bob Smith",
+            "relation": "Spouse",
+            "phone": "+919876543213"
+        },
+        is_system_user=False,  # This will NOT create a system user
+        created_by="admin_001"
+    )
+    
+    try:
+        # Create employee (this should NOT create a system user)
+        print("📝 Creating employee without system user flag...")
+        employee = await EmployeeService.create_employee(employee_data)
+        
+        print(f"✅ Employee created successfully!")
+        print(f"   - User ID: {employee.user_id}")
+        print(f"   - Employee Code: {employee.employee_code}")
+        print(f"   - Name: {employee.first_name} {employee.last_name}")
+        print(f"   - Is System User: {employee.is_system_user}")
+        
+        # Check if system user was created (should not exist)
+        db = get_database()
+        system_user_doc = await db["scm_system_users"].find_one({
+            "metadata.employee_user_id": employee.user_id
+        })
+        
+        if system_user_doc:
+            print("❌ System user was created (unexpected)")
+        else:
+            print("✅ System user was not created (as expected)")
+            
+    except Exception as e:
+        print(f"❌ Error: {str(e)}")
+
+
+async def main():
+    """Main test function"""
+    print("🚀 Employee System User Integration Test")
+    print("=" * 60)
+    
+    await test_employee_with_system_user()
+    await test_employee_without_system_user()
+    
+    print("\n" + "=" * 60)
+    print("✨ Test completed!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())