suprema-biostar-mcp 1.0.1__py3-none-any.whl

biostar_x_mcp_server/handlers/user_handler.py

@@ -0,0 +1,3568 @@
+import logging
+import json
+from typing import Sequence, Dict, Any, List, Optional, Tuple
+from mcp.types import TextContent
+import httpx
+from pydantic import ValidationError
+import os
+import platform
+import shutil
+import asyncio
+from pathlib import Path
+import csv
+import io
+import tempfile
+import re
+import base64
+
+from .base_handler import BaseHandler
+from ..schemas import (
+    CreateUserInput,
+    DeleteUserInput,
+    UpdateUserInput,
+    AdvancedSearchUserInput,
+    ExportCSVInput,
+    BulkAddUsersInput,
+    ToolResponse,
+    BulkEditUsersInput,
+)
+from ..utils.search import search_users_by_name
+
+logger = logging.getLogger(__name__)
+
+
+def parse_flexible_date(date_input: Any, is_start: bool = True) -> str:
+    """
+    다양한 날짜 포맷을 ISO 8601 형식으로 변환합니다.
+    
+    지원 포맷:
+    - 20251225
+    - 2025-12-25
+    - 12.25.2025
+    - 25.12.2025
+    - 2025/12/25
+    - 12/25/2025
+    - 25/12/2025
+    - 2025.12.25
+    
+    Args:
+        date_input: 변환할 날짜 (문자열 또는 숫자)
+        is_start: True이면 시작 시간(00:00:00), False이면 종료 시간(23:59:00)
+    
+    Returns:
+        ISO 8601 형식의 날짜 문자열 (예: "2025-12-25T00:00:00.00Z")
+    """
+    from datetime import datetime
+    import re
+    
+    if not date_input:
+        return None
+    
+    # Return as-is if already in ISO format
+    date_str = str(date_input).strip()
+    if re.match(r'\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}', date_str):
+        return date_str
+    
+    # Extract digits only
+    digits_only = re.sub(r'[^\d]', '', date_str)
+    
+    year, month, day = None, None, None
+    
+    try:
+        # YYYYMMDD 형식 (8자리 숫자)
+        if len(digits_only) == 8:
+            year = int(digits_only[0:4])
+            month = int(digits_only[4:6])
+            day = int(digits_only[6:8])
+        
+        # 구분자가 있는 경우
+        elif '/' in date_str or '.' in date_str or '-' in date_str:
+            # 구분자로 분리
+            parts = re.split(r'[/.\-]', date_str)
+            parts = [p for p in parts if p]  # 빈 문자열 제거
+            
+            if len(parts) == 3:
+                p1, p2, p3 = int(parts[0]), int(parts[1]), int(parts[2])
+                
+                # YYYY-MM-DD 또는 YYYY/MM/DD 또는 YYYY.MM.DD
+                if p1 > 1900:
+                    year, month, day = p1, p2, p3
+                # DD-MM-YYYY 또는 DD/MM/YYYY 또는 DD.MM.YYYY (일이 12보다 크면 확실)
+                elif p1 > 12:
+                    day, month, year = p1, p2, p3
+                # MM-DD-YYYY 또는 MM/DD/YYYY 또는 MM.DD.YYYY (두번째가 12보다 크면 확실)
+                elif p2 > 12:
+                    month, day, year = p1, p2, p3
+                # 애매한 경우: 기본적으로 MM/DD/YYYY로 가정
+                else:
+                    month, day, year = p1, p2, p3
+                
+                # 연도가 2자리인 경우 20XX로 변환
+                if year < 100:
+                    year += 2000
+        
+        if year and month and day:
+            # 유효한 날짜인지 확인
+            dt = datetime(year, month, day)
+            time_part = "T00:00:00.00Z" if is_start else "T23:59:00.00Z"
+            return f"{year:04d}-{month:02d}-{day:02d}{time_part}"
+    
+    except (ValueError, IndexError) as e:
+        logger.warning(f"Date parsing failed: {date_input}, error: {e}")
+    
+    # Return default value if parsing fails
+    return "2001-01-01T00:00:00.00Z" if is_start else "2030-12-31T23:59:00.00Z"
+
+
+class UserHandler(BaseHandler):
+    """Handle user-related operations."""
+    
+    # Static helper methods (for internal use)
+    @staticmethod
+    def _format_pin_from_phone_static(phone: str) -> str:
+        """Internal helper: Extract last 8 digits from phone number for PIN."""
+        digits_only = ''.join(c for c in phone if c.isdigit())
+        if len(digits_only) >= 8:
+            return digits_only[-8:]
+        else:
+            return digits_only.zfill(8)
+    
+    @staticmethod
+    def _format_phone_number_static(phone: str) -> str:
+        """Internal helper: Format phone number (digits only)."""
+        return ''.join(c for c in phone if c.isdigit())
+    
+    @staticmethod
+    def _format_datetime_range_static(date_str: str) -> Tuple[str, str]:
+        """Internal helper: Convert date string to BioStar datetime range."""
+        date_clean = date_str.strip()
+        start_datetime = f"{date_clean}T00:00:00.00Z"
+        end_datetime = f"{date_clean}T23:59:00.00Z"
+        return start_datetime, end_datetime
+    
+    # Tool methods (async, for AI to call)
+    async def format_pin_from_phone(self, phone: str) -> Sequence[TextContent]:
+        """
+        Extract last 8 digits from phone number for PIN.
+        Removes all non-numeric characters.
+        
+        Example:
+            "1) 415-732-9042" → "73290426" (last 8 digits)
+            "82) 10-9348-5721" → "93485721"
+        """
+        pin = self._format_pin_from_phone_static(phone)
+        return [TextContent(
+            type="text",
+            text=json.dumps({
+                "success": True,
+                "input_phone": phone,
+                "output_pin": pin,
+                "message": f"Extracted PIN: {pin} (last 8 digits of phone)"
+            }, indent=2)
+        )]
+    
+    async def format_phone_number(self, phone: str) -> Sequence[TextContent]:
+        """
+        Format phone number for BioStar (digits only).
+        Removes all non-numeric characters including hyphens, parentheses, spaces.
+        
+        Example:
+            "1) 415-732-9042" → "14157329042"
+            "82) 10-9348-5721" → "821093485721"
+        """
+        cleaned = self._format_phone_number_static(phone)
+        return [TextContent(
+            type="text",
+            text=json.dumps({
+                "success": True,
+                "input_phone": phone,
+                "output_phone": cleaned,
+                "message": f"Cleaned phone number: {cleaned}"
+            }, indent=2)
+        )]
+    
+    async def format_datetime_range(self, date_str: str) -> Sequence[TextContent]:
+        """
+        Convert date string to BioStar datetime range format.
+        
+        Args:
+            date_str: Date in format "2025-12-25" or "2025-12-25"
+        
+        Returns:
+            JSON with start_datetime and end_datetime in ISO format
+            
+        Example:
+            "2025-12-25" → {"start": "2025-12-25T00:00:00.00Z", "end": "2025-12-25T23:59:00.00Z"}
+        """
+        start, end = self._format_datetime_range_static(date_str)
+        return [TextContent(
+            type="text",
+            text=json.dumps({
+                "success": True,
+                "input_date": date_str,
+                "start_datetime": start,
+                "end_datetime": end,
+                "message": f"Formatted date range for {date_str}"
+            }, indent=2)
+        )]
+    
+    async def get_users(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get list of users."""
+        try:
+            self.check_auth()
+            
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/users",
+                    headers=headers
+                )
+            
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+            
+            data = response.json()
+            users = data.get("UserCollection", {}).get("rows", [])
+            
+            if not users:
+                return self.success_response({
+                    "message": "No users found",
+                    "users": []
+                })
+            
+            return self.success_response({
+                "message": f"Found {len(users)} users",
+                "total": len(users),
+                "users": [{"user_id": u["user_id"], "name": u["name"]} for u in users]
+            })
+            
+        except Exception as e:
+            return await self.handle_api_error(e)
+    
+    async def create_user(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Create a new user."""
+        try:
+            self.check_auth()
+            
+            # Validate input
+            try:
+                input_data = CreateUserInput(**args)
+            except ValidationError as e:
+                return self.handle_validation_error(e)
+            
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            
+            async with httpx.AsyncClient(verify=False) as client:
+                # Get next user ID
+                next_id_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/users/next_user_id",
+                    headers=headers
+                )
+                
+
+                if next_id_resp.status_code != 200:
+                    return self.error_response(f"Failed to get user ID: {next_id_resp.status_code}")
+                
+                user_id = next_id_resp.json()["User"]["user_id"]
+                
+                # Build user data
+                user_data = {
+                    "User": {
+                        "user_id": str(user_id),
+                        "user_group_id": {"id": 1},
+                        "start_datetime": "2001-01-01T00:00:00.00Z",
+                        "expiry_datetime": "2030-12-31T23:59:00.00Z",
+                        "name": input_data.name
+                    }
+                }
+                
+                # Add optional fields (passed as-is from AI/user)
+                if input_data.email:
+                    user_data["User"]["email"] = input_data.email
+                if input_data.department:
+                    user_data["User"]["department"] = input_data.department
+                if input_data.phone:
+                    user_data["User"]["phone"] = input_data.phone
+                if input_data.user_title:
+                    user_data["User"]["user_title"] = input_data.user_title
+                if input_data.disabled is not None:
+                    user_data["User"]["disabled"] = input_data.disabled
+                if input_data.access_groups:
+                    user_data["User"]["access_groups"] = input_data.access_groups
+                if input_data.pin is not None:
+                    user_data["User"]["pin"] = input_data.pin
+                
+                # Create user
+                create_resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/users",
+                    headers=headers,
+                    json=user_data
+                )
+                
+                if create_resp.status_code != 200:
+                    return self.error_response(
+                        f"Failed to create user: {create_resp.status_code}, {create_resp.text}"
+                    )
+                
+                return self.success_response({
+                    "message": f"User {input_data.name} created successfully with ID {user_id}",
+                    "user_id": user_id,
+                    "name": input_data.name
+                })
+                
+        except Exception as e:
+            return await self.handle_api_error(e)
+    
+    async def get_user(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get specific user details."""
+        try:
+            self.check_auth()
+            
+            user_id = args.get("user_id")
+            if not user_id:
+                return self.error_response("user_id is required")
+            
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/users/{user_id}",
+                    headers=headers
+                )
+            
+            if response.status_code != 200:
+                return self.error_response(f"Failed to get user: {response.status_code}")
+            
+            user_data = response.json().get("User", {})
+            
+            return self.success_response({
+                "user": user_data
+            })
+            
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_user(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Update an existing user (preserve current group/period unless explicitly changed)."""
+        try:
+            self.check_auth()
+
+            # ① Validate
+            try:
+                input_data = UpdateUserInput(**args)
+            except ValidationError as e:
+                return self.handle_validation_error(e)
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            provided = getattr(input_data, "model_fields_set", None) or getattr(input_data, "__fields_set__", set())
+            def is_provided(field: str) -> bool:
+                return field in provided
+
+            user_id = input_data.user_id
+            if not user_id and input_data.name:
+                users = await search_users_by_name(self.get_session_id(), input_data.name)
+                if not users:
+                    return self.error_response(f"No user found with name '{input_data.name}'")
+                if len(users) > 1:
+                    return self.error_response(f"Multiple users found with name '{input_data.name}'. Please specify user_id.")
+                user_id = users[0]["user_id"]
+            if not user_id:
+                return self.error_response("Either user_id or name is required")
+            user_id = str(user_id)
+
+            async with httpx.AsyncClient(verify=False) as client:
+                cur_resp = await client.get(f"{self.session.config.biostar_url}/api/users/{user_id}", headers=headers)
+            if cur_resp.status_code != 200:
+                return self.error_response(f"Failed to get user: {cur_resp.status_code} - {cur_resp.text}")
+
+            cur_user = (cur_resp.json() or {}).get("User", {}) or {}
+
+            def _to_iso(val: Any, fallback: str) -> str:
+                if isinstance(val, str) and val:
+                    return val
+                if isinstance(val, (int, float)) and val > 0:
+                    from datetime import datetime, timezone
+                    try:
+                        return datetime.fromtimestamp(val/1000.0, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+                    except Exception:
+                        pass
+                return fallback
+
+            cur_gid = None
+            ug = cur_user.get("user_group_id")
+            if isinstance(ug, dict) and ug.get("id") is not None:
+                try:
+                    cur_gid = int(str(ug["id"]))
+                except Exception:
+                    cur_gid = None
+
+            if is_provided("user_group_id"):
+                try:
+                    gid = int(input_data.user_group_id) if input_data.user_group_id is not None else None
+                except Exception:
+                    return self.error_response("Invalid 'user_group_id'. Must be numeric.")
+                if gid is None:
+                    return self.error_response("'user_group_id' cannot be null when provided.")
+            else:
+                if cur_gid is None:
+                    return self.error_response("Current user_group_id missing on server; cannot preserve safely.")
+                gid = cur_gid
+
+            # 날짜 처리: start_date/end_date alias 지원 및 flexible format 파싱
+            start_val = None
+            expiry_val = None
+            
+            # start_datetime 또는 start_date 처리
+            if is_provided("start_datetime") and input_data.start_datetime:
+                start_val = parse_flexible_date(input_data.start_datetime, is_start=True)
+            elif is_provided("start_date") and input_data.start_date:
+                start_val = parse_flexible_date(input_data.start_date, is_start=True)
+            else:
+                start_val = _to_iso(cur_user.get("start_datetime"), "2001-01-01T00:00:00.00Z")
+            
+            # expiry_datetime 또는 end_date 처리
+            if is_provided("expiry_datetime") and input_data.expiry_datetime:
+                expiry_val = parse_flexible_date(input_data.expiry_datetime, is_start=False)
+            elif is_provided("end_date") and input_data.end_date:
+                expiry_val = parse_flexible_date(input_data.end_date, is_start=False)
+            else:
+                expiry_val = _to_iso(cur_user.get("expiry_datetime"), "2030-12-31T23:59:00.00Z")
+
+            user_body: Dict[str, Any] = {
+                "name": (input_data.new_name or cur_user.get("name") or input_data.name or ""),
+                "user_group_id": {"id": gid},
+                "start_datetime": start_val,
+                "expiry_datetime": expiry_val,
+            }
+
+            if is_provided("email"):
+                user_body["email"] = input_data.email
+            if is_provided("department"):
+                user_body["department"] = input_data.department
+            if is_provided("phone"):
+                user_body["phone"] = input_data.phone
+            if is_provided("user_title"):
+                user_body["user_title"] = input_data.user_title
+            if is_provided("disabled"):
+                user_body["disabled"] = input_data.disabled
+            if is_provided("pin"):
+                user_body["pin"] = input_data.pin
+            
+            # 액세스 그룹 처리: ID 또는 이름으로 지정 가능
+            if is_provided("access_groups") and input_data.access_groups is not None:
+                user_body["access_groups"] = [{"id": str(g)} for g in input_data.access_groups]
+            elif is_provided("access_group_names") and input_data.access_group_names is not None:
+                # 액세스 그룹 이름으로 ID 찾기
+                async with httpx.AsyncClient(verify=False, timeout=30) as client:
+                    ag_resp = await client.post(
+                        f"{self.session.config.biostar_url}/api/v2/access_groups",
+                        headers=headers,
+                        json={"limit": 0, "order_by": "id:false"}
+                    )
+                    
+                if ag_resp.status_code == 200:
+                    ag_data = ag_resp.json()
+                    ag_rows = ((ag_data.get("AccessGroupCollection") or {}).get("rows") or [])
+                    ag_name_to_obj = {}
+                    for ag in ag_rows:
+                        name = str(ag.get("name") or "").strip()
+                        ag_id = ag.get("id")
+                        if name and ag_id is not None:
+                            ag_name_to_obj[name.lower()] = {"id": ag_id, "name": name}
+                    
+                    # 이름으로 ID 찾기
+                    access_groups = []
+                    not_found = []
+                    for ag_name in input_data.access_group_names:
+                        ag_name_lower = ag_name.strip().lower()
+                        if ag_name_lower in ag_name_to_obj:
+                            ag_obj = ag_name_to_obj[ag_name_lower]
+                            access_groups.append({"id": str(ag_obj["id"]), "name": ag_obj["name"]})
+                        else:
+                            not_found.append(ag_name)
+                    
+                    if not_found:
+                        return self.error_response(
+                            f"액세스 그룹을 찾을 수 없습니다: {', '.join(not_found)}",
+                            {"available_groups": [obj["name"] for obj in ag_name_to_obj.values()]}
+                        )
+                    
+                    user_body["access_groups"] = access_groups
+                else:
+                    return self.error_response(f"Failed to fetch access groups: {ag_resp.status_code}")
+
+            payload = {"User": user_body}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.put(
+                    f"{self.session.config.biostar_url}/api/users/{user_id}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if response.status_code == 200:
+                # Verify the update by fetching the user again
+                async with httpx.AsyncClient(verify=False) as client:
+                    verify_resp = await client.get(
+                        f"{self.session.config.biostar_url}/api/users/{user_id}",
+                        headers=headers
+                    )
+                
+                updated_user = {}
+                if verify_resp.status_code == 200:
+                    updated_user = (verify_resp.json() or {}).get("User", {}) or {}
+                
+                return self.success_response({
+                    "message": f" User {user_id} updated successfully and verified",
+                    "user_id": user_id,
+                    "before": {
+                        "name": cur_user.get("name"),
+                        "user_group": cur_user.get("user_group_id", {}).get("name") if isinstance(cur_user.get("user_group_id"), dict) else None,
+                        "email": cur_user.get("email"),
+                        "department": cur_user.get("department"),
+                        "phone": cur_user.get("phone"),
+                    },
+                    "after": {
+                        "name": updated_user.get("name"),
+                        "user_group": updated_user.get("user_group_id", {}).get("name") if isinstance(updated_user.get("user_group_id"), dict) else None,
+                        "email": updated_user.get("email"),
+                        "department": updated_user.get("department"),
+                        "phone": updated_user.get("phone"),
+                    },
+                    "request_body": payload
+                })
+            else:
+                return self.error_response(
+                    f"Failed to update user: {response.status_code} - {response.text}",
+                    {"request_body": payload}
+                )
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+    
+    async def delete_user(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Delete one or more users."""
+        try:
+            self.check_auth()
+            
+            # Validate input
+            try:
+                input_data = DeleteUserInput(**args)
+            except ValidationError as e:
+                return self.handle_validation_error(e)
+            
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            
+            deleted_users = []
+            failed_users = []
+            
+            async with httpx.AsyncClient(verify=False) as client:
+                if not input_data.id and input_data.name:
+                    # Search by name
+                    users = await search_users_by_name(self.get_session_id(), input_data.name)
+                    if not users:
+                        return self.error_response(f"No users found with name '{input_data.name}'")
+                    
+                    # CRITICAL SAFETY CHECK: If multiple users matched, require explicit confirmation
+                    if len(users) > 1 and not input_data.confirm_multiple:
+                        return self.error_response(
+                            f" SAFETY CHECK: Found {len(users)} users matching '{input_data.name}'. "
+                            f"To delete multiple users, please confirm by setting 'confirm_multiple=true'.",
+                            {
+                                "matched_users": users,
+                                "count": len(users),
+                                "requires_confirmation": True,
+                                "instruction": "Add 'confirm_multiple=true' to your request to proceed with deletion."
+                            }
+                        )
+                    
+                    user_ids = [user["user_id"] for user in users]
+                    user_names = {user["user_id"]: user["name"] for user in users}
+                    
+                    delete_param = "+".join(str(uid) for uid in user_ids)
+                    response = await client.delete(
+                        f"{self.session.config.biostar_url}/api/users",
+                        headers=headers,
+                        params={"id": delete_param, "group_id": "1"}
+                    )
+                    
+                    if response.status_code == 200:
+                        deleted_users = [{"user_id": uid, "name": user_names[uid]} for uid in user_ids]
+                    else:
+                        failed_users = [
+                            {"user_id": uid, "name": user_names[uid], "reason": response.text}
+                            for uid in user_ids
+                        ]
+                
+                elif input_data.id:
+                    # Delete by ID
+                    id_list = input_data.id if isinstance(input_data.id, list) else [input_data.id]
+                    delete_param = "+".join(str(uid) for uid in id_list)
+                    
+                    response = await client.delete(
+                        f"{self.session.config.biostar_url}/api/users",
+                        headers=headers,
+                        params={"id": delete_param, "group_id": "1"}
+                    )
+                    
+                    if response.status_code == 200:
+                        deleted_users = [{"user_id": uid} for uid in id_list]
+                    else:
+                        failed_users = [{"user_id": uid, "reason": response.text} for uid in id_list]
+                
+                else:
+                    return self.error_response("Either id or name must be provided")
+            
+            if deleted_users:
+                return self.success_response({
+                    "message": f"Successfully deleted {len(deleted_users)} user(s)",
+                    "deleted_users": deleted_users,
+                    "failed_users": failed_users
+                })
+            else:
+                return self.error_response("Failed to delete users", {"failed_users": failed_users})
+                
+        except Exception as e:
+            return await self.handle_api_error(e)
+    
+    async def search_users(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Search for users using search_text or specific criteria."""
+        try:
+            self.check_auth()
+            
+            search_text = args.get("search_text")
+            limit = args.get("limit", 50)
+            user_group_id = args.get("user_group_id")
+            order_by = args.get("order_by", "user_id:false")
+            
+            if not search_text:
+                return self.error_response("search_text is required")
+            
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            
+            # Build payload for search API (different from advance_search)
+            payload = {
+                "limit": limit,
+                "search_text": search_text
+            }
+            
+            if user_group_id:
+                payload["user_group_id"] = user_group_id
+            
+            if order_by:
+                payload["order_by"] = order_by
+            
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/v2/users/search",
+                    headers=headers,
+                    json=payload
+                )
+            
+            if response.status_code != 200:
+                return self.error_response(f"Search failed: {response.status_code} - {response.text}")
+            
+            data = response.json()
+            users = data.get("UserCollection", {}).get("rows", [])
+            
+            if not users:
+                return self.success_response({
+                    "message": f"No users found matching '{search_text}'",
+                    "users": [],
+                    "total": 0,
+                    "search_text": search_text
+                })
+            
+            # Extract key user information
+            user_list = []
+            for user in users:
+                user_info = {
+                    "user_id": user.get("user_id"),
+                    "name": user.get("name"),
+                    "email": user.get("email"),
+                    "department": user.get("department"),
+                    "user_title": user.get("user_title"),
+                    "phone": user.get("phone"),
+                    "disabled": user.get("disabled"),
+                    "user_group_id": user.get("user_group_id"),
+                    "access_groups": user.get("access_groups"),
+                    "start_datetime": user.get("start_datetime"),
+                    "expiry_datetime": user.get("expiry_datetime"),
+                    "operator_level": user.get("operator_level"),
+                    "fingerprint_template_count": user.get("fingerprint_template_count"),
+                    "face_count": user.get("face_count"),
+                    "card_count": user.get("card_count"),
+                    "have_pin": user.get("have_pin"),
+                    "qr_count": user.get("qr_count"),
+                    "mobile_count": user.get("mobile_count")
+                }
+                user_list.append(user_info)
+            
+            return self.success_response({
+                "message": f"Found {len(users)} user(s) matching '{search_text}'",
+                "users": user_list,
+                "total": len(users),
+                "search_text": search_text,
+                "search_criteria": payload
+            })
+            
+        except Exception as e:
+            return await self.handle_api_error(e)
+    
+    async def advanced_search_users(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Pass-through advanced search to BioStar 2.
+        - Do not add SQL wildcards or normalize fields.
+        - Let the API perform partial matching.
+        - Enforce operator level and offset types.
+        Defaults:
+        - user_operator_level_id = "0"
+        - limit = 50
+        - offset = "0" (string per API spec)
+        """
+        try:
+            self.check_auth()
+
+            raw_args: Dict[str, Any] = dict(args)
+
+            # Coerce offset int->str per API spec (offset must be string)
+            if "offset" in raw_args and isinstance(raw_args["offset"], int):
+                raw_args["offset"] = str(raw_args["offset"])
+
+            # Validate with Pydantic schema
+            try:
+                input_data = AdvancedSearchUserInput(**raw_args)
+            except ValidationError as e:
+                return self.handle_validation_error(e)
+
+            # Build payload excluding None
+            payload: Dict[str, Any] = {k: v for k, v in input_data.model_dump().items() if v is not None}
+
+            # Force critical defaults (caller value takes precedence if provided)
+            payload["user_operator_level_id"] = str(args.get("user_operator_level_id", "0"))
+            payload["limit"] = int(args.get("limit", payload.get("limit", 50)))
+            payload["offset"] = str(args.get("offset", payload.get("offset", "0")))
+
+            # Do not inject order_by unless explicitly provided by caller
+            if "order_by" not in args:
+                payload.pop("order_by", None)
+
+            # Align to API spec: if lists slip in, convert to comma-delimited strings
+            if "user_group_ids" in payload and isinstance(payload["user_group_ids"], list):
+                payload["user_group_ids"] = ",".join(str(x) for x in payload["user_group_ids"])
+            if "user_access_group_ids" in payload and isinstance(payload["user_access_group_ids"], list):
+                payload["user_access_group_ids"] = ",".join(str(x) for x in payload["user_access_group_ids"])
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json",
+            }
+
+            endpoint = f"{self.session.config.biostar_url}/api/v2/users/advance_search"
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(endpoint, headers=headers, json=payload)
+
+            if response.status_code != 200:
+                return self.error_response(f"Advanced search failed: {response.status_code} - {response.text}")
+            data = response.json()
+            users = data.get("UserCollection", {}).get("rows", [])
+            if not users:
+                return self.success_response({
+                    "message": "No users found matching the search criteria",
+                    "users": [],
+                    "total": 0,
+                    "search_criteria": payload
+                })
+            user_list = []
+            for user in users:
+                user_info = {
+                    "user_id": user.get("user_id"),
+                    "name": user.get("name"),
+                    "email": user.get("email"),
+                    "department": user.get("department"),
+                    "user_title": user.get("user_title"),
+                    "phone": user.get("phone"),
+                    "disabled": user.get("disabled"),
+                    "user_group_id": user.get("user_group_id"),
+                    "access_groups": user.get("access_groups"),
+                    "start_datetime": user.get("start_datetime"),
+                    "expiry_datetime": user.get("expiry_datetime"),
+                    "operator_level": user.get("operator_level"),
+                    "fingerprint_template_count": user.get("fingerprint_template_count"),
+                    "face_count": user.get("face_count"),
+                    "card_count": user.get("card_count"),
+                    "have_pin": user.get("have_pin"),
+                    "qr_count": user.get("qr_count"),
+                    "mobile_count": user.get("mobile_count")
+                }
+                user_list.append(user_info)
+            
+            return self.success_response({
+                "message": f"Found {len(users)} user(s) matching the search criteria",
+                "users": user_list,
+                "total": len(users),
+                "search_criteria": payload
+            })
+            
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def _resolve_user_group_by_name(
+        self,
+        headers: Dict[str, str],
+        query: str,
+    ) -> Dict[str, Any]:
+        """
+        Resolve a single user group by substring name matching.
+
+        Rules:
+        - 0 matches  -> {"status":"no_match", "needs_selection":True, ...} with the full list
+        - 1 match    -> {"status":"ok", "id":..., "name":...}
+        - >=2 matches -> {"status":"ambiguous", "needs_selection":True, "candidates":[...]}
+            (Never auto-pick even if an exact match is included.)
+        """
+        rows = await self._list_user_groups_rows(headers)
+        flat = self._flatten_groups_basic(rows)
+
+        def _norm(s: Any) -> str:
+            # normalize: trim, collapse spaces, lowercase
+            return " ".join(str(s or "").strip().lower().split())
+
+        q = _norm(query)
+        # substring match (LIKE %query%)
+        matches = [g for g in flat if q and q in _norm(g.get("name"))]
+
+        if len(matches) == 0:
+            return {
+                "status": "no_match",
+                "needs_selection": True,
+                "message": f"No user group matched '{query}'. Please pick one below.",
+                "prompt": "Which user group?",
+                "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat],
+            }
+
+        if len(matches) > 1:
+            return {
+                "status": "ambiguous",
+                "needs_selection": True,
+                "message": f"Multiple user groups matched '{query}'. Which one?",
+                "prompt": "Which user group?",
+                "candidates": [{"id": g["id"], "name": g["name"]} for g in matches],
+            }
+
+        return {"status": "ok", "id": int(matches[0]["id"]), "name": matches[0]["name"]}
+
+
+    async def _resolve_user_groups_by_names(self, headers: Dict[str, str], names: List[str]) -> Dict[str, Any]:
+        """
+        PRIVATE: Resolve multiple group names at once.
+        Returns:
+        - {"resolved":[{"query":<str>,"id":<int>,"name":<str>},...]}  # all good
+        - {"needs_selection":True,"issues":[{ per-name selection payloads ... }]}
+        """
+        issues: List[Dict[str, Any]] = []
+        resolved: List[Dict[str, Any]] = []
+        for q in names:
+            r = await self._resolve_user_group_by_name(headers, q)
+            if r.get("status") == "ok":
+                resolved.append({"query": q, "id": r["id"], "name": r.get("name")})
+            else:
+                item = {"query": q}
+                item.update({k: v for k, v in r.items() if k != "status"})
+                issues.append(item)
+        if issues:
+            return {"needs_selection": True, "issues": issues}
+        return {"resolved": resolved}
+
+    async def bulk_add_users(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Add multiple users at once.
+
+        Supports:
+        - user group assignment by id or name (0/1/many name resolution)
+        - multiple groups with round-robin or explicit counts
+        - naming controls: suffix width, start number, separator, or a free template
+
+        Disambiguation hard-stop:
+        - If name-based resolution is ambiguous or not found, return error with
+            candidates and a selection_token. The next call MUST include:
+            * selection_token (from the error response)
+            * user_group_id chosen by the user
+        - If a pending selection_token exists, passing user_group_id without
+            the token is rejected to prevent the agent from auto-picking.
+
+        Optional args:
+        - user_group_id: int|str
+        - user_group_name: str
+        - user_group_names: List[str]
+        - group_counts: List[int] (with user_group_names + distribution='by_counts')
+        - distribution: 'round_robin' | 'by_counts' (default: round_robin)
+        - group_allocations: List[{'group_id'| 'group_name', 'count'}], counts must sum to 'count'
+        - suffix_width: int (default 3)
+        - suffix_start: int (default 1)
+        - name_separator: str (default "")
+        - name_template: str (format string using {base}, {seq}, {user_id}; e.g., "홍길동 {seq:03d}")
+        - selection_token: str (required ONLY when previous call returned ambiguity)
+        """
+        try:
+            from uuid import uuid4
+
+            self.check_auth()
+
+            # ---------- small helpers for selection-token gating ----------
+            def _get_state() -> Dict[str, Any]:
+                st = getattr(self.session, "state", None)
+                if st is None:
+                    self.session.state = {}
+                    st = self.session.state
+                return st
+
+            def _set_pending_token(candidates: List[Dict[str, Any]]) -> str:
+                token = uuid4().hex
+                ids = {int(c["id"]) for c in candidates if isinstance(c, dict) and c.get("id") is not None}
+                st = _get_state()
+                st["bulk_add_pending"] = {"token": token, "ids": ids}
+                return token
+
+            def _has_pending_token() -> bool:
+                st = _get_state()
+                return bool(st.get("bulk_add_pending"))
+
+            def _consume_token_if_valid(token: str, selected_id: int) -> bool:
+                st = _get_state()
+                pending = st.get("bulk_add_pending")
+                if not pending:
+                    return False
+                if pending.get("token") != token:
+                    return False
+                ids: set = pending.get("ids") or set()
+                if int(selected_id) not in ids:
+                    return False
+                # consume
+                st.pop("bulk_add_pending", None)
+                return True
+
+            # --- Extract grouping params before Pydantic validation (to avoid extra-field errors) ---
+            group_id_arg = args.get("user_group_id")
+            group_name_arg = args.get("user_group_name") or args.get("group_name")
+            group_names_arg = args.get("user_group_names") or args.get("group_names")  # List[str]
+            group_counts_arg = args.get("group_counts")  # List[int], optional
+            group_allocations_arg = args.get("group_allocations")  # [{"group_id" or "group_name", "count"}...]
+            distribution_mode = (args.get("distribution") or "round_robin").strip().lower()  # "round_robin" | "by_counts"
+            selection_token_in = (args.get("selection_token") or "").strip()
+
+            # --- Validate base_name/count using Pydantic as-is ---
+            try:
+                input_data = BulkAddUsersInput(**{k: v for k, v in args.items() if k in {"base_name", "count"}})
+            except ValidationError as e:
+                return self.handle_validation_error(e)
+
+            if input_data.count > 30:
+                return self.error_response(f"Maximum 30 users can be created at once. Requested: {input_data.count}")
+
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                # Get starting user ID from server
+                resp = await client.get(f"{self.session.config.biostar_url}/api/users/next_user_id", headers=headers)
+                if resp.status_code != 200:
+                    return self.error_response(f"Failed to get user ID: {resp.status_code} - {resp.text}")
+                start_id = int(resp.json()["User"]["user_id"])
+
+            # --- Resolve target group ids for each user based on provided args ---
+            group_ids_for_each: List[int] = []
+
+            # Case A: explicit allocation objects [{"group_id":..|"group_name":.., "count": N}, ...]
+            if isinstance(group_allocations_arg, list) and group_allocations_arg:
+                total = 0
+                resolved_allocs: List[Tuple[int, int, str]] = []  # (gid, count, display_name)
+                for alloc in group_allocations_arg:
+                    if not isinstance(alloc, dict) or "count" not in alloc:
+                        return self.error_response(
+                            "Each item in 'group_allocations' must be an object containing 'count' and either 'group_id' or 'group_name'."
+                        )
+                    try:
+                        c = int(alloc["count"])
+                    except Exception:
+                        return self.error_response("Each 'count' in 'group_allocations' must be an integer.")
+                    if c < 0:
+                        return self.error_response("Counts in 'group_allocations' must be >= 0.")
+                    total += c
+
+                    if "group_id" in alloc and alloc["group_id"] is not None:
+                        try:
+                            gid = int(str(alloc["group_id"]).strip())
+                        except Exception:
+                            return self.error_response("Invalid 'group_id' in 'group_allocations'.")
+                        # If a pending token exists, enforce passing token for safety
+                        if _has_pending_token():
+                            if not selection_token_in or not _consume_token_if_valid(selection_token_in, gid):
+                                return self.error_response(
+                                    "Ambiguity previously detected. Provide a valid selection_token with a candidate group_id.",
+                                    {"error_code": "SELECTION_TOKEN_REQUIRED", "needs_selection": True}
+                                )
+                        resolved_allocs.append((gid, c, f"id={gid}"))
+                    elif "group_name" in alloc and alloc["group_name"]:
+                        res = await self._resolve_user_group_by_name(headers, str(alloc["group_name"]).strip())
+                        if res.get("status") != "ok":
+                            # Create a selection token and hard-stop
+                            candidates = res.get("candidates") or res.get("user_groups") or []
+                            token = _set_pending_token(candidates)
+                            detail = {
+                                "error_code": "AMBIGUOUS_USER_GROUP" if res.get("status") == "ambiguous" else "USER_GROUP_NOT_FOUND",
+                                "needs_selection": True,
+                                "prompt": res.get("prompt", "Which user group?"),
+                                "candidates": [{"id": x.get("id"), "name": x.get("name")} for x in candidates],
+                                "selection_token": token,
+                            }
+                            return self.error_response("User group resolution failed for 'group_allocations'.", detail)
+                        gid = int(res["id"])
+                        resolved_allocs.append((gid, c, res.get("name") or f"id={gid}"))
+                    else:
+                        return self.error_response("Each 'group_allocations' item must provide 'group_id' or 'group_name'.")
+
+                if total != input_data.count:
+                    return self.error_response(
+                        f"Sum of 'group_allocations.count' must equal requested 'count' ({input_data.count}). Got {total}."
+                    )
+
+                # Expand into per-user assignment
+                for (gid, c, _label) in resolved_allocs:
+                    group_ids_for_each.extend([gid] * c)
+
+            # Case B: single group by id/name for all
+            elif group_id_arg is not None or group_name_arg:
+                if group_id_arg is not None:
+                    try:
+                        single_gid = int(str(group_id_arg).strip())
+                    except Exception:
+                        return self.error_response("Invalid 'user_group_id'. It must be a number.")
+                    # If there is a pending ambiguity token, enforce token validation
+                    if _has_pending_token():
+                        if not selection_token_in or not _consume_token_if_valid(selection_token_in, single_gid):
+                            return self.error_response(
+                                "Ambiguity previously detected. Provide a valid selection_token with the chosen user_group_id.",
+                                {"error_code": "SELECTION_TOKEN_REQUIRED", "needs_selection": True}
+                            )
+                    group_ids_for_each = [single_gid] * input_data.count
+                else:
+                    # Name-based resolution -> HARD STOP if ambiguous or not found
+                    res = await self._resolve_user_group_by_name(headers, str(group_name_arg).strip())
+                    if res.get("status") != "ok":
+                        candidates = res.get("candidates") or res.get("user_groups") or []
+                        token = _set_pending_token(candidates)
+                        detail = {
+                            "error_code": "AMBIGUOUS_USER_GROUP" if res.get("status") == "ambiguous" else "USER_GROUP_NOT_FOUND",
+                            "needs_selection": True,
+                            "prompt": res.get("prompt", "Which user group?"),
+                            "candidates": [{"id": x.get("id"), "name": x.get("name")} for x in candidates],
+                            "selection_token": token,
+                        }
+                        return self.error_response("Ambiguous or missing user group. Please choose explicitly.", detail)
+                    single_gid = int(res["id"])
+                    group_ids_for_each = [single_gid] * input_data.count
+
+            # Case C: multiple group names with distribution
+            elif isinstance(group_names_arg, list) and group_names_arg:
+                multi = await self._resolve_user_groups_by_names(headers, [str(x).strip() for x in group_names_arg])
+                if multi.get("needs_selection"):
+                    # Any unresolved name -> create token and hard-stop
+                    # We gather all candidates to a single token for simplicity.
+                    issues = multi.get("issues", [])
+                    all_candidates: List[Dict[str, Any]] = []
+                    for it in issues:
+                        cands = (it.get("candidates") or it.get("user_groups") or [])
+                        for c in cands:
+                            if isinstance(c, dict) and "id" in c:
+                                all_candidates.append({"id": c["id"], "name": c.get("name")})
+                    token = _set_pending_token(all_candidates)
+                    return self.error_response(
+                        "One or more user group names require disambiguation.",
+                        {
+                            "error_code": "AMBIGUOUS_OR_NOT_FOUND",
+                            "needs_selection": True,
+                            "issues": issues,
+                            "selection_token": token,
+                            "prompt": "Resolve each group name to a specific id and call again."
+                        }
+                    )
+                resolved = multi.get("resolved", [])
+                gids = [int(x["id"]) for x in resolved]
+                if not gids:
+                    return self.error_response("No valid user groups resolved from 'user_group_names'.")
+
+                if distribution_mode == "by_counts":
+                    if not isinstance(group_counts_arg, list) or len(group_counts_arg) != len(gids):
+                        return self.error_response(
+                            "'group_counts' must be provided and match the length of 'user_group_names' when distribution='by_counts'."
+                        )
+                    try:
+                        counts = [int(c) for c in group_counts_arg]
+                    except Exception:
+                        return self.error_response("All 'group_counts' must be integers.")
+                    if any(c < 0 for c in counts):
+                        return self.error_response("All 'group_counts' must be >= 0.")
+                    if sum(counts) != input_data.count:
+                        return self.error_response(
+                            f"Sum of 'group_counts' must equal requested 'count' ({input_data.count})."
+                        )
+                    # expand by counts order
+                    for gid, c in zip(gids, counts):
+                        group_ids_for_each.extend([gid] * c)
+                else:
+                    # default round-robin
+                    for i in range(input_data.count):
+                        group_ids_for_each.append(gids[i % len(gids)])
+
+            # Case D: nothing provided → default to root (id=1)
+            else:
+                group_ids_for_each = [1] * input_data.count
+
+            # --- Naming options ---
+            suffix_width = int(args.get("suffix_width", 3))
+            suffix_start = int(args.get("suffix_start", 1))
+            name_separator = args.get("name_separator", "")
+            name_template = (args.get("name_template") or "").strip() or None
+            base = input_data.base_name
+
+            # --- Build user rows with computed group assignments ---
+            rows: List[Dict[str, Any]] = []
+            for i in range(input_data.count):
+                # seq is NOT the BioStar user_id; it's our logical counter (1..N)
+                seq = suffix_start + i
+
+                if name_template:
+                    # Supports {base}, {seq}, {user_id} and formatting like {seq:03d}
+                    try:
+                        name = name_template.format(base=base, seq=seq, user_id=start_id + i)
+                    except Exception:
+                        # Fallback if template formatting fails
+                        name = f"{base}{name_separator}{str(seq).zfill(suffix_width)}"
+                else:
+                    name = f"{base}{name_separator}{str(seq).zfill(suffix_width)}"
+
+                gid = int(group_ids_for_each[i])
+                rows.append({
+                    "user_id": start_id + i,
+                    "name": name,
+                    "user_group_id": {"id": gid},
+                    "start_datetime": "2001-01-01T00:00:00.00Z",
+                    "expiry_datetime": "2030-12-31T23:59:00.00Z"
+                })
+
+            payload = {"UserCollection": {"rows": rows}}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                post_resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/users",
+                    json=payload,
+                    headers=headers
+                )
+
+            if post_resp.status_code == 200:
+                created_users = [{
+                    "user_id": row["user_id"],
+                    "name": row["name"],
+                    "group_id": row["user_group_id"]["id"]
+                } for row in rows]
+
+                # summarize group distribution
+                dist: Dict[int, int] = {}
+                for gid in group_ids_for_each:
+                    dist[gid] = dist.get(gid, 0) + 1
+
+                return self.success_response({
+                    "message": f"Successfully created {len(rows)} users",
+                    "users": created_users,
+                    "group_distribution": [{"group_id": gid, "count": cnt} for gid, cnt in sorted(dist.items())]
+                })
+            else:
+                return self.error_response(
+                    f"Failed to create users: {post_resp.status_code} - {post_resp.text}"
+                )
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def export_users_csv(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        r"""
+        Export users to CSV via /api/users/csv_export and copy the file to Windows user's Downloads.
+
+        - Source (server) path:
+            C:\Program Files\BioStar X\nginx\html\download\<filename>  (or self.session.config.download_dir)
+        - Destination (Windows):
+            • If 'dest_dir' provided  -> use it as absolute path
+            • elif 'target_username'  -> C:\Users\<target_username>\Downloads
+            • else                    -> %USERPROFILE%\Downloads
+
+        Behavior:
+        - Only attempts the file copy on Windows.
+        - Always returns the server source path (even if copy is skipped/failed).
+        - Filters args before Pydantic validation to avoid 'extra fields' errors.
+        """
+        try:
+            self.check_auth()
+
+            # ---------- copy options (not validated by ExportCSVInput) ----------
+            copy_to_downloads: bool = bool(args.get("copy_to_downloads", True))
+            dest_dir_arg: str = (args.get("dest_dir") or "").strip()
+            target_username: str = (args.get("target_username") or "").strip()
+            
+            # ---------- advanced criteria (new: for server-side filtering) ----------
+            adv_criteria_arg: dict = args.get("adv_criteria") or {}
+
+            # ---------- validate inputs (allow only schema fields) ----------
+            schema_keys = {"ids", "search_text", "limit"}
+            filtered_args = {k: v for k, v in args.items() if k in schema_keys}
+
+            try:
+                input_data = ExportCSVInput(**filtered_args)
+            except ValidationError as e:
+                return self.handle_validation_error(e)
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # ---------- resolve user ids or use advanced criteria ----------
+            user_ids = input_data.ids
+            id_param = None
+            export_count_desc = "matching"
+            use_adv_criteria = False
+            
+            # Priority 1: Use advanced criteria (server-side filtering, no limit)
+            if adv_criteria_arg and not user_ids:
+                use_adv_criteria = True
+                id_param = "*"  # Export all users matching criteria
+                export_count_desc = "all matching"
+                logger.info(f"Using advanced criteria for CSV export: {adv_criteria_arg}")
+            
+            # Priority 2: Use provided IDs or search_text
+            elif input_data.search_text and not user_ids:
+                # Search first to resolve IDs
+                search_args = {
+                    "search_text": input_data.search_text,
+                    "limit": input_data.limit or 50
+                }
+                search_result = await self.search_users(search_args)
+                if not search_result:
+                    return self.error_response("No users found matching the search criteria")
+
+                try:
+                    search_content = search_result[0].text
+                    search_data = json.loads(search_content)
+                    users = search_data.get("users", []) or []
+                    user_ids = [str(u.get("user_id")) for u in users if u.get("user_id")]
+                    if not user_ids:
+                        return self.error_response("No user IDs found in search results")
+                except (json.JSONDecodeError, KeyError) as e:
+                    logger.error(f"Failed to parse search results: {e}")
+                    return self.error_response("Failed to parse search results")
+
+            # Priority 3: Use provided IDs or wildcard
+            if not use_adv_criteria:
+                if not user_ids:
+                    return self.error_response("At least one user ID, search_text, or adv_criteria must be provided")
+
+                if user_ids == ["*"]:
+                    id_param = "*"
+                    export_count_desc = "all"
+                else:
+                    id_param = "+".join(str(uid) for uid in user_ids)
+                    export_count_desc = str(len(user_ids))
+
+            # Build payload with advanced criteria
+            payload = {
+                "Query": {
+                    "offset": 0,
+                    "group_by": 1,
+                    "columns": [
+                        "user_id", "name", "email", "user_group_id", "access_groups",
+                        "start_datetime", "expiry_datetime", "operator_level",
+                        "fingerprint_template_count", "face_count", "visual_face_count",
+                        "card_count", "have_pin", "qr_count", "mobile_count", "disabled"
+                    ],
+                    "headers": [
+                        "ID", "Name", "Email", "Group", "Access Group", "Start datetime",
+                        "End datetime", "Operator Level", "Fingerprint", "Face",
+                        "Visual Face", "Card", "PIN", "QR/Barcode", "Mobile Access Card", "Status"
+                    ]
+                },
+                "adv_criteria": adv_criteria_arg if use_adv_criteria else {
+                    "user_group_ids": [],
+                    "user_group_id": "1",
+                    "user_operator_level_id": "0"
+                }
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/users/csv_export?id={id_param}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if resp.status_code != 200:
+                return self.error_response(f"Failed to export CSV: {resp.status_code} - {resp.text}")
+
+            data = resp.json() or {}
+            filename = (data.get("File") or {}).get("uri")
+            if not filename:
+                return self.error_response("Failed to create CSV file - no filename returned")
+
+            # ---------- compute server source path ----------
+            download_root = getattr(
+                self.session.config,
+                "download_dir",
+                r"C:\Program Files\BioStar X\nginx\html\download"
+            )
+            src_path = Path(download_root) / filename
+
+            # ---------- copy to Windows Downloads (optional) ----------
+            copied_to: str = ""
+            copy_status: str = "skipped"
+
+            if copy_to_downloads:
+                if platform.system().lower() == "windows":
+                    if dest_dir_arg:
+                        dest_dir = Path(dest_dir_arg)
+                    elif target_username:
+                        # Explicit username case
+                        dest_dir = Path(fr"C:\Users\{target_username}\Downloads")
+                    else:
+                        # Current user profile
+                        userprofile = os.environ.get("USERPROFILE") or str(Path.home())
+                        dest_dir = Path(userprofile) / "Downloads"
+
+                    try:
+                        dest_dir.mkdir(parents=True, exist_ok=True)
+
+                        if not src_path.exists():
+                            copy_status = "failed: source not found"
+                        else:
+                            dest_path = dest_dir / filename
+                            shutil.copy2(src_path, dest_path)
+                            copied_to = str(dest_path)
+                            copy_status = "success"
+                    except Exception as ce:
+                        logger.error(f"Copy to Downloads failed: {ce}")
+                        copy_status = f"failed: {ce}"
+                else:
+                    copy_status = "skipped: non-windows"
+
+            # ---------- final response ----------
+            return self.success_response({
+                "message": f"CSV file created successfully for {export_count_desc} users",
+                "filename": filename,
+                "download_url": f"/download/{filename}",
+                "source_path": str(src_path),
+                "copy": {
+                    "enabled": copy_to_downloads,
+                    "status": copy_status,
+                    "destination": copied_to
+                },
+                "user_count": export_count_desc
+            })
+
+        except Exception as e:
+            logger.error(f"Error in export_users_csv: {e}")
+            return await self.handle_api_error(e)
+
+    async def export_non_accessed_users_csv(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Export users who have NOT accessed a specific door within a given time period.
+        
+        This is a 2-step process:
+        1. Use occupancy handler to get list of users who accessed the door
+        2. Get all users and filter out the ones who accessed
+        3. Export only non-accessed users to CSV
+        """
+        try:
+            self.check_auth()
+            
+            door_id = args.get("door_id")
+            door_name = args.get("door_name")
+            days = args.get("days", 7)
+            hours = args.get("hours")
+            
+            if not door_id and not door_name:
+                return self.error_response("Either door_id or door_name is required")
+            
+            # Import OccupancyHandler to reuse logic
+            from .occupancy_handler import OccupancyHandler
+            occupancy_handler = OccupancyHandler(self.session)
+            occupancy_handler.client_session_id = self.client_session_id
+            
+            # Step 1: Get occupancy status to find users who DID access
+            logger.info(f" Finding users who accessed door in last {days} days...")
+            occupancy_args = {
+                "door_id": door_id,
+                "door_name": door_name,
+                "days": days
+            }
+            # Only include hours if explicitly provided
+            if hours is not None:
+                occupancy_args["hours"] = hours
+            
+            occupancy_result = await occupancy_handler.get_occupancy_status(occupancy_args)
+            
+            # Parse the result to extract accessed user IDs
+            accessed_user_ids = set()
+            try:
+                result_text = occupancy_result[0].text
+                result_data = json.loads(result_text)
+                
+                # Extract the actual data from the response wrapper
+                data = result_data.get("data", {})
+                
+                # Extract user IDs from currently_inside and recently_exited
+                for user in data.get("currently_inside", []):
+                    accessed_user_ids.add(str(user.get("user_id")))
+                
+                for user in data.get("recently_exited", []):
+                    accessed_user_ids.add(str(user.get("user_id")))
+                    
+                logger.info(f" Found {len(accessed_user_ids)} users who accessed the door")
+                logger.info(f"   Accessed user IDs: {sorted(accessed_user_ids)}")
+                
+            except Exception as e:
+                logger.error(f"Failed to parse occupancy result: {e}")
+                return self.error_response(f"Failed to analyze door access: {str(e)}")
+            
+            # Step 2: Get ALL users
+            logger.info(f" Getting all users...")
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/users",
+                    headers=headers
+                )
+            
+            if response.status_code != 200:
+                return self.error_response(f"Failed to get users: {response.status_code}")
+            
+            data = response.json()
+            all_users = data.get("UserCollection", {}).get("rows", [])
+            
+            # Step 3: Filter to get NON-accessed users
+            non_accessed_user_ids = []
+            for user in all_users:
+                user_id = str(user.get("user_id"))
+                if user_id not in accessed_user_ids:
+                    non_accessed_user_ids.append(user_id)
+            
+            logger.info(f" Found {len(non_accessed_user_ids)} non-accessed users out of {len(all_users)} total")
+            
+            if not non_accessed_user_ids:
+                return self.success_response({
+                    "message": "No non-accessed users found",
+                    "total_users": len(all_users),
+                    "accessed_users": len(accessed_user_ids),
+                    "non_accessed_users": 0
+                })
+            
+            # Step 4: Export only non-accessed users
+            logger.info(f" Exporting {len(non_accessed_user_ids)} non-accessed users to CSV...")
+            export_args = {
+                "ids": non_accessed_user_ids,
+                "copy_to_downloads": args.get("copy_to_downloads", True),
+                "dest_dir": args.get("dest_dir"),
+                "target_username": args.get("target_username")
+            }
+            
+            export_result = await self.export_users_csv(export_args)
+            
+            # Enhance the result with non-access context
+            try:
+                result_text = export_result[0].text
+                result_data = json.loads(result_text)
+                
+                # Add analysis summary
+                result_data["analysis"] = {
+                    "door_name": door_name or f"Door {door_id}",
+                    "period_days": days,
+                    "total_users": len(all_users),
+                    "accessed_users": len(accessed_user_ids),
+                    "non_accessed_users": len(non_accessed_user_ids),
+                    "percentage_non_accessed": round((len(non_accessed_user_ids) / len(all_users) * 100), 1) if all_users else 0
+                }
+                
+                return [TextContent(type="text", text=json.dumps(result_data, ensure_ascii=False, indent=2))]
+                
+            except Exception as e:
+                logger.warning(f"Could not enhance result: {e}")
+                return export_result
+                
+        except Exception as e:
+            logger.error(f"Error in export_non_accessed_users_csv: {e}")
+            return await self.handle_api_error(e)
+    
+    async def get_user_cards(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        try:
+            self.check_auth()
+            user_id = args.get("user_id")
+            if not user_id:
+                return self.error_response("user_id is required")
+
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(f"{self.session.config.biostar_url}/api/users/{user_id}", headers=headers)
+            if resp.status_code != 200:
+                return self.error_response(f"Failed to get user: {resp.status_code} - {resp.text}")
+
+            user = (resp.json() or {}).get("User", {}) or {}
+            cards_field = user.get("cards", [])
+            if isinstance(cards_field, dict) and "rows" in cards_field:
+                rows = cards_field["rows"]
+            elif isinstance(cards_field, list):
+                rows = cards_field
+            else:
+                rows = []
+
+            cards = [{"id": r.get("id"),
+                    "card_id": r.get("card_id"),
+                    "display_card_id": r.get("display_card_id")} for r in rows]
+
+            return self.success_response({"user_id": str(user_id), "cards": cards, "total": len(cards)})
+        except Exception as e:
+            return await self.handle_api_error(e)
+                
+    async def unassign_user_cards(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            user_id = args.get("user_id")
+            name = args.get("name")
+            if not user_id:
+                if not name:
+                    return self.error_response("Either user_id or name is required")
+                matches = await search_users_by_name(self.get_session_id(), name)
+                if not matches:
+                    return self.error_response(f"No user found with name '{name}'")
+                if len(matches) > 1:
+                    return self.error_response(f"Multiple users found with name '{name}'. Please specify user_id.")
+                user_id = matches[0]["user_id"]
+            user_id = str(user_id)
+
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.get(f"{self.session.config.biostar_url}/api/users/{user_id}", headers=headers)
+            if r.status_code != 200:
+                return self.error_response(f"Failed to get user: {r.status_code} - {r.text}")
+
+            user = (r.json() or {}).get("User", {}) or {}
+            cards_field = user.get("cards", [])
+            if isinstance(cards_field, dict) and "rows" in cards_field:
+                rows = cards_field["rows"]
+            elif isinstance(cards_field, list):
+                rows = cards_field
+            else:
+                rows = []
+
+            state_before = [{"id": x.get("id"), "card_id": x.get("card_id"), "display_card_id": x.get("display_card_id")} for x in rows]
+            assigned_row_ids = {str(x.get("id")) for x in rows if x.get("id") is not None}
+
+            remove_all     = bool(args.get("remove_all", False))
+            ignore_missing = bool(args.get("ignore_missing", False))
+            dry_run        = bool(args.get("dry_run", False))
+
+            if remove_all:
+                planned_payload = {"User": {"cards": []}}
+                if dry_run:
+                    return self.success_response({
+                        "message": "Dry run: would detach ALL cards",
+                        "user_id": user_id,
+                        "state_before": state_before,
+                        "request_body": planned_payload
+                    })
+                async with httpx.AsyncClient(verify=False) as client:
+                    put_resp = await client.put(f"{self.session.config.biostar_url}/api/users/{user_id}",
+                                                headers=headers, json=planned_payload)
+                if put_resp.status_code != 200:
+                    return self.error_response(f"Failed to unassign all cards: {put_resp.status_code} - {put_resp.text}",
+                                            {"request_body": planned_payload})
+                return self.success_response({
+                    "message": f"Detached all cards from user {user_id}",
+                    "user_id": user_id,
+                    "removed_count": len(rows),
+                    "request_body": planned_payload,
+                    "response": put_resp.json()
+                })
+
+            remove_ids = [str(x) for x in (args.get("remove_card_row_ids") or [])]
+            if not remove_ids:
+                return self.error_response("Provide remove_card_row_ids (or set remove_all=true)")
+
+            missing = [rid for rid in remove_ids if rid not in assigned_row_ids]
+            if missing and not ignore_missing:
+                return self.error_response(
+                    "One or more requested row ids are NOT assigned to the user. No changes applied.",
+                    {"user_id": user_id, "missing": missing, "assigned_row_ids": sorted(list(assigned_row_ids))}
+                )
+
+            to_remove = set(remove_ids) & assigned_row_ids
+            kept_rows = [x for x in rows if str(x.get("id")) not in to_remove]
+
+            planned_payload = {"User": {"cards": [{"id": str(x.get("id"))} for x in kept_rows if x.get("id") is not None]}}
+
+            if dry_run:
+                return self.success_response({
+                    "message": "Dry run: would detach selected cards",
+                    "user_id": user_id,
+                    "state_before": state_before,
+                    "remove_targets": sorted(list(to_remove)),
+                    "request_body": planned_payload,
+                    "missing": missing,
+                    "ignored_missing": ignore_missing
+                })
+
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(f"{self.session.config.biostar_url}/api/users/{user_id}",
+                                            headers=headers, json=planned_payload)
+            if put_resp.status_code != 200:
+                return self.error_response(f"Failed to detach cards: {put_resp.status_code} - {put_resp.text}",
+                                        {"request_body": planned_payload})
+
+            return self.success_response({
+                "message": f"Detached {len(to_remove)} card(s) from user {user_id}",
+                "user_id": user_id,
+                "removed": sorted(list(to_remove)),
+                "kept_count": len(kept_rows),
+                "request_body": planned_payload,
+                "response": put_resp.json(),
+                "missing": missing,
+                "ignored_missing": ignore_missing
+            })
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def search_user_cards(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Behavior:
+        - If user_id is provided (single or list), hydrate each via GET /api/users/{id} and parse cards.
+        - Else build advanced-search payload from args (or 'name' -> user_name) and call advanced_search_users().
+          Then hydrate each matched user_id via GET /api/users/{id} and parse cards.
+        - If require_has_card is True, exclude users with zero cards.
+        - Limit hydration via max_users (default 50).
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # 0) helpers
+            def _parse_cards(user_obj: Dict[str, Any]) -> List[Dict[str, Any]]:
+                cards_field = user_obj.get("cards", [])
+                if isinstance(cards_field, dict) and "rows" in cards_field:
+                    rows = cards_field.get("rows", []) or []
+                elif isinstance(cards_field, list):
+                    rows = cards_field
+                else:
+                    rows = []
+                cards = []
+                for r in rows:
+                    if not isinstance(r, dict):
+                        continue
+                    cards.append({
+                        "id": r.get("id"),
+                        "card_id": r.get("card_id"),
+                        "display_card_id": r.get("display_card_id"),
+                    })
+                return cards
+
+            require_has_card = bool(args.get("require_has_card", False))
+            max_users = int(args.get("max_users", 50))
+
+            # 1) Collect target user_ids
+            target_ids: List[str] = []
+
+            # 1-a) direct user_id(s)
+            if "user_id" in args and args["user_id"] is not None:
+                val = args["user_id"]
+                if isinstance(val, list):
+                    target_ids = [str(x) for x in val]
+                else:
+                    target_ids = [str(val)]
+
+            # 1-b) advanced search (or simple 'name' convenience) if no direct ids
+            if not target_ids:
+                # Build advanced args from incoming args
+                adv_keys = {
+                    "limit", "offset", "user_id", "user_group_id", "user_group_ids",
+                    "user_name", "user_email", "user_phone", "user_department",
+                    "user_access_group_ids", "user_title", "order_by", "user_operator_level_id"
+                }
+                adv_args: Dict[str, Any] = {k: v for k, v in args.items() if k in adv_keys and v is not None}
+
+                # convenience aliases
+                if args.get("name") and not adv_args.get("user_name"):
+                    adv_args["user_name"] = args.get("name")
+                if args.get("user_id_like") and not adv_args.get("user_id"):
+                    adv_args["user_id"] = args.get("user_id_like")
+
+                # defaults
+                if "limit" not in adv_args:
+                    adv_args["limit"] = int(args.get("limit", 50))
+                if "offset" in adv_args and isinstance(adv_args["offset"], int):
+                    adv_args["offset"] = str(adv_args["offset"])
+                if "offset" not in adv_args:
+                    adv_args["offset"] = str(args.get("offset", "0"))
+                if "user_operator_level_id" not in adv_args:
+                    adv_args["user_operator_level_id"] = str(args.get("user_operator_level_id", "0"))
+
+                # If nothing to search on, fail fast (폭주 방지)
+                if not any(k for k in adv_args if k != "limit" and k != "offset" and k != "user_operator_level_id"):
+                    return self.error_response(
+                        "Provide 'user_id' or at least one advanced search field (e.g., user_name/user_email/user_phone/user_department)."
+                    )
+
+                # Reuse existing advanced_search_users() for payload alignment and validation
+                adv_result = await self.advanced_search_users(adv_args)
+                if not adv_result:
+                    return self.error_response("Advanced search returned no result content")
+
+                try:
+                    adv_json = json.loads(adv_result[0].text)
+                except Exception as e:
+                    return self.error_response(f"Failed to parse advanced search result: {e!r}")
+
+                matched = adv_json.get("users", []) or []
+                if not matched:
+                    return self.success_response({
+                        "message": "No users matched the search criteria",
+                        "users": [],
+                        "total_users": 0
+                    })
+
+                target_ids = [str(u.get("user_id")) for u in matched if u.get("user_id") is not None]
+
+            # Cap the number of hydrated users
+            target_ids = target_ids[:max_users]
+
+            if not target_ids:
+                return self.success_response({"message": "No target users to hydrate", "users": [], "total_users": 0})
+
+            # 2) Hydrate each user and parse cards
+            results: List[Dict[str, Any]] = []
+            errors: List[Dict[str, Any]] = []
+
+            async with httpx.AsyncClient(verify=False) as client:
+                for uid in target_ids:
+                    resp = await client.get(f"{self.session.config.biostar_url}/api/users/{uid}", headers=headers)
+                    if resp.status_code != 200:
+                        errors.append({"user_id": uid, "status": resp.status_code, "error": resp.text})
+                        continue
+
+                    user_obj = (resp.json() or {}).get("User", {}) or {}
+                    cards = _parse_cards(user_obj)
+
+                    if require_has_card and not cards:
+                        continue
+
+                    results.append({
+                        "user_id": uid,
+                        "name": user_obj.get("name"),
+                        "email": user_obj.get("email"),
+                        "department": user_obj.get("department"),
+                        "card_count": len(cards),
+                        "cards": cards
+                    })
+
+            return self.success_response({
+                "message": f"Hydrated {len(results)} user(s)",
+                "total_users": len(results),
+                "users": results,
+                "errors": errors,
+                "require_has_card": require_has_card,
+                "max_users": max_users
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def create_user_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Create a new User Group.
+        - Blocks creation if the name already exists (case-insensitive, trimmed).
+        - If 'depth' not provided, auto-compute as (parent.depth + 1).
+        - Enforces name length <= 48 and max depth < 8 (root=0).
+        Body sent to BioStar 2:
+            {
+              "UserGroup": {
+                "parent_id": {"id": <int>},
+                "depth": <int>,
+                "name": "<str>"
+              }
+            }
+        """
+        try:
+            self.check_auth()
+
+            # ----- basic validation -----
+            name = (args.get("name") or "").strip()
+            parent_id = args.get("parent_id")
+            if not name:
+                return self.error_response("Parameter 'name' is required")
+            if parent_id is None:
+                return self.error_response("Parameter 'parent_id' is required")
+            if len(name) > 48:
+                return self.error_response("User group name must be 48 characters or fewer")
+
+            # normalize parent_id for compare/payload
+            parent_id_str = str(parent_id)
+            try:
+                parent_id_int = int(str(parent_id).strip())
+            except Exception:
+                return self.error_response("Parameter 'parent_id' must be a number")
+
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ----- fetch existing groups to check duplicates & compute depth -----
+            async with httpx.AsyncClient(verify=False) as client:
+                list_resp = await client.get(f"{self.session.config.biostar_url}/api/user_groups", headers=headers)
+            if list_resp.status_code != 200:
+                return self.error_response(f"Failed to list user groups: {list_resp.status_code} - {list_resp.text}")
+
+            data = list_resp.json() or {}
+            rows = (data.get("UserGroupCollection") or {}).get("rows", []) or []
+
+            # duplicate check (case-insensitive, trimmed)
+            target_norm = name.lower()
+            dup_matches = [
+                {"id": r.get("id"), "name": r.get("name")}
+                for r in rows
+                if isinstance(r, dict) and str(r.get("name", "")).strip().lower() == target_norm
+            ]
+            if dup_matches:
+                return self.error_response(
+                    f"User group '{name}' already exists. Please choose a different name.",
+                    {"conflicts": dup_matches}
+                )
+
+            # ----- resolve depth -----
+            depth_arg = args.get("depth")
+            if depth_arg is not None:
+                try:
+                    depth_val = int(depth_arg)
+                except Exception:
+                    return self.error_response("Parameter 'depth' must be an integer when provided")
+            else:
+                # find parent depth; 'All Users' typically depth=0
+                parent_row = next((r for r in rows if str(r.get("id")) == parent_id_str), None)
+                if parent_row and "depth" in parent_row:
+                    try:
+                        parent_depth = int(str(parent_row.get("depth")))
+                    except Exception:
+                        parent_depth = 0
+                else:
+                    # fallback: if parent not found but parent is root(1), assume depth=0; else default 0
+                    parent_depth = 0 if parent_id_int == 1 else 0
+                depth_val = parent_depth + 1
+
+            # enforce max 8 levels total (root=0 → allowed children depths: 1..7)
+            if depth_val >= 8:
+                return self.error_response(
+                    f"Max depth is 7 for child groups (root=0). Computed depth={depth_val} exceeds limit."
+                )
+
+            # ----- build & send create payload -----
+            payload = {
+                "UserGroup": {
+                    "parent_id": {"id": parent_id_int},
+                    "depth": depth_val,
+                    "name": name
+                }
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                create_resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/user_groups",
+                    headers=headers,
+                    json=payload
+                )
+
+            if create_resp.status_code != 200:
+                return self.error_response(
+                    f"Failed to create user group: {create_resp.status_code} - {create_resp.text}",
+                    {"request_body": payload}
+                )
+
+            cj = create_resp.json() or {}
+            created = (cj.get("UserGroup") or {}) if "UserGroup" in cj else cj
+
+            return self.success_response({
+                "message": f"User group '{name}' created successfully",
+                "created": {
+                    "id": created.get("id"),
+                    "name": created.get("name", name),
+                    "parent_id": parent_id_int,
+                    "depth": depth_val
+                }
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_user_groups(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """List all user groups (GET /api/user_groups)."""
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(f"{self.session.config.biostar_url}/api/user_groups", headers=headers)
+
+            if resp.status_code != 200:
+                return self.error_response(f"Failed to list user groups: {resp.status_code} - {resp.text}")
+
+            data = resp.json() or {}
+            coll = (data.get("UserGroupCollection") or {})
+            rows = coll.get("rows", []) or []
+            total = coll.get("total")
+
+            def _children(r):
+                ch = r.get("user_groups", []) or []
+                out = []
+                for c in ch:
+                    if isinstance(c, dict):
+                        out.append({"id": str(c.get("id")), "name": c.get("name")})
+                return out
+
+            groups = []
+            for r in rows:
+                if not isinstance(r, dict):
+                    continue
+                item = {
+                    "id": str(r.get("id")),
+                    "name": r.get("name"),
+                    "description": r.get("description", ""),
+                    "depth": str(r.get("depth")) if r.get("depth") is not None else None,
+                    "inherited": str(r.get("inherited")) if r.get("inherited") is not None else None,
+                    "user_count": r.get("user_count"),
+                }
+                if isinstance(r.get("parent_id"), dict):
+                    item["parent_id"] = {
+                        "id": str(r["parent_id"].get("id")),
+                        "name": r["parent_id"].get("name")
+                    }
+                item["user_groups"] = _children(r)
+                groups.append(item)
+
+            try:
+                total_int = int(total) if total is not None else len(groups)
+            except Exception:
+                total_int = len(groups)
+
+            return self.success_response({
+                "message": f"Found {total_int} user group(s)",
+                "total": total_int,
+                "groups": groups
+            })
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ---------- helpers (internal) ----------
+    async def _fetch_user_detail(self, headers: Dict[str, str], user_id: str) -> Optional[Dict[str, Any]]:
+        """GET /api/users/{id} and return 'User' object or None."""
+        async with httpx.AsyncClient(verify=False) as client:
+            r = await client.get(f"{self.session.config.biostar_url}/api/users/{user_id}", headers=headers)
+        if r.status_code != 200:
+            return None
+        return (r.json() or {}).get("User") or {}
+
+    async def _resolve_user(self, headers: Dict[str, str], user_id: Optional[Any], name: Optional[str]):
+        """
+        Resolve a user by user_id or name with 0/1/many branching.
+        - If user_id provided → verify existence.
+        - Else use search_users_by_name() to handle 0/1/many matches.
+        """
+        if user_id is not None:
+            uid = str(user_id)
+            detail = await self._fetch_user_detail(headers, uid)
+            if not detail:
+                return {"error": f"User '{uid}' not found"}
+            return {"user_id": uid, "user": detail}
+
+        nm = (name or "").strip()
+        if not nm:
+            return {"error": "Either 'user_id' or 'name' is required"}
+
+        matches = await search_users_by_name(self.get_session_id(), nm)
+        if not matches:
+            return {"error": f"No user found with name '{nm}'"}
+        if len(matches) > 1:
+            return {
+                "needs_selection": True,
+                "type": "user",
+                "message": f"Multiple users matched for '{nm}'. Which one?",
+                "prompt": "Which user?",
+                "candidates": [{"user_id": str(m.get("user_id")), "name": m.get("name")} for m in matches]
+            }
+        uid = str(matches[0]["user_id"])
+        detail = await self._fetch_user_detail(headers, uid)
+        if not detail:
+            return {"error": f"User '{uid}' not found"}
+        return {"user_id": uid, "user": detail}
+
+    async def _list_user_groups_rows(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """GET /api/user_groups and return raw rows."""
+        async with httpx.AsyncClient(verify=False) as client:
+            r = await client.get(f"{self.session.config.biostar_url}/api/user_groups", headers=headers)
+        if r.status_code != 200:
+            return []
+        data = r.json() or {}
+        return (data.get("UserGroupCollection") or {}).get("rows", []) or []
+
+    def _flatten_groups_basic(self, rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Flatten top-level rows and their children (id, name, depth, parent_id if possible).
+        """
+        flat: Dict[str, Dict[str, Any]] = {}
+        # top-level rows
+        for g in rows:
+            gid = g.get("id")
+            if gid is None:
+                continue
+            key = str(gid)
+            flat[key] = {
+                "id": int(gid),
+                "name": g.get("name"),
+                "depth": g.get("depth"),
+                "parent_id": (g.get("parent_id") or {}).get("id") if isinstance(g.get("parent_id"), dict) else g.get("parent_id"),
+            }
+        # children
+        for g in rows:
+            try:
+                base_depth = int(str(g.get("depth"))) if g.get("depth") is not None else 0
+            except Exception:
+                base_depth = 0
+            for ch in (g.get("user_groups") or []):
+                cid = ch.get("id")
+                if cid is None:
+                    continue
+                ckey = str(cid)
+                if ckey not in flat:
+                    flat[ckey] = {
+                        "id": int(cid),
+                        "name": ch.get("name"),
+                        "depth": base_depth + 1,
+                        "parent_id": g.get("id"),
+                    }
+        return list(flat.values())
+
+    def _filter_groups_by_name(self, rows: List[Dict[str, Any]], query: str) -> List[Dict[str, Any]]:
+        """Case-insensitive substring match on group name."""
+        q = " ".join((query or "").lower().split())
+        out = []
+        for r in rows:
+            nm = " ".join(str(r.get("name") or "").lower().split())
+            if q in nm:
+                out.append(r)
+        return out
+
+    # ---------- add user to a user group ----------
+    async def add_user_to_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Assign a user to a specific user group via PUT /api/users/{user_id}.
+        Flow:
+          1) Resolve user (id or name) with 0/1/many.
+          2) Resolve target group (id or name/search) with 0/1/many.
+          3) If same as current group -> no-op.
+          4) PUT with preserved name/start/expiry fields.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # 1) resolve user
+            user_res = await self._resolve_user(headers, args.get("user_id"), args.get("name"))
+            if "error" in user_res:
+                return self.error_response(user_res["error"])
+            if user_res.get("needs_selection"):
+                return self.success_response(user_res)
+            user_id = user_res["user_id"]
+            user_obj = user_res["user"]
+
+            # 2) resolve user group
+            rows = await self._list_user_groups_rows(headers)
+            flat = self._flatten_groups_basic(rows)
+            id_set = {str(g["id"]) for g in flat}
+
+            target_gid: Optional[int] = None
+            if args.get("user_group_id") is not None:
+                gid_str = str(args.get("user_group_id")).strip()
+                if gid_str not in id_set:
+                    return self.success_response({
+                        "status": "user_group_not_found",
+                        "needs_selection": True,
+                        "message": f"User group id '{gid_str}' not found. Please pick one.",
+                        "prompt": "Which user group?",
+                        "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                    })
+                target_gid = int(gid_str)
+            else:
+                gq = (args.get("group_name") or args.get("group_search_text") or "").strip()
+                if not gq:
+                    return self.success_response({
+                        "status": "user_group_required",
+                        "needs_selection": True,
+                        "message": "Please specify a user group to assign.",
+                        "prompt": "Which user group?",
+                        "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                    })
+                matches = self._filter_groups_by_name(flat, gq)
+                if len(matches) == 0:
+                    return self.success_response({
+                        "status": "user_group_not_found",
+                        "needs_selection": True,
+                        "message": f"No user group matched '{gq}'. Please pick one below.",
+                        "prompt": "Which user group?",
+                        "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                    })
+                if len(matches) > 1:
+                    return self.success_response({
+                        "status": "ambiguous_user_group",
+                        "needs_selection": True,
+                        "message": f"Multiple user groups matched '{gq}'. Which one?",
+                        "prompt": "Which user group?",
+                        "candidates": [{"id": g["id"], "name": g["name"]} for g in matches]
+                    })
+                target_gid = int(matches[0]["id"])
+
+            # 3) skip if already in the target group
+            cur_gid = None
+            ug = user_obj.get("user_group_id")
+            if isinstance(ug, dict) and ug.get("id") is not None:
+                try:
+                    cur_gid = int(str(ug.get("id")))
+                except Exception:
+                    cur_gid = None
+            if cur_gid == target_gid:
+                return self.success_response({
+                    "message": f"User {user_id} is already in group {target_gid}.",
+                    "user_id": user_id,
+                    "current_group_id": cur_gid,
+                    "target_group_id": target_gid,
+                    "changed": False
+                })
+
+            # 4) PUT (preserve required fields)
+            name_val = user_obj.get("name") or args.get("new_name") or args.get("name") or ""
+            start_val = user_obj.get("start_datetime") or "2001-01-01T00:00:00.00Z"
+            expiry_val = user_obj.get("expiry_datetime") or "2030-12-31T23:59:00.00Z"
+
+            payload = {
+                "User": {
+                    "name": name_val,
+                    "user_group_id": {"id": target_gid},
+                    "start_datetime": start_val,
+                    "expiry_datetime": expiry_val
+                }
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                pr = await client.put(f"{self.session.config.biostar_url}/api/users/{user_id}",
+                                      headers=headers, json=payload)
+
+            if pr.status_code != 200:
+                return self.error_response(
+                    f"Failed to update user: {pr.status_code} - {pr.text}",
+                    {"request_body": payload}
+                )
+
+            return self.success_response({
+                "message": f"User {user_id} has been assigned to group {target_gid}.",
+                "user_id": user_id,
+                "before_group_id": cur_gid,
+                "after_group_id": target_gid,
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ---------- remove user from a user group (move elsewhere) ----------
+    async def remove_user_from_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Exclude a user from a given group by moving to a destination group via PUT /api/users/{user_id}.
+        Behavior:
+          - If 'from_*' specified, user must currently belong to that group.
+          - Destination resolution priority:
+              1) destination_group_id
+              2) destination_group_name/search_text (0/1/many)
+              3) parent of current group → if none, fallback to 1 (All Users)
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # 1) resolve user
+            user_res = await self._resolve_user(headers, args.get("user_id"), args.get("name"))
+            if "error" in user_res:
+                return self.error_response(user_res["error"])
+            if user_res.get("needs_selection"):
+                return self.success_response(user_res)
+            user_id = user_res["user_id"]
+            user_obj = user_res["user"]
+
+            # current group
+            cur_gid = None
+            cur_gname = None
+            ug = user_obj.get("user_group_id")
+            if isinstance(ug, dict):
+                cur_gid = ug.get("id")
+                cur_gname = ug.get("name")
+            try:
+                cur_gid = int(str(cur_gid)) if cur_gid is not None else None
+            except Exception:
+                cur_gid = None
+
+            # 2) groups index
+            rows = await self._list_user_groups_rows(headers)
+            flat = self._flatten_groups_basic(rows)
+            id_set = {str(g["id"]) for g in flat}
+            by_id = {int(g["id"]): g for g in flat}
+
+            # 3) optional from-group validation
+            if args.get("from_user_group_id") is not None or args.get("from_group_name") or args.get("from_group_search_text"):
+                if args.get("from_user_group_id") is not None:
+                    fid_str = str(args.get("from_user_group_id")).strip()
+                    if fid_str not in id_set:
+                        return self.success_response({
+                            "status": "user_group_not_found",
+                            "needs_selection": True,
+                            "message": f"From-group id '{fid_str}' not found. Please pick one.",
+                            "prompt": "Which user group?",
+                            "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                        })
+                    from_gid = int(fid_str)
+                else:
+                    fq = (args.get("from_group_name") or args.get("from_group_search_text") or "").strip()
+                    matches = self._filter_groups_by_name(flat, fq)
+                    if len(matches) == 0:
+                        return self.success_response({
+                            "status": "user_group_not_found",
+                            "needs_selection": True,
+                            "message": f"No user group matched '{fq}'. Please pick one below.",
+                            "prompt": "Which user group?",
+                            "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                        })
+                    if len(matches) > 1:
+                        return self.success_response({
+                            "status": "ambiguous_user_group",
+                            "needs_selection": True,
+                            "message": f"Multiple user groups matched '{fq}'. Which one?",
+                            "prompt": "Which user group?",
+                            "candidates": [{"id": g["id"], "name": g["name"]} for g in matches]
+                        })
+                    from_gid = int(matches[0]["id"])
+
+                if cur_gid is None or cur_gid != from_gid:
+                    return self.error_response(
+                        "User is not currently in the specified 'from' group.",
+                        {"current_group_id": cur_gid, "current_group_name": cur_gname, "from_group_id": from_gid}
+                    )
+
+            # 4) resolve destination group
+            dest_gid: Optional[int] = None
+            if args.get("destination_group_id") is not None:
+                dg_str = str(args.get("destination_group_id")).strip()
+                if dg_str not in id_set:
+                    return self.success_response({
+                        "status": "user_group_not_found",
+                        "needs_selection": True,
+                        "message": f"Destination group id '{dg_str}' not found. Please pick one.",
+                        "prompt": "Which user group?",
+                        "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                    })
+                dest_gid = int(dg_str)
+            elif (args.get("destination_group_name") or args.get("destination_group_search_text")):
+                dq = (args.get("destination_group_name") or args.get("destination_group_search_text") or "").strip()
+                matches = self._filter_groups_by_name(flat, dq)
+                if len(matches) == 0:
+                    return self.success_response({
+                        "status": "user_group_not_found",
+                        "needs_selection": True,
+                        "message": f"No user group matched '{dq}'. Please pick one below.",
+                        "prompt": "Which user group?",
+                        "user_groups": [{"id": g["id"], "name": g["name"]} for g in flat]
+                    })
+                if len(matches) > 1:
+                    return self.success_response({
+                        "status": "ambiguous_user_group",
+                        "needs_selection": True,
+                        "message": f"Multiple user groups matched '{dq}'. Which one?",
+                        "prompt": "Which user group?",
+                        "candidates": [{"id": g["id"], "name": g["name"]} for g in matches]
+                    })
+                dest_gid = int(matches[0]["id"])
+            else:
+                # fallback: parent → if missing, move to 1 (All Users)
+                if cur_gid is not None and cur_gid in by_id:
+                    parent_id = by_id[cur_gid].get("parent_id")
+                    try:
+                        dest_gid = int(str(parent_id)) if parent_id is not None else 1
+                    except Exception:
+                        dest_gid = 1
+                else:
+                    dest_gid = 1
+
+            # 5) no-op if same
+            if cur_gid == dest_gid:
+                return self.success_response({
+                    "message": f"Destination group {dest_gid} equals current group; no change applied.",
+                    "user_id": user_id,
+                    "current_group_id": cur_gid,
+                    "target_group_id": dest_gid,
+                    "changed": False
+                })
+
+            # 6) PUT (preserve required fields)
+            name_val = user_obj.get("name") or ""
+            start_val = user_obj.get("start_datetime") or "2001-01-01T00:00:00.00Z"
+            expiry_val = user_obj.get("expiry_datetime") or "2030-12-31T23:59:00.00Z"
+
+            payload = {
+                "User": {
+                    "name": name_val,
+                    "user_group_id": {"id": dest_gid},
+                    "start_datetime": start_val,
+                    "expiry_datetime": expiry_val
+                }
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                pr = await client.put(f"{self.session.config.biostar_url}/api/users/{user_id}",
+                                      headers=headers, json=payload)
+
+            if pr.status_code != 200:
+                return self.error_response(
+                    f"Failed to update user: {pr.status_code} - {pr.text}",
+                    {"request_body": payload}
+                )
+
+            return self.success_response({
+                "message": f"User {user_id} has been moved from group {cur_gid} to {dest_gid}.",
+                "user_id": user_id,
+                "before_group_id": cur_gid,
+                "after_group_id": dest_gid,
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def bulk_edit_users(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Bulk update multiple users selected by 'adv_criteria' using the fixed endpoint:
+        PUT https://192.168.120.71/api/users?adv=mode1
+
+        Inputs:
+          - adv_criteria: dict (required)
+          - (optional) new_user_group_id OR new_user_group (object)
+          - (optional) start_datetime, expiry_datetime
+          - (optional) access_group_ids OR access_groups, or clear_access_groups=True
+          - dry_run: if true, return payload only
+          - timeout: request timeout in seconds
+
+        Behavior:
+          - Builds the 'User' patch from provided fields.
+          - Enforces at least one change.
+          - If dry_run: returns the planned payload without HTTP call.
+          - Otherwise: PUT to the fixed URL with 'bs-session-id' header.
+        """
+        try:
+            self.check_auth()
+
+            # Validate args with Pydantic
+            try:
+                input_data = BulkEditUsersInput(**args)
+            except Exception as e:
+                return self.handle_validation_error(e)
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # Build 'User' patch object
+            user_patch: Dict[str, Any] = {}
+
+            # 1) user_group_id (either minimal id form or pass-through object)
+            if input_data.new_user_group is not None:
+                # Pass-through as provided (e.g., {"id": "4036", "name": "ACE"})
+                user_patch["user_group_id"] = input_data.new_user_group
+            elif input_data.new_user_group_id is not None:
+                user_patch["user_group_id"] = {"id": str(input_data.new_user_group_id)}
+
+            # 2) period (start/expiry)
+            if input_data.start_datetime is not None:
+                user_patch["start_datetime"] = input_data.start_datetime
+            if input_data.expiry_datetime is not None:
+                user_patch["expiry_datetime"] = input_data.expiry_datetime
+
+            # 3) access_groups
+            if input_data.clear_access_groups:
+                user_patch["access_groups"] = []
+            elif input_data.access_groups is not None:
+                # Full objects pass-through (may contain accessLevels, users, etc.)
+                user_patch["access_groups"] = input_data.access_groups
+            elif input_data.access_group_ids is not None:
+                # Minimal id-only list
+                user_patch["access_groups"] = [{"id": str(gid)} for gid in input_data.access_group_ids]
+
+            # Sanity: ensure we actually have changes (should be guaranteed by validator)
+            if not user_patch:
+                return self.error_response(
+                    "No changes to apply. Provide at least one of group/period/access_groups."
+                )
+
+            payload: Dict[str, Any] = {
+                "adv_criteria": input_data.adv_criteria,
+                "User": user_patch
+            }
+
+            # Dry-run: return the planned payload without calling API
+            if input_data.dry_run:
+                return self.success_response({
+                    "message": "Dry run: no API call was made.",
+                    "request_body": payload,
+                    "endpoint": "https://192.168.120.71/api/users?adv=mode1",
+                    "method": "PUT"
+                })
+
+            # Execute PUT to the fixed endpoint (verify=False for internal/self-signed TLS)
+            endpoint = "https://192.168.120.71/api/users?adv=mode1"
+            async with httpx.AsyncClient(verify=False, timeout=input_data.timeout) as client:
+                resp = await client.put(endpoint, headers=headers, json=payload)
+
+            if resp.status_code != 200:
+                # Return API error with the request body for troubleshooting
+                return self.error_response(
+                    f"Bulk edit failed: {resp.status_code} - {resp.text}",
+                    {"request_body": payload}
+                )
+
+            # Try to parse JSON; if not JSON, return raw text
+            try:
+                resp_json = resp.json()
+            except Exception:
+                resp_json = {"raw": resp.text}
+
+            return self.success_response({
+                "message": "Bulk edit applied successfully.",
+                "endpoint": endpoint,
+                "request_body": payload,
+                "response": resp_json
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # -----------------------------------------
+    # Helper: write CSV into nginx/download dir
+    # -----------------------------------------
+    async def _write_csv_to_download_dir(self, filename: str, data: bytes) -> Dict[str, Any]:
+        DOWNLOAD_ROOT = r"C:\Program Files\BioStar X\nginx\html\download"
+        if not filename:
+            return {"error": "Missing filename."}
+        basename = Path(filename).name
+        target_path = Path(DOWNLOAD_ROOT) / basename
+        try:
+            os.makedirs(target_path.parent, exist_ok=True)
+            with open(target_path, "wb") as f:
+                f.write(data)
+        except PermissionError:
+            return {"error": f"Permission denied writing: {str(target_path)}"}
+        except Exception as e:
+            return {"error": f"Failed to write CSV: {e}"}
+        return {"path": str(target_path), "basename": basename}
+
+    # -------------------------------------------------
+    # NEW: try to locate CSV bytes from multiple places
+    # -------------------------------------------------
+    async def _load_csv_bytes_from_args(self, args: Dict[str, Any], *, timeout: int) -> Dict[str, Any]:
+        """
+        Returns:
+        { "bytes": <bytes>, "basename": <str> } or { "error": "..." }
+
+        Priority:
+        1) file_base64 / file_text / file_bytes (직접 바이트 제공)
+        2) file_path (URL이면 다운로드, 아니면 로컬 경로/후보 폴더에서 탐색)
+        """
+        # 1) explicit content
+        file_base64 = args.get("file_base64")
+        file_text = args.get("file_text")
+        file_bytes = args.get("file_bytes")
+
+        preferred_name = (
+            (args.get("original_file_name") or "")
+            or (args.get("fileName") or "")
+            or (args.get("file_path") or "")
+            or (args.get("uri") or "")
+            or "upload.csv"
+        )
+        basename = Path(preferred_name).name or "upload.csv"
+
+        if file_base64 is not None:
+            try:
+                b = base64.b64decode(file_base64)
+            except Exception:
+                return {"error": "Invalid 'file_base64'. Base64 decode failed."}
+            return {"bytes": b, "basename": basename}
+
+        if file_text is not None:
+            charset = str(args.get("charset", "utf-8-sig"))
+            try:
+                b = str(file_text).encode(charset or "utf-8")
+            except Exception:
+                return {"error": "Encoding 'file_text' failed."}
+            return {"bytes": b, "basename": basename}
+
+        if file_bytes is not None:
+            if isinstance(file_bytes, list):
+                try:
+                    b = bytes(file_bytes)
+                except Exception:
+                    return {"error": "Invalid 'file_bytes' list."}
+            elif isinstance(file_bytes, (bytes, bytearray)):
+                b = bytes(file_bytes)
+            else:
+                return {"error": "Invalid 'file_bytes'. Provide bytes/bytearray or list[int]."}
+            return {"bytes": b, "basename": basename}
+
+        # 2) fallback: file_path as URL or local path (+ smart search)
+        file_path = str(args.get("file_path") or "").strip()
+        if file_path:
+            # URL?
+            if re.match(r"^https?://", file_path, flags=re.I):
+                try:
+                    with httpx.Client(verify=False, timeout=timeout) as sclient:
+                        r = sclient.get(file_path)
+                    if r.status_code != 200:
+                        return {"error": f"Failed to download CSV from URL (HTTP {r.status_code})."}
+                    # use the remote filename if available
+                    remote_name = Path(file_path).name or basename
+                    return {"bytes": r.content, "basename": Path(remote_name).name}
+                except Exception as e:
+                    return {"error": f"Failed to download CSV from URL: {e}"}
+
+            # Local path exact
+            p = Path(file_path)
+            if p.exists():
+                try:
+                    return {"bytes": p.read_bytes(), "basename": p.name}
+                except Exception as e:
+                    return {"error": f"Failed to read local CSV: {e}"}
+
+            # Smart search candidates (so 'User_....csv' 같은 '파일명만'도 처리)
+            candidates: List[Path] = []
+            # 1) configured inbox
+            inbox = getattr(getattr(self, "session", None), "config", None)
+            inbox_dir = getattr(inbox, "upload_inbox_dir", None)
+            if inbox_dir:
+                candidates.append(Path(inbox_dir) / Path(file_path).name)
+            # 2) common MCP/Notebook mount
+            candidates.append(Path("/mnt/data") / Path(file_path).name)
+            # 3) current working dir
+            candidates.append(Path.cwd() / Path(file_path).name)
+            # 4) script dir (if available)
+            try:
+                candidates.append(Path(__file__).parent / Path(file_path).name)  # type: ignore
+            except Exception:
+                pass
+            # 5) user Downloads (best-effort)
+            try:
+                candidates.append(Path.home() / "Downloads" / Path(file_path).name)
+            except Exception:
+                pass
+
+            for c in candidates:
+                try:
+                    if c.exists():
+                        return {"bytes": c.read_bytes(), "basename": Path(file_path).name}
+                except Exception:
+                    continue
+
+            return {"error": "Local 'file_path' not found in known locations. "
+                            "Provide 'file_base64'/'file_text'/'file_bytes' or an 'http(s)://...' URL."}
+
+        return {"error": "CSV content is required. "
+                        "Provide 'file_base64', 'file_text', 'file_bytes', or a 'file_path' that resolves to a real file/URL."}
+
+    # ------------------------------------------------------------
+    # import_users_csv — write to download, preflight, then import
+    # ------------------------------------------------------------
+    async def import_users_csv(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        No /api/attachments.
+        1) Load CSV bytes (base64 / text / bytes / URL / smart local search incl. /mnt/data).
+        2) Save to: C:\Program Files\BioStar X\nginx\html\download\<basename>
+        3) Preflight: GET /download/<basename>
+        4) POST /api/users/csv_import with File.uri=<basename>, import_option=2
+        """
+        try:
+            self.check_auth()
+
+            DOWNLOAD_ROOT = r"C:\Program Files\BioStar X\nginx\html\download"
+            import_option = 2
+            if "import_option" in args:
+                args.pop("import_option", None)
+
+            start_line = int(args.get("start_line", 2))
+            timeout = int(args.get("timeout", 60))
+            headers_http = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json",
+            }
+
+            # Load bytes (now with /mnt/data and other fallbacks)
+            loaded = await self._load_csv_bytes_from_args(args, timeout=timeout)
+            if "error" in loaded:
+                return self.error_response(loaded["error"])
+            csv_bytes: bytes = loaded["bytes"]
+            basename: str = loaded["basename"]
+
+            # Write to nginx/download
+            w = await self._write_csv_to_download_dir(basename, csv_bytes)
+            if "error" in w:
+                return self.error_response(w["error"])
+
+            # Preflight (a few retries for disk/anti-virus lag)
+            ok = False
+            last = None
+            for _ in range(4):
+                try:
+                    with httpx.Client(verify=False, timeout=timeout) as sclient:
+                        r = sclient.get(f"{self.session.config.biostar_url}/download/{basename}", headers=headers_http)
+                    last = r.status_code
+                    if r.status_code == 200:
+                        ok = True
+                        break
+                except Exception:
+                    await asyncio.sleep(0.25)
+                    continue
+                await asyncio.sleep(0.25)
+            if not ok:
+                return self.error_response(
+                    f"CSV not served at /download/{basename} (HTTP {last}). "
+                    f"Check permissions on: {DOWNLOAD_ROOT}\\{basename}"
+                )
+
+            # Columns
+            status, j, _ = await self._http_get_json(
+                f"{self.session.config.biostar_url}/api/users/csv_option", headers_http, timeout
+            )
+            supported_cols: List[str] = []
+            if status == 200 and isinstance(j, dict):
+                supported_cols = ((j.get("CsvOption") or {}).get("columns") or {}).get("rows", []) or []
+
+            if args.get("columns"):
+                columns = list(args["columns"])
+            else:
+                columns = list(supported_cols) if supported_cols else await self._get_users_csv_columns(headers_http, timeout)
+
+            if args.get("headers"):
+                headers_map = list(args["headers"])
+            else:
+                headers_map = list(columns)
+
+            if len(headers_map) != len(columns):
+                return self.error_response(
+                    f"Length mismatch: headers({len(headers_map)}) vs columns({len(columns)})."
+                )
+
+            removed_unsupported: List[str] = []
+            if supported_cols:
+                f_cols, f_hdrs = [], []
+                for c, h in zip(columns, headers_map):
+                    if c in supported_cols:
+                        f_cols.append(c)
+                        f_hdrs.append(h)
+                    else:
+                        removed_unsupported.append(c)
+                columns, headers_map = f_cols, f_hdrs
+                if not columns:
+                    return self.error_response("All requested columns are unsupported by the server.")
+
+            file_info = {
+                "uri": basename,               # IMPORTANT: basename only
+                "fileName": basename,
+                "originalFileName": Path(args.get("original_file_name") or basename).name,
+                "type": "",
+            }
+            csv_option_block = {
+                "start_line": start_line,
+                "import_option": import_option,
+                "columns": {
+                    "total": str(len(columns)),
+                    "rows": columns,
+                },
+            }
+            query_block = {"headers": headers_map, "columns": columns}
+            body: Dict[str, Any] = {
+                "File": file_info,
+                "CsvOption": csv_option_block,
+                "Query": query_block,
+                "currentPhoneBook": 0,
+                "filterdUserIds": [],
+            }
+            data_rows = args.get("data_rows")
+            if isinstance(data_rows, list) and data_rows:
+                body["Data"] = data_rows
+
+            async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+                resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/users/csv_import",
+                    headers=headers_http,
+                    json=body,
+                )
+
+            if resp.status_code != 200:
+                return self.error_response(
+                    f"CSV import failed: {resp.status_code} - {resp.text}",
+                    {
+                        "request_body": {
+                            "File": file_info,
+                            "CsvOption": csv_option_block,
+                            "Query": query_block,
+                            **({"removed_unsupported": removed_unsupported} if removed_unsupported else {}),
+                            "server_path": str(Path(DOWNLOAD_ROOT) / basename),
+                        }
+                    },
+                )
+
+            try:
+                resp_json = resp.json()
+            except Exception:
+                resp_json = {"raw": resp.text}
+
+            summary = {
+                "message": "CSV import request accepted.",
+                "endpoint": "/api/users/csv_import",
+                "file": file_info,
+                "csv_option": {"start_line": start_line, "import_option": import_option},
+                "columns_total": len(columns),
+                "used_fields": [h for h in headers_map if h],
+                "skipped_fields": [c for (c, h) in zip(columns, headers_map) if not h],
+                **({"removed_unsupported": removed_unsupported} if removed_unsupported else {}),
+                "response": resp_json,
+                "server_path": str(Path(DOWNLOAD_ROOT) / basename),
+            }
+            return self.success_response(summary)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # -------------------------
+    # HTTP GET JSON helper
+    # -------------------------
+    async def _http_get_json(self, url: str, headers: Dict[str, str], timeout: int) -> Tuple[int, Any, str]:
+        """GET JSON helper (returns status, json-or-None, raw-text)."""
+        async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+            resp = await client.get(url, headers=headers)
+        raw = resp.text
+        try:
+            j = resp.json()
+        except Exception:
+            j = None
+        return resp.status_code, j, raw
+
+    # -------------------------
+    # Fetch CSV columns from server (fallback to baseline)
+    # -------------------------
+    async def _get_users_csv_columns(self, headers: Dict[str, str], timeout: int = 60) -> List[str]:
+        """
+        GET /api/users/csv_option → list of columns supported by the server.
+        If the server returns nothing or fails, return a safe baseline.
+        """
+        baseline = [
+            "user_id", "name", "department", "user_title", "phone", "email",
+            "user_group", "start_datetime", "expiry_datetime", "csn",
+            "secure_credential", "access_on_card",
+            "mobile_start_datetime", "mobile_expiry_datetime", "csn_mobile", "qr",
+            "26 bit SIA Standard-H10301", "HID 37 bit-H10302", "HID 37 bit-H10304",
+            "HID Corporate 1000", "HID Corporate 1000 48bit",
+            "MIFARE CSN 32bit", "MIFARE CSN 34bit (Parity)",
+            "DESFire 56bit", "DESFire 58bit (Parity)",
+            "face_image_file1", "face_image_file2", "pin", "tom_aoc", "tom_scc"
+        ]
+
+        url = f"{self.session.config.biostar_url}/api/users/csv_option"
+        status, j, _raw = await self._http_get_json(url, headers, timeout)
+
+        if status == 200 and isinstance(j, dict):
+            rows = ((j.get("CsvOption") or {}).get("columns") or {}).get("rows", [])
+            if isinstance(rows, list) and rows:
+                return rows
+
+        return baseline
+    async def import_users_csv_smart(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Smart CSV import (force overwrite, use next_user_id):
+        - Create an enhanced CSV that uses the server's full column list as headers
+        - Map name/email and inject defaults for user_group/start_datetime/expiry_datetime
+        - Get the starting ID via GET /api/users/next_user_id → fill user_id for each row
+        - Finally delegate to import_users_csv() (import_option=2 fixed)
+        - 🆕 After import, automatically update user groups, access groups, and dates from CSV
+        """
+        try:
+            self.check_auth()
+
+            # ---- Defaults/Options ----
+            default_group  = str(args.get("default_group_name", "All Users"))
+            default_start  = str(args.get("default_start_datetime", "2001-01-01 00:00"))
+            default_expiry = str(args.get("default_expiry_datetime", "2030-12-31 23:59"))
+            start_line     = int(args.get("start_line", 2))
+            timeout        = int(args.get("timeout", 60))
+            dry_run        = bool(args.get("dry_run", False))
+            auto_update    = bool(args.get("auto_update", True))  # 🆕 자동 업데이트 기능
+
+            # ---- Load original CSV ----
+            loaded = await self._load_csv_bytes_from_args(args, timeout=timeout)
+            if "error" in loaded:
+                return self.error_response(loaded["error"])
+            orig_bytes: bytes  = loaded["bytes"]
+            orig_basename: str = loaded["basename"] or "upload.csv"
+
+            # ---- CSV parsing ----
+            import csv, io, re
+            text = orig_bytes.decode(args.get("charset") or "utf-8-sig", errors="replace")
+            try:
+                sniff_sample = text[:2048]
+                dialect = csv.Sniffer().sniff(sniff_sample, delimiters=[",", ";", "|", "\t"])
+            except Exception:
+                class _D(csv.excel):
+                    delimiter = (args.get("delimiter") or ",")
+                dialect = _D
+
+            reader = csv.DictReader(io.StringIO(text), dialect=dialect)
+            src_headers_exact = [h for h in (reader.fieldnames or []) if h]
+            src_rows = list(reader)
+
+            # ---- Fetch full server column list ----
+            headers_http = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+            status, j, _raw = await self._http_get_json(
+                f"{self.session.config.biostar_url}/api/users/csv_option", headers_http, timeout
+            )
+            if status == 200 and isinstance(j, dict):
+                server_columns: list[str] = ((j.get("CsvOption") or {}).get("columns") or {}).get("rows", []) or []
+            else:
+                server_columns = await self._get_users_csv_columns(headers_http, timeout)
+            if not server_columns:
+                return self.error_response("Server did not provide CSV columns and no baseline is available.")
+
+            # ---- Aliases/Mapping ----
+            aliases = {
+                "name": {"name", "full name", "username"},
+                "email": {"email", "e-mail"},
+                "user_group": {"user_group", "user group", "group", "group_name", "group name"},
+                "start_datetime": {"start_datetime", "start", "start date", "valid_from", "start datetime"},
+                "expiry_datetime": {"expiry_datetime", "end", "end_datetime", "valid_to", "expiration_datetime", "end datetime"},
+            }
+            src_idx = {(h or "").strip().lower(): h for h in src_headers_exact if isinstance(h, str)}
+
+            def pick_src_header(alias_set: set[str]) -> str | None:
+                for cand in alias_set:
+                    k = str(cand).strip().lower()
+                    if k in src_idx:
+                        return src_idx[k]
+                return None
+
+            def _normalize_dt(s: str) -> str:
+                if not isinstance(s, str):
+                    return s
+                s = s.strip()
+                if re.match(r"^\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}$", s):
+                    return s + ":00"
+                return s
+
+            map_src_for = {
+                "name":            pick_src_header(aliases["name"]),
+                "email":           pick_src_header(aliases["email"]),
+                "user_group":      pick_src_header(aliases["user_group"]),
+                "start_datetime":  pick_src_header(aliases["start_datetime"]),
+                "expiry_datetime": pick_src_header(aliases["expiry_datetime"]),
+            }
+
+            # ---- Build enhanced CSV headers/rows ----
+            enhanced_headers_exact = list(server_columns)
+
+            def get_ci(row: dict, header_label: str) -> str | None:
+                want = (header_label or "").strip().lower()
+                for k, v in row.items():
+                    if (k or "").strip().lower() == want:
+                        return v
+                return None
+
+            enhanced_rows: list[dict[str, str]] = []
+            for row in src_rows:
+                out = {col: "" for col in enhanced_headers_exact}
+                if map_src_for["name"]:
+                    out["name"] = str(get_ci(row, map_src_for["name"]) or "").strip()
+                if map_src_for["email"]:
+                    out["email"] = str(get_ci(row, map_src_for["email"]) or "").strip()
+
+                out["user_group"] = (
+                    (str(get_ci(row, map_src_for["user_group"]) or "").strip())
+                    if map_src_for["user_group"] else ""
+                ) or default_group
+
+                sdt = (str(get_ci(row, map_src_for["start_datetime"]) or "").strip()
+                    if map_src_for["start_datetime"] else "") or default_start
+                edt = (str(get_ci(row, map_src_for["expiry_datetime"]) or "").strip()
+                    if map_src_for["expiry_datetime"] else "") or default_expiry
+                out["start_datetime"]  = _normalize_dt(sdt)
+                out["expiry_datetime"] = _normalize_dt(edt)
+
+                enhanced_rows.append(out)
+
+            # ---- Fill user_id using next_user_id ----
+            # (Note: assign sequentially for the number of rows. If there is concurrency, the server may reject some; check the error CSV.)
+            try:
+                async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+                    nid_resp = await client.get(f"{self.session.config.biostar_url}/api/users/next_user_id", headers=headers_http)
+                if nid_resp.status_code != 200:
+                    return self.error_response(f"Failed to get next_user_id: {nid_resp.status_code} - {nid_resp.text}")
+                start_id = int((nid_resp.json() or {}).get("User", {}).get("user_id"))
+            except Exception as e:
+                return self.error_response(f"Failed to parse next_user_id: {e!r}")
+
+            if "user_id" in enhanced_headers_exact:
+                for i, r in enumerate(enhanced_rows):
+                    r["user_id"] = str(start_id + i)
+
+            # ---- Dry-run ----
+            if dry_run:
+                return self.success_response({
+                    "message": "Dry-run: full-width enhanced CSV prepared with user_id assigned.",
+                    "enhanced_filename": f"enh_{orig_basename}",
+                    "enhanced_headers": enhanced_headers_exact,
+                    "row_count": len(enhanced_rows),
+                    "defaults_used": {
+                        "user_group": default_group,
+                        "start_datetime": default_start,
+                        "expiry_datetime": default_expiry,
+                    },
+                    "next_user_id_start": start_id,
+                    "server_columns_total": len(enhanced_headers_exact),
+                })
+
+            # ---- Serialize and delegate to import_users_csv() (import_option=2 fixed here) ----
+            import io as _io
+            buf = _io.StringIO()
+            w = csv.DictWriter(buf, fieldnames=enhanced_headers_exact, dialect=dialect)
+            w.writeheader()
+            for r in enhanced_rows:
+                w.writerow(r)
+            enhanced_text  = buf.getvalue()
+            enhanced_bytes = enhanced_text.encode("utf-8-sig")
+            enhanced_name  = f"enh_{orig_basename}"
+
+            # import_users_csv writes to the download folder + /download preflight + calls csv_import(import_option=2)
+            call_args = {
+                "file_bytes": enhanced_bytes,
+                "original_file_name": enhanced_name,
+                "start_line": start_line,
+                "timeout": timeout,
+                "columns": enhanced_headers_exact,
+                "headers": enhanced_headers_exact,
+            }
+            import_result = await self.import_users_csv(call_args)
+            
+            # 🆕 Auto-update: CSV에 User Group, Access Group, Start Date, End Date가 있으면 자동 업데이트
+            if auto_update and not dry_run:
+                # CSV에 추가 정보가 있는지 확인
+                has_user_group = any(col.lower() in ["user group", "user_group", "group"] for col in src_headers_exact)
+                has_access_group = any(col.lower() in ["access group", "access_group", "출입그룹"] for col in src_headers_exact)
+                has_dates = any(col.lower() in ["start date", "start_date", "end date", "end_date", "시작일", "종료일", "만료일"] for col in src_headers_exact)
+                
+                if has_user_group or has_access_group or has_dates:
+                    logger.info(f" Auto-update triggered: user_group={has_user_group}, access_group={has_access_group}, dates={has_dates}")
+                    
+                    # 원본 CSV 파일을 사용해서 bulk_update_users_from_file 호출
+                    try:
+                        update_args = {
+                            "file_bytes": orig_bytes,
+                            "original_file_name": orig_basename,
+                            "timeout": timeout,
+                        }
+                        update_result = await self.bulk_update_users_from_file(update_args)
+                        
+                        # import 결과와 update 결과를 결합
+                        combined_result = import_result[0] if import_result else TextContent(type="text", text="")
+                        update_text = update_result[0].text if update_result else ""
+                        
+                        return [TextContent(
+                            type="text",
+                            text=f"{combined_result.text}\n\n"
+                                 f"{'='*60}\n"
+                                 f" 자동 업데이트 완료 (User Groups, Access Groups, Dates)\n"
+                                 f"{'='*60}\n\n"
+                                 f"{update_text}"
+                        )]
+                    except Exception as e:
+                        logger.warning(f" Auto-update failed: {e}")
+                        # import는 성공했으므로 그 결과만 반환
+                        return import_result
+            
+            return import_result
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+
+    # ---- helper: CSV attachment upload ----
+    async def _upload_csv_attachment(self, filename: str, file_bytes: bytes, timeout: int) -> tuple[int, dict]:
+        """
+        Upload CSV to /api/attachments to obtain the uri.
+        Depending on the server, the key may be 'File' or 'Attachment'; the caller handles flexibly.
+        """
+        headers = {"bs-session-id": self.get_session_id()}
+        # Use the multipart upload helper if available
+        if hasattr(self, "_http_post_multipart"):
+            status, j, _raw = await self._http_post_multipart(
+                f"{self.session.config.biostar_url}/api/attachments",
+                files={"file": (filename, file_bytes, "text/csv")},
+                headers=headers,
+                timeout=timeout
+            )
+            return status, (j or {})
+        # Otherwise, upload JSON body (only if the server allows it); on failure, handle in the caller
+        status, j, _raw = await self._http_post_json(
+            f"{self.session.config.biostar_url}/api/attachments",
+            {"fileName": filename, "content_base64": file_bytes.decode("latin1")},
+            {**headers, "Content-Type": "application/json"},
+            timeout
+        )
+        return status, (j or {})
+
+    # JSON POST
+    async def _http_post_json(self, url: str, body: Dict[str, Any], headers: Dict[str, str], timeout: int) -> tuple[int, Any, str]:
+        async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+            resp = await client.post(url, headers=headers, json=body)
+        raw = resp.text
+        try:
+            j = resp.json()
+        except Exception:
+            j = None
+        return resp.status_code, j, raw
+
+    # multipart/form-data POST (file upload)
+    async def _http_post_multipart(self, url: str, files: Dict[str, tuple], headers: Dict[str, str], timeout: int) -> tuple[int, Any, str]:
+        async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+            resp = await client.post(url, headers=headers, files=files)
+        raw = resp.text
+        try:
+            j = resp.json()
+        except Exception:
+            j = None
+        return resp.status_code, j, raw
+
+    async def bulk_update_users_from_file(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Read a CSV-like file and update users:
+        - User Group: exclusive 1:1 replacement via PUT /api/users/{id}
+        - Access Group: additive only via PUT /api/access_groups/{id} with new_users
+        Name resolution rules:
+        - 0 match: return all users as candidates and ask for confirmation
+        - >1 matches: return matched candidates and ask for confirmation
+        - 1 match: proceed
+        Columns (case/spacing tolerant): name, group (user group), access group (can be name or id; multiple allowed by delimiters)
+        """
+        try:
+            # ---------- 0) Auth check ----------
+            self.check_auth()
+
+            timeout = int(args.get("timeout", 60))
+
+            # ---------- 1) Load CSV bytes ----------
+            loaded = await self._load_csv_bytes_from_args(args, timeout=timeout)
+            if "error" in loaded:
+                return self.error_response(loaded["error"])
+            file_bytes: bytes = loaded["bytes"]
+            basename: str = loaded.get("basename") or "upload.csv"
+
+            # ---------- 2) Decode & parse CSV ----------
+            import csv, io, re
+            text = file_bytes.decode(args.get("charset") or "utf-8-sig", errors="replace")
+            try:
+                sniff_sample = text[:2048]
+                dialect = csv.Sniffer().sniff(sniff_sample, delimiters=[",", ";", "|", "\t"])
+            except Exception:
+                class _D(csv.excel):
+                    delimiter = (args.get("delimiter") or ",")
+                dialect = _D
+
+            reader = csv.DictReader(io.StringIO(text), dialect=dialect)
+            src_headers_exact = list(reader.fieldnames or [])
+            src_rows: list[dict] = [dict(r) for r in reader]
+
+            # Case-insensitive header picking helper
+            def _pick(src_headers: list[str], *cands: str) -> Optional[str]:
+                norm = { (h or "").strip().lower(): h for h in src_headers if isinstance(h, str) }
+                for c in cands:
+                    k = (c or "").strip().lower()
+                    if k in norm:
+                        return norm[k]
+                return None
+
+            col_name  = _pick(src_headers_exact, "name", "user name", "username", "full name")
+            col_ug    = _pick(src_headers_exact, "group", "user group", "user_group", "group name", "group_name")
+            col_ag    = _pick(src_headers_exact, "access group", "access_group", "ag", "access-group", "출입그룹", "출입 그룹")
+            col_start = _pick(src_headers_exact, "start date", "start_date", "start datetime", "start_datetime", "시작일", "시작 일자")
+            col_end   = _pick(src_headers_exact, "end date", "end_date", "expiry date", "expiry_date", "expiry datetime", "expiry_datetime", "종료일", "만료일", "종료 일자", "만료 일자")
+
+            if not col_name:
+                return self.error_response(f"Missing required column 'name'. Detected headers: {src_headers_exact}")
+
+            # ---------- 3) Headers & base URL ----------
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+            base = self.session.config.biostar_url
+
+            # ---------- 4) List all users once (for name resolution & defaults) ----------
+            # Use v2 users search with minimal sort
+            users_body = {"limit": 0, "order_by": "user_id:false"}
+            st_users, users_json, users_raw = await self._http_post_json(
+                f"{base}/api/v2/users/search", users_body, headers, timeout
+            )
+            if st_users != 200 or not isinstance(users_json, dict):
+                return self.error_response(f"Failed to list users: {st_users}", {"raw": users_raw})
+
+            users_rows = ((users_json.get("UserCollection") or {}).get("rows") or [])
+
+            # Build: name -> list[user], uid -> minimal info for fallback
+            name_to_users: dict[str, list[dict]] = {}
+            uid_to_min: dict[str, dict] = {}
+            for u in users_rows:
+                nm = str(u.get("name") or "").strip()
+                name_to_users.setdefault(nm.lower(), []).append(u)
+                uid = u.get("user_id")
+                if uid is not None:
+                    uid_str = str(uid)
+                    uid_to_min[uid_str] = {
+                        "name": u.get("name") or "",
+                        "start_datetime": u.get("start_datetime") or "2001-01-01T00:00:00.00Z",
+                        "expiry_datetime": u.get("expiry_datetime") or "2030-12-31T23:59:00.00Z",
+                    }
+
+            # ---------- 5) List all user groups (FULL) and build name->id map ----------
+            # Prefer GET /api/user_groups (stable), then fallback to POST /api/v2/user_groups
+            st_ug, ug_json, ug_raw = await self._http_get_json(f"{base}/api/user_groups", headers, timeout)
+            if st_ug != 200 or not isinstance(ug_json, dict):
+                st_ug, ug_json, ug_raw = await self._http_post_json(
+                    f"{base}/api/v2/user_groups", {"limit": 0, "order_by": "id:false"}, headers, timeout
+                )
+                if st_ug != 200 or not isinstance(ug_json, dict):
+                    return self.error_response(f"Failed to list user groups: {st_ug}", {"raw": ug_raw})
+
+            ug_rows = ((ug_json.get("UserGroupCollection") or {}).get("rows") or [])
+            user_group_name_to_id: dict[str, int] = {}
+            # Flatten top-level rows + nested user_groups field
+            for g in ug_rows:
+                nm = str(g.get("name") or "").strip()
+                gid = g.get("id")
+                if nm and gid is not None:
+                    user_group_name_to_id[nm.lower()] = int(gid)
+                for child in (g.get("user_groups") or []):
+                    cnm = str(child.get("name") or "").strip()
+                    cid = child.get("id")
+                    if cnm and cid is not None:
+                        user_group_name_to_id[cnm.lower()] = int(cid)
+
+            # ---------- 6) Resolve each row's user by name (collect conflicts) ----------
+            provided_resolutions = args.get("name_resolutions") or {}
+            conflicts: list[dict] = []
+            resolved_rows: list[dict] = []  # [{name, user_id, user_group_name, access_group_tokens[]}]
+
+            # Build a quick 'all users' list used for 0-match suggestion
+            all_users_min = [{"user_id": str(u.get("user_id")), "name": u.get("name"), "email": u.get("email")} for u in users_rows]
+
+            for row in src_rows:
+                name_val = (str(row.get(col_name) or "").strip())
+                if not name_val:
+                    continue
+
+                candidates = name_to_users.get(name_val.lower(), [])
+                resolved_user_id: Optional[str] = None
+                if len(candidates) == 1:
+                    resolved_user_id = str(candidates[0].get("user_id"))
+                else:
+                    chosen = provided_resolutions.get(name_val)  # caller can provide mapping {name: user_id}
+                    if chosen:
+                        resolved_user_id = str(chosen)
+                    else:
+                        if len(candidates) == 0:
+                            conflicts.append({
+                                "name": name_val,
+                                "reason": "no_match",
+                                "candidates": all_users_min
+                            })
+                        else:
+                            conflicts.append({
+                                "name": name_val,
+                                "reason": "multiple_matches",
+                                "candidates": [
+                                    {
+                                        "user_id": str(c.get("user_id")),
+                                        "name": c.get("name"),
+                                        "email": c.get("email"),
+                                        "user_group": (c.get("user_group_id") or {}).get("name"),
+                                    } for c in candidates
+                                ]
+                            })
+
+                if resolved_user_id:
+                    # Normalize target user group (if present)
+                    target_group_name = str(row.get(col_ug) or "").strip() if col_ug else ""
+
+                    # Normalize access group cell -> tokens (can be delimited or single)
+                    ag_tokens: list[str] = []
+                    if col_ag:
+                        cell = str(row.get(col_ag) or "").strip()
+                        if cell:
+                            for tok in re.split(r"[;,/|]", cell):
+                                t = tok.strip()
+                                if t:
+                                    ag_tokens.append(t)
+                    
+                    # 날짜 값 파싱
+                    start_date_val = None
+                    end_date_val = None
+                    if col_start:
+                        start_raw = str(row.get(col_start) or "").strip()
+                        if start_raw:
+                            start_date_val = parse_flexible_date(start_raw, is_start=True)
+                    if col_end:
+                        end_raw = str(row.get(col_end) or "").strip()
+                        if end_raw:
+                            end_date_val = parse_flexible_date(end_raw, is_start=False)
+
+                    resolved_rows.append({
+                        "name": name_val,
+                        "user_id": resolved_user_id,
+                        "user_group_name": target_group_name,
+                        "access_group_tokens": ag_tokens,
+                        "start_datetime": start_date_val,
+                        "expiry_datetime": end_date_val,
+                    })
+
+            if conflicts:
+                import uuid
+                sel_token = args.get("selection_token") or f"sel_{uuid.uuid4().hex}"
+                return self.error_response("Some names need confirmation.", {
+                    "needs_selection": True,
+                    "selection_token": sel_token,
+                    "conflicts": conflicts,
+                })
+
+            if not resolved_rows:
+                return self.error_response("No resolvable rows found (empty or invalid file?)")
+
+            # ---------- 7) Build user-group changes (exclusive 1:1 replace) ----------
+            # Note: only when target group is found in user_group_name_to_id; otherwise record as unknown
+            # We do not send no-op changes (when current group == target)
+            uid_to_user = {str(u.get("user_id")): u for u in users_rows}
+            user_group_changes: list[dict] = []  # each: {user_id, gid, start_datetime, expiry_datetime}
+            unknown_user_groups: set[str] = set()
+
+            # 날짜 업데이트가 필요한 사용자들 (그룹 변경이 없어도 날짜만 업데이트)
+            user_date_updates: list[dict] = []  # each: {user_id, start_datetime, expiry_datetime}
+
+            for r in resolved_rows:
+                gname = (r.get("user_group_name") or "").strip()
+                has_group_change = False
+                gid = None
+                
+                if gname:
+                    gid = user_group_name_to_id.get(gname.lower())
+                    if gid is None:
+                        unknown_user_groups.add(gname)
+                    else:
+                        cur_u = uid_to_user.get(str(r["user_id"])) or {}
+                        cur_gid = ((cur_u.get("user_group_id") or {}).get("id"))
+                        try:
+                            if cur_gid is None or int(cur_gid) != int(gid):
+                                has_group_change = True
+                        except Exception:
+                            has_group_change = True
+
+                # 날짜 변경이 있는지 확인
+                has_date_change = r.get("start_datetime") is not None or r.get("expiry_datetime") is not None
+                
+                if has_group_change or has_date_change:
+                    change_info = {
+                        "user_id": str(r["user_id"]),
+                        "start_datetime": r.get("start_datetime"),
+                        "expiry_datetime": r.get("expiry_datetime"),
+                    }
+                    if has_group_change:
+                        change_info["gid"] = int(gid)
+                        user_group_changes.append(change_info)
+                    elif has_date_change:
+                        user_date_updates.append(change_info)
+
+            # ---------- 8) List access groups and map by name/id ----------
+            # Use v2 (no '/search'); if fails, fallback to legacy GET
+            st_ag, ag_json, ag_raw = await self._http_post_json(
+                f"{base}/api/v2/access_groups", {"limit": 0, "order_by": "id:false"}, headers, timeout
+            )
+            ag_rows = []
+            if st_ag == 200 and isinstance(ag_json, dict):
+                ag_rows = ((ag_json.get("AccessGroupCollection") or {}).get("rows") or [])
+            else:
+                st2, j2, raw2 = await self._http_get_json(f"{base}/api/access_groups", headers, timeout)
+                if st2 == 200 and isinstance(j2, dict):
+                    ag_rows = ((j2.get("AccessGroupCollection") or {}).get("rows") or [])
+                else:
+                    return self.error_response(f"Failed to list access groups: {st_ag} / fallback {st2}", {"raw": ag_raw})
+
+            ag_name_to_obj = {str(g.get("name") or "").strip().lower(): g for g in ag_rows}
+            ag_id_to_obj = {}
+            for g in ag_rows:
+                gid = g.get("id")
+                if gid is not None:
+                    try:
+                        ag_id_to_obj[int(gid)] = g
+                    except Exception:
+                        pass
+
+            # Build: {access_group_id(int) -> set(user_id)}
+            ag_to_user_ids: dict[int, set[str]] = {}
+            for r in resolved_rows:
+                for tok in (r.get("access_group_tokens") or []):
+                    # Accept either numeric ID or name-like token
+                    gid_resolved: Optional[int] = None
+                    # Try numeric first
+                    try:
+                        gid_try = int(str(tok))
+                        if gid_try in ag_id_to_obj:
+                            gid_resolved = gid_try
+                    except Exception:
+                        gid_resolved = None
+                    # Fallback to name
+                    if gid_resolved is None:
+                        gobj = ag_name_to_obj.get(str(tok).strip().lower())
+                        if gobj and gobj.get("id") is not None:
+                            try:
+                                gid_resolved = int(gobj["id"])
+                            except Exception:
+                                gid_resolved = None
+                    if gid_resolved is not None:
+                        ag_to_user_ids.setdefault(gid_resolved, set()).add(str(r["user_id"]))
+
+            # ---------- 9) Dry-run summary ----------
+            if bool(args.get("dry_run", False)):
+                return self.success_response({
+                    "message": "Dry run: no updates were sent.",
+                    "file": basename,
+                    "resolved_row_count": len(resolved_rows),
+                    "user_group_updates": {
+                        "total_users": len(user_group_changes),
+                        "unknown_user_groups": sorted(list(unknown_user_groups)),
+                    },
+                    "access_group_updates": {
+                        "groups_to_update": len(ag_to_user_ids),
+                        "per_group_counts": {str(gid): len(uids) for gid, uids in ag_to_user_ids.items()},
+                    },
+                })
+
+            # ---------- 10) Execute: per-user PUT /api/users/{id} (exclusive group replace + date updates) ----------
+            ug_results: list[dict] = []
+            date_results: list[dict] = []
+            
+            # 그룹 변경이 있는 사용자들 처리
+            if user_group_changes:
+                async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+                    for ch in user_group_changes:
+                        uid = ch["user_id"]
+                        tgt_gid = ch["gid"]
+
+                        # Hydrate details from server; fallback to pre-fetched minimal info
+                        user_obj = await self._fetch_user_detail(headers, uid)
+                        if not user_obj:
+                            user_obj = uid_to_min.get(uid, {})  # minimal but enough
+
+                        name_val   = user_obj.get("name") or (uid_to_min.get(uid) or {}).get("name") or ""
+                        
+                        # CSV에서 지정한 날짜 사용, 없으면 기존 값 유지
+                        start_val  = ch.get("start_datetime") or user_obj.get("start_datetime") or (uid_to_min.get(uid) or {}).get("start_datetime") or "2001-01-01T00:00:00.00Z"
+                        expiry_val = ch.get("expiry_datetime") or user_obj.get("expiry_datetime") or (uid_to_min.get(uid) or {}).get("expiry_datetime") or "2030-12-31T23:59:00.00Z"
+
+                        payload = {
+                            "User": {
+                                "name": name_val,
+                                "user_group_id": {"id": tgt_gid},   # exclusive replace: server moves user to this group
+                                "start_datetime": start_val,
+                                "expiry_datetime": expiry_val,
+                            }
+                        }
+                        resp = await client.put(f"{base}/api/users/{uid}", headers=headers, json=payload)
+                        ok = (resp.status_code == 200)
+                        try:
+                            body = resp.json()
+                        except Exception:
+                            body = {"raw": resp.text}
+                        ug_results.append({
+                            "ok": ok, "status": resp.status_code, "response": body,
+                            "user_id": uid, "target_group_id": tgt_gid
+                        })
+            
+            # 날짜만 업데이트하는 사용자들 처리
+            if user_date_updates:
+                async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+                    for ch in user_date_updates:
+                        uid = ch["user_id"]
+
+                        # Hydrate details from server
+                        user_obj = await self._fetch_user_detail(headers, uid)
+                        if not user_obj:
+                            user_obj = uid_to_min.get(uid, {})
+
+                        name_val = user_obj.get("name") or (uid_to_min.get(uid) or {}).get("name") or ""
+                        cur_gid = None
+                        ug = user_obj.get("user_group_id")
+                        if isinstance(ug, dict) and ug.get("id") is not None:
+                            cur_gid = int(str(ug["id"]))
+                        
+                        if cur_gid is None:
+                            date_results.append({
+                                "ok": False, "status": 0, "response": {"error": "No user_group_id found"},
+                                "user_id": uid
+                            })
+                            continue
+
+                        # CSV에서 지정한 날짜 사용, 없으면 기존 값 유지
+                        start_val  = ch.get("start_datetime") or user_obj.get("start_datetime") or (uid_to_min.get(uid) or {}).get("start_datetime") or "2001-01-01T00:00:00.00Z"
+                        expiry_val = ch.get("expiry_datetime") or user_obj.get("expiry_datetime") or (uid_to_min.get(uid) or {}).get("expiry_datetime") or "2030-12-31T23:59:00.00Z"
+
+                        payload = {
+                            "User": {
+                                "name": name_val,
+                                "user_group_id": {"id": cur_gid},
+                                "start_datetime": start_val,
+                                "expiry_datetime": expiry_val,
+                            }
+                        }
+                        resp = await client.put(f"{base}/api/users/{uid}", headers=headers, json=payload)
+                        ok = (resp.status_code == 200)
+                        try:
+                            body = resp.json()
+                        except Exception:
+                            body = {"raw": resp.text}
+                        date_results.append({
+                            "ok": ok, "status": resp.status_code, "response": body,
+                            "user_id": uid
+                        })
+
+            # ---------- 11) Execute: PUT /api/access_groups/{id} with new_users (additive only) ----------
+            ag_results: list[dict] = []
+            if ag_to_user_ids:
+                async with httpx.AsyncClient(verify=False, timeout=timeout) as client:
+                    for gid, uids in ag_to_user_ids.items():
+                        gobj = ag_id_to_obj.get(gid) or {}
+                        body = {
+                            "AccessGroup": {
+                                "name": gobj.get("name") or f"AG-{gid}",
+                                "access_levels": gobj.get("access_levels") or [],
+                                "user_groups": gobj.get("user_groups") or [],
+                                "new_users": [{"user_id": int(uid)} for uid in sorted(uids)],
+                            }
+                        }
+                        resp = await client.put(f"{base}/api/access_groups/{gid}", headers=headers, json=body)
+                        ok = (resp.status_code == 200)
+                        try:
+                            j = resp.json()
+                        except Exception:
+                            j = {"raw": resp.text}
+                        ag_results.append({
+                            "group_id": gid, "ok": ok, "status": resp.status_code, "response": j,
+                            "new_users_count": len(uids),
+                        })
+
+            # ---------- 12) Return summary ----------
+            return self.success_response({
+                "message": "Bulk update completed.",
+                "file": basename,
+                "user_group_updates": ug_results,
+                "user_date_only_updates": date_results,
+                "access_group_updates": ag_results,
+                "unknown_user_groups": sorted(list(unknown_user_groups)),
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+
+# ---------- NEW HELPER (place once at module level; do not modify existing helpers) ----------
+def _build_full_mapping_arrays(
+    server_columns: list[str],
+    csv_headers: list[str],
+    *,
+    alias_map: dict[str, list[str]],
+    forbid_headers_lower: set[str],
+) -> tuple[list[str], list[str]]:
+    """
+    Build full Query.columns/Query.headers arrays:
+    - columns: exact server-case list from /api/users/csv_option (as given)
+    - headers: same length; for each server column, put the CSV header name to map, or "" to skip
+    - forbid headers: any CSV header whose lower() is in forbid_headers_lower will NOT be mapped
+    - alias_map: keys are server column lower() -> list of candidate CSV header names (lower-case)
+    """
+    csv_idx = {str(h).strip().lower(): str(h).strip() for h in csv_headers if isinstance(h, str) and str(h).strip()}
+
+    full_columns: list[str] = list(server_columns)
+    full_headers: list[str] = []
+
+    for server_col in server_columns:
+        sc_lower = str(server_col).strip().lower()
+
+        # Never map user-defined IDs or forbidden headers
+        if sc_lower in forbid_headers_lower:
+            full_headers.append("")  # skip
+            continue
+
+        mapped_header = ""
+        # direct match
+        if sc_lower in csv_idx:
+            mapped_header = csv_idx[sc_lower]
+        else:
+            # alias match
+            for cand in alias_map.get(sc_lower, []):
+                lc = str(cand).strip().lower()
+                if lc in csv_idx and lc not in forbid_headers_lower:
+                    mapped_header = csv_idx[lc]
+                    break
+
+        full_headers.append(mapped_header or "")
+
+    return full_columns, full_headers