api.schemas =========== .. py:module:: api.schemas .. autoapi-nested-parse:: Pydantic 请求/响应模型定义，FastAPI 自动据此生成 OpenAPI 文档。 Classes ------- .. autoapisummary:: api.schemas.POIItem api.schemas.POILookupRequest api.schemas.POILookupItem api.schemas.POILookupResponse api.schemas.PlanRequest api.schemas.ChatRequest api.schemas.PlanAdjustRequest api.schemas.HistoryCreate api.schemas.HistorySummary api.schemas.HistoryDetail api.schemas.HistoryListResponse api.schemas.HistoryDeleteRequest Module Contents --------------- .. py:class:: POIItem(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 单个景点数据模型。 Attributes: name: 景点名称（用于显示和 API 查询）。 lon: 经度（GCJ-02 坐标系，与高德 API 一致）。 lat: 纬度。 tw_start: 时间窗开始，距午夜分钟数（默认 480 = 8:00）。 tw_end: 时间窗结束，距午夜分钟数（默认 1020 = 17:00）。 stay: 建议停留时长（分钟），影响时间窗有效结束时间。 expected_arrival: 用户期望到达时间，可为空。 .. py:attribute:: name :type: str .. py:attribute:: lon :type: float .. py:attribute:: lat :type: float .. py:attribute:: tw_start :type: float :value: None .. py:attribute:: tw_end :type: float :value: None .. py:attribute:: stay :type: float :value: None .. py:attribute:: expected_arrival :type: float | None :value: None .. py:class:: POILookupRequest(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` POI 坐标/地址查询请求。 调用高德 POI 搜索 API 批量获取坐标和地址。 酒店也作为普通 POI 查询，前端根据名称匹配区分。 .. py:attribute:: city :type: str .. py:attribute:: names :type: list[str] :value: None .. py:class:: POILookupItem(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 单个 POI 查询结果。 tw_start/tw_end 由 LLM 解析 opentime2 后返回， 前端不再硬编码默认营业时间。 .. py:attribute:: name :type: str .. py:attribute:: lon :type: float .. py:attribute:: lat :type: float .. py:attribute:: address :type: str .. py:attribute:: tw_start :type: int | None :value: None .. py:attribute:: tw_end :type: int | None :value: None .. py:class:: POILookupResponse(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` POI 查询响应。 items: 查询成功的 POI 列表。 failed: 未找到的 POI 名称列表。 .. py:attribute:: items :type: list[POILookupItem] .. py:attribute:: failed :type: list[str] .. py:class:: PlanRequest(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 统一请求模型，适用于 /api/suggest 和 /api/plan。 包含酒店信息、景点列表和算法参数。 n_days 为 None 时返回方案建议（ca_suggest），否则返回完整方案。 Attributes: city: 城市名（用于文件命名和显示）。 hotel_name: 酒店名称。 hotel_lon/lat: 酒店坐标（GCJ-02）。 hotel_tw_start/end: 酒店时间窗（默认 0:00~24:00）。 spots: 景点列表，至少 1 个。 min_days: 搜索最小天数（默认由引擎自动推断，n_spots//8+1）。 n_days: 行程天数。None 时走建议模式，有值时走规划模式。 mode: "fast"(CA) 或 "deep"(VNS)。 day_start: 一天启程时间，对所有景点生效（默认 0 = 午夜）。 cost_matrix: 成本矩阵（分钟），复用 suggest 阶段结果时传入以跳过驾车 API。 dist_matrix: 距离矩阵（km），与 cost_matrix 一同传入。 penalty_weight: 迟到惩罚权重。 early_wait_weight: 早到等待惩罚权重。 late_return_weight: 晚归惩罚权重。 .. py:attribute:: city :type: str .. py:attribute:: hotel_name :type: str .. py:attribute:: hotel_lon :type: float .. py:attribute:: hotel_lat :type: float .. py:attribute:: hotel_tw_start :type: float :value: None .. py:attribute:: hotel_tw_end :type: float :value: None .. py:attribute:: min_days :type: int | None :value: None .. py:attribute:: spots :type: list[POIItem] :value: None .. py:attribute:: n_days :type: int | None :value: None .. py:attribute:: mode :type: str :value: None .. py:attribute:: day_start :type: float :value: None .. py:attribute:: cost_matrix :type: list[list[float]] | None :value: None .. py:attribute:: dist_matrix :type: list[list[float]] | None :value: None .. py:attribute:: penalty_weight :type: float :value: None .. py:attribute:: early_wait_weight :type: float :value: None .. py:attribute:: late_return_weight :type: float :value: None .. py:class:: ChatRequest(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` LLM Agent 对话请求。 message: 用户输入的消息。 plan_result: 可选的规划结果上下文，供 Agent 参考。 .. py:attribute:: message :type: str :value: None .. py:attribute:: plan_result :type: dict | None :value: None .. py:class:: PlanAdjustRequest(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 方案调整请求。 前端在查看方案后希望调整（如均衡天、改天数、移除/添加景点）时调用。 支持 balance / adjust_days / remove_poi / add_poi。 .. py:attribute:: spots :type: dict .. py:attribute:: cost_matrix :type: list[list[float]] :value: None .. py:attribute:: dist_matrix :type: list[list[float]] :value: None .. py:attribute:: routes :type: list .. py:attribute:: adjustments :type: dict :value: None .. py:class:: HistoryCreate(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 保存历史记录的请求体。 device_id 由前端 localStorage 生成，仅用于删除鉴权。 plan_result 为完整 PlanResult JSON，含 routes/spots/polylines/commentary 等。 request_params 为用户输入参数，方便复现。 .. py:attribute:: device_id :type: str | None :value: None .. py:attribute:: note :type: str | None :value: None .. py:attribute:: city :type: str .. py:attribute:: hotel :type: str | None :value: None .. py:attribute:: n_days :type: int .. py:attribute:: cost :type: float | None :value: None .. py:attribute:: spot_count :type: int | None :value: None .. py:attribute:: plan_result :type: dict .. py:attribute:: request_params :type: dict | None :value: None .. py:class:: HistorySummary(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 历史记录列表中的摘要信息。 .. py:attribute:: id :type: str .. py:attribute:: city :type: str .. py:attribute:: hotel :type: str | None :value: None .. py:attribute:: n_days :type: int .. py:attribute:: cost :type: float | None :value: None .. py:attribute:: spot_count :type: int | None :value: None .. py:attribute:: note :type: str | None :value: None .. py:attribute:: created_at :type: str .. py:class:: HistoryDetail(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 历史记录完整信息，含全量 plan_result。 .. py:attribute:: id :type: str .. py:attribute:: city :type: str .. py:attribute:: hotel :type: str | None :value: None .. py:attribute:: n_days :type: int .. py:attribute:: cost :type: float | None :value: None .. py:attribute:: spot_count :type: int | None :value: None .. py:attribute:: note :type: str | None :value: None .. py:attribute:: plan_result :type: dict .. py:attribute:: request_params :type: dict | None :value: None .. py:attribute:: created_at :type: str .. py:class:: HistoryListResponse(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 历史记录分页列表响应。 .. py:attribute:: items :type: list[HistorySummary] .. py:attribute:: total :type: int .. py:attribute:: page :type: int .. py:attribute:: page_size :type: int .. py:class:: HistoryDeleteRequest(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` 删除历史记录的请求体，需与创建时的 device_id 一致。 .. py:attribute:: device_id :type: str