Skip to content

项目交接书.md

Latest commit

 

History

History
104 lines (78 loc) · 7.88 KB

项目交接书.md

File metadata and controls

104 lines (78 loc) · 7.88 KB

🌍 开发者与 AI 协作百科：旅游行程优化引擎 (V6.0 Final)

文档性质： 核心开发文档 / AI 协作协议 / 架构演进指南 受众： 后续接手的 AI 协作伙伴 (需具备算法逻辑与运筹优化背景) 当前状态： V6.0 内核算法完备 (PoC)，已实现“自动搜索与全局成本决策”，待进入 V2.0 跨城架构升级。

📖 一、 项目画像与核心功能预期 (Vision & Expectations)

1.1 项目目标

解决多约束条件下（多人、多天、多偏好）的旅行规划难题，将传统数天的人工规划缩短至秒级。

1.2 核心竞争力：自动搜索与全局决策 (AI Search & Decision)

这是本引擎的“灵魂”，接手者必须维持其自动化决策的预期：

  • 组合空间自动遍历： 系统需自动遍历“地点子集 (Location Subsets) × 航班选项 (Flight Options)”的笛卡尔积空间。
  • 智能盈亏权衡 (Trade-off Analysis)： 算法不只是寻找低价，而是计算“低价机票节省的钱”是否能覆盖“因延天天数产生的额外住宿、交通和包车费”。
  • 方案可行性预审： 在搜索过程中，排期算法会即时校验航班时间窗（如“早上返回”是否会导致当天景点无法排下）。若排期冲突，该组合将被自动剔除。

1.3 当前进度 (Current Milestones)

已实现功能模块

我们已成功构建了一个功能强大的后端计算引擎，实现了以下核心模块：

  1. 配置驱动架构 (Configuration-Driven Architecture): 项目的核心逻辑与数据配置完全解耦，所有规划参数均可通过一个结构化的 Excel 文件进行管理。
  2. 多模式交通优化 (Multi-modal Transport Optimization): 实现了基于人数和行李约束的、最低成本的多车型（含租赁、网约车）组合分配算法。
  3. 地点子集剪枝 (Location Subset Pruning): 能够根据“必去/可选”标签，智能生成所有满足基本约束的候选地点组合。
  4. 性别感知住宿优化 (Gender-Aware Accommodation Optimization): 实现了基于动态规划的房间分配算法，确保团体同址、性别隔离，并能在不同住宿类型（酒店 vs. 别墅）间做出最优选择。
  5. 航班时间感知排期 (Flight Time-Aware Scheduling): 能够解析不同时段（上午/下午）的航班，并动态调整行程首末两日的有效游玩窗口，生成精确到分钟的每日路书。
  6. 全局成本决策引擎 (Global Cost Decision Engine): 能够综合评估所有“地点组合 x 航班选项”的可能性，并基于总成本（机票+住宿+交通+门票）做出最终的全局最优推荐。

当前开发阶段

项目目前处于 “核心功能完备的技术验证 (PoC) 向最小可行产品 (MVP) 过渡” 的阶段。我们拥有一个强大的、经过验证的后端计算核心，但尚未构建用户交互界面和外部数据接口。

🛠 二、 技术规格与数据契约 (Technical Specs)

2.1 技术栈

  • 语言: Python 3.10+
  • 核心库: Pandas (数据处理), Openpyxl (Excel I/O)。
  • 算法模型: - 住宿分配: 动态规划 (DP) 求解性别组内最优组合。
    • 路径优化: 全排列 (itertools) 解决 TSP 问题。

2.2 数据契约 (Excel V6.0 标准)

系统严格依赖 travel_data_v6.xlsx 中的 7 个 Sheet：

  1. 配置参数: 包含总人数、总行李、天数范围约束。
  2. 人员信息: 姓名与性别（住宿优化的输入）。
  3. 地点: 景点门票、建议耗时及必去标记。
  4. 交通矩阵: 地点间耗时，必须包含 Hotel 锚点。
  5. 住宿方案: 定义 Hotel（分房型）或 Villa（整栋）供应商。
  6. 房型详情: 关联住宿方案的容量与单价。
  7. 机票价格: 包含天数、起降时间段及单价。

⚙️ 三、 核心算法逻辑链 (Logic Flow)

  1. 载入与校验: 通过 TravelPlannerEngine.from_excel 一键初始化。
  2. 交通层 (_optimize_transport): 求解 N 人与行李约束下的最低车型组合成本。
  3. 住宿层 (_optimize_accommodation): 坚持“同址隔离”原则。分别计算男/女组的 DP 最优解，合并为该地点的住宿总价。
  4. 决策层 (generate_itinerary): 执行自动搜索。对比所有可行方案的总成本（机票+住宿+交通+门票）。
  5. 排期层 (_solve_tsp_and_schedule): 航班时间感知。根据具体起降时段（如“下午出发”）自动调整首尾两日的可用时长。

⚠️ 四、 已知局限~改进建议 (Identified Gaps) 与 运行警示

4.1 产品逻辑漏洞与改进建议

  1. 缺乏用户交互与调整: 当前引擎是一个“黑盒”，用户无法对生成的方案进行微调（例如：“我不喜欢这家酒店，换一个”、“把长城安排在第二天”）。
    • 改进建议: 开发一个简约的前端界面（可使用 Streamlit 或 Flask 快速搭建 MVP），允许用户查看方案后，锁定或替换某些选项，然后触发引擎重新计算。
  2. 行程“节奏”单一: 调度算法会尽可能填满每日 09:00-21:00 的窗口，可能导致行程过于紧张。
    • 改进建议: 在配置中增加“行程松紧度 (Pacing)”参数（如：轻松/标准/紧凑），算法可据此在活动间自动增加 1-2 小时的缓冲时间。
  3. 单点住宿假设: 当前模型假设整个行程中只入住一个住宿点。对于长途或多城市旅行，这显然不适用。
    • 改进建议: 将行程按城市或区域进行分段，为每个分段独立调用住宿优化模块。这是一个重大的架构升级，应在 V2.0 中规划。
  4. 航班时间模型过于简化 (Oversimplified Flight Time Model): (新增) 当前系统使用‘上午/下午出发’等模糊时间段，并将其映射为固定的行程开始/结束时间（如 12:00）。这忽略了实际的飞行时长、机场与酒店间的交通耗时，以及提前到达机场办理登机手续的必要时间。
    • 改进建议: 增强数据模型，允许输入具体的航班号或起降时间。排期算法 _solve_tsp_and_schedule 需重构，以精确计算首日的“可用活动开始时间”（航班落地时间 + 出机场耗时 + 机场到酒店耗时）和末日的“最晚活动结束时间”（航班起飞时间 - 酒店到机场耗时 - 提前量）。这将使路书的精确度达到可直接执行的级别。
    • 静态数据局限: 所有价格和耗时均来自静态 Excel，无法反映实时市场。

4.2 运行警示

  • PermissionError: 若 Excel 文件被外部占用，读取将失败。
  • 初始化风险: from_excel 必须显式返回 engine 对象，否则实例将为 None。

🚀 五、 演进路线图 (Next Steps for AI)

阶段 1: 精细化排期 (MVP -> V1.0)

  • 行程平摊: 引入日均活动量限制，将景点均匀摊分。
  • 生理时间点插入: 自动预留午餐/晚餐/休息的 1.5 小时窗口。
  • 可视化报表: 导出带图文和明细的精美路书 (HTML/PDF)。

阶段 2: 动态数据与 AI 搜索功能 (V2.0 升级)

  • 支持用户交互 确定前端平台，开发一个前端界面
  • AI 实时搜索接入: 设计适配器层，对接携程、高德 API 实现价格与路况的实时查询。
  • 跨城架构重构: 支持多 Base、多城市流转。
  • TSP 算法升级: 使用模拟退火或遗传算法替换全排列，支持 10 个以上地点。

📝 六、 AI 协作输出协议 (The AI Contract)

  1. 全量代码块原则: 修改时仅输出受影响的方法，但严禁内部省略。
  2. 数据先行原则: 任何重构（如跨城功能）必须先从修改 Excel 模板和 create_excel_data.py 开始。
  3. 计算准则: 内部始终以“总价”计算，严禁中间环节使用人均价以防误差累积。