app/system_users/models/model.py

"""System user document model for `scm_system_users` collection."""
from datetime import datetime
from typing import Optional, Dict, Any
from pydantic import BaseModel, Field, EmailStr
from enum import Enum


class UserStatus(str, Enum):
    """User account status options."""
    ACTIVE = "active"
    INACTIVE = "inactive"
    SUSPENDED = "suspended"
    LOCKED = "locked"
    PENDING_ACTIVATION = "pending_activation"


class SystemUserModel(BaseModel):
    """Represents a system user stored in MongoDB."""

    user_id: str = Field(..., description="Unique business identifier (e.g. usr_xxx)")
    username: str = Field(..., description="Unique username", min_length=3, max_length=50)
    email: EmailStr = Field(..., description="User email address")
    password_hash: str = Field(..., description="Bcrypt hashed password")
    full_name: Optional[str] = Field(None, description="Full name of the user")
    role_id: Optional[str] = Field(None, description="Role identifier e.g. role_distributor_manager")
    merchant_id: Optional[str] = Field(None, description="Owning merchant id")
    merchant_type: Optional[str] = Field(None, description="Merchant type (ncnf, cnf, distributor, retail)")
    status: UserStatus = Field(default=UserStatus.ACTIVE, description="Account status")
    last_login: Optional[datetime] = Field(None, description="Timestamp of last successful login")
    created_by: str = Field(..., description="User id who created this record")
    created_at: datetime = Field(default_factory=datetime.utcnow, description="Creation timestamp")
    updated_by: Optional[str] = Field(None, description="User id who last updated this record")
    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
    metadata: Optional[Dict[str, Any]] = Field(None, description="Optional metadata bag")

    class Config:
        json_schema_extra = {
            "example": {
                "user_id": "user_Ob1gQvSwV1o",
                "username": "distmanager_delhi",
                "email": "delhi.manager@premiumbeauty.com",
                "password_hash": "b308f5bfd37e72c3d3a63d218000f0bf1eaf4efa7d11eaf9e61f76b88462d3f8",
                "full_name": "Vikram Singh",
                "role_id": "role_distributor_manager",
                "merchant_id": "dist_delhi_premium",
                "status": "active",
                "last_login": None,
                "created_by": "user_company_admin",
                "created_at": "2025-11-30T16:52:33.902Z"
            }
        }