feat: 新增用户设备列表API、region筛选和配置接口

- 新增 /facescore/user_devices 接口，支持分页、device_id/region 筛选
- 新增 /facescore/config 配置接口，返回 region_codes 等字典配置
- 新增 /facescore/clean_debug_data 清理调试数据接口
- 新增 region_code_utils.py 地区代码转国家名称工具类（完整250+国家）
- database.py 新增 fetch_user_devices/count_user_devices/clean_debug_data
- models.py 新增 UserDeviceItem/UserDeviceListResponse，ImageScoreItem 增加 region/region_country
- 修改 outputs 接口支持 region 筛选并返回 region/region_country
- 所有 App 端接口（/app/analyze, /restore, /upscale, /face_verify, /upcolor, /anime_style, /celebrity/match）添加 region 获取和存储逻辑
- 设备列表支持检测总量统计（子查询关联 tpl_app_processed_images）

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

api_routes.py

@@ -76,10 +76,42 @@ from database import (
     infer_category_from_filename,
     fetch_today_category_counts,
     upsert_device_record,
+    fetch_user_devices,
+    count_user_devices,
+    clean_debug_data,
 )
+from region_code_utils import get_country_name_by_region_code, REGION_CODE_TO_NAME
 
 SERVER_HOSTNAME = os.environ.get("HOSTNAME", "")
 
+
+async def _record_device_info(request: Request) -> None:
+    """
+    从请求头中提取设备信息并异步记录到数据库
+    获取不到 region 时存空串
+    """
+    device_id = request.headers.get("x-device-id")
+    if device_id:
+        try:
+            device_info = {
+                "device_id": device_id,
+                "device_type": request.headers.get("x-device-type"),
+                "device_model": request.headers.get("x-device-model"),
+                "os_version": request.headers.get("x-os-version"),
+                "app_version": request.headers.get("x-app-version"),
+                "region": request.headers.get("x-region") or "",
+                "timezone": request.headers.get("x-timezone"),
+                "language": request.headers.get("Accept-Language"),
+            }
+            asyncio.create_task(upsert_device_record(**device_info))
+        except Exception as e:
+            logger.warning(f"Failed to record device info for {device_id}: {e}")
+
+
+def _get_region_from_headers(request: Request) -> str:
+    """从请求头获取 region，获取不到返回空串"""
+    return request.headers.get("x-region") or ""
+
 # 尝试导入DeepFace
 deepface_module = None
 if DEEPFACE_AVAILABLE:
@@ -339,6 +371,8 @@ from models import (
     CelebrityMatchResponse,
     CategoryStatsResponse,
     CategoryStatItem,
+    UserDeviceItem,
+    UserDeviceListResponse,
 )
 
 from face_analyzer import EnhancedFaceAnalyzer
@@ -743,6 +777,7 @@ async def _record_output_file(
     category: Optional[str] = None,
     bos_uploaded: bool = False,
     score: Optional[float] = None,
+    region: Optional[str] = None,
     extra: Optional[Dict[str, Any]] = None,
 ) -> None:
     """封装的图片记录写入，避免影响主流程"""
@@ -762,6 +797,7 @@ async def _record_output_file(
                 category=category,
                 bos_uploaded=bos_uploaded,
                 score=score_value,
+                region=region,
                 extra_metadata=extra,
             )
             # 使用与数据库一致的路径转换
@@ -1602,23 +1638,7 @@ async def app_analyze_face(
     App专用人脸分析接口，参数与原 /analyze 保持完全一致并透传。
     """
     # 异步记录设备信息
-    device_id = request.headers.get("x-device-id")
-    if device_id:
-        try:
-            device_info = {
-                "device_id": device_id,
-                "device_type": request.headers.get("x-device-type"),
-                "device_model": request.headers.get("x-device-model"),
-                "os_version": request.headers.get("x-os-version"),
-                "app_version": request.headers.get("x-app-version"),
-                "region": request.headers.get("x-region"),
-                "timezone": request.headers.get("x-timezone"),
-                "language": request.headers.get("Accept-Language"),
-            }
-            # 创建异步任务，不阻塞当前请求
-            asyncio.create_task(upsert_device_record(**device_info))
-        except Exception as e:
-            logger.warning(f"Failed to record device info for {device_id}: {e}")
+    await _record_device_info(request)
 
     return await analyze_face(
         request=request,
@@ -1877,6 +1897,87 @@ async def get_daily_category_stats():
     return CategoryStatsResponse(stats=stats, total=total)
 
 
+@api_router.post("/user_devices", response_model=UserDeviceListResponse, tags=["用户设备列表"])
+@log_api_params
+async def list_user_devices(
+    device_id: Optional[str] = Query(None, description="设备 ID 筛选"),
+    region: Optional[str] = Query(None, description="地区筛选"),
+    page: int = Query(1, ge=1, description="页码"),
+    page_size: int = Query(10, ge=1, le=100, description="每页数量"),
+):
+    """查询用户设备列表，支持按 device_id 和 region 筛选，按 created_at 倒序"""
+    try:
+        offset = (page - 1) * page_size
+        
+        devices = await fetch_user_devices(
+            device_id=device_id,
+            region=region,
+            offset=offset,
+            limit=page_size,
+        )
+        
+        total_count = await count_user_devices(device_id=device_id, region=region)
+        total_pages = (total_count + page_size - 1) // page_size
+        
+        results = []
+        for device in devices:
+            region_code = device.get("region") or ""
+            region_country = get_country_name_by_region_code(region_code) if region_code else ""
+            
+            results.append(UserDeviceItem(
+                device_id=device.get("device_id", ""),
+                device_type=device.get("device_type"),
+                device_model=device.get("device_model"),
+                os_version=device.get("os_version"),
+                app_version=device.get("app_version"),
+                timezone=device.get("timezone"),
+                region=region_code,
+                region_country=region_country,
+                language=device.get("language"),
+                created_at=device.get("created_at", "").strftime("%Y-%m-%d %H:%M:%S") if device.get("created_at") else "",
+                updated_at=device.get("updated_at", "").strftime("%Y-%m-%d %H:%M:%S") if device.get("updated_at") else "",
+            ))
+            # 添加 detection_count 字段
+            results[-1].detection_count = device.get("detection_count", 0)
+        
+        return UserDeviceListResponse(
+            results=results,
+            count=total_count,
+            page=page,
+            page_size=page_size,
+            total_pages=total_pages,
+        )
+    except Exception as e:
+        logger.error(f"Failed to get user devices list: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@api_router.post("/clean_debug_data", tags=["系统维护"])
+async def clean_debug_data_api():
+    """清理调试数据接口"""
+    try:
+        results = await clean_debug_data()
+        return {
+            "success": True,
+            "message": "清理成功",
+            "details": results,
+        }
+    except Exception as e:
+        logger.error(f"Failed to clean debug data: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@api_router.get("/config", tags=["系统配置"])
+async def get_app_config():
+    """
+    获取前端应用配置字典
+    返回地区代码映射表等配置项，支持后续扩展
+    """
+    return {
+        "region_codes": REGION_CODE_TO_NAME,
+    }
+
+
 @api_router.post("/outputs", response_model=PagedImageFileList, tags=["检测列表"])
 @log_api_params
 async def list_outputs(
@@ -1951,6 +2052,8 @@ async def list_outputs(
                     is_cropped = False
                     nickname_value = record.get("nickname") if record else None
                     hostname_value = record.get("hostname") if record else None
+                    region_code = record.get("region") or "" if record else ""
+                    region_country = get_country_name_by_region_code(region_code) if region_code else ""
                     last_modified_dt = None
 
                     if record:
@@ -1987,6 +2090,8 @@ async def list_outputs(
                         "last_modified": last_modified_str,
                         "nickname": nickname_value,
                         "hostname": hostname_value,
+                        "region": region_code,
+                        "region_country": region_country,
                     }
                     all_files.append(file_info)
 
@@ -2012,9 +2117,11 @@ async def list_outputs(
         # 普通文件列表模式（无关键词或CLIP不可用）
         logger.info("Returning regular file list")
         try:
+            region_filter = request.region if hasattr(request, 'region') else None
             total_count = await count_image_records(
                 category=category,
                 nickname=nickname_filter,
+                region=region_filter,
                 is_cropped_face=is_cropped_filter,
             )
             if total_count > 0:
@@ -2022,6 +2129,7 @@ async def list_outputs(
                 rows = await fetch_paged_image_records(
                     category=category,
                     nickname=nickname_filter,
+                    region=region_filter,
                     offset=offset,
                     limit=page_size,
                     is_cropped_face=is_cropped_filter,
@@ -2038,6 +2146,9 @@ async def list_outputs(
                     else:
                         last_modified_dt = last_modified
                     size_bytes = int(row.get("size_bytes") or 0)
+                    region_code = row.get("region") or ""
+                    region_country = get_country_name_by_region_code(region_code) if region_code else ""
+                    
                     paged_results.append({
                         "file_path": row.get("file_path"),
                         "score": float(row.get("score") or 0.0),
@@ -2048,6 +2159,8 @@ async def list_outputs(
                             "%Y-%m-%d %H:%M:%S") if last_modified_dt else "",
                         "nickname": row.get("nickname"),
                         "hostname": row.get("hostname"),
+                        "region": region_code,
+                        "region_country": region_country,
                     })
                 total_pages = (total_count + page_size - 1) // page_size
                 return PagedImageFileList(
@@ -2097,6 +2210,8 @@ async def list_outputs(
                     ),
                     "nickname": None,
                     "hostname": None,
+                    "region": None,
+                    "region_country": None,
                 }
                 all_files.append(file_info)
 
@@ -2336,6 +2451,7 @@ async def sync_bos_resources(
 @api_router.post("/restore")
 @log_api_params
 async def restore_old_photo(
+    request: Request,
     file: UploadFile = File(...),
     md5: str = Query(None, description="前端传递的文件md5，用于提前保存记录"),
     colorize: bool = Query(False, description="是否对黑白照片进行上色"),
@@ -2453,6 +2569,7 @@ async def restore_old_photo(
                 nickname=nickname,
                 category="restore",
                 bos_uploaded=True,
+                region=_get_region_from_headers(request),
                 extra={
                     "source": "restore",
                     "colorize": colorize,
@@ -2484,6 +2601,7 @@ async def restore_old_photo(
 @api_router.post("/upcolor")
 @log_api_params
 async def colorize_photo(
+    request: Request,
     file: UploadFile = File(...),
     md5: str = Query(None, description="前端传递的文件md5，用于提前保存记录"),
     nickname: str = Form(None, description="操作者昵称"),
@@ -2563,6 +2681,7 @@ async def colorize_photo(
                 nickname=nickname,
                 category="upcolor",
                 bos_uploaded=True,
+                region=_get_region_from_headers(request),
                 extra={
                     "source": "upcolor",
                     "md5": actual_md5,
@@ -2663,6 +2782,7 @@ async def preload_anime_models(
 @api_router.post("/anime_style")
 @log_api_params
 async def anime_stylize_photo(
+    request: Request,
     file: UploadFile = File(...),
     style_type: str = Form("handdrawn",
                            description="动漫风格类型: handdrawn=手绘风格, disney=迪士尼风格, illustration=插画风格, artstyle=艺术风格, anime=二次元风格, sketch=素描风格"),
@@ -2755,6 +2875,7 @@ async def anime_stylize_photo(
             nickname=nickname,
             category="anime_style",
             bos_uploaded=original_bos_uploaded,
+            region=_get_region_from_headers(request),
             extra={
                 "source": "anime_style",
                 "style_type": style_type,
@@ -2793,6 +2914,7 @@ async def anime_stylize_photo(
                 nickname=nickname,
                 category="anime_style",
                 bos_uploaded=bos_uploaded,
+                region=_get_region_from_headers(request),
                 extra={
                     "source": "anime_style",
                     "style_type": style_type,
@@ -2922,6 +3044,7 @@ async def grayscale_photo(
 @api_router.post("/upscale")
 @log_api_params
 async def upscale_photo(
+    request: Request,
     file: UploadFile = File(...),
     md5: str = Query(None, description="前端传递的文件md5，用于提前保存记录"),
     scale: int = Query(UPSCALE_SIZE, description="放大倍数，支持2或4倍"),
@@ -3010,6 +3133,7 @@ async def upscale_photo(
                 nickname=nickname,
                 category="upscale",
                 bos_uploaded=True,
+                region=_get_region_from_headers(request),
                 extra={
                     "source": "upscale",
                     "md5": actual_md5,
@@ -4283,6 +4407,7 @@ async def load_celebrity_database():
 @api_router.post("/celebrity/match", tags=["Face Recognition"])
 @log_api_params
 async def match_celebrity_face(
+    request: Request,
     file: UploadFile = File(..., description="待匹配的用户图片"),
     nickname: str = Form(None, description="操作者昵称"),
 ):
@@ -4346,6 +4471,7 @@ async def match_celebrity_face(
             file_path=temp_path,
             nickname=nickname,
             category="celebrity",
+            region=_get_region_from_headers(request),
             extra={
                 "source": "celebrity_match",
                 "role": "query",
@@ -4502,6 +4628,7 @@ async def match_celebrity_face(
                     file_path=face_path,
                     nickname=nickname,
                     category="face",
+                    region=_get_region_from_headers(request),
                     extra={
                         "source": "celebrity_match",
                         "role": "face_crop",
@@ -4522,6 +4649,7 @@ async def match_celebrity_face(
                     file_path=temp_path,
                     nickname=nickname,
                     category="celebrity",
+                    region=_get_region_from_headers(request),
                     extra={
                         "source": "celebrity_match",
                         "role": "annotated",
@@ -4571,6 +4699,7 @@ async def match_celebrity_face(
 @api_router.post("/face_verify")
 @log_api_params
 async def face_similarity_verification(
+    request: Request,
     file1: UploadFile = File(..., description="第一张人脸图片"),
     file2: UploadFile = File(..., description="第二张人脸图片"),
     nickname: str = Form(None, description="操作者昵称"),
@@ -4773,6 +4902,7 @@ async def face_similarity_verification(
                 file_path=original_path1,
                 nickname=nickname,
                 category="original",
+                region=_get_region_from_headers(request),
                 extra={
                     "source": "face_verify",
                     "role": "original1",
@@ -4784,6 +4914,7 @@ async def face_similarity_verification(
                 file_path=original_path2,
                 nickname=nickname,
                 category="original",
+                region=_get_region_from_headers(request),
                 extra={
                     "source": "face_verify",
                     "role": "original2",
@@ -4816,6 +4947,7 @@ async def face_similarity_verification(
                         file_path=face_path1,
                         nickname=nickname,
                         category="face",
+                        region=_get_region_from_headers(request),
                         extra={
                             "source": "face_verify",
                             "role": "face1",
@@ -4826,6 +4958,7 @@ async def face_similarity_verification(
                         file_path=face_path2,
                         nickname=nickname,
                         category="face",
+                        region=_get_region_from_headers(request),
                         extra={
                             "source": "face_verify",
                             "role": "face2",

database.py

@@ -125,6 +125,7 @@ async def upsert_image_record(
     last_modified: datetime,
     bos_uploaded: bool,
     hostname: Optional[str] = None,
+    region: Optional[str] = None,
     extra_metadata: Optional[Dict[str, Any]] = None,
 ) -> None:
   """写入或更新图片记录"""
@@ -139,8 +140,9 @@ async def upsert_image_record(
             last_modified,
             bos_uploaded,
             hostname,
+            region,
             extra_metadata
-        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
         ON DUPLICATE KEY UPDATE
             category = VALUES(category),
             nickname = VALUES(nickname),
@@ -150,6 +152,7 @@ async def upsert_image_record(
             last_modified = VALUES(last_modified),
             bos_uploaded = VALUES(bos_uploaded),
             hostname = VALUES(hostname),
+            region = VALUES(region),
             extra_metadata = VALUES(extra_metadata),
             updated_at = CURRENT_TIMESTAMP
     """
@@ -166,6 +169,7 @@ async def upsert_image_record(
         last_modified,
         1 if bos_uploaded else 0,
         hostname,
+        region,
         extra_value,
       ),
   )
@@ -175,6 +179,7 @@ async def fetch_paged_image_records(
     *,
     category: Optional[str],
     nickname: Optional[str],
+    region: Optional[str] = None,
     offset: int,
     limit: int,
     is_cropped_face: Optional[int] = None,
@@ -188,6 +193,9 @@ async def fetch_paged_image_records(
   if nickname:
     where_clauses.append("nickname LIKE %s")
     params.append(f"{nickname}%")
+  if region:
+    where_clauses.append("region = %s")
+    params.append(region)
   if is_cropped_face is not None:
     where_clauses.append("is_cropped_face = %s")
     params.append(is_cropped_face)
@@ -202,7 +210,8 @@ async def fetch_paged_image_records(
             size_bytes,
             last_modified,
             bos_uploaded,
-            hostname
+            hostname,
+            region
         FROM tpl_app_processed_images
         {where_sql}
         ORDER BY last_modified DESC, id DESC
@@ -216,6 +225,7 @@ async def count_image_records(
     *,
     category: Optional[str],
     nickname: Optional[str],
+    region: Optional[str] = None,
     is_cropped_face: Optional[int] = None,
 ) -> int:
   """按条件统计图片记录数量"""
@@ -227,6 +237,9 @@ async def count_image_records(
   if nickname:
     where_clauses.append("nickname LIKE %s")
     params.append(f"{nickname}%")
+  if region:
+    where_clauses.append("region = %s")
+    params.append(region)
   if is_cropped_face is not None:
     where_clauses.append("is_cropped_face = %s")
     params.append(is_cropped_face)
@@ -277,7 +290,8 @@ async def fetch_records_by_paths(file_paths: Iterable[str]) -> Dict[
             size_bytes,
             last_modified,
             bos_uploaded,
-            hostname
+            hostname,
+            region
         FROM tpl_app_processed_images
         WHERE file_path IN ({placeholders})
     """
@@ -389,6 +403,79 @@ async def upsert_device_record(
         logger.warning(f"写入设备记录失败: {exc}")
 
 
+async def fetch_user_devices(
+    *,
+    device_id: Optional[str] = None,
+    region: Optional[str] = None,
+    offset: int,
+    limit: int,
+) -> List[Dict[str, Any]]:
+    """查询用户设备列表，支持按 device_id 和 region 筛选，按 created_at 倒序"""
+    where_clauses: List[str] = []
+    params: List[Any] = []
+    
+    if device_id:
+        where_clauses.append("d.device_id LIKE %s")
+        params.append(f"{device_id}%")
+    
+    if region:
+        where_clauses.append("d.region = %s")
+        params.append(region)
+    
+    where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
+    
+    query = f"""
+        SELECT
+            d.device_id,
+            d.device_type,
+            d.device_model,
+            d.os_version,
+            d.app_version,
+            d.timezone,
+            d.region,
+            d.language,
+            d.created_at,
+            d.updated_at,
+            COALESCE((
+                SELECT COUNT(*) 
+                FROM tpl_app_processed_images p 
+                WHERE p.nickname LIKE CONCAT('android_release_', d.device_id, '%%')
+            ), 0) AS detection_count
+        FROM tpl_app_user_devices d
+        {where_sql}
+        ORDER BY d.created_at DESC
+        LIMIT %s OFFSET %s
+    """
+    params.extend([limit, offset])
+    return await fetch_all(query, params)
+
+
+async def count_user_devices(
+    *,
+    device_id: Optional[str] = None,
+    region: Optional[str] = None,
+) -> int:
+    """统计用户设备数量"""
+    where_clauses: List[str] = []
+    params: List[Any] = []
+    
+    if device_id:
+        where_clauses.append("d.device_id LIKE %s")
+        params.append(f"{device_id}%")
+    
+    if region:
+        where_clauses.append("d.region = %s")
+        params.append(region)
+    
+    where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
+    
+    query = f"SELECT COUNT(*) AS total FROM tpl_app_user_devices d {where_sql}"
+    rows = await fetch_all(query, params)
+    if not rows:
+        return 0
+    return int(rows[0].get("total", 0) or 0)
+
+
 async def record_image_creation(
     *,
     file_path: str,
@@ -396,6 +483,7 @@ async def record_image_creation(
     score: float = 0.0,
     category: Optional[str] = None,
     bos_uploaded: bool = False,
+    region: Optional[str] = None,
     extra_metadata: Optional[Dict[str, Any]] = None,
 ) -> None:
   """
@@ -437,7 +525,34 @@ async def record_image_creation(
         last_modified=last_modified,
         bos_uploaded=bos_uploaded,
         hostname=HOSTNAME,
+        region=region,
         extra_metadata=extra_metadata,
     )
   except Exception as exc:
     logger.warning(f"写入图片记录失败: {exc}")
+
+
+# 清理调试数据 SQL 列表，可在此处增删 SQL
+CLEAN_DEBUG_SQLS = [
+    "DELETE FROM tpl_app_user_devices WHERE device_model='Xiaomi 23127PN0CC' AND region='CN'",
+    "DELETE FROM tpl_app_processed_images WHERE nickname LIKE 'android_debug%'",
+    "DELETE FROM tpl_app_processed_images WHERE nickname='android_release_1b708ef79ac4f484'",
+    "DELETE FROM tpl_app_processed_images WHERE nickname='9527'",
+]
+
+
+async def clean_debug_data() -> Dict[str, int]:
+    """
+    清理调试数据
+    :return: 返回每个 SQL 影响的行数
+    """
+    results = {}
+    for idx, sql in enumerate(CLEAN_DEBUG_SQLS):
+        try:
+            affected = await execute(sql)
+            results[f"sql_{idx + 1}"] = affected
+            logger.info(f"Clean debug SQL #{idx + 1} executed, affected: {affected}")
+        except Exception as exc:
+            logger.warning(f"Clean debug SQL #{idx + 1} failed: {exc}")
+            results[f"sql_{idx + 1}"] = -1
+    return results

models.py

@@ -21,6 +21,8 @@ class ImageScoreItem(BaseModel):
     last_modified: str
     nickname: Optional[str] = None
     hostname: Optional[str] = None
+    region: Optional[str] = None
+    region_country: Optional[str] = None
 
 
 class SearchRequest(BaseModel):
@@ -29,6 +31,7 @@ class SearchRequest(BaseModel):
     top_k: Optional[int] = 5
     score_threshold: float = 0.0
     nickname: Optional[str] = None
+    region: Optional[str] = None
 
 
 class ImageSearchRequest(BaseModel):
@@ -68,3 +71,26 @@ class CategoryStatItem(BaseModel):
 class CategoryStatsResponse(BaseModel):
   stats: List[CategoryStatItem]
   total: int
+
+
+class UserDeviceItem(BaseModel):
+    device_id: str
+    device_type: Optional[str] = None
+    device_model: Optional[str] = None
+    os_version: Optional[str] = None
+    app_version: Optional[str] = None
+    timezone: Optional[str] = None
+    region: Optional[str] = None
+    region_country: Optional[str] = None
+    language: Optional[str] = None
+    detection_count: int = 0
+    created_at: str
+    updated_at: str
+
+
+class UserDeviceListResponse(BaseModel):
+    results: List[UserDeviceItem]
+    count: int
+    page: int
+    page_size: int
+    total_pages: int

region_code_utils.py

@@ -0,0 +1,294 @@
+# region_code_utils.py
+"""
+地区代码转换工具类
+将 ISO 3166-1 alpha-2 两位字母代码转换为完整国家名称
+"""
+
+# ISO 3166-1 alpha-2 国家代码映射表 (完整)
+REGION_CODE_TO_NAME = {
+    # A
+    "AF": "阿富汗",
+    "AL": "阿尔巴尼亚",
+    "DZ": "阿尔及利亚",
+    "AS": "美属萨摩亚",
+    "AD": "安道尔",
+    "AO": "安哥拉",
+    "AI": "安圭拉",
+    "AQ": "南极洲",
+    "AG": "安提瓜和巴布达",
+    "AR": "阿根廷",
+    "AM": "亚美尼亚",
+    "AW": "阿鲁巴",
+    "AU": "澳大利亚",
+    "AT": "奥地利",
+    "AZ": "阿塞拜疆",
+    # B
+    "BS": "巴哈马",
+    "BH": "巴林",
+    "BD": "孟加拉国",
+    "BB": "巴巴多斯",
+    "BY": "白俄罗斯",
+    "BE": "比利时",
+    "BZ": "伯利兹",
+    "BJ": "贝宁",
+    "BM": "百慕大",
+    "BT": "不丹",
+    "BO": "玻利维亚",
+    "BA": "波黑",
+    "BW": "博茨瓦纳",
+    "BV": "布韦岛",
+    "BR": "巴西",
+    "IO": "英属印度洋领地",
+    "BN": "文莱",
+    "BG": "保加利亚",
+    "BF": "布基纳法索",
+    "BI": "布隆迪",
+    # C
+    "KH": "柬埔寨",
+    "CM": "喀麦隆",
+    "CA": "加拿大",
+    "CV": "佛得角",
+    "KY": "开曼群岛",
+    "CF": "中非",
+    "TD": "乍得",
+    "CL": "智利",
+    "CN": "中国",
+    "CX": "圣诞岛",
+    "CC": "科科斯群岛",
+    "CO": "哥伦比亚",
+    "KM": "科摩罗",
+    "CG": "刚果",
+    "CD": "刚果民主共和国",
+    "CK": "库克群岛",
+    "CR": "哥斯达黎加",
+    "CI": "科特迪瓦",
+    "HR": "克罗地亚",
+    "CU": "古巴",
+    "CY": "塞浦路斯",
+    "CZ": "捷克",
+    # D
+    "DK": "丹麦",
+    "DJ": "吉布提",
+    "DM": "多米尼加",
+    "DO": "多米尼加共和国",
+    # E
+    "EC": "厄瓜多尔",
+    "EG": "埃及",
+    "SV": "萨尔瓦多",
+    "GQ": "赤道几内亚",
+    "ER": "厄立特里亚",
+    "EE": "爱沙尼亚",
+    "ET": "埃塞俄比亚",
+    # F
+    "FK": "福克兰群岛",
+    "FO": "法罗群岛",
+    "FJ": "斐济",
+    "FI": "芬兰",
+    "FR": "法国",
+    "GF": "法属圭亚那",
+    "PF": "法属波利尼西亚",
+    "TF": "法属南部领地",
+    "GA": "加蓬",
+    "GM": "冈比亚",
+    "GE": "格鲁吉亚",
+    "DE": "德国",
+    "GH": "加纳",
+    "GI": "直布罗陀",
+    "GR": "希腊",
+    "GL": "格陵兰",
+    "GD": "格林纳达",
+    "GP": "瓜德罗普",
+    "GU": "关岛",
+    "GT": "危地马拉",
+    "GN": "几内亚",
+    "GW": "几内亚比绍",
+    "GY": "圭亚那",
+    # H
+    "HT": "海地",
+    "HM": "赫德岛和麦克唐纳岛",
+    "HN": "洪都拉斯",
+    "HK": "中国香港",
+    "HU": "匈牙利",
+    # I
+    "IS": "冰岛",
+    "IN": "印度",
+    "ID": "印度尼西亚",
+    "IR": "伊朗",
+    "IQ": "伊拉克",
+    "IE": "爱尔兰",
+    "IL": "以色列",
+    "IT": "意大利",
+    "JM": "牙买加",
+    "JP": "日本",
+    "JO": "约旦",
+    # K
+    "KZ": "哈萨克斯坦",
+    "KE": "肯尼亚",
+    "KI": "基里巴斯",
+    "KP": "朝鲜",
+    "KR": "韩国",
+    "KW": "科威特",
+    "KG": "吉尔吉斯斯坦",
+    "LA": "老挝",
+    "LV": "拉脱维亚",
+    "LB": "黎巴嫩",
+    "LS": "莱索托",
+    "LR": "利比里亚",
+    "LY": "利比亚",
+    "LI": "列支敦士登",
+    "LT": "立陶宛",
+    "LU": "卢森堡",
+    "MO": "中国澳门",
+    # M
+    "MK": "北马其顿",
+    "MG": "马达加斯加",
+    "MW": "马拉维",
+    "MY": "马来西亚",
+    "MV": "马尔代夫",
+    "ML": "马里",
+    "MT": "马耳他",
+    "MH": "马绍尔群岛",
+    "MQ": "马提尼克",
+    "MR": "毛里塔尼亚",
+    "MU": "毛里求斯",
+    "YT": "马约特",
+    "MX": "墨西哥",
+    "FM": "密克罗尼西亚",
+    "MD": "摩尔多瓦",
+    "MC": "摩纳哥",
+    "MN": "蒙古",
+    "ME": "黑山",
+    "MS": "蒙特塞拉特",
+    "MA": "摩洛哥",
+    "MZ": "莫桑比克",
+    "MM": "缅甸",
+    # N
+    "NA": "纳米比亚",
+    "NR": "瑙鲁",
+    "NP": "尼泊尔",
+    "NL": "荷兰",
+    "NC": "新喀里多尼亚",
+    "NZ": "新西兰",
+    "NI": "尼加拉瓜",
+    "NE": "尼日尔",
+    "NG": "尼日利亚",
+    "NU": "纽埃",
+    "NF": "诺福克岛",
+    "MP": "北马里亚纳群岛",
+    "NO": "挪威",
+    # O
+    "OM": "阿曼",
+    # P
+    "PK": "巴基斯坦",
+    "PW": "帕劳",
+    "PS": "巴勒斯坦",
+    "PA": "巴拿马",
+    "PG": "巴布亚新几内亚",
+    "PY": "巴拉圭",
+    "PE": "秘鲁",
+    "PH": "菲律宾",
+    "PN": "皮特凯恩群岛",
+    "PL": "波兰",
+    "PT": "葡萄牙",
+    "PR": "波多黎各",
+    "QA": "卡塔尔",
+    # R
+    "RE": "留尼汪",
+    "RO": "罗马尼亚",
+    "RU": "俄罗斯",
+    "RW": "卢旺达",
+    # S
+    "BL": "圣巴泰勒米",
+    "SH": "圣赫勒拿",
+    "KN": "圣基茨和尼维斯",
+    "LC": "圣卢西亚",
+    "MF": "法属圣马丁",
+    "PM": "圣皮埃尔和密克隆",
+    "VC": "圣文森特和格林纳丁斯",
+    "WS": "萨摩亚",
+    "SM": "圣马力诺",
+    "ST": "圣多美和普林西比",
+    "SA": "沙特阿拉伯",
+    "SN": "塞内加尔",
+    "RS": "塞尔维亚",
+    "SC": "塞舌尔",
+    "SL": "塞拉利昂",
+    "SG": "新加坡",
+    "SX": "荷属圣马丁",
+    "SK": "斯洛伐克",
+    "SI": "斯洛文尼亚",
+    "SB": "所罗门群岛",
+    "SO": "索马里",
+    "ZA": "南非",
+    "GS": "南乔治亚和南桑威奇群岛",
+    "SS": "南苏丹",
+    "ES": "西班牙",
+    "LK": "斯里兰卡",
+    "SD": "苏丹",
+    "SR": "苏里南",
+    "SJ": "斯瓦尔巴和扬马延",
+    "SZ": "斯威士兰",
+    "SE": "瑞典",
+    "CH": "瑞士",
+    "SY": "叙利亚",
+    # T
+    "TW": "中国台湾",
+    "TJ": "塔吉克斯坦",
+    "TZ": "坦桑尼亚",
+    "TH": "泰国",
+    "TL": "东帝汶",
+    "TG": "多哥",
+    "TK": "托克劳",
+    "TO": "汤加",
+    "TT": "特立尼达和多巴哥",
+    "TN": "突尼斯",
+    "TR": "土耳其",
+    "TM": "土库曼斯坦",
+    "TC": "特克斯和凯科斯群岛",
+    "TV": "图瓦卢",
+    "UG": "乌干达",
+    "UA": "乌克兰",
+    "AE": "阿联酋",
+    "GB": "英国",
+    "US": "美国",
+    "UM": "美国本土外小岛屿",
+    "UY": "乌拉圭",
+    "UZ": "乌兹别克斯坦",
+    # V
+    "VU": "瓦努阿图",
+    "VA": "梵蒂冈",
+    "VE": "委内瑞拉",
+    "VN": "越南",
+    "VG": "英属维尔京群岛",
+    "VI": "美属维尔京群岛",
+    # W
+    "WF": "瓦利斯和富图纳",
+    "EH": "西撒哈拉",
+    "YE": "也门",
+    "ZM": "赞比亚",
+    "ZW": "津巴布韦",
+    "AX": "奥兰群岛",
+    "BQ": "荷兰加勒比区",
+    "CW": "库拉索",
+    "GG": "根西岛",
+    "IM": "马恩岛",
+    "JE": "泽西岛",
+    "XK": "科索沃",
+    "AQ": "南极洲",
+}
+
+
+def get_country_name_by_region_code(region_code: str) -> str:
+    """
+    根据地区代码获取国家名称
+    :param region_code: ISO 3166-1 alpha-2 两位字母代码，如 "CN", "US"
+    :return: 完整国家名称，如 "中国", "美国"；如果代码不存在则返回原始代码
+    """
+    if not region_code:
+        return ""
+    
+    upper_code = region_code.strip().upper()
+    if not upper_code:
+        return ""
+    
+    return REGION_CODE_TO_NAME.get(upper_code, region_code)