docs/security/EMPLOYEE_SYSTEM_USER_INTEGRATION.md

# 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