feat: 手机号国家筛选 + 归属地自动识别

- 新增 phone_service.py（基于 phonenumbers 库）
- Sender 模型新增 country_code/country/phone_location 字段
- 3313 条发送者手机号自动解析归属地
- API 支持按国家和归属地下拉筛选
- GET /senders/countries/list 国家列表
- GET /senders/locations/list 归属地列表

Author: chu0119

backend/app/api/senders.py

@@ -16,6 +16,8 @@
 async def list_senders(
     has_phone: Optional[bool] = Query(None, description="筛选有手机号的发送者"),
     keyword: Optional[str] = Query(None, description="搜索用户名或手机号"),
+    country: Optional[str] = Query(None, description="按国家筛选"),
+    phone_location: Optional[str] = Query(None, description="按归属地筛选"),
     page: int = Query(1, ge=1),
     page_size: int = Query(50, ge=1, le=200),
     db: AsyncSession = Depends(get_db),
@@ -34,6 +36,10 @@ async def list_senders(
                 Sender.phone.ilike(f"%{keyword}%"),
             )
         )
+    if country:
+        conditions.append(Sender.country == country)
+    if phone_location:
+        conditions.append(Sender.phone_location.ilike(f"%{phone_location}%"))
 
     # 总数
     count_query = select(func.count(Sender.id))
@@ -78,6 +84,9 @@ async def list_senders(
             "is_premium": s.is_premium,
             "message_count": s.message_count,
             "alert_count": real_alert_count or 0,
+            "country": s.country or "",
+            "country_code": s.country_code or "",
+            "phone_location": s.phone_location or "",
             "created_at": s.created_at.isoformat() if s.created_at else None,
         })
 
@@ -192,3 +201,32 @@ async def get_sender_messages(
         "page_size": page_size,
         "total_pages": (total + page_size - 1) // page_size if total else 0,
     }
+
+
+@router.get("/countries/list")
+async def list_countries(db: AsyncSession = Depends(get_db)):
+    """获取所有国家/地区列表（去重）"""
+    from sqlalchemy import text
+    result = await db.execute(
+        text("SELECT DISTINCT country, COUNT(*) as cnt FROM senders WHERE country IS NOT NULL AND country != '' GROUP BY country ORDER BY cnt DESC")
+    )
+    return [{"name": row[0], "count": row[1]} for row in result.all()]
+
+
+@router.get("/locations/list")
+async def list_locations(
+    country: Optional[str] = Query(None, description="按国家筛选"),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取归属地列表（去重）"""
+    from sqlalchemy import text
+    if country:
+        result = await db.execute(
+            text("SELECT DISTINCT phone_location, COUNT(*) as cnt FROM senders WHERE phone_location IS NOT NULL AND phone_location != '' AND country = :country GROUP BY phone_location ORDER BY cnt DESC"),
+            {"country": country}
+        )
+    else:
+        result = await db.execute(
+            text("SELECT DISTINCT phone_location, COUNT(*) as cnt FROM senders WHERE phone_location IS NOT NULL AND phone_location != '' GROUP BY phone_location ORDER BY cnt DESC")
+        )
+    return [{"name": row[0], "count": row[1]} for row in result.all()]

backend/app/models/sender.py

@@ -18,6 +18,9 @@ class Sender(Base):
     first_name = Column(String(100), comment="名字")
     last_name = Column(String(100), comment="姓氏")
     phone = Column(String(20), comment="手机号")
+    country_code = Column(String(10), comment="国家代码")
+    country = Column(String(50), comment="国家/地区")
+    phone_location = Column(String(100), comment="手机号归属地")
     is_bot = Column(Boolean, default=False, comment="是否Bot")
     is_verified = Column(Boolean, default=False, comment="是否认证")
     is_premium = Column(Boolean, default=False, comment="是否Premium")

backend/app/services/phone_service.py

@@ -0,0 +1,126 @@
+"""手机号解析服务 - 基于 Google phonenumbers 库"""
+import phonenumbers
+from phonenumbers import geocoder, carrier as ph_carrier, timezone as ph_tz
+from typing import Optional, Tuple
+
+# 国家代码 → 国家名
+COUNTRY_NAMES = {
+    "CN": "中国", "HK": "香港", "MO": "澳门", "TW": "台湾",
+    "US": "美国", "CA": "加拿大", "GB": "英国", "JP": "日本",
+    "KR": "韩国", "AU": "澳大利亚", "DE": "德国", "FR": "法国",
+    "IN": "印度", "ID": "印尼", "TH": "泰国", "PH": "菲律宾",
+    "VN": "越南", "MY": "马来西亚", "SG": "新加坡", "RU": "俄罗斯",
+    "BR": "巴西", "MX": "墨西哥", "ES": "西班牙", "IT": "意大利",
+    "NL": "荷兰", "SE": "瑞典", "NO": "挪威", "TR": "土耳其",
+    "SA": "沙特", "AE": "阿联酋", "EG": "埃及", "ZA": "南非",
+    "PK": "巴基斯坦", "BD": "孟加拉", "NG": "尼日利亚",
+}
+
+
+# 已知国家代码前缀 → 区域映射
+PREFIX_REGION_MAP = {
+    "86": "CN", "852": "HK", "853": "MO", "886": "TW",
+    "44": "GB", "81": "JP", "82": "KR", "61": "AU",
+    "33": "DE", "39": "IT", "91": "IN", "62": "ID",
+    "66": "TH", "63": "PH", "84": "VN", "60": "MY",
+    "65": "SG", "90": "TR", "966": "SA", "971": "AE",
+    "7": "RU", "55": "BR", "52": "MX", "34": "ES",
+    "31": "NL", "46": "SE", "47": "NO", "380": "UA",
+    "855": "KH", "95": "MM", "977": "NP", "94": "LK",
+}
+
+
+def parse_phone(phone: str) -> Optional[phonenumbers.PhoneNumber]:
+    """解析手机号 - 智能区域检测"""
+    if not phone or not phone.strip():
+        return None
+    try:
+        normalized = phone.replace(" ", "").replace("-", "").replace("(", "").replace(")", "")
+
+        # 带+号的直接解析
+        if normalized.startswith("+"):
+            return phonenumbers.parse(normalized, None)
+
+        # 没有+号的，尝试加+解析
+        if normalized.startswith("86") and len(normalized) >= 13:
+            return phonenumbers.parse("+" + normalized, None)
+
+        # 中国11位手机号（以1开头）
+        if len(normalized) == 11 and normalized.startswith("1"):
+            return phonenumbers.parse("+86" + normalized, None)
+
+        # 尝试匹配已知国家代码前缀
+        for prefix, region in sorted(PREFIX_REGION_MAP.items(), key=lambda x: -len(x[0])):
+            if normalized.startswith(prefix):
+                try:
+                    return phonenumbers.parse("+" + normalized, region)
+                except Exception:
+                    continue
+
+        # 兜底：用中国区域解析
+        return phonenumbers.parse(normalized, "CN")
+    except Exception:
+        return None
+
+
+def get_country_info(phone: str) -> Tuple[str, str]:
+    """获取国家代码和国家名"""
+    pn = parse_phone(phone)
+    if not pn:
+        return ("", "")
+    region = phonenumbers.region_code_for_number(pn)
+    if not region:
+        return ("", "未知")
+    country_name = COUNTRY_NAMES.get(region, region)
+    return (region, country_name)
+
+
+def get_carrier_name(phone: str) -> str:
+    """获取运营商名称"""
+    pn = parse_phone(phone)
+    if not pn:
+        return ""
+    name = ph_carrier.name_for_number(pn, "zh")
+    return name or ""
+
+
+def get_location_name(phone: str) -> str:
+    """获取归属地"""
+    pn = parse_phone(phone)
+    if not pn:
+        return ""
+    name = geocoder.description_for_number(pn, "zh")
+    return name or ""
+
+
+def get_full_info(phone: str) -> dict:
+    """获取手机号完整信息"""
+    if not phone:
+        return {"raw": "", "country_code": "", "country": "", "carrier": "", "location": ""}
+    
+    pn = parse_phone(phone)
+    if not pn:
+        return {"raw": phone, "country_code": "", "country": "", "carrier": "", "location": ""}
+    
+    region = phonenumbers.region_code_for_number(pn) or ""
+    country_name = COUNTRY_NAMES.get(region, region)
+    carrier = ph_carrier.name_for_number(pn, "zh") or ""
+    location = geocoder.description_for_number(pn, "zh") or ""
+    
+    return {
+        "raw": phone,
+        "country_code": region,
+        "country": country_name,
+        "carrier": carrier,
+        "location": location,
+    }
+
+
+def normalize_phone(phone: str) -> str:
+    """标准化手机号"""
+    if not phone:
+        return ""
+    pn = parse_phone(phone)
+    if pn and phonenumbers.is_valid_number(pn):
+        return phonenumbers.format_number(pn, phonenumbers.PhoneNumberFormat.E164)
+    return phone