湖南师范大学校园指南（WebGIS）

面向新生与在校生的校园服务与地图导览项目：基于 Vue 3 + Vite + TypeScript + Mapbox GL JS，提供校园 POI、3D 建筑、打卡/评论、以及公交/地铁通勤可视化与通勤指南。

✨ 特性

• 🗺️ WebGIS 校园地图 - Mapbox GL JS 渲染地图，支持缩放、旋转与平滑交互
• 🏢 3D 建筑展示 - 建筑轮廓与 3D 挤出渲染，增强空间感
• 📍 POI 分类展示 - 多类 POI 图标 + 名称标注，按缩放级别渐进显示
• 🧭 定位与打卡 - 定位到当前位置；上传图片+文字创建打卡点，并在地图上展示
• ⭐ 评论与评分（API 驱动） - POI 评论/评分、评论图片、用户头像上传
• 🚇🚌 交通可视化 + 通勤指南 - 公交线路/地铁线路/地铁站点叠加显示；通勤指南支持公交分段串联与地铁换乘
• 🔐 环境变量安全配置 - Mapbox Token、后端 API Base URL 均通过环境变量注入（适配 Cloudflare Pages）
• 📱 移动端适配 - 响应式布局，常用控件贴近拇指区

🚀 快速开始

安装依赖

npm install

开发模式

npm run dev

访问 http://localhost:5173 查看效果

如需本地联调后端（打卡/评论/上传），请同时启动 Worker（见下方“后端（Worker）本地开发”）。

构建生产版本

npm run build

预览构建结果

npm run preview

📂 项目结构

.
├── public/
│   ├── Geo/                      # 地理数据（GeoJSON）
│   │   ├── Campus.geojson
│   │   ├── Buildings.geojson
│   │   ├── Bus.geojson           # 公交线路
│   │   ├── Metro.geojson         # 地铁线路
│   │   ├── MetroStation.geojson  # 地铁站点
│   │   └── POI/                  # 各类 POI 数据
│   ├── Icons/                    # UI 图标
│   ├── Icons_POI/                # POI 图标（含地铁站 SVG 标识）
│   └── Pictures/                 # 图片资源

src/
├── api/
│   └── client.ts               # API 客户端（VITE_API_BASE_URL）
├── components/
│   ├── MapView.vue              # 地图主视图（Mapbox 图层/交互入口）
│   ├── TransportGuide.vue       # 通勤指南面板（从 MapView 拆分）
│   ├── POIPopup.vue             # POI 弹窗（评论/评分入口）
│   ├── CheckinPopup.vue         # 打卡详情弹窗（删除等）
│   ├── UserAuth.vue             # 登录/注册
│   ├── QRButton.vue             # 二维码弹出按钮
│   ├── SiteHeader.vue
│   ├── NavigationBar.vue
│   └── ...
├── config/
│   └── poiConfig.ts            # POI 分类与样式配置
├── data/
│   └── sections.ts             # 页面内容数据（导航/常用链接等）
├── types/
│   ├── index.ts
│   └── transport.ts            # 交通数据类型
├── App.vue
├── main.ts
└── style.css

worker/                          # Cloudflare Worker 后端（D1 + 可选 R2）
├── src/index.ts                 # API 路由与业务逻辑
└── wrangler.jsonc               # Worker 配置（绑定 D1/R2、变量等）

database.sql                     # D1 表结构（便于初始化/迁移）

📖 开发文档

• 开发指南.md - 内容维护与开发说明
• DEPLOYMENT.md - 部署到 Cloudflare Pages 的步骤
• CLOUDFLARE_SETUP.md - D1/R2/Worker 绑定与初始化说明
• PROJECT_SUMMARY.md - 项目实现摘要

🎯 快速添加内容

编辑 src/data/sections.ts,按照以下格式添加:

{
  title: '板块标题',
  items: [
    {
      title: '条目标题',
      links: [
        { type: 'link', text: '访问', url: 'https://example.com' },
        { type: 'qr', text: '二维码', qrImage: '/Pictures/qr.jpg' }
      ],
      description: '描述内容'
    }
  ]
}

🛠️ 技术栈

• 框架: Vue 3
• 语言: TypeScript
• 构建工具: Vite
• 地图: Mapbox GL JS v3
• 样式: CSS（组件 scoped + 全局样式）
• 后端（可选）: Cloudflare Worker + D1（SQLite）+ R2（图片存储）

🔧 环境变量

前端使用 Vite 环境变量（VITE_*）注入配置：

• VITE_MAPBOX_ACCESS_TOKEN：Mapbox 访问令牌（必须）
• VITE_API_BASE_URL：后端 Worker Base URL（生产环境必须；本地默认 http://localhost:8787）

本地开发可使用根目录的 .env.local；部署到 Cloudflare Pages 时请在项目 Settings → Environment variables 中设置上述变量并重新部署。

注意：生产环境若未配置 VITE_API_BASE_URL，前端会拒绝请求并给出明确提示，避免把 Pages 返回的 HTML 当 JSON 解析。

🧪 后端（Worker）本地开发（可选）

如果你需要评论/评分/图片上传/打卡等功能联调：

cd worker
npm install
npm run dev

默认会在本地启动 wrangler dev（通常为 http://localhost:8787）。

📝 主要功能

实用官网官微

• 校园网登录
• 图书馆系统
• 教务管理平台
• 在线教学平台
• 校园云盘
• EDU邮箱
• 学信网

学校热门论坛

• 师大论坛
• 青年师大

学校周边好店

• 美食推荐
• 位置导航

校园通勤指南

• 公交/地铁通勤建议（同名公交分段串联、地铁换乘路径）
• 地图叠加展示：公交线路、地铁线路（4/6 号线分色）、地铁站点 POI

交通可视化（地图图层）

• 公交线路：主题色（透明度 60%）
• 地铁线路：稍粗，4 号线 #974396、6 号线 #333EBC（透明度 50%）
• 地铁站点：使用 public/Icons_POI/Changsha_Metro_logo.svg 作为站点图标（优先级低于普通 POI）

🤝 贡献

欢迎提交Issue和Pull Request来帮助改进这个项目!

📄 许可

本项目仅供学习交流使用。

🔗 相关链接

• 湖南师范大学官网
• Vue 3 文档
• Vite 文档
• TypeScript 文档

---

Made for HNNU Students