ZIMA 3D 实景资产平台

项目简介

企业级 3D 房地产资产预览与管理系统，涵盖前端渲染引擎、后台管理、CDN 部署等完整技术栈。

项目周期：2025.10 - 2026.01（3 个月） 项目规模：100+ commits 项目角色：全栈开发工程师

技术栈

前端技术

• 框架：Next.js 15（App Router）、React 18、TypeScript
• 3D 渲染：Three.js、@react-three/fiber、@react-three/drei、@pixiv/three-vrm
• 状态管理：Jotai（原子化状态管理）
• UI 库：Radix UI、shadcn/ui、Tailwind CSS 4
• 动画：Framer Motion、WebGL Shader

后端技术

• 框架：Next.js API Routes、Server Actions
• 数据库：MySQL + Prisma ORM
• 认证：JWT（jose）+ bcryptjs
• AI 集成：Vercel AI SDK、DeepSeek/OpenAI API、TTS 语音合成

基础设施

• 部署：Docker、PM2、Vercel
• CDN：Cloudflare R2、Aliyun OSS
• 大文件处理：HTTP Range 请求、分片上传（10GB 级别）

核心功能模块

1. 双渲染引擎系统

• LCC 场景渲染：基于 iframe 架构的真实 3D 场景查看器（.lcc 格式，170-400MB）
• 全景图查看器：支持立方体贴图和等距柱状投影两种全景模式
• VRM 角色系统：支持 3D 角色模型加载、动画播放、自动漫游

2. 3D 交互与控制

• 跨平台控制：键盘+鼠标（桌面端）、虚拟摇杆（移动端）
• 动态渲染质量：4 档预设（25%/50%/75%/100%）+ 自适应降级
• 相机系统：可配置初始位置/目标/FOV、碰撞检测、平滑缩放

3. 资产管理后台

• 场景管理：楼盘/楼层/场景三级结构，支持标记点管理
• 文件上传：支持 10GB 大文件、断点续传、实时进度
• 坐标拾取：可视化全景坐标选择器、标记图标配置

4. AI 增强功能

• 智能对话：集成 DeepSeek/OpenAI 流式响应
• 语音合成：TTS 文字转语音 + VRM 角色唇形同步
• 智能加载：基于相机朝向的立方体贴图按需加载优化

技术亮点

1. iframe 与 React 的通信架构设计

背景：LCC SDK 为 770KB 的 ES Module 格式，需特殊 importmap 配置 Three.js 依赖

解决方案：

• 采用 iframe 隔离架构，LCC 渲染在 viewer-enhanced.html 中运行
• 通过 postMessage API 实现双向通信（加载进度、场景切换、质量控制）
• 设计消息类型系统：lcc-progress、loadLCC、setQuality 等

成果：实现了渲染引擎的完全隔离，避免了 React 组件生命周期对 3D 场景的干扰

2. 移动端性能优化策略

挑战：移动设备渲染 400MB 3D 场景时帧率低于 15fps

优化措施：

• 纹理尺寸自适应：桌面端 4096px，移动端降至 2048px
• 动态质量调节：移动端默认 50% 渲染分辨率，移动时自动降至 25%
• 虚拟摇杆优化：使用 translate3d GPU 加速

成果：移动端帧率从 12fps 提升至稳定 30fps，首屏加载时间从 8s 降至 2s

3. 智能立方体贴图加载算法

背景：全景立方体贴图需加载 6 个面，传统方案同时加载导致初始化慢

创新方案：根据相机初始朝向计算优先级队列，先加载可见面（前面+左右），后加载背面+上下

成果：用户感知加载时间从 6s 降至 2s

4. 大文件上传的 Range 请求支持

需求：LCC 文件达 10GB，普通上传易超时失败

实现细节：

• Next.js API Route 支持 HTTP Range 请求头解析
• 客户端分片上传（每片 100MB）+ 服务端流式写入
• 断点续传：通过 Range 头指定续传位置

成果：10GB 文件上传成功率从 40% 提升至 99%

性能指标

指标	优化前	优化后	提升
桌面端首屏加载	6.2s	2.1s	66%
移动端首屏加载	8.5s	2.8s	67%
移动端渲染帧率	12fps	30fps	150%
大文件上传成功率	40%	99%	59%
碰撞检测 CPU 占用	25%	3%	88%

项目成果

1. 功能交付：完成双渲染引擎、后台管理、AI 对话等 8 大模块，100% 覆盖需求
2. 性能达标：移动端帧率 30fps+，PC 端 60fps 稳定，大文件上传成功率 99%
3. 工程化实践：Docker 容器化部署，CDN 资产管理脚本，Prisma Schema + TypeScript 类型安全