通用旅游行程优化引擎 (Travel Planner Engine) V6.0 Final

这是一个基于 Python 的自动化旅游行程规划与成本优化工具。该引擎通过整合机票、住宿、交通及景点数据，在满足特定约束（如人数、性别、行李、必去点）的前提下，计算并生成全局成本最低的最优旅行方案。

---

核心功能

• 交通组合优化：根据出行人数和行李数量，从轿车、商务车及中巴等车型中自动组合出每日成本最低的租车方案。
• 车辆逻辑：该算法包含了商务车在行李空间与座位数量间的转换逻辑。
• 性别感知住宿分配：支持“酒店”与“别墅”两种模式。
• 酒店分配算法：根据性别对成员进行分组，并利用动态规划算法在特定房型（单间、标间、三人间）中寻找最优且最省钱的房间组合。
• 别墅容量校验：自动核算总人数是否在别墅承载范围内。
• 多维地点排期：结合“必去”与“可选”标签进行地点筛选。
• 路径优化：利用 TSP（旅行商问题）算法优化地点间的行驶路径。
• 时间段感知：根据机票的出发与返回时间段进行贪心排期，确保行程在预设天数内完全可行。
• 全局最低成本决策：引擎会遍历所有可能的“地点组合 × 航班选项”，综合机票、住宿、交通及门票的总价，挑选出性价比最高的方案。

---

项目结构

• travel_planner_engine.py: 核心引擎代码，包含交通、住宿优化逻辑及排期决策算法。
• create_excel_data.py: 数据准备脚本，用于生成符合引擎输入规范的 Excel 数据模版。
• travel_data_v6.xlsx: (由脚本生成) 存储所有基础数据，包含以下关键 Sheet：
  • 配置参数: 定义人数、行李数及天数范围。
  • 人员信息: 记录每位成员的姓名与性别。
  • 地点: 景点属性、票价及预计游玩时长。
  • 交通矩阵: 存储酒店与各地点间的预估交通耗时。
  • 住宿方案: 提供的住宿供应商及其类型。
  • 房型详情: 酒店模式下的具体房型及容量价格。
  • 机票价格: 不同行程天数对应的航班时段及价格。
• LICENSE: 项目采用 MIT 开源协议。

---

快速开始

1. 环境准备

确保已安装 Python 环境及 pandas 和 openpyxl 库。

2. 生成演示数据

运行脚本以生成标准的 travel_data_v6.xlsx 文件：

python create_excel_data.py

3. 执行行程规划

启动引擎进行计算并输出最优路书：

python travel_planner_engine.py

---

数据规范要求

• 配置一致性：人员信息中的总人数必须与配置参数中的 num_people 匹配。
• 名称匹配：交通矩阵中的行/列名称必须与地点 Sheet 中的名称完全一致。
• 航班感知：首日活动开始时间受出发时间段影响，末日结束时间受返回时间段约束。

---

📝 配置说明 (Configuration)

本项目的所有核心逻辑均由一个 Excel 文件驱动。您可以参考项目中的 travel_data_v6.xlsx 模板进行配置。

为了支持未来的 LLM 功能（例如使用 LangChain），您可能需要配置 API 密钥。请创建一个 .env 文件：

1. 复制示例文件:

   cp .env.example .env

2. 编辑 .env 文件并填入您的密钥:

   # .env
   OPENAI_API_KEY="sk-..."

🚧 已知局限与未来规划 (Roadmap)

我们深知 Itineris AI 仍有广阔的提升空间。我们诚实地列出当前的局限并欢迎社区共同建设。

当前局限:

• TSP 求解器: 目前使用暴力全排列，对于超过 10 个地点的规划会变得非常缓慢。
• 静态数据源: 所有数据（如交通时间、酒店价格）均来自静态 Excel 文件，无法反映实时变化。
• 交通模型简化: 未考虑实时路况、公共交通等更复杂的交通模式。

未来规划:

• 集成实时 API: 对接机票、酒店预订平台和地图服务（如 Google Maps, Amap）API，获取实时价格和路况信息。
• 优化 TSP 算法: 替换为更高效的近似算法，如 Google OR-Tools，以支持更大规模的地点规划。
• 集成 LangChain: 实现通过自然语言对话生成和调整行程的强大功能。
• 用户系统: 增加用户账户，支持保存、分享和协作编辑行程方案。
• 更丰富的约束: 支持更多自定义约束，如“下午3点前必须离开颐和园”、“必须安排一顿烤鸭晚餐”等。

🤝 参与贡献 (Contributing)

我们热烈欢迎各种形式的贡献！无论是提交 Bug 报告、建议新功能，还是直接贡献代码。

1. Fork 本项目。
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)。
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')。
4. 将分支推送到您的 Fork (git push origin feature/AmazingFeature)。
5. 开启一个 Pull Request。

请在提交 PR 前确保您的代码遵循 PEP 8 规范。如果您有任何问题，请随时开启一个 Issue！

许可协议

本项目基于 MIT License 授权。