data.amap_loader
================

.. py:module:: data.amap_loader

.. autoapi-nested-parse::

   高德地图 API 封装：POI 搜索、营业时间解析、驾车路径规划与成本矩阵构建。



Attributes
----------

.. autoapisummary::

   data.amap_loader._MIDDLE_DOTS


Functions
---------

.. autoapisummary::

   data.amap_loader.normalize_text
   data.amap_loader._parse_date
   data.amap_loader._parse_opentime_to_tw
   data.amap_loader.get_poi_details
   data.amap_loader._get_driving_data
   data.amap_loader.build_real_data


Module Contents
---------------

.. py:data:: _MIDDLE_DOTS

.. py:function:: normalize_text(text: str) -> str

   全角→半角 + 空白压缩 + 中点符号归一化，用于名称匹配。

   用户输入与高德返回的名称常有空格/中点符号的细微差异，
   归一化后做双向子串匹配，提高酒店/景点名称匹配成功率。


.. py:function:: _parse_date(date_str: str, year: int) -> datetime.date | None

   解析高德营业时间中的日期段，如 '04月01日' → datetime.date。成功返回 date，失败返回 None。


.. py:function:: _parse_opentime_to_tw(opentime_str: str) -> tuple[int, int] | None

   解析高德营业时间字符串为时间窗元组。

   支持格式：'月-日:时段-时段'（如 "6-1:09:00-22:00"），
   以及跨日期段 '月-日-月-日:时段-时段'。
   仅返回与当天匹配的时段。

   Args:
       opentime_str: 高德 API 返回的营业时间字符串。

   Returns:
       Tuple[int, int] | None: (开始分钟, 结束分钟)，解析失败返回 None。


.. py:function:: get_poi_details(poi_name: str, city: str) -> tuple[float, float, str, str, str, str, str, str] | str

   获取 POI 详细信息（坐标 + 营业时间 + 地址 + 省/市名 + 实际名称 + 行业分类）。

   Args:
       poi_name: 景点名称。
       city: 城市名。

   Returns:
       tuple[float, float, str, str, str, str, str, str]: 成功返回 8 元组
       第 8 项 poi_type 为高德行业分类（如 "住宿服务;宾馆酒店"）。
       str: 失败返回错误信息字符串。


.. py:function:: _get_driving_data(origin: tuple[float, float], destination: tuple[float, float], max_retries: int = 3)

   调用高德驾车路径规划 API 获取距离、耗时、轨迹折线。

   Args:
       origin: (经度, 纬度) 起点坐标。
       destination: (经度, 纬度) 终点坐标。
       max_retries: 失败重试次数，默认 3。

   Returns:
       Tuple[float | None, int | None, str | None]: (距离 km, 耗时 秒, 折线字符串)。

   Raises:
       Exception: 网络请求异常时重试，重试耗尽后返回 (None, None, None)。


.. py:function:: build_real_data(poi_names: list[str], coords: list[tuple[float, float]], delay: float = 0.4)

   调用高德 API 构建完整的驾车成本矩阵。

   利用对称性优化：A→B 与 B→A 使用相同 API 结果填充，减少一半请求量。
   delay 参数用于控制 QPS，避免触发高德 API 限流。

   Args:
       poi_names: POI 名称列表（含酒店）。
       coords: 坐标列表，与 poi_names 一一对应。
       delay: API 调用间隔秒数，默认 0.4（高德 QPS 限制约 2-3 次/秒）。

   Returns:
       Tuple[np.ndarray, np.ndarray, dict]: cost_matrix（分钟）、dist_matrix_km、polylines_dict。

   Raises:
       Exception: 驾车 API 调用失败时输出警告，对应矩阵元素置为 -1 标记不可达。