项目总览

修改记录

日期	变更
2026-07-18	重写为交叉引用总览模式，补全 ADR 索引

技术栈总览

层	技术	说明
后端框架	Python 3.12 + FastAPI	异步 HTTP + SSE 流式
求解引擎	CA（模拟退火）+ VNS+（变邻域搜索 + SA 混合 + 自适应算子）	核心算法
前端框架	Vue 3 + Vite + TypeScript	SPA 单页应用
地图 SDK	高德 AMap JS API v2.0	2D 路线可视化
数据库	PostgreSQL 16（pgvector）	历史记录持久化
缓存	Redis	预留
LLM	DeepSeek API（兼容 OpenAI SDK）	营业时间解析 + Agent 对话
容器化	Docker Compose（Nginx + uvicorn + Postgres + Redis）	一键部署

顶层目录

TravelPal/
├── backend/        后端 FastAPI        → 详见 backend.md
├── frontend/       前端 Vue 3 + Vite   → 详见 frontend.md
├── docs/           项目文档体系        → 本目录（结构文档 + ADR + 编码规范）
├── data/           数据集
│   ├── DataSets/    TSPTW 测试集（n100w20, n60w60...）
│   └── spots/       景点 MD 仓库（待填充）
├── tests/          测试目录
├── docker-compose.yml    四服务编排（postgres/redis/backend/nginx）
├── docker/
│   ├── Dockerfile.backend    后端容器镜像（Poetry export + pip）
│   ├── Dockerfile.frontend   前端容器镜像（双阶段：Node build → Nginx serve）
│   └── nginx.conf            Nginx 反向代理配置（API proxy + 前端静态 + SSE）
├── deploy.sh             一键部署脚本
├── .env.example          环境变量模板
├── Makefile              开发命令（dev/serve/lint/build/test/docker）
└── pyproject.toml        Poetry 项目配置 + 依赖管理

系统级调用链路

用户操作
  │
  ├── POST /api/poi-lookup    →  高德 POI 搜索（LLM 解析营业时间）
  │
  ├── POST /api/suggest       →  ca_suggest()：6 种聚类 × 天数遍历
  │     └── 返回建议列表       →  用户选择天数 → 前端合成 PlanResult
  │
  ├── POST /api/plan          →  指定天数 → cluster_and_solve()
  │     └── 返回完整方案       →  前端 AMap 渲染 + SchedulePanel
  │
  └── POST /api/chat (SSE)    →  LLM Agent 流式对话
        └── 返回流式回复       →  聊天面板渲染

各环节的完整数据流和关键数据结构见以下文档：

链路环节	关键文档
端到端前端交互	frontend.md
Suggest/Plan 引擎分支	backend.md
POI 查询 + LLM 解析流程	backend.md
数据结构全貌	data.md

ADR 索引

文档	主题	状态
ADR/001.md	CA / VNS 平级并行架构	✅ 已采纳
ADR/002.md	前端架构选型（Vue 3 + FastAPI 分离）	✅ 已采纳
ADR/003.md	可视化方案变更（Cesium 3D → AMap 2D）	✅ 已采纳
ADR/004.md	项目哲学——"旅行伴侣"而非"规划工具"	✅ 已采纳
ADR/005.md	营业时间 LLM 解析与 Agent 架构决策	✅ 已采纳