75db836d29
- 文件上传验证: ModelUploader组件增强、上传API错误处理 - GLTF解析器: 增强节点提取和元数据 - 板材编辑: PanelEditor客户端验证 + panels API服务端验证 - 装配步骤编辑: 修复未使用代码，添加预览按钮 - 装配动画播放: AssemblyPlayer步骤导航边界检查优化 - 分享链接: 完整CRUD API（创建、获取、删除），含验证和过期检查 跳过可选测试任务以加快MVP开发
16 KiB
16 KiB
产品安装展示系统 - MVP 开发规划
项目定位
核心价值：为家具制造商提供一个产品安装展示系统，让客户通过交互式 3D 动画一步步学习产品安装过程。
MVP 目标：优先实现产品安装展示功能，其他功能模块化设计，便于后续扩展。
一、核心功能优先级
🔴 P0 - 核心功能（必须实现）
1. 产品 3D 展示
- glTF 模型加载和渲染
- 模型旋转、缩放、平移
- 部件高亮和标注
- 爆炸图视图
2. 交互式装配动画
- 分步装配动画播放
- 客户可控制播放进度（上一步/下一步）
- 步骤说明文字
- 进度指示器
3. 客户预览页面
- 公开访问（无需登录）
- 分享链接生成
- 移动端适配
- 简洁的操作界面
🟡 P1 - 重要功能（第二阶段）
4. 产品管理
- 产品列表
- 产品上传（glTF 文件）
- 产品基本信息编辑
- 装配步骤编辑器
5. BOM 清单展示
- 板件清单
- 五金件清单
- 数据展示和导出
🟢 P2 - 增强功能（第三阶段）
6. 供应商报价系统
- 供应商管理
- 报价功能
- 成本管理
7. 高级功能
- 视频录制
- PDF 导出
- 包装方案
二、技术架构设计
2.1 整体架构（模块化设计）
furniture-3d-system/
├── app/ # Next.js App Router
│ ├── (public)/ # 公开访问路由组
│ │ ├── share/[token]/ # 客户预览页面 ⭐ P0
│ │ └── preview/[id]/ # 产品预览页面
│ ├── (dashboard)/ # 内部管理路由组
│ │ ├── products/ # 产品管理 ⭐ P1
│ │ ├── assembly/ # 装配编辑器 ⭐ P1
│ │ ├── suppliers/ # 供应商管理 🔵 P2
│ │ └── settings/ # 系统设置
│ ├── api/ # API 路由
│ │ ├── products/ # 产品 API
│ │ ├── assembly/ # 装配 API
│ │ ├── share/ # 分享 API
│ │ └── upload/ # 文件上传 API
│ └── layout.tsx # 根布局
│
├── components/ # 组件库（模块化）
│ ├── 3d/ # 3D 相关组件 ⭐ P0
│ │ ├── ModelViewer/ # 3D 模型查看器
│ │ ├── AssemblyPlayer/ # 装配动画播放器
│ │ ├── PartHighlight/ # 部件高亮
│ │ └── ExplodedView/ # 爆炸图
│ ├── assembly/ # 装配相关组件 ⭐ P0
│ │ ├── StepList/ # 步骤列表
│ │ ├── StepControls/ # 播放控制
│ │ └── ProgressIndicator/ # 进度指示器
│ ├── product/ # 产品相关组件 ⭐ P1
│ │ ├── ProductCard/ # 产品卡片
│ │ ├── ProductForm/ # 产品表单
│ │ └── BOMTable/ # BOM 表格
│ ├── ui/ # 基础 UI 组件
│ │ ├── Button/
│ │ ├── Card/
│ │ ├── Input/
│ │ └── Modal/
│ └── layout/ # 布局组件
│ ├── Header/
│ ├── Sidebar/
│ └── Container/
│
├── lib/ # 工具库（模块化）
│ ├── 3d/ # 3D 相关工具 ⭐ P0
│ │ ├── gltf-loader.ts # glTF 加载器
│ │ ├── animation-engine.ts # 动画引擎
│ │ └── camera-controller.ts # 相机控制
│ ├── api/ # API 客户端
│ │ ├── products.ts
│ │ ├── assembly.ts
│ │ └── share.ts
│ ├── hooks/ # 自定义 Hooks
│ │ ├── use3DViewer.ts
│ │ ├── useAssembly.ts
│ │ └── useProduct.ts
│ ├── utils/ # 工具函数
│ │ ├── format.ts
│ │ ├── validation.ts
│ │ └── storage.ts
│ └── prisma.ts # Prisma 客户端
│
├── prisma/ # 数据库
│ └── schema.prisma # 数据模型
│
├── public/ # 静态资源
│ ├── models/ # 示例模型
│ └── images/
│
└── types/ # TypeScript 类型
├── product.ts
├── assembly.ts
└── api.ts
2.2 核心模块设计
模块 1：3D 渲染引擎（独立模块）⭐ P0
// lib/3d/engine.ts
export class ThreeDEngine {
private scene: THREE.Scene
private camera: THREE.Camera
private renderer: THREE.WebGLRenderer
private controls: OrbitControls
constructor(container: HTMLElement) {
// 初始化 Three.js
}
loadModel(url: string): Promise<THREE.Group> {
// 加载 glTF 模型
}
highlightPart(partId: string): void {
// 高亮部件
}
playAnimation(steps: AssemblyStep[]): void {
// 播放装配动画
}
}
模块 2：装配动画系统（独立模块）⭐ P0
// lib/assembly/player.ts
export class AssemblyPlayer {
private currentStep: number = 0
private steps: AssemblyStep[]
private engine: ThreeDEngine
constructor(steps: AssemblyStep[], engine: ThreeDEngine) {
this.steps = steps
this.engine = engine
}
play(): void {
// 播放当前步骤
}
next(): void {
// 下一步
}
previous(): void {
// 上一步
}
goToStep(index: number): void {
// 跳转到指定步骤
}
}
模块 3：产品管理系统（独立模块）⭐ P1
// lib/product/manager.ts
export class ProductManager {
async createProduct(data: ProductInput): Promise<Product> {
// 创建产品
}
async uploadModel(file: File): Promise<string> {
// 上传模型文件
}
async parseGLTF(url: string): Promise<BOMData> {
// 解析 glTF 生成 BOM
}
}
三、数据模型设计（最小化）
3.1 核心数据模型
// prisma/schema.prisma
// 产品
model Product {
id String @id @default(cuid())
name String
sku String @unique
category String
modelUrl String // glTF 模型 URL
thumbnailUrl String? // 缩略图
// 关联
assemblySteps AssemblyStep[]
panels Panel[]
shareLinks ShareLink[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
// 装配步骤 ⭐ 核心
model AssemblyStep {
id String @id @default(cuid())
productId String
product Product @relation(fields: [productId], references: [id], onDelete: Cascade)
order Int // 步骤顺序
title String // 步骤标题
description String? // 步骤说明
// 动画数据（JSON）
partIds String[] // 参与的部件 ID
transform Json // 目标变换 {position, rotation, scale}
duration Int // 动画时长(ms)
easing String // 缓动函数
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([productId, order])
}
// 板件（简化版）
model Panel {
id String @id @default(cuid())
productId String
product Product @relation(fields: [productId], references: [id], onDelete: Cascade)
code String // 编号
name String // 名称
gltfNodeName String // glTF 节点名
// 尺寸
length Float
width Float
thickness Float
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([productId])
}
// 分享链接 ⭐ 核心
model ShareLink {
id String @id @default(cuid())
productId String
product Product @relation(fields: [productId], references: [id], onDelete: Cascade)
token String @unique // 分享令牌
expiresAt DateTime? // 过期时间（可选）
viewCount Int @default(0) // 查看次数
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([token])
}
// 用户（简化版，后续扩展）
model User {
id String @id @default(cuid())
email String @unique
name String
password String
role String @default("user") // user, admin
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
3.2 扩展模块数据模型（P2 阶段）
// 供应商（P2）
model Supplier {
id String @id @default(cuid())
name String
code String @unique
contact String
phone String
email String
quotes MaterialQuote[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
// 材料报价（P2）
model MaterialQuote {
id String @id @default(cuid())
productId String
supplierId String
supplier Supplier @relation(fields: [supplierId], references: [id])
materialType String // panel, hardware, edgeband
materialId String
unitPrice Float
moq Int // 最小起订量
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
四、开发路线图
阶段 0：环境搭建（1-2天）
目标：搭建开发环境，创建项目骨架
任务：
- Docker 环境配置
- 创建 Next.js 项目
- 配置 Tailwind CSS
- 配置 Prisma
- 创建基础目录结构
- 配置 TypeScript
- 设置 ESLint 和 Prettier
输出：
- 可运行的 Next.js 项目
- 数据库连接正常
- 基础配置完成
阶段 1：3D 渲染核心（3-5天）⭐ P0
目标：实现 3D 模型加载和基础交互
任务：
- 集成 Three.js 和 @react-three/fiber
- 创建 ModelViewer 组件
- 实现 glTF 模型加载
- 实现相机控制（旋转、缩放、平移）
- 实现部件高亮功能
- 实现爆炸图视图
- 添加加载状态和错误处理
输出：
- 可以加载和展示 glTF 模型
- 支持基础交互操作
- 部件可以高亮显示
测试：
- 使用示例 glTF 文件测试
- 测试不同尺寸的模型
- 测试移动端适配
阶段 2：装配动画系统（5-7天）⭐ P0
目标：实现交互式装配动画播放
任务：
- 创建 AssemblyPlayer 组件
- 实现动画引擎（GSAP 或 Tween.js）
- 实现步骤控制（上一步/下一步）
- 创建 StepList 组件（步骤列表）
- 创建 ProgressIndicator 组件（进度指示器）
- 实现步骤说明文字展示
- 添加动画播放状态管理
- 实现自动播放和手动控制切换
输出：
- 完整的装配动画播放器
- 用户可以控制播放进度
- 清晰的步骤说明
测试：
- 测试多步骤动画
- 测试动画流畅度
- 测试移动端操作
阶段 3：客户预览页面（2-3天）⭐ P0
目标：实现公开访问的客户预览页面
任务：
- 创建
/share/[token]路由 - 实现分享链接生成 API
- 设计极简的预览界面
- 集成 3D 渲染和装配动画
- 实现移动端适配
- 添加分享功能（复制链接）
- 添加查看统计
输出：
- 客户可以通过链接访问
- 无需登录即可查看
- 移动端体验良好
测试：
- 测试分享链接生效
- 测试不同设备访问
- 测试链接过期机制
🎯 MVP 里程碑（10-15天）
完成标准：
- ✅ 客户可以通过分享链接查看产品
- ✅ 3D 模型可以旋转、缩放
- ✅ 装配动画可以一步步播放
- ✅ 移动端体验良好
- ✅ 界面简洁美观
演示场景：
- 商家上传一个家具产品的 glTF 模型
- 商家定义装配步骤
- 商家生成分享链接
- 客户打开链接，看到 3D 模型
- 客户点击"开始安装"
- 动画播放第一步，显示说明文字
- 客户点击"下一步"，继续播放
- 客户可以随时旋转模型查看细节
阶段 4：产品管理系统（5-7天）⭐ P1
目标：实现产品的创建、编辑、管理
任务：
- 创建产品列表页面
- 创建产品详情页面
- 实现文件上传功能（glTF）
- 实现产品信息编辑
- 创建装配步骤编辑器
- 实现 BOM 清单展示
- 添加用户认证
输出：
- 商家可以管理产品
- 可以上传和编辑模型
- 可以定义装配步骤
阶段 5：BOM 清单系统（3-5天）⭐ P1
目标：自动解析 glTF 生成 BOM 清单
任务：
- 实现 glTF 解析逻辑
- 自动提取板件信息
- 创建 BOM 表格组件
- 实现数据编辑功能
- 实现 Excel 导出
输出：
- 自动生成 BOM 清单
- 可以手动编辑
- 可以导出 Excel
阶段 6：供应商报价系统（7-10天）🔵 P2
目标：实现供应商管理和报价功能
任务：
- 供应商管理 CRUD
- 报价邀请链接生成
- 供应商报价页面
- 报价对比功能
- 成本计算
输出：
- 完整的供应商报价流程
- 成本管理功能
五、技术选型确认
5.1 核心技术栈
{
"framework": "Next.js 14 (App Router)",
"language": "TypeScript 5.5+",
"styling": "Tailwind CSS 3.4",
"3d": {
"core": "Three.js",
"react": "@react-three/fiber",
"helpers": "@react-three/drei"
},
"animation": "GSAP",
"database": "PostgreSQL 15+",
"orm": "Prisma 5.22",
"storage": "MinIO",
"state": "Zustand",
"forms": "React Hook Form + Zod"
}
5.2 开发工具
{
"ide": "VS Code",
"extensions": [
"Prisma",
"Tailwind CSS IntelliSense",
"ESLint",
"Prettier"
],
"ai": "GitHub Copilot / Cursor"
}
六、模块化设计原则
6.1 独立性原则
每个模块应该：
- ✅ 有清晰的职责边界
- ✅ 最小化依赖
- ✅ 可以独立测试
- ✅ 可以独立部署（如果需要）
6.2 扩展性原则
新功能添加时：
- ✅ 不影响现有模块
- ✅ 通过接口集成
- ✅ 配置化而非硬编码
6.3 示例：添加新功能
场景：后续要添加"视频录制"功能
// 1. 创建新模块
// lib/video/recorder.ts
export class VideoRecorder {
constructor(private engine: ThreeDEngine) {}
startRecording(): void {
// 开始录制
}
stopRecording(): Promise<Blob> {
// 停止录制并返回视频
}
}
// 2. 在现有组件中集成
// components/assembly/AssemblyPlayer.tsx
import { VideoRecorder } from '@/lib/video/recorder'
export function AssemblyPlayer() {
const recorder = new VideoRecorder(engine)
const handleRecord = () => {
recorder.startRecording()
}
return (
<div>
{/* 现有功能 */}
<button onClick={handleRecord}>录制视频</button>
</div>
)
}
七、质量保证
7.1 代码质量
- TypeScript 严格模式
- ESLint 规则
- Prettier 格式化
- 代码审查
7.2 性能优化
- 3D 模型压缩（Draco）
- 图片优化（Next.js Image）
- 代码分割
- 懒加载
7.3 用户体验
- 加载状态
- 错误处理
- 移动端适配
- 无障碍访问
八、下一步行动
立即执行（今天）
-
设置 Docker 自动清理
.\scripts\setup-auto-cleanup.ps1 -
创建项目
npx create-next-app@latest furniture-3d-system --typescript --tailwind --app cd furniture-3d-system -
安装核心依赖
npm install @prisma/client prisma three @react-three/fiber @react-three/drei gsap zustand npm install -D @types/three -
初始化 Prisma
npx prisma init
本周目标
- ✅ 完成环境搭建
- ✅ 完成阶段 1（3D 渲染核心）
- ✅ 开始阶段 2（装配动画系统）
两周目标
- ✅ 完成 MVP（阶段 1-3）
- ✅ 可以演示完整的客户预览流程
九、成功标准
MVP 成功标准
技术指标：
- 3D 模型加载时间 < 3秒
- 动画播放流畅（60fps）
- 移动端响应速度 < 1秒
- 页面加载时间 < 2秒
用户体验：
- 客户无需培训即可使用
- 操作直观，无需说明
- 移动端体验良好
- 界面简洁美观
业务价值：
- 减少客户安装咨询
- 提升客户满意度
- 降低售后成本
- 提升品牌形象
准备好开始了吗？我可以立即帮你创建项目！ 🚀