# 共创空间会议室预约系统 - 技术架构文档

## 一、项目概述

### 1.1 项目简介

共创空间会议室预约系统，提供微信小程序用户端和 PC 管理端，支持会议室浏览、时间段预约、在线支付、二维码生成、订单管理、会员体系等功能。

### 1.2 系统组成

| 端 | 技术栈 | 说明 |
|----|--------|------|
| 小程序用户端 | 微信原生（WXML + JS/TS） | 面向终端用户，预约会议室 |
| PC 管理端 | Vben Admin 5.x (Vue 3 + Vite + TypeScript) | 面向运营/管理员，管理后台 |
| 后端服务 | Spring Boot 3 + Java 17 | 统一 API 服务 |

### 1.3 开发模式

- 一人开发 + AI 辅助
- 工期 30 天（含缓冲）
- 预算 3W（纯开发费用）

---

## 二、技术选型总览

| 层 | 选型 | 版本 | 理由 |
|----|------|------|------|
| 后端框架 | Spring Boot | 3.x | Java 生态主流，稳定 |
| 鉴权 | Sa-Token | 最新 | 轻量、中文文档友好、JWT 集成简单 |
| ORM | MyBatis-Plus | 3.5.x | 国内最流行，上手快 |
| 数据库 | MySQL | 8.0 | 通用、运维简单 |
| 缓存 | Redis | 7.x | token 存储、预约冲突检测、限流 |
| 前端管理端 | Vben Admin | 5.x | Vue 3 + Vite + TypeScript，模块化现代 |
| 小程序 | 微信原生 | - | 性能最好，API 全覆盖 |
| 小程序状态管理 | MobX-miniprogram | - | 响应式，多页面状态同步 |
| 接口风格 | RESTful | - | 简单直接 |
| 服务部署 | 单服务 | - | 一人维护，够用 |

---

## 三、系统架构

### 3.1 整体架构

```
┌──────────────────────────────────────────────────────────┐
│                        客户端                             │
│                                                          │
│  ┌────────────────────┐      ┌────────────────────┐      │
│  │ 微信小程序（原生）   │      │ PC 管理端（Vue 3）  │      │
│  │                    │      │ Vben Admin 5.x     │      │
│  │  · 扫码登录         │      │  · 会议室管理       │      │
│  │  · 预约/支付        │      │  · 订单管理         │      │
│  │  · 二维码展示       │      │  · 用户/会员管理    │      │
│  │  · 订单管理         │      │  · 报表统计         │      │
│  │  · 个人中心         │      │  · 系统设置         │      │
│  └────────┬───────────┘      └────────┬───────────┘      │
│           │ HTTPS                     │ HTTPS              │
└───────────┼───────────────────────────┼───────────────────┘
            │                           │
            ▼                           ▼
┌──────────────────────────────────────────────────────────┐
│                    Nginx 反向代理                         │
│           · SSL 终结                                      │
│           · /api/** → Spring Boot                         │
│           · /admin/** → 静态资源                           │
└──────────────────────────┬───────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│              Spring Boot 3 (单服务)                       │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  Controller  │  │   Service   │  │   Mapper    │      │
│  │  (RESTful)   │  │  (业务逻辑) │  │ (MyBatis+)  │      │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘      │
│         │                │                │              │
│  ┌──────┴────────────────┴────────────────┴──────┐      │
│  │              Sa-Token 鉴权层                    │      │
│  │  · JWT token 生成/验证                          │      │
│  │  · 角色权限校验                                  │      │
│  │  · 登录态管理（Redis 存储）                      │      │
│  └───────────────────────────────────────────────┘      │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │ 微信支付 SDK │  │ 短信 SDK    │  │ @Scheduled  │      │
│  │ (甲方商户号) │  │ (到期提醒)  │  │ (定时任务)   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└──────────────┬────────────┬──────────────────────────────┘
               │            │
       ┌───────┴──┐    ┌────┴───┐
       │  MySQL   │    │ Redis  │
       │  8.0     │    │        │
       │ 业务数据  │    │ token  │
       │          │    │ 缓存   │
       └──────────┘    └────────┘
```

### 3.2 接口分组

单服务下，接口按端分组：

```
/api/wx/**       → 小程序端接口（wx_user 鉴权）
/api/admin/**    → 管理端接口（sys_user 鉴权）
/api/public/**   → 公开接口（无需登录）
```

### 3.3 鉴权方案（Sa-Token）

```
小程序登录流程：
  1. 小程序调用 wx.login() 获取 code
  2. 后端用 code 换取 openid + session_key
  3. 查找/创建 wx_user 记录
  4. Sa-Token 生成 token，存入 Redis
  5. 返回 token 给小程序，后续请求 header 携带

管理端登录流程：
  1. 手机号 + 密码登录
  2. 校验通过后 Sa-Token 生成 token，存入 Redis
  3. 返回 token + 权限列表
  4. 后续请求 header 携带 token

权限校验：
  · @SaCheckRole("ADMIN")  -- 角色校验
  · @SaCheckPermission("room:edit")  -- 权限校验
  · StpUtil.getLoginIdAsLong()  -- 获取当前用户 ID
```

---

## 四、数据库设计

### 4.1 用户体系（分离设计）

```
sys_user             -- 管理端用户
├── id, username, password, real_name, phone, email
├── status (启用/禁用)
├── created_at, updated_at
└── 角色：总管理员 / 运营 / 普通管理员

wx_user              -- 小程序用户
├── id, openid, union_id
├── nickname, avatar_url, phone
├── role (租户/散客)
├── member_level_id (关联会员等级)
├── status (正常/封禁)
├── created_at, updated_at
└── 登录方式：微信授权 + 手机号绑定

tenant               -- 租户信息（长期租客）
├── id, wx_user_id
├── company_name, contact_name, contact_phone
├── contract_start, contract_end
├── free_hours_per_month (每月免费额度)
├── discount_rate (专属折扣)
├── status (有效/过期)
└── 备注：根据手机号由管理端绑定身份

member_level         -- 会员等级配置
├── id, name (普通/银卡/金卡)
├── min_orders (最低订单数)
├── discount_rate (折扣比例)
├── free_hours_per_month (每月免费小时)
└── status
```

### 4.2 业务数据

```
room                 -- 会议室
├── id, name (创客A/B/C/D)
├── description, capacity, location
├── image_url, price_per_hour
├── amenities (JSON: ["投影仪","白板","WiFi"])
├── status (可预约/维护中/已下架)
├── created_at, updated_at
└── 关联：room_schedule

booking              -- 预约订单
├── id, order_no (业务单号)
├── wx_user_id, room_id
├── booking_date, start_time, end_time
├── duration_minutes, total_price
├── discount_amount, actual_price
├── purpose (预约用途)
├── status (待支付/已确认/已完成/已取消/退款中)
├── cancel_reason, refund_amount
├── qr_code (二维码内容)
├── created_at, updated_at
└── 关联：payment

payment              -- 支付记录
├── id, booking_id
├── pay_type (微信支付)
├── amount, refund_amount
├── trade_no (微信支付交易号)
├── status (待支付/已支付/已退款/部分退款)
├── paid_at, refunded_at
└── created_at

invoice_request      -- 发票申请
├── id, wx_user_id
├── booking_ids (关联订单)
├── invoice_type (普票/专票)
├── title, tax_no, email
├── amount
├── status (待处理/已开具/已发送)
└── created_at
```

### 4.3 系统配置

```
system_config        -- 系统配置
├── id, config_key, config_value, description
├── 示例：
│   · business_start_time = "08:00"
│   · business_end_time = "22:00"
│   · time_slot_minutes = 30
│   · default_price_per_hour = 50
│   · cancel_same_day_threshold = 2 (小时)
│   · cancel_refund_rate = 80 (%)
│   · cancel_free_next_day = true
│   · reminder_sms_enabled = true
│   · reminder_sms_template = "..."
└── created_at, updated_at

sms_log              -- 短信发送记录
├── id, phone, template, content
├── status (成功/失败)
└── created_at
```

### 4.4 角色权限

```
sys_role             -- 角色
├── id, name, code, description
├── created_at
└── 角色：总管理员 / 运营

sys_permission       -- 权限
├── id, name, code, type (菜单/按钮)
├── parent_id, path, icon, sort_order
└── 示例：room:list, room:edit, booking:export

sys_role_permission  -- 角色-权限关联
├── role_id, permission_id

sys_user_role        -- 用户-角色关联
├── user_id, role_id
```

---

## 五、小程序架构

### 5.1 项目结构

```
qrm-mini/
├── app.js / app.json / app.wxss     # 全局配置和样式
├── pages/
│   ├── login/                        # 登录页
│   ├── index/                        # 首页（会议室列表）
│   ├── booking/                      # 预约页（日历 + 时间段选择）
│   ├── payment/                      # 订单确认 + 支付
│   ├── orders/                       # 我的订单列表
│   ├── order-detail/                 # 订单详情 + 二维码
│   └── profile/                      # 个人中心
├── components/                       # 公共组件
│   ├── tab-bar/                      # 底部导航
│   ├── room-card/                    # 会议室卡片
│   ├── calendar-strip/               # 日历条
│   ├── time-slot-grid/               # 时间段网格
│   └── empty-state/                  # 空状态
├── store/                            # MobX 状态管理
│   ├── user.js                       # 用户状态
│   ├── booking.js                    # 预约状态
│   └── index.js                      # 统一导出
├── utils/
│   ├── request.js                    # 封装 wx.request
│   ├── auth.js                       # 登录/鉴权工具
│   ├── format.js                     # 日期/金额格式化
│   └── qrcode.js                     # 二维码生成
├── constants/                        # 常量
│   └── index.js
└── assets/                           # 静态资源
```

### 5.2 MobX 状态管理设计

```javascript
// store/user.js
import { observable, action } from 'mobx-miniprogram'

export const userStore = observable({
  // 状态
  token: '',
  userInfo: null,
  memberLevel: null,

  // 计算属性
  isTenant: computed(function() {
    return this.userInfo?.role === 'TENANT'
  }),

  // 动作
  login: action(function(token, userInfo) {
    this.token = token
    this.userInfo = userInfo
    wx.setStorageSync('token', token)
  }),

  logout: action(function() {
    this.token = ''
    this.userInfo = null
    wx.removeStorageSync('token')
  })
})
```

### 5.3 请求封装

```javascript
// utils/request.js
const BASE_URL = 'https://api.example.com'

const request = (options) => {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + options.url,
      method: options.method || 'GET',
      data: options.data,
      header: {
        'Content-Type': 'application/json',
        'satoken': wx.getStorageSync('token'),
        ...options.header
      },
      success: (res) => {
        if (res.data.code === 401) {
          // token 过期，跳转登录
          wx.navigateTo({ url: '/pages/login/index' })
          return
        }
        resolve(res.data)
      },
      fail: reject
    })
  })
}
```

### 5.4 核心页面流程

**预约流程：**

```
首页选会议室 → 预约页（选日期 + 多选时间段）→ 确认页（显示金额 + 折扣）→ 微信支付 → 回调更新订单 → 跳转订单详情（展示二维码）
```

**取消退款流程：**

```
订单详情点"取消" → 弹窗确认 → 后端判断取消规则 → 调微信退款接口 → 退款回调 → 更新订单状态
```

---

## 六、管理端架构（Vben Admin 5.x）

### 6.1 核心功能模块

| 模块 | 页面 | 主要功能 |
|------|------|---------|
| 工作台 | Dashboard | 数据卡片、预约趋势图、即将到期列表、最近订单 |
| 会议室管理 | 列表 + 编辑弹窗 | CRUD、上下架、时间段配置 |
| 预约订单 | 筛选列表 + 详情 + 导出 | 多条件筛选、导出 Excel、手动取消 |
| 用户管理 | 用户列表 | 查看用户、绑定租户身份、封禁/解封 |
| 会员管理 | 等级列表 | 配置等级、折扣、免费额度 |
| 发票管理 | 申请列表 | 查看、处理、标记状态 |
| 报表统计 | 统计页 + 导出 | 按时间统计订单/收入、导出 Excel |
| 系统设置 | 配置页 | 营业时间、取消规则、折扣规则、短信模板 |
| 角色权限 | 角色列表 | 分配权限（Vben 内置） |

### 6.2 API 对接

```
Vben Admin 5.x 内置 request 封装，需要配置：
· baseURL: '/api/admin'
· 请求拦截器：自动携带 satoken
· 响应拦截器：处理 401 跳转登录
· token 刷新机制
```

### 6.3 权限模型

```
基于 Vben Admin 内置的 RBAC：
· 后端返回：用户信息 + 权限列表 + 角色列表
· 前端动态生成菜单
· 按钮级别权限控制（v-auth 指令）
```

---

## 七、部署架构

### 7.1 服务器规划

```
腾讯云轻量应用服务器（推荐配置）
├── CPU: 2核
├── 内存: 4GB
├── 硬盘: 60GB SSD
├── 带宽: 5Mbps
├── 系统: Ubuntu 22.04 / CentOS 8
│
├── Nginx
│   ├── 反向代理 /api/** → localhost:8080
│   ├── 静态资源 /admin/** → /var/www/admin/dist
│   └── SSL 证书（必须，小程序要求 HTTPS）
│
├── Spring Boot (JAR)
│   ├── 端口: 8080
│   └── JVM: -Xms512m -Xmx1g
│
├── MySQL 8.0
│   ├── 端口: 3306
│   └── 数据库: qrm
│
└── Redis 7.x
    ├── 端口: 6379
    └── 用途: token 存储、缓存
```

### 7.2 部署流程

```
后端部署：
  1. Maven 打包: mvn clean package -DskipTests
  2. 上传 JAR 到服务器
  3. systemctl restart qrm-server

管理端部署：
  1. pnpm build
  2. 上传 dist/ 到 /var/www/admin/
  3. Nginx 自动生效

小程序发布：
  1. 微信开发者工具上传代码
  2. 后台提交审核
  3. 审核通过后发布
```

---

## 八、关键技术决策记录

| # | 决策 | 选择 | 理由 |
|---|------|------|------|
| D1 | 小程序方案 | 微信原生 | 性能最好，仅微信平台 |
| D2 | 后端框架 | Spring Boot 3 | Java 生态，团队熟悉 |
| D3 | 鉴权方案 | Sa-Token | 轻量、中文文档、JWT 简单 |
| D4 | ORM | MyBatis-Plus | 国内主流，上手快 |
| D5 | 数据库 | MySQL 8.0 | 通用、运维简单 |
| D6 | 缓存 | Redis | token 存储，先上，资源不足再调整 |
| D7 | 服务数量 | 单服务 | 一人维护，够用 |
| D8 | 接口风格 | RESTful | 简单直接 |
| D9 | 用户体系 | 分离（sys_user + wx_user + tenant） | 职责清晰 |
| D10 | 订单/支付 | 分表（booking + payment） | 退款追溯方便 |
| D11 | 管理端框架 | Vben Admin 5.x | 现代、模块化 |
| D12 | 小程序状态管理 | MobX-miniprogram | 响应式，多页面同步 |
| D13 | 微信支付 | 甲方提供商户号 | 不承担商户申请 |
| D14 | 二维码 | 先生成展示，扫码开门后补 | 门禁设备未定 |
| D15 | 部署 | 腾讯云 + Nginx + SPA | 简单够用 |

---

## 九、开发优先级

| 阶段 | 内容 | 工期 |
|------|------|------|
| P0 骨架 | 项目初始化、数据库建表、基础 CRUD | 2天 |
| P1 登录鉴权 | 微信登录、管理端登录、Sa-Token 配置 | 2天 |
| P2 核心预约 | 会议室列表→预约→支付→订单→二维码 | 7天 |
| P3 订单操作 | 取消/退款、延期、短信提醒 | 3天 |
| P4 会员体系 | 等级、折扣、免费额度 | 3天 |
| P5 管理端 | 全部管理页面（9个模块） | 5天 |
| P6 联调部署 | 前后端联调、测试、上线 | 3天 |
| 缓冲 | 修 bug + 不可预见问题 | 5天 |
| **合计** | | **30天** |

---

## 十、待明确事项

| # | 事项 | 影响 | 当前状态 |
|---|------|------|---------|
| 1 | 时间段存储方案 | 数据库设计 | 等需求明确 |
| 2 | 订单/支付表详细字段 | 数据库设计 | 等需求明确 |
| 3 | 取消规则具体参数 | 业务逻辑 | 甲方确认 |
| 4 | 会员等级具体规则 | 业务逻辑 | 甲方确认 |
| 5 | 门禁设备协议 | 二维码对接 | 甲方确认 |
| 6 | 短信服务商 | SDK 对接 | 甲方确认 |
| 7 | 发票开具方式 | 发票模块 | 甲方确认 |