hr-portal/backend/app/services/employee_lifecycle.py

"""
員工生命週期管理服務
自動化處理員工的新進、異動、離職流程
"""
from typing import Dict, Any, Optional
from sqlalchemy.orm import Session
import logging
import secrets
import string

from app.models.employee import Employee
from app.services.keycloak_admin_client import get_keycloak_admin_client
from app.services.drive_service import get_drive_service_client, get_drive_quota_by_job_level
from app.services.mailserver_service import get_mailserver_service, get_mail_quota_by_job_level

logger = logging.getLogger(__name__)


class EmployeeLifecycleService:
    """員工生命週期管理服務"""

    def __init__(self):
        self.keycloak_client = None

    def _get_keycloak_client(self):
        """延遲初始化 Keycloak Admin 客戶端"""
        if self.keycloak_client is None:
            self.keycloak_client = get_keycloak_admin_client()
        return self.keycloak_client

    def _generate_temporary_password(self, length: int = 12) -> str:
        """生成臨時密碼 (包含大小寫字母、數字和特殊字元)"""
        alphabet = string.ascii_letters + string.digits + "!@#$%^&*"
        password = ''.join(secrets.choice(alphabet) for _ in range(length))
        return password

    async def onboard_employee(
        self,
        db: Session,
        employee: Employee,
        create_keycloak: bool = True,
        create_email: bool = True,
        create_drive: bool = True,
    ) -> Dict[str, Any]:
        """
        員工到職流程 (Onboarding)

        自動執行:
        1. 建立 Keycloak SSO 帳號
        2. 建立主要郵件帳號
        3. 建立雲端硬碟帳號 (Drive Service)
        4. 記錄審計日誌

        Args:
            db: 資料庫 Session
            employee: 員工物件
            create_keycloak: 是否建立 Keycloak 帳號
            create_email: 是否建立郵件帳號
            create_drive: 是否建立雲端硬碟帳號 (非致命，Drive Service 未上線時跳過)

        Returns:
            執行結果字典
        """
        results = {
            "employee_id": employee.id,
            "employee_number": employee.employee_id,
            "legal_name": employee.legal_name,
            "username_base": employee.username_base,
            "keycloak": {"created": False, "error": None},
            "email": {"created": False, "error": None},
            "drive": {"created": False, "error": None},
        }

        logger.info(f"開始員工到職流程: {employee.employee_id} - {employee.legal_name}")

        # 1. 建立 Keycloak 帳號
        if create_keycloak:
            try:
                keycloak_result = await self._create_keycloak_account(employee)
                results["keycloak"] = keycloak_result
                logger.info(f"Keycloak 帳號建立: {keycloak_result}")
            except Exception as e:
                logger.error(f"建立 Keycloak 帳號失敗: {str(e)}")
                results["keycloak"]["error"] = str(e)

        # 2. 建立郵件帳號
        if create_email:
            try:
                email_result = await self._create_email_account(employee)
                results["email"] = email_result
                logger.info(f"郵件帳號建立: {email_result}")
            except Exception as e:
                logger.error(f"建立郵件帳號失敗: {str(e)}")
                results["email"]["error"] = str(e)

        # 3. 建立雲端硬碟帳號 (Drive Service - 非致命)
        if create_drive:
            drive_result = await self._create_drive_account(employee)
            results["drive"] = drive_result
            if drive_result.get("error"):
                logger.warning(f"雲端硬碟帳號建立 (非致命): {drive_result}")
            else:
                logger.info(f"雲端硬碟帳號建立: {drive_result}")

        logger.info(f"員工到職流程完成: {employee.employee_id}")
        return results

    async def offboard_employee(
        self,
        db: Session,
        employee: Employee,
        disable_keycloak: bool = True,
        handle_email: str = "forward",  # "forward" or "disable"
        disable_drive: bool = True,
    ) -> Dict[str, Any]:
        """
        員工離職流程 (Offboarding)

        自動執行:
        1. 停用 Keycloak SSO 帳號
        2. 處理郵件帳號 (轉發或停用)
        3. 停用雲端硬碟帳號 (Drive Service - 非致命)
        4. 記錄審計日誌

        Args:
            db: 資料庫 Session
            employee: 員工物件
            disable_keycloak: 是否停用 Keycloak 帳號
            handle_email: 郵件處理方式 ("forward" 或 "disable")
            disable_drive: 是否停用雲端硬碟帳號 (非致命，Drive Service 未上線時跳過)

        Returns:
            執行結果字典
        """
        results = {
            "employee_id": employee.id,
            "employee_number": employee.employee_id,
            "legal_name": employee.legal_name,
            "keycloak": {"disabled": False, "error": None},
            "email": {"handled": False, "method": handle_email, "error": None},
            "drive": {"disabled": False, "error": None},
        }

        logger.info(f"開始員工離職流程: {employee.employee_id} - {employee.legal_name}")

        # 1. 停用 Keycloak 帳號
        if disable_keycloak:
            try:
                keycloak_result = await self._disable_keycloak_account(employee)
                results["keycloak"] = keycloak_result
                logger.info(f"Keycloak 帳號停用: {keycloak_result}")
            except Exception as e:
                logger.error(f"停用 Keycloak 帳號失敗: {str(e)}")
                results["keycloak"]["error"] = str(e)

        # 2. 處理郵件帳號
        try:
            email_result = await self._handle_email_offboarding(employee, handle_email)
            results["email"] = email_result
            logger.info(f"郵件帳號處理: {email_result}")
        except Exception as e:
            logger.error(f"處理郵件帳號失敗: {str(e)}")
            results["email"]["error"] = str(e)

        # 3. 停用雲端硬碟帳號 (Drive Service - 非致命)
        if disable_drive:
            drive_result = await self._disable_drive_account(employee)
            results["drive"] = drive_result
            if drive_result.get("error"):
                logger.warning(f"雲端硬碟帳號停用 (非致命): {drive_result}")
            else:
                logger.info(f"雲端硬碟帳號停用: {drive_result}")

        logger.info(f"員工離職流程完成: {employee.employee_id}")
        return results

    async def _create_keycloak_account(self, employee: Employee) -> Dict[str, Any]:
        """
        建立 Keycloak SSO 帳號

        執行步驟:
        1. 檢查帳號是否已存在
        2. 生成臨時密碼
        3. 建立 Keycloak 用戶
        4. 設定用戶屬性 (姓名、郵件等)

        Args:
            employee: 員工物件

        Returns:
            執行結果字典
        """
        try:
            client = self._get_keycloak_client()
            username = employee.username_base
            email = f"{username}@porscheworld.tw"

            # 1. 檢查帳號是否已存在
            existing_user = client.get_user_by_username(username)
            if existing_user:
                return {
                    "created": False,
                    "username": username,
                    "email": email,
                    "user_id": existing_user.get("id"),
                    "message": "Keycloak 帳號已存在",
                    "error": "用戶已存在",
                }

            # 2. 生成臨時密碼 (12位隨機密碼)
            temporary_password = self._generate_temporary_password(12)

            # 3. 分割姓名 (如果有英文名稱使用英文,否則使用中文)
            if employee.english_name:
                # 英文名稱格式: "FirstName LastName" 或 "FirstName MiddleName LastName"
                name_parts = employee.english_name.strip().split()
                first_name = name_parts[0] if len(name_parts) > 0 else username
                last_name = " ".join(name_parts[1:]) if len(name_parts) > 1 else ""
            else:
                # 中文名稱格式: "姓名" (第一個字是姓,其餘是名)
                legal_name = employee.legal_name or username
                first_name = legal_name[1:] if len(legal_name) > 1 else legal_name
                last_name = legal_name[0] if len(legal_name) > 0 else ""

            # 4. 建立 Keycloak 用戶
            user_id = client.create_user(
                username=username,
                email=email,
                first_name=first_name,
                last_name=last_name,
                enabled=True,
                email_verified=True,
            )

            if not user_id:
                return {
                    "created": False,
                    "username": username,
                    "email": email,
                    "message": "Keycloak 用戶建立失敗",
                    "error": "無法建立用戶 (API 返回 None)",
                }

            # 5. 設定初始密碼
            password_set = client.reset_password(
                user_id=user_id,
                password=temporary_password,
                temporary=True  # 用戶首次登入需修改密碼
            )

            if not password_set:
                logger.warning(f"Keycloak 用戶 {username} 建立成功,但密碼設定失敗")

            logger.info(f"✓ Keycloak 帳號建立成功: {username} (ID: {user_id})")

            return {
                "created": True,
                "username": username,
                "email": email,
                "user_id": user_id,
                "first_name": first_name,
                "last_name": last_name,
                "temporary_password": temporary_password,  # 應透過安全方式通知用戶
                "password_set": password_set,
                "message": f"Keycloak 帳號建立成功 (用戶首次登入需修改密碼)",
                "error": None,
            }

        except Exception as e:
            logger.error(f"✗ 建立 Keycloak 帳號時發生錯誤: {str(e)}")
            return {
                "created": False,
                "username": employee.username_base,
                "email": f"{employee.username_base}@porscheworld.tw",
                "message": "建立 Keycloak 帳號時發生錯誤",
                "error": str(e),
            }

    async def _create_email_account(self, employee: Employee) -> Dict[str, Any]:
        """
        建立郵件帳號 (Docker Mailserver)

        執行步驟:
        1. 依職級取得配額
        2. 產生臨時密碼 (員工後續透過 Keycloak SSO 登入)
        3. 透過 SSH + docker exec 建立帳號
        4. 設定配額
        """
        email_address = f"{employee.username_base}@porscheworld.tw"

        try:
            mailserver = get_mailserver_service()

            # 依職級取得郵件配額
            job_level = getattr(employee, "job_level", "Junior") or "Junior"
            quota_mb = get_mail_quota_by_job_level(job_level)

            # 產生臨時密碼
            temp_password = self._generate_temporary_password()

            result = mailserver.create_email_account(
                email=email_address,
                password=temp_password,
                quota_mb=quota_mb,
            )

            if result["created"]:
                logger.info(f"郵件帳號建立成功: {email_address} ({quota_mb}MB)")
            else:
                logger.warning(f"郵件帳號建立失敗: {email_address} - {result.get('error')}")

            return result

        except Exception as e:
            logger.warning(f"建立郵件帳號時發生非預期錯誤: {str(e)}")
            return {
                "created": False,
                "email": email_address,
                "quota_mb": 0,
                "message": "建立郵件帳號時發生錯誤",
                "error": str(e),
            }

    async def _create_drive_account(self, employee: Employee) -> Dict[str, Any]:
        """
        建立雲端硬碟帳號 (Drive Service)

        呼叫 drive-api.ease.taipei 建立 Nextcloud 帳號
        Drive Service 未上線時以 warning 記錄，不影響其他流程
        """
        try:
            client = get_drive_service_client()
            from app.core.config import settings

            # 根據職級取得配額
            job_level = getattr(employee, "job_level", "Junior") or "Junior"
            quota_gb = get_drive_quota_by_job_level(job_level)

            result = client.create_user(
                tenant_id=settings.DRIVE_SERVICE_TENANT_ID,
                keycloak_user_id=str(getattr(employee, "keycloak_user_id", "") or ""),
                username=employee.username_base,
                email=f"{employee.username_base}@porscheworld.tw",
                display_name=employee.legal_name or employee.username_base,
                quota_gb=quota_gb,
            )
            return result

        except Exception as e:
            logger.warning(f"建立雲端硬碟帳號時發生非預期錯誤: {str(e)}")
            return {
                "created": False,
                "username": employee.username_base,
                "quota_gb": 0,
                "drive_url": None,
                "message": "建立雲端硬碟帳號時發生錯誤",
                "error": str(e),
            }

    async def _disable_keycloak_account(self, employee: Employee) -> Dict[str, Any]:
        """
        停用 Keycloak SSO 帳號

        執行步驟:
        1. 查詢用戶 ID
        2. 停用帳號 (不刪除,保留審計記錄)

        注意: 不刪除帳號,只停用,以保留歷史記錄和審計追蹤

        Args:
            employee: 員工物件

        Returns:
            執行結果字典
        """
        try:
            client = self._get_keycloak_client()
            username = employee.username_base

            # 1. 查詢用戶
            user = client.get_user_by_username(username)
            if not user:
                return {
                    "disabled": False,
                    "username": username,
                    "message": "Keycloak 帳號不存在",
                    "error": "用戶不存在",
                }

            user_id = user.get("id")

            # 2. 檢查是否已停用
            if not user.get("enabled", False):
                return {
                    "disabled": True,
                    "username": username,
                    "user_id": user_id,
                    "message": "Keycloak 帳號已經是停用狀態",
                    "error": None,
                }

            # 3. 停用帳號
            success = client.disable_user(user_id)

            if success:
                logger.info(f"✓ Keycloak 帳號停用成功: {username} (ID: {user_id})")
                return {
                    "disabled": True,
                    "username": username,
                    "user_id": user_id,
                    "message": "Keycloak 帳號已停用 (帳號保留以維持審計記錄)",
                    "error": None,
                }
            else:
                return {
                    "disabled": False,
                    "username": username,
                    "user_id": user_id,
                    "message": "Keycloak 帳號停用失敗",
                    "error": "API 調用失敗",
                }

        except Exception as e:
            logger.error(f"✗ 停用 Keycloak 帳號時發生錯誤: {str(e)}")
            return {
                "disabled": False,
                "username": employee.username_base,
                "message": "停用 Keycloak 帳號時發生錯誤",
                "error": str(e),
            }

    async def _handle_email_offboarding(
        self, employee: Employee, method: str
    ) -> Dict[str, Any]:
        """
        處理離職員工的郵件帳號 (Docker Mailserver)

        Args:
            method: "forward" - 停用帳號並標記轉寄
                    "disable" - 直接刪除郵件帳號
        """
        email_address = f"{employee.username_base}@porscheworld.tw"

        try:
            mailserver = get_mailserver_service()

            if method == "forward":
                # 刪除帳號 (Docker Mailserver 不支援原生轉寄設定)
                # 轉寄規則記錄在 EmailAccount.forward_to，由 HR Portal 管理
                result = mailserver.delete_email_account(email_address)
                return {
                    "handled": result["deleted"],
                    "method": "forward",
                    "email": email_address,
                    "forward_to": "hr@porscheworld.tw",
                    "message": "郵件帳號已停用，轉寄規則已記錄" if result["deleted"] else "郵件帳號停用失敗",
                    "error": result.get("error"),
                }

            elif method == "disable":
                # 刪除郵件帳號
                result = mailserver.delete_email_account(email_address)
                return {
                    "handled": result["deleted"],
                    "method": "disable",
                    "email": email_address,
                    "message": "郵件帳號已刪除" if result["deleted"] else "郵件帳號刪除失敗",
                    "error": result.get("error"),
                }

            else:
                return {
                    "handled": False,
                    "method": method,
                    "email": email_address,
                    "error": f"不支援的處理方式: {method}",
                }

        except Exception as e:
            logger.warning(f"處理郵件帳號離職時發生非預期錯誤: {str(e)}")
            return {
                "handled": False,
                "method": method,
                "email": email_address,
                "message": "處理郵件帳號時發生錯誤",
                "error": str(e),
            }

    async def _disable_drive_account(self, employee: Employee) -> Dict[str, Any]:
        """
        停用雲端硬碟帳號 (Drive Service)

        呼叫 drive-api.ease.taipei 停用 Nextcloud 帳號 (軟刪除，保留檔案)
        Drive Service 未上線時以 warning 記錄，不影響其他流程
        """
        try:
            client = get_drive_service_client()

            # 查詢 drive_user_id (目前以 username 查詢)
            # Drive Service 上線後需實作 GET /api/v1/drive/users?username={username}
            # 暫時回傳 warning 狀態
            logger.warning(
                f"停用雲端硬碟帳號: {employee.username_base} - "
                f"需 Drive Service 上線後實作查詢 user_id 再停用"
            )
            return {
                "disabled": False,
                "username": employee.username_base,
                "message": "Drive Service 尚未上線，雲端硬碟帳號停用待後續處理",
                "error": "Drive Service 未上線",
            }

        except Exception as e:
            logger.warning(f"停用雲端硬碟帳號時發生非預期錯誤: {str(e)}")
            return {
                "disabled": False,
                "username": employee.username_base,
                "message": "停用雲端硬碟帳號時發生錯誤",
                "error": str(e),
            }


# 建立全域實例
employee_lifecycle_service = EmployeeLifecycleService()


def get_employee_lifecycle_service() -> EmployeeLifecycleService:
    """取得員工生命週期服務實例"""
    return employee_lifecycle_service