engine.pipeline
===============

.. py:module:: engine.pipeline

.. autoapi-nested-parse::

   行程规划双阶段编排：数据加载 → 聚类求解 → 每日行程重建。



Attributes
----------

.. autoapisummary::

   engine.pipeline.TRAVEL_SPEED


Functions
---------

.. autoapisummary::

   engine.pipeline._supplement_polylines
   engine.pipeline.run_planning
   engine.pipeline._rebuild_schedule
   engine.pipeline.adjust_plan


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

.. py:data:: TRAVEL_SPEED
   :value: 1.0


.. py:function:: _supplement_polylines(routes_list: list[list[list[int]]], coords: list[tuple[float, float]], polylines: dict[tuple[int, int], str]) -> None

   扫描 routes 涉及的缺失 polyline 段，逐段补调驾车 API。

   build_real_data 中 cost/dist 对称复用但 polyline 不复制，
   此处对 route 需要但 polylines 中缺失的方向单独补调。

   Args:
       routes_list: 所有方案的 route 列表，每项为 [[0, ...], [0, ...]] 格式。
       coords: 坐标列表，与索引一一对应。
       polylines: 已有 polyline 字典，函数会原地追加缺失项。


.. py:function:: run_planning(poi_cache: backend.typedefs.PoiCache, city: str, hotel_name: str, penalty_weight: float, early_wait_weight: float, late_return_weight: float, mode: str = 'fast', n_days: int | None = None, day_start: int = 0, min_days: int | None = None, cost_matrix_override: list[list[float]] | None = None, dist_matrix_override: list[list[float]] | None = None) -> backend.typedefs.PlanResult | dict

   双阶段流程编排入口。

   加载真实数据 → 构建景点字典 → 执行 cluster_and_solve → 生成每日行程 → 返回前端可视化数据。

   Args:
       poi_cache: 包含 hotel 和 spots 的缓存数据（由前端/外部传入）。
       city: 城市名，用于高德 API 查询和文件命名。
       hotel_name: 酒店名称。
       penalty_weight: 违规惩罚权重。
       early_wait_weight: 早到等待惩罚权重。
       late_return_weight: 晚归惩罚权重。
       mode: "fast" 或 "deep"。
       n_days: 行程天数（可选），None 时走建议模式。
       day_start: 每天最早出发时间（0-1440），默认 0（午夜）。
       min_days: 建议模式最小搜索天数（默认由引擎自动推断）。
       cost_matrix_override: 复用 suggest 阶段的成本矩阵，传入时跳过驾车 API。
       dist_matrix_override: 与 cost_matrix_override 一同传入的距离矩阵。

   Returns:
       dict: type="suggestion"（未指定天数）时含 suggestions、algo_time、cost_matrix、dist_matrix、polylines；
             规划模式时含 solution、best_days、daily_schedules、cost_matrix、dist_matrix、polylines、commentary 等。


.. py:function:: _rebuild_schedule(routes: list, spots_dict: dict[int, backend.typedefs.SpotDict], cost_matrix: numpy.ndarray) -> list[list[backend.typedefs.ScheduleItem]]

   从路径和景点字典重建每日行程表。

   Args:
       routes: 路径列表，每组含首尾 depot (0)。
       spots_dict: 景点字典。
       cost_matrix: 旅行时间矩阵（分钟）。

   Returns:
       list[list[ScheduleItem]]: 每日行程列表。


.. py:function:: adjust_plan(spots_dict: dict[int, backend.typedefs.SpotDict], cost_matrix_list: list, dist_matrix_list: list, routes: list, adjustments: dict) -> backend.typedefs.PlanResult

   对已有方案执行调整（均衡、移除景点、改天数）。

   从 routes 重构分组 → 按 adjustments 类型分发 → 重新求解 → 生成新每日行程。

   Args:
       spots_dict: 景点字典（与 run_planning 返回的 spots 格式一致）。
       cost_matrix_list: 成本矩阵（2D list，前端传回）。
       dist_matrix_list: 距离矩阵（2D list，前端传回）。
       routes: 当前方案路径列表，每组含首尾 depot。
       adjustments: 调整指令 dict，支持 {"balance": true}、{"adjust_days": <int>}、{"remove_poi": "<poi_name>"}、            {"add_poi": {name, lon, lat, tw_start, tw_end, stay}} 之一。

   Returns:
       dict: 与 run_planning 相同格式的完整规划结果。

   Raises:
       ValueError: adjustments 中未识别的指令类型。