# tripChina

**Repository Path**: docevan/tripChina

## Basic Information

- **Project Name**: tripChina
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-20
- **Last Updated**: 2025-11-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 打卡中国 - 旅游足迹记录应用

基于 UniApp 和腾讯云开发（CloudBase）的旅游打卡应用，支持 **H5** 和 **微信小程序**。用户可以记录旅游足迹、管理心愿清单、查看个人统计，探索中国的美丽风景。

[![Powered by CloudBase](https://7463-tcb-advanced-a656fc-1257967285.tcb.qcloud.la/mcp/powered-by-cloudbase-badge.svg)](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit)

> 本项目基于 [**CloudBase AI ToolKit**](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit) 开发，通过AI提示词和 MCP 协议+云开发，让开发更智能、更高效，支持AI生成全栈代码、一键部署至腾讯云开发（免服务器）、智能日志修复。

## 项目特点

- 🗺️ **打卡地图** - 在地图上记录旅游足迹，可视化展示已打卡的省份和城市
- ❤️ **心愿清单** - 收藏想去的地方，支持3D游览功能解锁
- 📊 **个人统计** - 详细的旅游数据统计和成就系统
- 🏛️ **景区详情** - 丰富的景区信息展示和用户评价系统
- 🚀 基于 UniApp 构建，一套代码多端运行
- ⚡ 使用 Vue 3 Composition API 构建现代化 UI
- 🌐 支持 **H5** 和 **微信小程序**，其他平台适配开发中
- 🎁 深度集成腾讯云开发 CloudBase，提供一站式后端云服务
- 📱 完整的 TypeScript 支持，提供更好的开发体验
- 🗺️ **双地图服务** - 支持高德地图和腾讯地图，用户可自由切换
- 🔒 **安全密钥管理** - 腾讯地图API密钥存储在云函数中，确保安全性

## 项目架构

### 前端架构

- **框架**：UniApp (基于 Vue 3)
- **构建工具**：Vite
- **多端支持**：H5、微信小程序（其他平台适配开发中）
- **状态管理**：Vue 3 Reactivity API
- **类型支持**：TypeScript

### 云开发资源

本项目使用了以下腾讯云开发（CloudBase）资源：

- **身份认证**：用于用户登录和身份验证（匿名登录）
- **云数据库**：存储用户打卡记录、心愿清单、景区数据等
- **云函数**：实现打卡管理、心愿清单管理、景区查询、统计等业务逻辑
- **云存储**：存储景区图片等静态资源
- **静态网站托管**：用于部署 H5 版本

### 第三方服务集成

- **高德地图API**：提供地图显示、位置服务、POI搜索、路径规划等功能
- **高德地图服务**：通过云函数封装高德地图API，提供统一的后端服务接口
- **腾讯地图API**：提供地图显示、位置服务、POI搜索、路径规划等功能（新增）
- **腾讯地图服务**：通过云函数封装腾讯地图API，提供统一的后端服务接口（新增）

### 数据库设计

- **user_checkins** - 用户打卡记录
- **user_wishlist** - 用户心愿清单
- **user_attraction_status** - 用户景区状态（已打卡、已心愿等）
- **attractions** - 景区基础数据（包含5A级景区信息）

## 目录结构

```
├── src/
│   ├── pages/                    # 页面文件
│   │   ├── index/               # 首页
│   │   │   ├── index.vue
│   │   │   └── index.json
│   │   ├── checkin-map/         # 打卡地图页面
│   │   │   ├── checkin-map.vue
│   │   │   └── checkin-map.json
│   │   ├── wishlist/            # 心愿清单页面
│   │   │   ├── wishlist.vue
│   │   │   └── wishlist.json
│   │   ├── stats/               # 个人统计页面
│   │   │   ├── stats.vue
│   │   │   └── stats.json
│   │   ├── attraction-detail/   # 景区详情页面
│   │   │   ├── attraction-detail.vue
│   │   │   └── attraction-detail.json
│   │   └── demo/                # 云开发演示页面
│   │       ├── demo.vue
│   │       └── demo.json
│   ├── utils/                   # 工具函数和云开发初始化
│   │   ├── adapter.js           # UniApp 适配器
│   │   ├── cloudbase.ts         # 云开发配置
│   │   └── index.ts             # 通用工具函数
│   ├── static/                  # 静态资源
│   ├── App.vue                  # 应用入口组件
│   ├── main.ts                  # 应用入口文件
│   ├── pages.json               # 页面路由配置
│   └── manifest.json            # 应用配置文件
├── cloudfunctions/              # 云函数目录
│   ├── hello/                   # 示例云函数
│   │   ├── index.js
│   │   └── package.json
│   ├── initAttractions/         # 初始化景区数据
│   │   ├── index.js
│   │   └── package.json
│   ├── checkinManager/          # 打卡管理
│   │   ├── index.js
│   │   └── package.json
│   ├── wishlistManager/         # 心愿清单管理
│   │   ├── index.js
│   │   └── package.json
│   ├── attractionManager/       # 景区管理
│   │   ├── index.js
│   │   └── package.json
│   ├── amapService/             # 高德地图服务
│   │   ├── index.js
│   │   └── package.json
│   ├── httpRequest/             # HTTP请求代理
│   │   ├── index.js
│   │   └── package.json
│   └── httpRequestCore/         # HTTP请求核心
│       ├── index.js
│       └── package.json
├── index.html                   # H5 模板
├── vite.config.ts               # Vite 配置
├── tsconfig.json                # TypeScript 配置
├── package.json                 # 项目依赖
├── cloudbaserc.json            # CloudBase CLI 配置
└── README.md                   # 项目说明
```

## 功能说明

### 🗺️ 打卡地图
- **高德地图集成**：基于高德地图API的交互式地图显示
- **实时定位**：获取用户当前位置并在地图上标记
- **景点搜索**：支持关键词搜索景点、城市
- **附近景点**：基于位置查找附近景点并在地图上标记
- **地图控制**：缩放、平移、切换地图类型
- **位置打卡**：支持当前位置快速打卡
- **路径规划**：提供景点间的路径规划功能

### ❤️ 心愿清单
- 添加/移除心愿景区
- 心愿分类管理（想去、必去、推荐）
- 优先级排序功能
- 3D游览功能解锁

### 📊 个人统计
- 打卡地图可视化展示
- 景区等级分布图表
- 月度打卡统计
- 成就系统（省份收集者、景区达人等）

### 🏛️ 景区详情
- 景区基本信息、图片、介绍
- 门票价格、开放时间、交通信息
- 用户评价和打卡记录
- 相关推荐景区
- 3D游览链接

## 开始使用

<details>
<summary>前提条件</summary>

- 安装 Node.js (版本 16 或更高)
- 安装 HBuilderX 或其他支持 UniApp 的开发工具
- 腾讯云开发账号 (可在[腾讯云开发官网](https://tcb.cloud.tencent.com/)注册)

</details>

<details>
<summary>安装依赖</summary>

```bash
npm install
```

</details>

<details>
<summary>配置云开发环境</summary>

1. 打开 `src/utils/cloudbase.ts` 文件
2. 将 `ENV_ID` 变量的值修改为您的云开发环境 ID

```typescript
const ENV_ID = 'your-env-id'; // 替换为您的云开发环境ID
```

</details>

<details>
<summary>配置高德地图API</summary>

1. 在[高德开放平台](https://lbs.amap.com/)注册账号并创建应用
2. 获取API Key
3. 在 `cloudfunctions/amapService/index.js` 中配置API Key：

```javascript
const AMAP_API_KEY = 'your-amap-api-key'; // 替换为您的高德地图API Key
```

4. 重新部署 `amapService` 云函数

</details>

<details>
<summary>云开发环境配置</summary>

#### 1. 开启匿名登录

在云开发控制台的【环境】->【登录授权】中开启匿名登录。

#### 2. 配置安全域名（H5 端）

在云开发控制台的【环境】->【安全配置】->【WEB 安全域名】中添加：
- 开发域名：`http://localhost:5173`（本地开发）
- 生产域名：您的实际部署域名

#### 3. 配置小程序域名（微信小程序）

在微信小程序管理后台的【开发】->【开发管理】->【开发设置】->【服务器域名】中配置：

**request 合法域名：**
```
https://tcb-api.tencentcloudapi.com
https://your-env-id.service.tcloudbase.com
```

**uploadFile 合法域名：**
```
https://cos.ap-shanghai.myqcloud.com
```

**downloadFile 合法域名：**
```
https://your-env-id.tcb.qcloud.la
https://cos.ap-shanghai.myqcloud.com
```

> 注意：请将 `your-env-id` 替换为您的实际环境 ID，地域根据您的云开发环境所在地域调整。

#### 4. 配置腾讯地图服务（新增）

**获取腾讯地图API密钥：**
1. 访问 [腾讯位置服务控制台](https://lbs.qq.com/console/mykey.html)
2. 创建应用并获取API密钥
3. 在云开发控制台设置环境变量 `TENCENT_MAP_KEY`

**配置域名白名单：**
在腾讯位置服务控制台添加以下域名：
- 开发环境：`localhost:3000`
- 生产环境：您的实际域名

**部署腾讯地图云函数：**
```bash
# 部署腾讯地图服务云函数
tcb functions:deploy tencentMapService
```

</details>

<details>
<summary>本地开发</summary>

```bash
# H5 开发
npm run dev:h5

# 微信小程序开发
npm run dev:mp-weixin

# 注意：目前仅支持 H5 和微信小程序，其他平台适配开发中
```

</details>

<details>
<summary>构建生产版本</summary>

```bash
# 构建 H5 版本
npm run build:h5

# 构建微信小程序
npm run build:mp-weixin

# 注意：目前仅支持 H5 和微信小程序构建
```

</details>

## 云开发使用示例

通过 `src/utils/cloudbase.ts` 访问云开发服务：

```typescript
import { app, ensureLogin } from './utils/cloudbase'

// 确保用户已登录
await ensureLogin();

// 打卡管理
const checkinResult = await app.callFunction({
  name: 'checkinManager',
  data: {
    action: 'addCheckin',
    data: {
      province: '北京',
      city: '北京市',
      note: '打卡天安门'
    }
  }
});

// 心愿清单管理
const wishlistResult = await app.callFunction({
  name: 'wishlistManager',
  data: {
    action: 'addToWishlist',
    data: {
      attractionId: 'attraction_id',
      wishType: '想去',
      priority: 3
    }
  }
});

// 景区查询
const attractionResult = await app.callFunction({
  name: 'attractionManager',
  data: {
    action: 'getAttractionsByLocation',
    data: { province: '北京', limit: 10 }
  }
});

// 获取统计数据
const statsResult = await app.callFunction({
  name: 'checkinManager',
  data: { action: 'getCheckinStats' }
});

// 高德地图服务
// 搜索景点
const searchResult = await app.callFunction({
  name: 'amapService',
  data: {
    action: 'searchPoi',
    data: {
      keywords: '故宫',
      city: '北京',
      types: '风景名胜'
    }
  }
});

// 获取附近景点
const nearbyResult = await app.callFunction({
  name: 'amapService',
  data: {
    action: 'getNearbyAttractions',
    data: {
      location: '116.397128,39.916527',
      radius: 10000
    }
  }
});

// 逆地理编码（坐标转地址）
const reverseGeocodeResult = await app.callFunction({
  name: 'amapService',
  data: {
    action: 'reverseGeocode',
    data: {
      location: '116.397128,39.916527'
    }
  }
});
```

## 部署指南

### 部署云函数

可以使用 CloudBase CLI 或 MCP 工具部署云函数：

```bash
# 使用 CloudBase CLI
tcb functions:deploy hello
```

### 部署到云开发静态网站托管（H5版本）

1. 构建 H5 版本：`npm run build:h5`
2. 登录腾讯云开发控制台
3. 进入您的环境 -> 静态网站托管
4. 上传 `dist/build/h5` 目录中的文件

### 微信小程序发布

1. 构建微信小程序版本：`npm run build:mp-weixin`
2. 使用微信开发者工具打开 `dist/build/mp-weixin` 目录
3. 上传代码包并发布

## 平台适配状态

### ✅ 已适配平台

#### H5 端
- ✅ 完全支持所有云开发功能
- ✅ 支持本地开发和生产部署
- ✅ 已配置相关安全域名

#### 微信小程序
- ✅ 完全支持所有云开发功能
- ✅ 支持本地开发和发布
- ✅ 已配置相关域名白名单

### 🚧 开发中平台

#### 支付宝小程序
- 🚧 适配开发中

#### App 端
- 🚧 适配开发中

#### 其他小程序平台
- 🚧 适配开发中

<!--
## 移动应用安全凭证配置

如果需要在 App 端使用，需要配置移动应用安全凭证：

1. 在云开发控制台【环境】->【安全配置】->【移动应用安全来源】中添加应用
2. 输入应用标识（如：`uni-app`）
3. 获取凭证信息
4. 在 `src/utils/cloudbase.ts` 中取消注释并配置：

```typescript
const config = {
  env: 'your-env-id',
  appSign: 'your-app-sign',
  appSecret: {
    appAccessKeyId: 1,
    appAccessKey: 'your-app-secret'
  }
};
```

注意：目前 App 端适配开发中，此配置暂时不需要。
-->

## 功能演示

项目包含完整的旅游打卡功能：

- **打卡地图**: 在地图上记录和查看旅游足迹
- **心愿清单**: 管理想去的地方，解锁3D游览
- **个人统计**: 查看详细的旅游数据和成就
- **景区详情**: 浏览景区信息，进行打卡和评价
- **云开发功能**: 认证、数据库、云函数等基础功能

访问各个页面体验完整功能。

## 使用 CloudBase CLI 部署

```bash
# 安装 CloudBase CLI
npm install -g @cloudbase/cli

# 登录
tcb login

# 部署到云开发
tcb framework deploy
```

## 技术栈

- **UniApp** - 跨平台应用开发框架
- **Vue 3** - 渐进式 JavaScript 框架
- **TypeScript** - JavaScript 的超集，提供类型支持
- **Vite** - 下一代前端构建工具
- **CloudBase JS SDK** - 腾讯云开发 JavaScript SDK

## 开发注意事项

1. **环境变量**: 确保正确配置云开发环境 ID
2. **安全域名**: 根据部署平台配置相应的安全域名
3. **权限配置**: 注意数据库集合的读写权限设置
4. **跨端兼容**: 部分 API 在不同平台表现可能不同，注意测试
5. **Babel 插件**: 项目已配置 `@babel/plugin-transform-private-property-in-object` 插件，解决微信小程序编译时的 Babel 依赖问题

## 常见问题

### 微信小程序编译错误

如果遇到 `@babel/plugin-proposal-private-property-in-object` 相关的编译错误，请确保已安装正确的 Babel 插件：

```bash
npm install @babel/plugin-transform-private-property-in-object --save-dev
```

项目已配置使用最新的 `@babel/plugin-transform-private-property-in-object` 插件替代已废弃的 `@babel/plugin-proposal-private-property-in-object`。

### CloudBase SDK 警告

#### wx.getSystemInfoSync 废弃警告

在微信小程序中运行时，可能会看到 `wx.getSystemInfoSync is deprecated` 的警告。这是 CloudBase SDK 内部使用的微信 API 已废弃导致的，属于正常现象，不影响功能使用。

**解决方案：**
- 这些警告来自 CloudBase SDK 内部，项目代码已优化为使用单例模式避免重复初始化
- 等待 CloudBase 官方更新 SDK 以使用新的 API
- 当前版本已更新到 `@cloudbase/js-sdk@2.18.0` 以减少警告

#### CloudBase 实例重复创建警告

如果看到 `every cloudbase instance should has only one auth object` 警告，说明 CloudBase 实例被重复创建。

**解决方案：**
项目已实现单例模式，确保 CloudBase 实例只创建一次：

```typescript
// 单例模式，避免重复创建实例
let appInstance: any = null;
let isInitializing = false;

export const getApp = () => {
  if (!appInstance && !isInitializing) {
    isInitializing = true;
    appInstance = init();
    isInitializing = false;
  }
  return appInstance;
};
```

### 高德地图 JSAPI 错误

#### AMap JSAPI can only be used in Browser

在微信小程序中运行时，可能会看到 `AMap JSAPI can only be used in Browser` 错误。这是因为高德地图的 JSAPI 只能在浏览器环境中使用，不能在微信小程序中直接使用。

**解决方案：**
项目已使用 UniApp 的条件编译功能，确保高德地图相关代码只在 H5 端加载：

```typescript
// 在页面中条件导入
// #ifdef H5
import MapService from '../../components/MapService.vue'
import { loadAMap } from '../../utils/amapLoader'
// #endif

// 在组件中条件使用
// #ifdef H5
await loadAMap()
// #endif
```

**平台支持说明：**
- **H5 端**：使用高德地图 JSAPI 提供完整的地图功能
- **微信小程序**：使用微信小程序原生地图组件 `<map>` 提供基础地图功能
- **其他平台**：根据平台特性使用相应的地图解决方案

## 相关链接

- [UniApp 官方文档](https://uniapp.dcloud.io/)
- [云开发官方文档](https://cloud.tencent.com/document/product/876)
- [云开发 JS SDK](https://docs.cloudbase.net/api-reference/web/initialization)
- [CloudBase AI ToolKit](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit)

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个模板！

## 许可证

MIT License