feat: 新增贸易查询筛选条件并完善巴西贸易数据解析

- 扩展TradeQueryRequest查询schema，新增贸易方向、商品名称、原产国、目的国等筛选参数
- 更新贸易路由文档，补充新支持的筛选维度
- 为贸易路由添加对应新增参数的数据库筛选逻辑
- 重构巴西ComexStat连接器，新增官方表格数据加载与标准化映射工具
- 完善巴西贸易记录的国家、港口、运输方式及商品名称解析逻辑
- 补充完整的巴西运输方式标准化映射表

apps/api/routers/trade.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, Query, HTTPException
+from fastapi import APIRouter, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func, desc
 
@@ -15,7 +15,7 @@ async def search_trade_records(
 ):
     """
     检索标准贸易记录
-    支持按国家、HS 编码、进口商模糊查询及日期范围筛选
+    支持按国家、方向、HS、商品、企业名、起运/目的国及日期范围筛选
     """
     stmt = select(StandardTradeRecord)
     count_stmt = select(func.count()).select_from(StandardTradeRecord)
@@ -24,10 +24,20 @@ async def search_trade_records(
     filters = []
     if query.source_country:
         filters.append(StandardTradeRecord.source_country == query.source_country)
+    if query.trade_direction:
+        filters.append(StandardTradeRecord.trade_direction == query.trade_direction)
     if query.hs_code:
         filters.append(StandardTradeRecord.hs_code.like(f"{query.hs_code}%"))
+    if query.product_name:
+        filters.append(StandardTradeRecord.product_name.ilike(f"%{query.product_name}%"))
     if query.importer_name:
         filters.append(StandardTradeRecord.importer_name.ilike(f"%{query.importer_name}%"))
+    if query.exporter_name:
+        filters.append(StandardTradeRecord.exporter_name.ilike(f"%{query.exporter_name}%"))
+    if query.origin_country:
+        filters.append(StandardTradeRecord.origin_country == query.origin_country)
+    if query.destination_country:
+        filters.append(StandardTradeRecord.destination_country == query.destination_country)
     if query.start_date:
         filters.append(StandardTradeRecord.trade_date >= query.start_date)
     if query.end_date:

apps/api/schemas/trade.py

@@ -4,9 +4,13 @@ from datetime import datetime
 
 class TradeQueryRequest(BaseModel):
     source_country: Optional[str] = Field(None, description="来源国 (如 US, BR)")
+    trade_direction: Optional[str] = Field(None, description="贸易方向 (import / export)")
     hs_code: Optional[str] = Field(None, description="HS编码 (模糊前缀匹配)")
+    product_name: Optional[str] = Field(None, description="商品描述 (模糊匹配)")
     importer_name: Optional[str] = Field(None, description="进口商名称 (模糊匹配)")
     exporter_name: Optional[str] = Field(None, description="出口商名称 (模糊匹配)")
+    origin_country: Optional[str] = Field(None, description="原产国/启运国")
+    destination_country: Optional[str] = Field(None, description="目的国")
     start_date: Optional[datetime] = Field(None, description="起始时间")
     end_date: Optional[datetime] = Field(None, description="结束时间")
     page: int = Field(1, ge=1, description="页码")

logs/app_2026-06-10.log

@@ -9,3 +9,39 @@
 2026-06-10 22:40:51.104 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv
 2026-06-10 22:40:51.104 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv
 2026-06-10 22:40:51.106 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv | Attempt: 2/3
+2026-06-10 22:54:10.790 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv | Attempt: 1/3
+2026-06-10 22:54:12.527 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv
+2026-06-10 22:54:12.536 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv
+2026-06-10 22:54:12.555 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv | Attempt: 2/3
+2026-06-10 22:55:04.641 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv | Attempt: 1/3
+2026-06-10 22:55:07.338 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv
+2026-06-10 22:55:07.341 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv
+2026-06-10 22:55:07.356 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/comexstat-bd/ncm/EXP_2026.csv | Attempt: 2/3
+2026-06-10 22:55:37.527 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv | Attempt: 1/3
+2026-06-10 22:55:39.243 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv
+2026-06-10 22:55:39.247 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv
+2026-06-10 22:55:39.264 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv | Attempt: 2/3
+2026-06-10 22:55:42.802 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv | Attempt: 1/3
+2026-06-10 22:55:44.414 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv
+2026-06-10 22:55:44.416 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv
+2026-06-10 22:55:44.418 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv | Attempt: 2/3
+2026-06-10 22:55:47.150 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv | Attempt: 1/3
+2026-06-10 22:55:48.884 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv
+2026-06-10 22:55:48.886 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv
+2026-06-10 22:55:48.888 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv | Attempt: 2/3
+2026-06-10 22:55:53.270 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/NCM.csv | Attempt: 1/3
+2026-06-10 22:55:55.969 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/NCM.csv
+2026-06-10 22:55:55.979 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/NCM.csv
+2026-06-10 22:55:55.992 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/NCM.csv | Attempt: 2/3
+2026-06-10 22:56:54.255 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv | Attempt: 1/3
+2026-06-10 22:56:56.671 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv
+2026-06-10 22:56:56.678 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv
+2026-06-10 22:56:56.698 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/PAIS.csv | Attempt: 2/3
+2026-06-10 22:57:04.412 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv | Attempt: 1/3
+2026-06-10 22:57:06.215 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv
+2026-06-10 22:57:06.250 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv
+2026-06-10 22:57:06.306 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/URF.csv | Attempt: 2/3
+2026-06-10 22:57:11.485 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv | Attempt: 1/3
+2026-06-10 22:57:13.171 | WARNING  | packages.core.http_client:request:79 - Request Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1081) for https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv
+2026-06-10 22:57:13.172 | WARNING  | packages.core.http_client:request:82 - SSL 证书校验失败，降级为 verify=False 重试: https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv
+2026-06-10 22:57:13.174 | DEBUG    | packages.core.http_client:request:55 - Request: GET https://balanca.economia.gov.br/balanca/bd/tabelas/VIA.csv | Attempt: 2/3

packages/connectors/brazil.py

@@ -7,7 +7,12 @@ from typing import Any, Dict, List, Optional
 from packages.connectors.base import BaseConnector
 from packages.core.http_client import http_client
 from packages.core.models import RawTradeRecord, StandardTradeRecord
-from packages.dictionaries.brazil import TRANSPORT_MODE_MAP
+from packages.dictionaries.brazil import (
+    get_country_alpha3,
+    get_ncm_name,
+    get_transport_mode,
+    get_urf_name,
+)
 
 class BrazilComexStatConnector(BaseConnector):
     """
@@ -115,8 +120,10 @@ class BrazilComexStatConnector(BaseConnector):
             day=1,
         )
         ncm_code = (data.get("co_ncm") or "").strip()
-        partner_country = self._truncate(data.get("co_pais"), 10)
-        transport_mode = TRANSPORT_MODE_MAP.get((data.get("co_via") or "").strip().upper(), "UNKNOWN")
+        partner_country = await get_country_alpha3(data.get("co_pais"))
+        urf_name = await get_urf_name(data.get("co_urf"))
+        transport_mode = await get_transport_mode(data.get("co_via"))
+        product_name = await get_ncm_name(ncm_code)
         record_id = str(uuid.uuid5(uuid.NAMESPACE_URL, f"{self.country_code}:{raw.id}"))
 
         return StandardTradeRecord(
@@ -129,15 +136,15 @@ class BrazilComexStatConnector(BaseConnector):
             importer_name=None,
             exporter_name=None,
             hs_code=ncm_code,
-            product_name=f"NCM {ncm_code}" if ncm_code else None,
+            product_name=product_name or (f"NCM {ncm_code}" if ncm_code else None),
             amount=self._safe_float(data.get("vl_fob")),
             currency="USD",
             weight=self._safe_float(data.get("kg_liquido")),
             weight_unit="KG",
-            origin_country=partner_country if trade_direction == "import" else self.country_code,
-            destination_country=partner_country if trade_direction == "export" else self.country_code,
-            departure_port=self._truncate(data.get("co_urf"), 100) if trade_direction == "export" else None,
-            arrival_port=self._truncate(data.get("co_urf"), 100) if trade_direction == "import" else None,
+            origin_country=partner_country if trade_direction == "import" else "BRA",
+            destination_country=partner_country if trade_direction == "export" else "BRA",
+            departure_port=self._truncate(urf_name or data.get("co_urf"), 100) if trade_direction == "export" else None,
+            arrival_port=self._truncate(urf_name or data.get("co_urf"), 100) if trade_direction == "import" else None,
             transport_mode=transport_mode,
         )
 

packages/dictionaries/brazil.py

@@ -1,8 +1,14 @@
+import csv
+import io
+from typing import Dict, Optional
+
+from packages.core.http_client import http_client
+
 # 巴西货币映射字典
 CURRENCY_MAP = {
-    "BRL": "BRL",  # 巴西雷亚尔
+    "BRL": "BRL",
     "REAL": "BRL",
-    "USD": "USD",  # 美元
+    "USD": "USD",
     "DÓLAR": "USD",
 }
 
@@ -16,12 +22,166 @@ UNIT_MAP = {
     "UN": "PCS",
 }
 
-# 巴西运输方式映射
+# 巴西运输方式名称到标准方式的归一化映射
 TRANSPORT_MODE_MAP = {
     "MARITIMO": "SEA",
     "MARÍTIMO": "SEA",
+    "MARITIMA": "SEA",
+    "MARÍTIMA": "SEA",
     "AEREO": "AIR",
     "AÉREO": "AIR",
+    "AEREA": "AIR",
+    "AÉREA": "AIR",
     "RODOVIARIO": "ROAD",
     "RODOVIÁRIO": "ROAD",
+    "RODOVIARIA": "ROAD",
+    "RODOVIÁRIA": "ROAD",
+    "FERROVIARIO": "RAIL",
+    "FERROVIÁRIO": "RAIL",
+    "FERROVIARIA": "RAIL",
+    "FERROVIÁRIA": "RAIL",
+    "FLUVIAL": "WATERWAY",
+    "LACUSTRE": "WATERWAY",
+    "POSTAL": "POSTAL",
+    "COURIER": "COURIER",
+    "DUTOVIARIO": "PIPELINE",
+    "DUTOVIÁRIO": "PIPELINE",
+    "POR REBOQUE": "TOWED",
+    "ENTRADA/SAIDA FICTA": "FICTITIOUS",
+    "ENTRADA/SAÍDA FICTA": "FICTITIOUS",
+    "VIA DESCONHECIDA": "UNKNOWN",
 }
+
+BRAZIL_TABLE_BASE_URL = "https://balanca.economia.gov.br/balanca/bd/tabelas"
+
+_COUNTRY_ALPHA3_BY_CODE: Optional[Dict[str, str]] = None
+_URF_NAME_BY_CODE: Optional[Dict[str, str]] = None
+_UF_NAME_BY_CODE: Optional[Dict[str, str]] = None
+_VIA_NAME_BY_CODE: Optional[Dict[str, str]] = None
+_NCM_NAME_BY_CODE: Optional[Dict[str, str]] = None
+
+
+async def get_country_alpha3(code: Optional[str]) -> Optional[str]:
+    if not code:
+        return None
+    lookup = await _get_country_lookup()
+    normalized = _normalize_code(code)
+    return lookup.get(normalized)
+
+
+async def get_urf_name(code: Optional[str]) -> Optional[str]:
+    if not code:
+        return None
+    lookup = await _get_urf_lookup()
+    normalized = _normalize_code(code)
+    return lookup.get(normalized)
+
+
+async def get_state_name(code: Optional[str]) -> Optional[str]:
+    if not code:
+        return None
+    lookup = await _get_uf_lookup()
+    return lookup.get(str(code).strip().upper())
+
+
+async def get_transport_mode(code: Optional[str]) -> str:
+    if not code:
+        return "UNKNOWN"
+    lookup = await _get_via_lookup()
+    via_name = lookup.get(_normalize_code(code), "")
+    normalized_name = via_name.upper()
+    if normalized_name in TRANSPORT_MODE_MAP:
+        return TRANSPORT_MODE_MAP[normalized_name]
+
+    for keyword, standard_mode in TRANSPORT_MODE_MAP.items():
+        if keyword and keyword in normalized_name:
+            return standard_mode
+
+    return "UNKNOWN"
+
+
+async def get_ncm_name(code: Optional[str]) -> Optional[str]:
+    if not code:
+        return None
+    lookup = await _get_ncm_lookup()
+    normalized = _normalize_code(code)
+    return lookup.get(normalized)
+
+
+async def _get_country_lookup() -> Dict[str, str]:
+    global _COUNTRY_ALPHA3_BY_CODE
+    if _COUNTRY_ALPHA3_BY_CODE is None:
+        rows = await _load_csv_rows("PAIS.csv")
+        _COUNTRY_ALPHA3_BY_CODE = {
+            _normalize_code(row.get("CO_PAIS")): (row.get("CO_PAIS_ISOA3") or "").strip().upper()
+            for row in rows
+            if row.get("CO_PAIS")
+        }
+    return _COUNTRY_ALPHA3_BY_CODE
+
+
+async def _get_urf_lookup() -> Dict[str, str]:
+    global _URF_NAME_BY_CODE
+    if _URF_NAME_BY_CODE is None:
+        rows = await _load_csv_rows("URF.csv")
+        _URF_NAME_BY_CODE = {
+            _normalize_code(row.get("CO_URF")): (row.get("NO_URF") or "").strip()
+            for row in rows
+            if row.get("CO_URF")
+        }
+    return _URF_NAME_BY_CODE
+
+
+async def _get_uf_lookup() -> Dict[str, str]:
+    global _UF_NAME_BY_CODE
+    if _UF_NAME_BY_CODE is None:
+        rows = await _load_csv_rows("UF.csv")
+        _UF_NAME_BY_CODE = {
+            (row.get("SG_UF") or "").strip().upper(): (row.get("NO_UF") or "").strip()
+            for row in rows
+            if row.get("SG_UF")
+        }
+    return _UF_NAME_BY_CODE
+
+
+async def _get_via_lookup() -> Dict[str, str]:
+    global _VIA_NAME_BY_CODE
+    if _VIA_NAME_BY_CODE is None:
+        rows = await _load_csv_rows("VIA.csv")
+        _VIA_NAME_BY_CODE = {
+            _normalize_code(row.get("CO_VIA")): (row.get("NO_VIA") or "").strip()
+            for row in rows
+            if row.get("CO_VIA")
+        }
+    return _VIA_NAME_BY_CODE
+
+
+async def _get_ncm_lookup() -> Dict[str, str]:
+    global _NCM_NAME_BY_CODE
+    if _NCM_NAME_BY_CODE is None:
+        rows = await _load_csv_rows("NCM.csv")
+        _NCM_NAME_BY_CODE = {
+            _normalize_code(row.get("CO_NCM")): (row.get("NO_NCM_POR") or "").strip()
+            for row in rows
+            if row.get("CO_NCM")
+        }
+    return _NCM_NAME_BY_CODE
+
+
+async def _load_csv_rows(file_name: str) -> list[dict]:
+    url = f"{BRAZIL_TABLE_BASE_URL}/{file_name}"
+    response = await http_client.get(
+        url,
+        headers={"User-Agent": "customs-data/1.0"},
+        timeout=180,
+        follow_redirects=True,
+        allow_insecure_fallback=True,
+    )
+    text = response.content.decode("latin-1", errors="ignore")
+    return list(csv.DictReader(io.StringIO(text), delimiter=";"))
+
+
+def _normalize_code(value: Optional[str]) -> str:
+    if value is None:
+        return ""
+    return str(value).replace('"', "").strip()