# wx-study-room

**Repository Path**: AlexanderBean/wx-study-room

## Basic Information

- **Project Name**: wx-study-room
- **Description**: 微信小程序自习室
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 付费自习室微信小程序

一个基于 uni-app + Spring Boot 的付费自习室预约平台，支持用户预约自习室座位、扫码签到、商家管理等功能。

## 📱 技术栈

### 前端
- **框架**：uni-app (Vue 2.6)
- **UI 组件库**：uView 2.0
- **地图服务**：腾讯地图 SDK (qqmap-wx-jssdk)
- **状态管理**：Vuex
- **开发工具**：HBuilderX、微信开发者工具
- **构建目标**：微信小程序

### 后端
- **框架**：Spring Boot 2.7.18
- **ORM 框架**：MyBatis Plus 3.5.3.1
- **数据库**：MariaDB 11.8 (兼容 MySQL 8.0)
- **缓存/分布式锁**：Redis + Redisson 3.17.7
- **API 文档**：Knife4j 3.0.3
- **认证**：JWT 0.9.1
- **工具库**：Hutool 5.8.16、FastJSON 1.2.83
- **开发工具**：IntelliJ IDEA
- **构建工具**：Maven

## 🗂 项目结构

```
wx-study-room/
├── backend/                      # 后端 Spring Boot 项目
│   ├── src/main/java/           # Java 源代码
│   ├── src/main/resources/      # 配置文件
│   │   └── application.yml      # 主配置文件
│   └── pom.xml                  # Maven 依赖
├── database/                     # 数据库脚本
│   └── database_complete.sql    # 完整数据库初始化脚本
── pages/                       # 主包页面
│   ├── index/index.vue          # 首页 - 地图找座
│   ├── order/order.vue          # 我的订单
│   ├── mine/mine.vue            # 个人中心
│   ├── room/detail.vue          # 自习室详情
│   ├── room/seat.vue            # 座位选择
│   └── merchant/manage.vue      # 商家管理
├── other_pages/                  # 分包1 - 功能页面
│   ├── rank/rank.vue            # 学习排行
│   ├── seat/seat.vue            # 座位管理
│   ├── check-seat/check-seat.vue # 查座
│   ├── payment/payment.vue      # 支付
│   ├── recharge/recharge.vue    # 充值
│   ├── recharge-card/recharge-card.vue  # 充值卡
│   ├── recharge-locker/recharge-locker.vue  # 充值储物柜
│   └── check-in/check-in.vue    # 扫码签到
├── other_pages_mine/             # 分包2 - 我的页面
│   ├── account/account.vue      # 账户信息
│   ├── card_package/card_package.vue  # 卡包
│   ├── locker/locker.vue        # 储物柜
│   ├── learn_record/learn_record.vue  # 学习记录
│   ── statistics/statistics.vue  # 数据统计
── components/                   # 自定义组件
│   ├── my-navbar/               # 自定义导航栏
│   ├── my-tabbar/               # 自定义底部标签栏
│   └── my-action-sheet/         # 自定义操作面板
── static/                       # 静态资源
── store/                        # Vuex 状态管理
├── utils/                        # 工具函数
├── config/                       # 配置文件
── manifest.json                 # uni-app 配置
├── pages.json                    # 页面路由配置
├── package.json                  # NPM 依赖
└── project.config.json           # 微信小程序配置
```

## 🎯 核心功能

### 用户端
1. **地图找座**：基于腾讯地图，搜索方圆 20 公里内的自习室
2. **座位可视化预约**：
   - 选择日期和时间段
   - 可视化选择座位（普通座、VIP 座、包间）
   - 实时显示座位状态（空闲/已占用/维修中）
3. **扫码签到**：扫描座位二维码签到
4. **我的订单**：查看预约记录、订单状态
5. **充值支付**：余额充值、订单支付
6. **学习记录**：查看历史学习时长统计
7. **卡包管理**：管理充值卡、优惠卡

### 商家端
1. **自习室管理**：添加、编辑自习室信息
2. **座位管理**：配置座位类型、价格、布局
3. **订单核销**：扫码核销用户预约
4. **数据统计**：营业额、使用率统计

### 管理员端
1. **用户管理**：管理用户账号
2. **商家审核**：审核商家入驻申请
3. **系统配置**：配置腾讯地图 Key、微信 AppID 等

## 🚀 环境要求

### 前端
- **Node.js**：>= 14.0.0
- **npm**：>= 6.0.0
- **HBuilderX**：>= 3.0.0
- **微信开发者工具**：>= 2.01.2510290

### 后端
- **JDK**：>= 1.8 (项目使用 JDK 17.0.17)
- **Maven**：>= 3.6.0
- **MariaDB**：>= 11.8 (或 MySQL 8.0)
- **Redis**：>= 6.0.0

## 📋 安装步骤

### 1. 数据库初始化

1. 确保 MariaDB/MySQL 服务已启动：
   ```cmd
   net start MariaDB
   ```

2. 连接到数据库：
   ```cmd
   mysql -u root -p
   ```

3. 执行数据库初始化脚本：
   ```sql
   source C:/Users/Administrator/IdeaProjects/wx-study-room/database/database_complete.sql
   ```

   或者在 MySQL 命令行中：
   ```sql
   CREATE DATABASE IF NOT EXISTS study_room DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   USE study_room;
   source C:/Users/Administrator/IdeaProjects/wx-study-room/database/database_complete.sql;
   ```

4. 验证数据：
   ```sql
   USE study_room;
   SELECT COUNT(*) AS room_count FROM study_room;  -- 应返回 33 条记录
   ```

### 2. Redis 安装与启动

**方式一：Windows 安装 Redis**
1. 下载：[https://github.com/tporadowski/redis/releases](https://github.com/tporadowski/redis/releases)
2. 解压到 `C:\Redis`
3. 启动：
   ```cmd
   cd C:\Redis
   redis-server.exe redis.windows.conf
   ```

**方式二：Docker 启动**
```cmd
docker run -d --name redis-study-room -p 6379:6379 redis
```

### 3. 后端配置与启动

1. **修改配置文件** `backend/src/main/resources/application.yml`：

   ```yaml
   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/study_room?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
       username: root
       password: root  # 修改为你的 MariaDB root 密码
   
     redis:
       host: localhost
       port: 6379
   
   study-room:
     tencent-map:
       key: 你的腾讯地图Key  # 从 https://lbs.qq.com/console/mykey.html 获取
       # 需在控制台开启 WebserviceAPI 权限
   
   jwt:
     secret: 你的JWT密钥  # 至少32位字符
   
   wx:
     miniapp:
       appid: 你的微信小程序AppID  # 从微信公众平台获取
       secret: 你的微信小程序AppSecret  # 从微信公众平台获取
   ```

2. **获取腾讯地图 Key**：
   - 访问 [https://lbs.qq.com/console/mykey.html](https://lbs.qq.com/console/mykey.html)
   - 创建密钥，产品类型勾选：**WebServiceAPI** + **微信小程序SDK**
   - 启用产品：**WebServiceAPI**
   - 复制 Key 到 `application.yml`

3. **获取微信小程序 AppID 和 AppSecret**：
   - 访问 [https://mp.weixin.qq.com](https://mp.weixin.qq.com)
   - 登录小程序后台
   - **开发** → **开发管理** → **开发设置**
   - 复制 AppID 和 AppSecret 到 `application.yml`

4. **启动后端**：
   ```cmd
   cd C:\Users\Administrator\IdeaProjects\wx-study-room\backend
   mvn clean package -DskipTests
   java -jar target/study-room-backend-1.0.0.jar
   ```

   或使用 IDEA：
   - 打开 `backend` 目录
   - 找到 `StudyRoomApplication.java`
   - 右键 → Run 'StudyRoomApplication'

5. **验证后端启动成功**：
   - 访问：[http://localhost:8080/api/doc.html](http://localhost:8080/api/doc.html)
   - 看到 Knife4j API 文档页面即成功

### 4. 前端配置与启动

1. **安装依赖**：
   ```cmd
   cd C:\Users\Administrator\IdeaProjects\wx-study-room
   npm install
   ```

2. **配置 manifest.json**：
   - 打开 `manifest.json`
   - 找到 `mp-weixin` → `appid`
   - 填入你的微信小程序 AppID：
     ```json
     "mp-weixin": {
         "appid": "wx261a2b88a2c3304f",
         ...
     }
     ```

3. **使用 HBuilderX 编译**：
   - 打开 HBuilderX
   - 文件 → 打开目录 → 选择 `C:\Users\Administrator\IdeaProjects\wx-study-room`
   - 运行 → 运行到小程序模拟器 → 微信开发者工具
   - 等待编译完成，自动打开微信开发者工具

4. **在微信开发者工具中配置**：
   - 项目目录：`C:\Users\Administrator\IdeaProjects\wx-study-room\unpackage\dist\dev\mp-weixin`
   - AppID：`wx261a2b88a2c3304f`（替换为你的 AppID）
   
   **重要配置**：
   - 点击顶部菜单 **详情** → **本地设置**
   - 勾选：
     - ✅ 不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书
     - ✅ 启用条件编译
     - ✅ 启用 SWC 编译脚本文件
     - ✅ 上传代码时自动压缩样式文件
     - ✅ 上传代码时自动压缩脚本文件
     - ✅ 上传代码时自动压缩 wxml 文件
     - ✅ 上传时过滤无依赖文件
     - ✅ 启用代码自动热重载

5. **启动小程序**：
   - 在微信开发者工具中刷新（Ctrl + R）
   - 确保位置权限已开启

## 📖 使用说明

### 用户端使用流程

1. **打开小程序** → 首页展示地图和附近自习室
2. **搜索自习室** → 输入关键词（自习室、考研教室等）
3. **选择自习室** → 查看自习室详情、价格、设施
4. **预约座位**：
   - 选择日期
   - 选择时间段（如 08:00-10:00）
   - 在座位图上点击选择座位（A1、B2 等）
   - 确认预约并支付
5. **扫码签到**：
   - 到达自习室
   - 点击"扫码签到"
   - 扫描座位二维码
6. **查看订单**：
   - 点击底部"我的订单"
   - 查看预约记录、订单状态
7. **个人中心**：
   - 查看余额、学习记录、卡包
   - 充值、查看数据统计

### 商家端使用流程

1. **登录商家账号**（使用测试账号：openid: `test_openid_003`）
2. **进入商家管理** → 点击"我的" → "商家管理"
3. **管理自习室**：
   - 添加自习室信息
   - 编辑价格、营业时间、设施
4. **管理座位**：
   - 配置座位布局（X、Y 坐标）
   - 设置座位类型（普通座、VIP 座、包间）
   - 标记座位状态（空闲、维修中）
5. **核销订单**：
   - 查看待核销订单
   - 扫码核销或手动核销

## 🔑 测试账号

数据库已预置测试数据：

| 角色 | OpenID | 手机号 | 昵称 | 密码 |
|------|--------|--------|------|------|
| 普通用户 | test_openid_001 | 13800138001 | 学霸小明 | - |
| 普通用户 | test_openid_002 | 13800138002 | 考研达人 | - |
| 商家 | test_openid_003 | 13800138003 | 学霸自习室 | - |
| 管理员 | test_openid_004 | 13800138004 | 系统管理员 | - |

## ⚙️ 配置说明

### 必需配置项

| 配置项 | 文件位置 | 说明 |
|--------|----------|------|
| MariaDB 密码 | `backend/src/main/resources/application.yml` 第15行 | 数据库连接密码 |
| Redis 配置 | `backend/src/main/resources/application.yml` 第17-28行 | Redis 地址和端口 |
| 腾讯地图 Key | `backend/src/main/resources/application.yml` 第61行 | 需开启 WebserviceAPI |
| 微信小程序 AppID | `manifest.json` 第53行 / `backend/src/main/resources/application.yml` 第81行 | 小程序标识 |
| 微信小程序 AppSecret | `backend/src/main/resources/application.yml` 第82行 | 小程序密钥 |
| JWT Secret | `backend/src/main/resources/application.yml` 第73行 | JWT 签名密钥（至少32位） |

### 可选配置项

| 配置项 | 文件位置 | 说明 |
|--------|----------|------|
| 服务器端口 | `application.yml` 第2行 | 默认 8080 |
| 搜索半径 | `application.yml` 第64行 | 默认 5000 米 |
| 文件上传路径 | `application.yml` 第67行 | 默认 /data/upload/ |

## 🐛 常见问题

### 1. 后端启动失败 - MariaDB 连接失败
**原因**：MariaDB 服务未启动或密码错误
**解决**：
```cmd
net start MariaDB
mysql -u root -p  # 验证密码
```
修改 `application.yml` 中的密码。

### 2. 后端启动失败 - Redis 连接失败
**原因**：Redis 服务未启动
**解决**：
```cmd
redis-server
```

### 3. 小程序无法调用腾讯地图 API
**原因**：
- 未勾选"不校验合法域名"
- 腾讯地图 Key 未开启 WebserviceAPI

**解决**：
- 微信开发者工具 → 详情 → 本地设置 → 勾选"不校验合法域名"
- 腾讯地图控制台 → 开启 WebserviceAPI 权限

### 4. 小程序提示"未找到自习室"
**原因**：
- 当前位置20公里内无自习室数据
- 定位权限未开启

**解决**：
- 在微信开发者工具中切换位置到运城、北京、上海等大城市
- 小程序设置 → 开启位置权限

### 5. 前端编译失败
**原因**：依赖未安装或版本不匹配
**解决**：
```cmd
npm install
```

### 6. 后端 API 文档无法访问
**原因**：后端未启动或端口冲突
**解决**：
- 检查后端是否运行：`http://localhost:8080/api/doc.html`
- 修改 `application.yml` 中的端口号

## 📚 API 文档

后端启动后访问：
- **Knife4j 文档**：[http://localhost:8080/api/doc.html](http://localhost:8080/api/doc.html)
- **Swagger 文档**：[http://localhost:8080/api/swagger-ui.html](http://localhost:8080/api/swagger-ui.html)

##  数据库表结构

| 表名 | 说明 | 记录数 |
|------|------|--------|
| user | 用户表（游客/用户/商家/管理员） | 4 |
| study_room | 自习室表（全国33个自习室） | 33 |
| seat | 座位表 | 16 |
| booking_order | 预约订单表 | 2 |
| review | 评价表 | 2 |
| study_record | 学习记录表 | 0 |
| seat_lock | 座位预约锁表 | 0 |
| sys_config | 系统配置表 | 5 |

##  开发工具推荐

### 前端
- **HBuilderX**：uni-app 官方 IDE，支持一键编译到微信小程序
- **微信开发者工具**：小程序调试和预览
- **VS Code**：代码编辑（可选）

### 后端
- **IntelliJ IDEA**：Java 开发 IDE
- **Maven**：依赖管理和构建
- **Navicat / DBeaver**：数据库管理工具

### 数据库
- **MariaDB 11.8**：数据库服务器
- **Redis**：缓存和分布式锁

## 📝 开发说明

### 前后端联调
1. 确保后端服务运行在 `http://localhost:8080`
2. 前端请求地址配置在 `config/config.js`
3. 本地开发时需关闭域名校验

### 分包加载
项目采用 uni-app 分包机制优化包体积：
- **主包**：首页、订单、我的、自习室详情、座位选择、商家管理
- **分包1**（other_pages）：排行榜、座位管理、查座、支付、充值、签到
- **分包2**（other_pages_mine）：账户、卡包、储物柜、学习记录、数据统计

### 自定义组件
- `my-navbar`：自定义导航栏，支持返回按钮、标题、右侧按钮
- `my-tabbar`：自定义底部标签栏，替代原生 tabBar
- `my-action-sheet`：自定义操作面板

## 📄 许可证

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

##  联系方式

如有问题，请查看本文档或提交 Issue。

---

**版本**：v1.0.0  
**更新日期**：2026-05-12  
**作者**：自习室项目团队