# Python-13-AI旅行规划师

**Repository Path**: sanxiadaer/python-13--a-beautiful-artwork

## Basic Information

- **Project Name**: Python-13-AI旅行规划师
- **Description**: 人工凑智能组
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ✈️ AI 旅行规划师

这是一个基于 **FastAPI、原生 HTML / CSS / JavaScript、MySQL、通义千问和高德地图** 开发的 AI 旅行规划系统。

用户填写出发地、目的地、天数、人数、预算和旅行偏好后，系统会生成经济型、舒适型和体验型三套行程方案，并提供方案选择、详情展示、地图点位、历史恢复和 PDF 导出等功能。真实模型或外部服务暂时不可用时，系统会自动切换到本地规则方案，保证主要流程可以继续使用。

## ✨ 主要功能

### 📝 旅行需求填写

- 填写出发地、目的地、旅行天数和出行人数
- 设置总预算、旅行偏好、住宿档次和交通方式
- 使用 Pydantic 校验输入范围和数据格式
- 通过中文提示说明缺失或不符合要求的字段

### 🤖 AI 多方案生成

- 使用通义千问 `qwen3.7-plus` 生成行程
- 一次返回经济型、舒适型和体验型三套方案
- 展示每日活动、地点、餐饮、交通和分类费用
- 使用 Pydantic 检查方案数量、行程天数、费用和活动结构
- 通过 `generation_mode` 区分真实模型与本地规则方案

### 🗺️ 高德地图点位

- 使用高德地理编码获取真实经纬度
- 地理编码无结果时自动切换到 POI 关键词搜索
- 对调用频率超限进行有限重试，并控制相邻请求间隔
- 在详情页显示小地图，在完整地图页按天筛选点位
- 成功解析的地图点位统一标记为 `amap`

### 🗂️ 历史行程管理

- 将旅行需求、三套方案、每日计划和活动一次保存到 MySQL
- 在仪表盘查看已经保存的历史行程
- 从数据库恢复详情、费用、地图点位和当前选中方案
- 返回三方案页面重新选择并更新选中状态
- 确认后删除指定历史行程及其关联数据

### 📄 PDF 行程导出

- 在详情页一键生成中文 PDF
- 导出方案名称、每日行程、餐饮、交通和费用信息
- PDF 在服务端内存中生成，不长期保存在服务器目录

### 🛡️ 容错与降级

- 模型超时、连接失败或配置缺失时使用本地规则方案
- 模型返回结构不符合要求时重试一次，仍失败则自动降级
- 单个地点解析失败时保留行程正文，不使用虚构坐标补齐地图
- 数据库或 PDF 服务异常时给出明确提示，不擅自修改已有行程

## 🛠️ 技术架构

| 模块 | 技术实现 |
|---|---|
| 前端 | 原生 HTML + CSS + JavaScript |
| 页面与静态资源 | FastAPI 同源托管 |
| 接口通信 | 浏览器原生 `fetch()` |
| 后端 | Python + FastAPI + Pydantic |
| 大模型 | 通义千问 `qwen3.7-plus` |
| 模型接口 | OpenAI 兼容接口 + 统一模型适配层 |
| 地图 | 高德地图 JavaScript API |
| 坐标解析 | 高德地理编码 + POI 关键词搜索 |
| 数据库 | MySQL 8.0 |
| PDF 导出 | ReportLab |
| 自动化测试 | pytest |

## 🧩 主要接口

| 方法与路径 | 作用 |
|---|---|
| `POST /api/v1/plans` | 根据旅行需求生成三套方案 |
| `GET /api/v1/map/config` | 返回前端高德地图配置 |
| `POST /api/trips` | 保存旅行需求和完整方案数据 |
| `GET /api/trips` | 查询仪表盘历史行程 |
| `GET /api/trips/{trip_id}` | 恢复指定历史行程详情 |
| `PATCH /api/trips/{request_id}/selection` | 更新当前选中的方案 |
| `DELETE /api/trips/{trip_id}` | 删除指定历史行程 |
| `POST /api/v1/exports/pdf` | 生成并下载 PDF 行程 |

## 🕹️ 运行环境

- Windows 10 / 11
- Python 3.12
- MySQL 8.0
- 现代浏览器（推荐 Edge 或 Chrome）
- VSCode

真实模型生成和地图点位解析需要可用的网络、接口配置与调用额度。本地规则降级、数据库、页面和自动化测试可在本地环境中运行。

## 🚀 项目运行

### 目录介绍

```text
ai-travel-planner/
├─ app/               # FastAPI入口、配置和Pydantic数据模型
├─ services/          # 模型生成、地图解析、数据库和PDF服务
├─ frontend/          # 原生HTML、CSS和JavaScript页面
├─ database/          # MySQL建表脚本与数据库文件
├─ tests/             # 自动化测试
├─ docs/              # 需求、技术设计和部署说明
├─ .env.example       # 环境变量示例，不包含真实密钥
├─ requirements.txt   # Python依赖
└─ README.md          # 项目介绍与运行说明
```

### 项目运行准备

- 安装 Python 3.12 和 MySQL 8.0
- 准备通义千问 API Key，并开通对应模型的使用权限
- 准备高德 Web 服务与 JavaScript API 配置
- 根据 `database/schema.sql` 初始化 `travel_planner` 数据库
- 根据 `docs/数据库部署与最小权限说明.md` 配置应用账户权限

### 运行项目

1. 克隆项目

```powershell
git clone https://gitee.com/sanxiadaer/python-13--a-beautiful-artwork.git
Set-Location "python-13--a-beautiful-artwork"
```

2. 创建并激活虚拟环境

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

3. 安装项目依赖

```powershell
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

4. 创建本地环境配置

```powershell
Copy-Item .env.example .env
```

打开 `.env`，按照本机环境填写配置。下面仅展示变量结构，所有密钥和密码都需要替换为自己的值：

```dotenv
MODEL_PROVIDER=qwen
MODEL_NAME=qwen3.7-plus
MODEL_API_KEY=your_qwen_api_key
MODEL_BASE_URL=https://your-model-endpoint.example.com
MODEL_TIMEOUT=60

AMAP_JS_API_KEY=your_amap_js_api_key
AMAP_SECURITY_JS_CODE=your_amap_security_code

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=travel_app
DB_PASSWORD=your_database_password
DB_NAME=travel_planner
```

高德 Web 服务端密钥等其余变量请直接按照 `.env.example` 填写，不要修改变量名称。

5. 初始化数据库

进入 MySQL 客户端后执行：

```sql
SOURCE database/schema.sql;
```

数据库应用账户应连接 `127.0.0.1`，并按照项目说明授予保存、查询、更新选中方案和删除行程所需的最小权限。

6. 启动 FastAPI

```powershell
python -m uvicorn app.main:app --reload
```

启动成功后访问：

```text
首页：http://127.0.0.1:8000/
仪表盘：http://127.0.0.1:8000/dashboard
新建行程：http://127.0.0.1:8000/plans/new
接口文档：http://127.0.0.1:8000/docs
```