# treasure_hunt_client

**Repository Path**: it4/treasure_hunt_client

## Basic Information

- **Project Name**: treasure_hunt_client
- **Description**: 本项目是“趣味寻宝应用”的移动端前端，基于 Vue 3 + Vite+ Vant UI移动端组件库构建，深度集成高德地图 JS API。用户可以在地图上直观地浏览宝物、发布新宝物、认领宝物并获取积分。
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, Ant-Design, Vant

## README

# 🗺️ 寻宝应用前端移动端 (Treasure Hunt Frontend)

本项目是“趣味寻宝应用”的移动端前端，基于 **Vue 3** + **Vite** + **Vant UI** 移动端组件库构建，深度集成**高德地图 JS API**。用户可以在地图上直观地浏览宝物、发布新宝物、认领宝物并获取积分。

---

## 🚀 项目亮点

- 📱 **移动端适配**：基于 Vant UI 开发，完美适配手机浏览器，提供流畅的类 App 原生体验。
- 🗺️ **地图深度集成**：使用高德地图 JS API，支持高精度定位、海量点标记（Markers）、信息窗体展示。
- 📍 **经纬度拾取**：发布宝物时支持在地图上直接点击拾取精确的经纬度和地址解析（逆地理编码）。
- 🔑 **全新安全架构**：支持高德地图最新的 JS API v2.0 安全密钥校验机制。
- ⚡ **轻量高效**：基于 Vite 构建，支持热重载，毫秒级编译，Pinia 状态管理实现高效的数据分发。

---

## 🛠️ 技术栈

| 技术 | 作用 | 备注 |
| :--- | :--- | :--- |
| **Vue 3** | 渐进式 JavaScript 框架 | 使用 Composition API 写法 |
| **Vite 5** | 下一代前端构建工具 | 极速冷启动与热更新 |
| **Vant UI 4** | 轻量、可靠的移动端 Vue 组件库 | 移动端极致适配 |
| **Pinia** | Vue 的专属状态管理库 | 响应式共享状态存储 |
| **Vue Router 4** | 官方路由管理器 | 支持路由拦截与守卫 |
| **Axios** | 基于 Promise 的 HTTP 客户端 | 统一拦截器，自动处理 JWT Token |
| **AMap JSAPI Loader** | 高德地图官方 API 加载器 | 支持安全密钥配置 |

---

## 📦 本地运行指引

请按照以下步骤在本地开发环境启动并运行前端项目。

### 1. 环境准备
- 推荐安装 **Node.js** 版本在 `v18.x` 或 `v20.x`（至少 `v16.0.0` 以上）。
- 推荐使用包管理器 **npm**（Node.js 自带）或 **pnpm**。

### 2. 获取并配置高德地图 API 密钥 ⚠️
由于高德地图服务限制，本地运行和地图展示**必须**使用您自己申请的高德 API Key。

1. 登录 [高德开放平台控制台](https://console.amap.com/)。
2. 创建一个“Web端 (JS API)”类型的应用，获取 **Key** 和 **安全密钥 (Security JS Code)**。
3. 打开前端配置文件：[frontend/src/api/config.js](file:///f:/ai_workspace/index4/frontend/src/api/config.js)。
4. 将获取到的值填入以下字段中：

```javascript
export const AMAP_CONFIG = {
  // 1. 高德 Web 端 JS API Key (在此填入您申请的 Key)
  key: "您的实际高德地图JS API Key",

  // 2. 安全密钥 (在此填入您申请的安全密钥)
  securityJsCode: "您的实际高德地图安全密钥",

  // 默认地图初始化中心点: 上海世纪公园 (经度, 纬度)
  defaultCenter: [121.54321, 31.21852],
};
```

> [!WARNING]
> 为了保障您的财产与账户安全，请在将代码提交到 Git 远程仓库（如 Gitee 或 GitHub）前，**务必确认已将真实的 Key 清除或替换为占位符**！

### 3. 安装依赖
在 `frontend` 目录下打开终端，执行以下命令安装项目所需的 npm 包：

```bash
npm install
```

### 4. 本地开发启动
运行以下命令启动本地开发服务器：

```bash
npm run dev
```

启动成功后，终端会输出本地访问地址，通常为：
👉 [http://localhost:5173](http://localhost:5173)

### 5. 生产打包
如果您需要将项目部署到服务器，可以运行以下命令进行打包构建：

```bash
npm run build
```
打包完成后，会在 `frontend` 目录下生成一个 `dist` 静态资源目录，您可以直接将其部署到 Nginx、Caddy 或托管服务中。

---

## 📂 项目目录结构说明

```text
frontend/
├── src/
│   ├── api/            # API 请求与基础配置
│   │   ├── config.js   # 🛠️ 高德地图 API 配置 & 基础中心点
│   │   └── request.js  # Axios 网络请求封装 (统一拦截、Token 注入)
│   ├── router/         # 路由配置 (页面导航与角色访问拦截)
│   ├── store/          # Pinia 全局状态管理 (用户登录态、角色、积分)
│   ├── views/          # 📱 页面视图组件
│   │   ├── Login.vue   # 登录与注册页面
│   │   ├── Home.vue    # 地图主页 (寻宝地图、宝物交互、认领功能)
│   │   ├── Publish.vue # 发布宝物页面 (点选地图自动定位与逆地址解析)
│   │   ├── Audits.vue  # 宝物审核列表 (支持管理员审核宝物认领)
│   │   └── Admin.vue   # 管理后台 (平台级数据监控与全局数据清空)
│   ├── App.vue         # 根组件
│   ├── main.js         # 前端入口文件
│   └── style.css       # 全局样式文件
├── index.html          # HTML 模板入口
├── package.json        # 依赖与脚本配置文件
├── vite.config.js      # Vite 配置文件
└── README.md           # 本文档
```

---

## 🔒 接口联调与代理配置

在本地开发时，前端通过 Axios 请求后端的接口。默认请求地址在 `frontend/src/api/request.js` 中配置。
- **默认后端 API 基础路径**：`http://localhost:8490/api`

如需更改后端服务地址，请在 `frontend/src/api/request.js` 中修改 `baseURL`。