# 云隙-旅行计划助手

**Repository Path**: LLS312885991/cloudgap

## Basic Information

- **Project Name**: 云隙-旅行计划助手
- **Description**: 云隙-旅行计划助手：一个专注于旅行规划的开源项目，提供行程安排、景点推荐和实用指南，帮助用户轻松制定完美旅行计划。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 云隙 CloudGap

> 当阳光透过云层缝隙倾泻而下时，光便有了形状。

**云隙**（CloudGap）是一款基于 AI 对话的智能旅行规划助手。用户通过与助手对话，输入目的地、出发地、时间等关键信息，即可自动生成完整的旅行计划——包括总体行程路线（地图展示）、每一天的日程安排、交通/美食/景点等详细内容，确认后生成行程日历提醒。

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| JDK | 25 | 运行环境 |
| Spring Boot | 4.0.0 | 后端框架 |
| MyBatis-Plus | 3.5.15 | ORM（spring-boot4-starter） |
| PostgreSQL | 16 | 数据库 |
| Flyway | — | 数据库迁移 |
| Spring AI Alibaba | 1.0.0.3 | AI 对话（DashScope） |
| Spring AI OpenAI | 1.0.0 | DeepSeek 模型接入 |
| iCal4j | 4.0.3 | 日历文件生成 |
| Maven | 3.9.16 | 构建工具 |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.x | 前端框架 |
| Vue Router | 4.6.x | 路由管理 |
| Vite | 8.x | 构建工具 |
| 高德地图 JS API | 2.0 | 地图展示与路线绘制 |

## 目录结构

```
cloudgap/
├── cloudgap-server/          # Spring Boot 后端
│   ├── src/main/java/com/cloudgap/
│   │   ├── agent/            # AI Agent 工作流节点
│   │   │   ├── TripPlannerWorkflow.java
│   │   │   ├── IntentExtractNode.java
│   │   │   ├── PoiNode.java
│   │   │   ├── RouteNode.java
│   │   │   ├── ScheduleNode.java
│   │   │   ├── PolishNode.java
│   │   │   └── FrameworkNode.java
│   │   ├── config/           # 配置类
│   │   ├── controller/       # REST 控制器
│   │   │   ├── AuthController.java
│   │   │   ├── ChatController.java
│   │   │   ├── MapController.java
│   │   │   ├── TripController.java
│   │   │   └── UserController.java
│   │   ├── dto/              # 数据传输对象
│   │   ├── entity/           # 数据库实体
│   │   ├── mapper/           # MyBatis-Plus Mapper
│   │   └── service/          # 业务服务
│   │       ├── AmapService.java    # 高德地图 API 服务
│   │       ├── CalendarService.java
│   │       ├── ChatService.java
│   │       ├── TripService.java
│   │       └── UserService.java
│   └── src/main/resources/
│       ├── application.yml
│       └── db/migration/     # Flyway SQL 脚本
├── cloudgap-web/             # Vue 3 前端
│   └── src/
│       ├── components/       # 公共组件
│       │   ├── CloudGapIcon.vue
│       │   └── NavBar.vue
│       ├── composables/      # 组合式函数
│       │   └── useChat.js
│       ├── router/           # 路由配置
│       ├── views/            # 页面视图
│       │   ├── SplashView.vue
│       │   ├── LoginView.vue
│       │   ├── ChatView.vue
│       │   ├── TripListView.vue
│       │   ├── TripDetailView.vue
│       │   ├── TripDayView.vue
│       │   └── ProfileView.vue
│       ├── App.vue
│       ├── main.js
│       └── style.css
├── docs/                     # 设计文档与原型
│   ├── prototype/            # 原型图
│   └── superpowers/          # 设计规格与实施计划
├── docker-compose.yml        # PostgreSQL 容器
└── README.md
```

## 快速启动

### 环境要求

- JDK 25（路径：`D:\jdks\jdk-25.0.3`）
- Maven 3.9.16（路径：`D:\applications\apache-maven-3.9.16`）
- Node.js 18+
- Docker（用于启动 PostgreSQL）

### 1. 启动 PostgreSQL

```bash
docker compose up -d
```

### 2. 配置环境变量

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `AMAP_KEY` | 高德地图 Web 服务 API Key | `your_amap_key_here` |
| `DASHSCOPE_API_KEY` | 阿里云 DashScope API Key | — |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | — |

### 3. 启动后端

```bash
cd cloudgap-server

# 设置环境变量（PowerShell）
$env:JAVA_HOME = "D:\jdks\jdk-25.0.3"

# 编译运行
D:\applications\apache-maven-3.9.16\bin\mvn spring-boot:run
```

后端启动后访问：`http://localhost:8080`

### 4. 启动前端

```bash
cd cloudgap-web
npm install
npm run dev
```

前端开发服务器默认访问：`http://localhost:5173`

## 高德地图 API 配置

本项目的后端和前端均使用高德地图 API。服务端通过 Web 服务 API（`restapi.amap.com`）进行 POI 搜索和路径规划，前端使用 JS API 2.0 展示地图和绘制路线。

### 高德开放平台 Key 体系说明

高德地图不同平台需要申请**不同类型的 Key**，不可混用：

| 平台类型 | 申请入口 | Key 类型 | 是否需要安全密钥 |
|----------|----------|----------|:---:|
| **Web 端（JS API）** | 高德开放平台 → Web端(JS API) | Web 端 Key | ✅ 是 |
| **Web 服务（Rest API）** | 高德开放平台 → Web服务 | Web 服务 Key | ❌ 否 |
| **微信小程序** | 高德开放平台 → 微信小程序 | 小程序 Key | ❌ 否（需绑定 AppID） |

> **重要**：本项目同时使用了 Web 服务 API（后端）和 JS API（前端），需要分别申请对应类型的 Key，或使用同一个已开通两种服务的 Key。

### Web 端 JS API 安全密钥机制

自 **2021 年 12 月 02 日**起，高德地图新申请的 Web 端 JS API Key **必须配合安全密钥（jscode）**一起使用。安全密钥的作用是防止 Key 被恶意冒用。

#### 配置方式（开发环境 — 明文）

在加载 JS API 脚本**之前**，设置 `window._AMapSecurityConfig`：

```html
<script>
  window._AMapSecurityConfig = {
    securityJsCode: "你的安全密钥",
  };
</script>
<script src="https://webapi.amap.com/maps?v=2.0&key=你的Key"></script>
```

> ⚠️ **注意**：明文方式仅适合开发调试，生产环境请使用代理服务器方式。

#### 配置方式（生产环境 — 代理服务器，推荐）

通过 Nginx 反向代理，将安全密钥放在服务端：

```nginx
server {
  listen 80;
  server_name 127.0.0.1;

  location /_AMapService/ {
    set $args "$args&jscode=你的安全密钥";
    proxy_pass https://restapi.amap.com/;
  }
}
```

前端配置：

```html
<script>
  window._AMapSecurityConfig = {
    serviceHost: "http://你的服务器地址/_AMapService",
  };
</script>
<script src="https://webapi.amap.com/maps?v=2.0&key=你的Key"></script>
```

> `_AMapService` 为固定前缀，不可修改。

### 微信小程序 vs Web JS API 核心差异

| 维度 | Web JS API | 微信小程序 |
|------|-----------|-----------|
| **加载方式** | `<script>` 标签或 npm loader | 引入 `amap-wx.js` 文件 |
| **安全管理** | Key + 安全密钥（jscode） | Key + 绑定 AppID + 域名白名单 |
| **安全密钥** | ✅ 必须（新 Key） | ❌ 无此机制 |
| **地图渲染** | `new AMap.Map(container)` | 通过 `amap-wx.js` 调用 API |
| **域名限制** | 高德控制台设置 | 微信公众平台 `request` 合法域名 |
| **不可混用** | 小程序不能使用 Web 端 Key | Web 端不能使用小程序 Key |

### 本项目后端配置

服务端使用 Web 服务 API（不涉及 JS API 安全密钥），在 `application.yml` 中配置：

```yaml
amap:
  key: ${AMAP_KEY:your_amap_key_here}
```

使用方式：启动时通过环境变量 `AMAP_KEY` 传入。

### 本项目前端配置

前端在 `index.html` 中加载高德 JS API。需要在页面中先设置安全密钥，再加载 API：

```html
<script>
  window._AMapSecurityConfig = {
    securityJsCode: "你的安全密钥",
  };
</script>
<script src="https://webapi.amap.com/maps?v=2.0&key=你的Key"></script>
```

推荐使用 `@amap/amap-jsapi-loader` 以 npm 包方式加载：

```bash
npm install @amap/amap-jsapi-loader
```

```javascript
import AMapLoader from '@amap/amap-jsapi-loader';

window._AMapSecurityConfig = {
  securityJsCode: '你的安全密钥',
};

AMapLoader.load({
  key: '你的Key',
  version: '2.0',
  plugins: ['AMap.Scale', 'AMap.ToolBar'],
}).then((AMap) => {
  const map = new AMap.Map('container', {
    zoom: 12,
    center: [116.397428, 39.90923],
  });
});
```

### 常见问题

| 现象 | 可能原因 | 解决方式 |
|------|---------|---------|
| 地图白屏/加载失败 | 安全密钥未在 JS API 加载前设置 | 确保 `_AMapSecurityConfig` 在 `<script>` 之前 |
| `INVALID_USER_KEY` | Key 与安全密钥不匹配 | 确认两者来自同一应用 |
| 地图瓦片 401 | 静态资源请求未携带安全密钥 | 使用代理服务器方式 |
| 小程序 `invalid key` | Key 类型选错 | 检查是否申请了"微信小程序"类型 Key |

## 功能概览

| 页面 | 路由 | 说明 |
|------|------|------|
| 启动页 | `/` | 品牌展示，"丁达尔效应"意境 |
| 登录页 | `/login` | 微信授权登录 |
| 对话页 | `/chat` | AI 对话，输入行程需求 |
| 行程列表 | `/trips` | 已生成/历史行程 |
| 行程详情 | `/trips/:id` | 路线总览 + 每日折叠面板 |
| 日详情 | `/trips/:id/day/:dayNum` | 时间轴展示当天所有活动 |
| 个人中心 | `/profile` | 用户信息与统计 |

## AI 工作流

后端采用 Spring AI Alibaba Graph Core 实现多节点 Agent 工作流：

```
用户输入 → IntentExtractNode（意图提取）→ PoiNode（景点搜索）
    → RouteNode（路线规划）→ ScheduleNode（日程编排）
    → PolishNode（文案润色）→ FrameworkNode（结构化输出）
```

## 数据库

- 数据库：PostgreSQL 16
- 迁移工具：Flyway
- 日期格式：`Long` 类型，`yyyyMMdd`（8位）或 `yyyyMMddHHmmss`（14位）

### 主要数据表

| 表名 | 说明 |
|------|------|
| `wx_user` | 微信用户信息 |
| `conversation` | 对话记录 |
| `trip` | 旅行计划 |
| `trip_day` | 行程日 |
| `trip_item` | 行程项目（活动/交通/美食等） |