typedefs
========

.. py:module:: typedefs

.. autoapi-nested-parse::

   后端内部数据模型的 TypedDict 定义。

   API 边界用 Pydantic（schemas.py），内部数据传递用 TypedDict。
   TypedDict 零运行时开销，只做类型约束，可平滑升级为 Pydantic Model。



Classes
-------

.. autoapisummary::

   typedefs.SpotDict
   typedefs.PoiCacheItem
   typedefs.PoiCache
   typedefs.RouteResult
   typedefs.ClusterResult
   typedefs.ScheduleItem
   typedefs.PlanResult


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

.. py:class:: SpotDict

   Bases: :py:obj:`TypedDict`


   景点/酒店在引擎内部的数据结构。

   x/y 为 GCJ-02 坐标，tw 为 (start, end) 分钟数对。


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: x
      :type:  float


   .. py:attribute:: y
      :type:  float


   .. py:attribute:: tw
      :type:  tuple[float, float]


   .. py:attribute:: stay
      :type:  float


   .. py:attribute:: original_tw
      :type:  tuple[float, float]


   .. py:attribute:: lon
      :type:  NotRequired[float]


   .. py:attribute:: lat
      :type:  NotRequired[float]


   .. py:attribute:: expected_arrival
      :type:  NotRequired[float]


.. py:class:: PoiCacheItem

   Bases: :py:obj:`TypedDict`


   POI 缓存中单个条目，来自前端或 LLM 解析。


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: lon
      :type:  float


   .. py:attribute:: lat
      :type:  float


   .. py:attribute:: tw
      :type:  tuple[float, float]


   .. py:attribute:: stay
      :type:  float


   .. py:attribute:: address
      :type:  NotRequired[str]


   .. py:attribute:: expected_arrival
      :type:  NotRequired[float]


.. py:class:: PoiCache

   Bases: :py:obj:`TypedDict`


   前端传入的完整 POI 缓存，含酒店和景点列表。


   .. py:attribute:: hotel
      :type:  PoiCacheItem


   .. py:attribute:: spots
      :type:  list[PoiCacheItem]


.. py:class:: RouteResult

   Bases: :py:obj:`TypedDict`


   solve_groups / balance_groups 的求解结果。


   .. py:attribute:: routes
      :type:  list[list[int]]


   .. py:attribute:: histories
      :type:  list[list[float]]


   .. py:attribute:: total_cost
      :type:  float


   .. py:attribute:: total_dist
      :type:  float


   .. py:attribute:: wait
      :type:  float


   .. py:attribute:: late
      :type:  float


   .. py:attribute:: valid
      :type:  bool


.. py:class:: ClusterResult

   Bases: :py:obj:`TypedDict`


   cluster_and_solve 的返回结果。type="suggestion" 时无 solution。


   .. py:attribute:: type
      :type:  str


   .. py:attribute:: solution
      :type:  NotRequired[RouteResult]


   .. py:attribute:: best_days
      :type:  int


   .. py:attribute:: best_m
      :type:  str


.. py:class:: ScheduleItem

   Bases: :py:obj:`TypedDict`


   每日行程中的一条记录。


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: arrival
      :type:  int


   .. py:attribute:: departure
      :type:  int


   .. py:attribute:: tw
      :type:  str


   .. py:attribute:: stay
      :type:  str


   .. py:attribute:: arrival_status
      :type:  str


   .. py:attribute:: departure_status
      :type:  str


.. py:class:: PlanResult

   Bases: :py:obj:`TypedDict`


   run_planning / adjust_plan 的完整返回。


   .. py:attribute:: solution
      :type:  RouteResult


   .. py:attribute:: mode
      :type:  str


   .. py:attribute:: best_days
      :type:  int


   .. py:attribute:: best_m
      :type:  str


   .. py:attribute:: spots
      :type:  dict[int, SpotDict]


   .. py:attribute:: dataset_name
      :type:  str


   .. py:attribute:: algo_time
      :type:  float


   .. py:attribute:: daily_schedules
      :type:  list[list[ScheduleItem]]


   .. py:attribute:: cost_matrix
      :type:  list[list[float]]


   .. py:attribute:: dist_matrix
      :type:  list[list[float]]


   .. py:attribute:: polylines
      :type:  dict[str, str]


   .. py:attribute:: commentary
      :type:  str


   .. py:attribute:: amap_api_key
      :type:  NotRequired[str]


   .. py:attribute:: amap_security_code
      :type:  NotRequired[str]