engine.pipeline

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

Attributes

TRAVEL_SPEED

Functions

_supplement_polylines(→ None)	扫描 routes 涉及的缺失 polyline 段，逐段补调驾车 API。
run_planning(→ backend.typedefs.PlanResult | dict)	双阶段流程编排入口。
_rebuild_schedule(...)	从路径和景点字典重建每日行程表。
adjust_plan(→ backend.typedefs.PlanResult)	对已有方案执行调整（均衡、移除景点、改天数）。

Module Contents

engine.pipeline.TRAVEL_SPEED = 1.0

engine.pipeline._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 字典，函数会原地追加缺失项。

engine.pipeline.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 等。

engine.pipeline._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]]: 每日行程列表。

engine.pipeline.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 中未识别的指令类型。