📋 目录
🎯 项目概述
华科智家 BIM 户型模型展示系统是一个专业的建筑信息模型可视化平台，为用户提供沉浸式的 3D 户型查看体验。系统支持聊城市区域内多个房地产项目的户型模型展示，用户可以通过微信小程序进行在线浏览、交互和收藏。
核心价值
- 🏠 真实还原：基于 BIM 技术的高精度 3D 户型模型
- 📱 便捷访问：微信小程序，即用即走
- 🎮 交互体验：支持 360° 旋转、缩放、房间切换
- 🔐 安全可靠：完整的用户认证和权限管理
- 📊 数据管理：完善的后台管理系统
🏗️ 系统架构
部署环境后端技术栈前端技术栈PM2进程管理Windows Server + IISMySQL 8.0MySQL数据库Node.js + ExpressExpress后端APIJWT认证文件上传/下载Vue3 + Piniauni-app前端Three.js + WebGLH5 3D模型展示Vue3 + Element Plus管理员后台用户微信小程序模型文件存储
💻 技术栈
前端技术栈
微信小程序端 (frontend/)
| 技术 | 版本 | 用途 | 说明 |
|---|
| uni-app | 最新版 | 跨平台开发框架 | 微信小程序主框架 |
| Vue 3 | 3.5.13 | 渐进式 JavaScript 框架 | SSR 应用，支持 uni-app x |
| Pinia | 3.0.2 | 状态管理 | 自定义持久化插件 |
| Three.js | 0.175.0 | 3D 图形库 | WebGL 3D 模型渲染 |
| Vite | 6.2.2 | 构建工具 | uni-app 官方 Vite 插件 |
| Webpack | 5.x | 模块打包 | vue.config.js 配置优化 |
| UTS | 最新版 | TypeScript 方言 | uni-app x 原生开发语言 |
管理后台端 (admin-frontend/)
| 技术 | 版本 | 用途 | 说明 |
|---|
| Vue 3 | 3.5.13 | 渐进式 JavaScript 框架 | Composition API |
| Vue Router | 4.5.1 | 路由管理 | SPA 单页应用路由 |
| Element Plus | 2.9.11 | UI 组件库 | 管理后台 UI 组件 |
| Vite | 6.3.5 | 构建工具 | 现代化前端构建工具 |
| Axios | 1.9.0 | HTTP 客户端 | API 请求库 |
后端技术栈
| 技术 | 版本 | 用途 | 说明 |
|---|
| Node.js | 14+ | JavaScript 运行时 | 服务端运行环境 |
| Express | 4.21.2 | Web 框架 | RESTful API 服务 |
| MySQL | 8.0.42 | 关系型数据库 | 数据持久化存储 |
| mysql2 | 3.14.0 | 数据库驱动 | 原生 SQL 查询，连接池管理 |
| JWT | 9.0.2 | 身份认证 | 无状态用户认证 |
| bcrypt | 5.1.1 | 密码加密 | 用户密码安全存储 |
| Winston | 3.17.0 | 日志系统 | 多传输方式日志（文件+DB） |
| winston-mysql | 1.1.1 | MySQL 日志传输 | 日志写入数据库 |
| 阿里云 SMS SDK | 1.1.6 | 短信服务 | 验证码发送服务 |
| express-validator | 7.2.1 | 请求验证 | API 参数验证 |
| express-rate-limit | 7.5.0 | 接口限流 | 防止恶意请求 |
| helmet | 8.1.0 | 安全中间件 | HTTP 安全头设置 |
| multer | 1.4.5 | 文件上传 | 多媒体文件上传处理 |
| PM2 | – | 进程管理 | 生产环境进程守护 |
3D 渲染技术
| 技术 | 用途 | 特性 |
|---|
| HKGLTF-ES6 | 自研 3D 引擎 | 基于 Three.js 的定制化 3D 模型查看器 |
| DRACO 压缩 | 模型压缩 | 几何体压缩，减少传输大小 |
| WebGL | 硬件加速 | GPU 加速的 3D 图形渲染 |
| 材质系统 | 真实感渲染 | 支持 PBR 材质和光照系统 |
✨ 功能特性
🔐 用户认证系统
- 微信小程序授权登录
- 手机号快捷登录
- 短信验证码认证
- JWT Token + Refresh Token 双令牌机制
- 用户角色权限管理（用户/管理员）
🏠 户型选择系统
3D展示功能认证方式模型加载3D模型展示视角控制房间标签系统管线材质切换微信授权登录用户认证短信验证码密码登录微信小程序启动户型选择区县选择街道选择小区选择楼栋选择户型绑定
- 四级筛选：区县 → 街道 → 小区 → 楼栋
- 智能搜索：支持关键词快速定位
- 收藏功能：用户可收藏心仪户型
- 绑定管理：用户户型绑定和变更申请
🎮 3D 模型交互
- 高质量渲染：基于 Three.js 的 WebGL 渲染
- 多种控制：旋转、缩放、平移、飞行
- 房间导航：房间列表、房间标签、快速跳转
- 视角预设：鸟瞰视角、平面视角、房间视角
- 材质系统：电气系统、供暖系统可视化
- 亮度调节：用户可调节场景亮度
📊 管理后台
- 用户管理：用户信息查看、角色分配
- 模型管理：3D 模型上传、编辑、删除
- 绑定审核：用户换绑申请审核
- 日志监控：系统操作日志记录
📁 项目结构
A-WXXCX/
├── 📱 frontend/ # uni-app 微信小程序
│ ├── src/
│ │ ├── pages/ # 页面组件
│ │ │ ├── launch.vue # 启动页面
│ │ │ ├── login.vue # 登录页面
│ │ │ ├── xuanzehuxing.vue # 户型选择页面
│ │ │ ├── zhuce.vue # 注册页面
│ │ │ └── wode.vue # 个人中心
│ │ ├── subpackages/model/ # 3D 模型分包
│ │ │ ├── pages/
│ │ │ │ └── huxingmoxing.vue # 3D 模型展示页面
│ │ │ └── static/HKGLTF-ES6/ # 3D 渲染引擎
│ │ │ ├── js/src/ # 核心渲染逻辑
│ │ │ ├── libs/ # 第三方库（DRACO等）
│ │ │ └── loaders/ # 模型加载器
│ │ ├── api/ # API 接口封装
│ │ ├── store/ # Pinia 状态管理
│ │ ├── components/ # 公共组件
│ │ ├── utils/ # 工具函数
│ │ ├── main.js # JavaScript 入口文件
│ │ ├── main.uts # UTS 入口文件 (uni-app x)
│ │ ├── App.vue # Vue 应用根组件
│ │ ├── App.uvue # UVue 根组件 (uni-app x)
│ │ └── vite.config.js # Vite 配置文件
│ ├── manifest.json # 小程序配置
│ ├── pages.json # 页面路由配置
│ ├── vue.config.js # Webpack 构建配置
│ ├── clean-unused-files.js # 文件清理脚本
│ └── 分包优化指南.md # 分包优化文档
│
├── 🖥️ backend/ # Node.js 后端服务
│ ├── src/
│ │ ├── controllers/ # 控制器层（HTTP 请求处理）
│ │ │ ├── authController.js # 用户认证控制器
│ │ │ ├── modelController.js # 3D 模型控制器
│ │ │ ├── districtController.js # 区域数据控制器
│ │ │ ├── communityController.js # 小区数据控制器
│ │ │ ├── adminController.js # 管理员功能控制器
│ │ │ ├── uploadController.js # 文件上传控制器
│ │ │ └── userBindingController.js # 用户绑定控制器
│ │ ├── middleware/ # Express 中间件
│ │ │ ├── authMiddleware.js # JWT 认证中间件
│ │ │ ├── adminMiddleware.js # 管理员权限中间件
│ │ │ └── errorHandler.js # 全局错误处理中间件
│ │ ├── routes/ # 路由定义
│ │ │ ├── api.js # 公共 API 路由
│ │ │ └── admin.js # 管理员路由
│ │ ├── services/ # 业务逻辑服务层
│ │ │ ├── adminService.js # 管理员业务服务
│ │ │ ├── bindingService.js # 绑定业务服务
│ │ │ ├── smsService.js # 短信服务（阿里云）
│ │ │ └── dbService.js # 数据库查询服务
│ │ ├── models/ # 数据模型层
│ │ │ └── model.js # 模型数据操作
│ │ ├── utils/ # 工具函数
│ │ │ ├── logger.js # Winston 日志配置
│ │ │ ├── dbPool.js # 数据库连接池
│ │ │ └── httpError.js # HTTP 错误处理
│ │ ├── config/ # 配置文件
│ │ │ └── database.js # 数据库连接配置
│ │ └── index.js # Express 应用入口
│ ├── database/
│ │ └── db.js # 数据库连接与查询封装
│ ├── scripts/
│ │ └── sync-model-library.js # 模型库自动同步脚本
│ ├── models/
│ │ ├── Model-library/ # 3D 模型文件存储目录
│ │ └── server.js # 独立模型服务器（测试用）
│ ├── logs/ # 日志文件目录
│ ├── hash_password.js # 密码哈希工具脚本
│ ├── package.json # 项目依赖配置
│ └── ecosystem.config.js # PM2 进程管理配置
│
├── 🔧 admin-frontend/ # Vue3 + Vite 管理后台
│ ├── src/
│ │ ├── views/ # 页面视图
│ │ │ ├── Login.vue # 管理员登录
│ │ │ ├── ModelManage.vue # 模型管理
│ │ │ ├── DesignDoc.vue # 设计文档
│ │ │ └── BindingChangeReview.vue # 绑定审核
│ │ ├── components/ # 管理组件
│ │ ├── router/ # Vue Router 路由
│ │ ├── services/ # API 服务层
│ │ ├── stores/ # 状态管理（可选）
│ │ ├── utils/ # 工具函数
│ │ ├── assets/ # 静态资源
│ │ ├── main.js # 应用入口
│ │ ├── App.vue # 根组件
│ │ └── style.css # 全局样式
│ ├── public/ # 公共静态文件
│ ├── dist/ # 构建输出目录
│ ├── vite.config.js # Vite 配置
│ └── index.html # HTML 入口
│
├── 📊 111.sql # 数据库结构文件
├── 🚀 deploy.bat # 自动部署脚本
└── 📖 README.md # 项目说明文档
🗄️ 数据库设计
usersuser_huxing_bindingsrefresh_tokensfavoritesadmin_logsbinding_change_requestsmodelsmodel_propertiesmodel_roomsmodel_viewpointsdistrictsstreetscommunitiesbuildings绑定拥有收藏记录申请被绑定属性房间视点被收藏包含包含包含关联包含包含关联包含关联关联
完整数据表结构（16 张表）
核心业务表
| 表名 | 用途 | 主要字段 | 说明 |
|---|
users | 用户信息 | id, phone, openid, name, avatar, role | 支持微信用户和管理员 |
models | 3D 模型信息 | id, name, file_path, area, description | 模型元数据和文件路径 |
districts | 区县信息 | id, name, type | 行政区划-区县级 |
streets | 街道信息 | id, district_id, name | 行政区划-街道级 |
communities | 小区信息 | id, district_id, street_id, name | 房地产项目-小区级 |
buildings | 楼栋信息 | id, community_id, name | 房地产项目-楼栋级 |
用户业务表
| 表名 | 用途 | 主要字段 | 说明 |
|---|
user_huxing_bindings | 用户户型绑定 | user_id, model_id, status | 用户与户型的绑定关系 |
binding_change_requests | 换绑申请 | user_id, old_huxing_id, new_huxing_id | 用户换绑申请审核 |
favorites | 用户收藏 | user_id, model_id | 用户收藏的户型模型 |
refresh_tokens | 刷新令牌 | user_id, token, expires_at | JWT 刷新令牌管理 |
模型扩展表
| 表名 | 用途 | 主要字段 | 说明 |
|---|
model_properties | 模型属性 | model_id, property_name, property_value | 模型的自定义属性 |
model_rooms | 模型房间信息 | model_id, name, area, position_x/y/z | 房间空间信息和位置 |
model_viewpoints | 模型视点 | model_id, name, position_x/y/z, target_x/y/z | 预设相机视点 |
系统管理表
| 表名 | 用途 | 主要字段 | 说明 |
|---|
admin_logs | 管理员日志 | admin_id, action_type, target_resource | 管理员操作审计日志 |
system_logs | 系统日志 | level, message, meta, timestamp | Winston 日志存储 |
sms_codes | 短信验证码 | phone, code, expires_at | 短信验证码临时存储 |
verification_codes | 通用验证码 | phone, code, purpose, is_used | 通用验证码管理 |
🔌 API 接口
认证接口
| 方法 | 路径 | 说明 | 参数 |
|---|
POST | /api/auth/sms/send | 发送短信验证码 | phone |
POST | /api/auth/register | 用户注册 | phone, code, password |
POST | /api/auth/login | 用户登录 | loginType, phone, password/code |
POST | /api/auth/wechat | 微信小程序登录 | code |
POST | /api/auth/refresh | 刷新 Token | refreshToken |
GET | /api/auth/profile | 获取用户信息 | – |
区域接口
| 方法 | 路径 | 说明 | 参数 |
|---|
GET | /api/districts | 获取所有区县 | – |
GET | /api/streets | 获取街道列表 | district |
GET | /api/communities | 获取小区列表 | district, street |
GET | /api/buildings | 获取楼栋列表 | communityId |
模型接口
| 方法 | 路径 | 说明 | 参数 |
|---|
GET | /api/model | 获取模型信息 | district, street, communityId, buildingId |
GET | /api/model/:id | 获取模型详情 | id |
GET | /api/model-file/:id | 获取模型文件流 | id |
GET | /api/huxing | 获取户型列表 | buildingId |
用户绑定接口
| 方法 | 路径 | 说明 | 参数 |
|---|
POST | /api/user/binding | 绑定户型 | modelId |
GET | /api/user/binding/status | 获取绑定状态 | – |
DELETE | /api/user/binding | 解绑户型 | – |
POST | /api/user/binding-change | 申请换绑 | newModelId |
🚀 快速开始
环境要求
- Node.js 14+
- MySQL 8.0+
- HBuilderX 最新版
- 微信开发者工具
1. 克隆项目
git clone https://gitee.com/your-repo/bim-miniprogram.git
cd bim-miniprogram
2. 配置数据库
# 导入数据库结构
mysql -u root -p < 111.sql
3. 后端环境配置
在 backend 目录下创建 .env 文件：
# 服务器配置
PORT=11409
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=model-library
# JWT 配置
JWT_SECRET_CURRENT=your_jwt_secret_key
REFRESH_TOKEN_SECRET=your_refresh_token_secret
JWT_EXPIRES_IN=1h
REFRESH_EXPIRES_IN=7d
# 微信小程序配置
WECHAT_APPID=your_wechat_miniprogram_appid
WECHAT_SECRET=your_wechat_miniprogram_secret
# 阿里云短信服务配置（可选）
ALI_SMS_ACCESS_KEY_ID=your_ali_access_key_id
ALI_SMS_ACCESS_KEY_SECRET=your_ali_access_key_secret
ALI_SMS_SIGN_NAME=your_sms_sign_name
ALI_SMS_TEMPLATE_CODE=your_sms_template_code
配置说明：
- 如果未配置阿里云短信服务，验证码将只在控制台输出（开发模式）
- 数据库名称必须为
model-library（与 SQL 文件对应） - JWT 密钥建议使用 32 位以上的随机字符串
4. 启动后端服务
cd backend
npm install
npm run dev # 开发模式
# 或
npm run start # 生产模式
可选：模型库同步
如果需要将文件系统的模型数据同步到数据库：
# 运行模型库同步脚本
node scripts/sync-model-library.js
可选：管理员账户设置
# 生成管理员密码哈希（默认密码 BIM1409）
node hash_password.js
# 将输出的哈希值手动插入数据库 users 表
5. 配置微信小程序
方式一：HBuilderX（推荐）
- 在 HBuilderX 中打开
frontend 目录 - 修改
src/manifest.json 中的微信小程序 AppID - 点击”运行” -> “运行到小程序模拟器” -> “微信开发者工具”
方式二：命令行
cd frontend
npm install
# uni-app 构建命令
npm run dev:mp-weixin # 开发环境
npm run build:mp-weixin # 生产环境
重要说明：
frontend 使用 uni-app 框架，支持 Vue3 + UTS- 支持双构建系统：Vite（主要）+ Webpack（兼容）
- 包含自定义 Pinia 持久化插件
- 支持 uni-app x 原生开发
6. 启动管理后台
cd admin-frontend
npm install
npm run dev
访问 http://localhost:5173 进入管理后台
管理后台特性：
- 纯 Vue3 + Vite SPA 应用
- Element Plus UI 组件库
- Vue Router 4 路由管理
- 开发服务器代理后端 API
🌐 部署说明
生产环境要求
- 服务器：Windows Server 2012R2+
- Web 服务器：IIS + PM2
- 域名：hk-ad.cn（已配置 NAT 映射）
- 数据库：MySQL 8.0
部署步骤
- 代码部署
# 使用自动部署脚本
deploy.bat
- PM2 进程管理
cd backend
pm2 start ecosystem.config.js
pm2 save
pm2 startup
- IIS 配置
- 配置反向代理到 Node.js 服务
- 启用 HTTPS 证书
- 配置静态文件服务
- 小程序发布
- 在 HBuilderX 中构建小程序
- 上传到微信开发者工具
- 提交审核并发布
监控与维护
- 日志文件：
backend/logs/ - PM2 监控：
pm2 monit - 健康检查：
GET /health
📈 性能优化
前端优化
微信小程序端
- 分包加载：3D 模型相关代码分包处理，减少主包大小
- 双构建支持：Vite + Webpack 双构建系统，确保兼容性
- 资源压缩：DRACO 几何体压缩，Terser 代码压缩
- 懒加载：按需加载模型文件，优化首屏时间
- UTS 优化：uni-app x 原生性能优化
- 自定义插件：Pinia 持久化插件，减少第三方依赖
管理后台端
- Vite 构建：快速的热重载和构建速度
- 代码分割：动态 import 实现路由级别的代码分割
- Tree Shaking：删除未使用的代码
- 静态资源优化：图片压缩和格式优化
后端优化
- 数据库连接池：mysql2 连接池，支持并发查询优化
- 模型文件服务：静态文件缓存，支持大文件流式传输
- 接口限流：express-rate-limit 防护，按 IP 和功能分级限流
- 多层日志系统：Winston 文件+数据库双写，分级记录
- 自动化脚本：模型库文件系统与数据库自动同步
- 安全中间件：Helmet 安全头，CORS 跨域配置
- 错误处理：统一错误处理中间件，结构化错误响应
- 文件上传：Multer 多媒体文件处理，支持头像上传
3D 渲染优化
- LOD 技术：多细节层次模型
- 视锥体裁剪：只渲染可见部分
- 材质合并：减少 DrawCall
- 纹理压缩：减少显存占用
🤝 开发规范
代码规范
- 前端：ESLint + Prettier
- 后端：统一错误处理和响应格式
- 数据库：统一命名规范和外键约束
Git 工作流
- 主分支：
master（生产环境） - 开发分支：
develop（测试环境） - 功能分支：
feature/xxx - 修复分支：
bugfix/xxx
部署流程
- 功能开发 →
feature 分支 - 合并到
develop → 测试环境验证 - 合并到
master → 生产环境部署
📄 许可证
本项目为私有项目，版权归华科智家所有。
