# 3D 家具安装展示系统 - 功能规划文档

> **创建时间**：2026-01-29  
> **文档状态**：进行中  
> **参考来源**：`方案设定/` 文件夹中的视频截图（31张）

---

## 一、项目背景理解

### 1.1 项目定位

这是一个面向**家具外贸企业**的 3D 产品展示和安装指导系统，核心目标是：

1. **快速报价**：给外贸客户提供完整的产品报价信息
2. **设计确认**：当客户反馈"板子设计错了"时，能快速展示和确认
3. **安装指导**：生成安装动画，让客户确认"安装对不对"
4. **包装方案**：自动计算包装尺寸和成本

### 1.2 核心使用场景（来自字幕）

| 字幕内容 | 对应场景 |
|---------|---------|
| "这是我给我外贸客户的一个报价" | 给客户发送产品报价 |
| "客户说我的板子设计错了" | 客户反馈设计问题 |
| "我的设计师已经改完了" | 设计师修改后快速更新 |
| "我可以随时截图给客户看整个的结构" | 展示产品结构 |
| "包括直接生成安装动画" | 生成安装动画 |
| "丢给客户看安装对不对" | 客户确认安装方案 |
| "包括这个包装方案，我也可以立刻马上出来" | 快速生成包装方案 |

---

## 二、功能需求梳理

### 2.1 产品信息展示

**目标**：展示完整的产品报价信息

**需要展示的字段**：
- 货号（如 AFZWG251129A）
- 品类（如 置物柜）
- 产品板材、产品颜色
- 产品尺寸（mm）
- 预估包装尺寸
- 预估包装总量（kg）、产品净重（kg）
- 建议零售价（CNY）、供货价（CNY）

**展示形式**：
- 3D 外观尺寸图（带尺寸标注）
- 爆炸图（展示内部结构）
- 五金透视图
- 包材说明图

---

### 2.2 3D 模型展示系统

**目标**：让客户直观了解产品结构

**核心功能**：
1. **快速渲染**："立刻马上渲染出了3D图"
2. **360度旋转查看**："然后这样360度再转一圈"
3. **板件编号标注**："每一块板都标了数字"
4. **爆炸图展示**："我可以随时截图给客户看整个的结构"
5. **设计更新后快速刷新**："我的设计师已经改完了"

**与现有项目对应**：
- 已有 `@react-three/fiber` + `@react-three/drei` 3D 渲染能力
- 已有 `Panel` 模型存储板件信息
- 需要增强：板件编号渲染、爆炸图视图切换

---

### 2.3 安装动画系统（重点功能）

**目标**：生成安装动画，让客户确认安装是否正确

**核心功能**：
1. **自动生成安装动画**："包括直接生成安装动画"
2. **动画播放控制**："这个安装动画生成完了之后"
3. **动画下载**："我可以直接下载下来"、"就会提示我下载看到了吧"
   - 格式：MP4
   - 分辨率：720×1080 (9:16 竖屏)
   - 文件大小：约 1.90MB
4. **分享给客户**："丢给客户看安装对不对"、"让客户看安装图纸了"

**底部操作按钮**（参考截图）：
- 退出安装
- 生成图纸
- 预览孔位
- 播放控制

**与现有项目对应**：
- 已有 `AssemblyStep` 模型存储装配步骤
- 已有 `animation-engine.ts` 动画引擎
- 已有 `AssemblyPlayer.tsx` 播放器组件
- 需要新增：**动画录制和导出为视频功能**

---

### 2.4 BOM 清单系统

**目标**：展示完整的物料清单

**清单内容**：

#### 2.4.1 板材清单
| 材质 | 颜色 | 厚度(mm) | 平方(m²) |
|------|------|----------|----------|
| E0刨花板 | 绿色 | 16 | 1.52 |

#### 2.4.2 小板信息
| 材质 | 颜色 | 名称 | 规格(mm) | 面积(m²) | 重量(kg) |
|------|------|------|----------|----------|----------|
| E0刨花板 | 绿色 | 底板 | 668×411×16 | 0.27 | 2.95 |
| E0刨花板 | 绿色 | 左侧板 | 636×450×16 | 0.29 | 3.08 |
| ... | ... | ... | ... | ... | ... |

#### 2.4.3 五金配件清单
| 名称 | 规格 | 五金件包编号 | 数量/包 |
|------|------|-------------|---------|
| 木棒 | Φ6*40 | LJJM50003016 | 28 |
| 滑轨/双镜座 | Φ3*12 | LS40LJ003018 | 16 |
| ... | ... | ... | ... |

#### 2.4.4 封边清单
| 颜色 | 宽度(mm) | 厚度(mm) | 长度(m) |
|------|----------|----------|---------|
| 绿色 | 18 | 1 | 15.804 |

**与现有项目对应**：
- 已有 `Panel` 模型（板件）
- 需要新增：五金配件模型、封边数据、BOM清单页面

---

### 2.5 包装方案系统

**目标**：自动计算包装方案和成本

**核心功能**：
1. **板件排版**："他就开始进行排版"
2. **箱体尺寸计算**："这样整体就出来了我们箱体的大小"
3. **成本计算**：
   - 纸箱成本价：4.45元
   - 纸箱面积：0.83 m²
   - 箱体尺寸：668×450×101mm
4. **分层展示**：第3层、第6层等，显示厚度

**与现有项目对应**：
- 已有 `PackagingPlan` 模型
- 已有 `boxes` JSON 字段存储箱子详情
- 需要新增：**板件排版算法**、**成本计算功能**、**可视化展示**

---

### 2.6 产品列表管理

**目标**：管理所有产品，提供快捷操作

**列表字段**：
- 规格/包装尺寸
- 颜色
- 材质
- 设计者
- 设计日期
- 创建/更新/编辑时间
- 自动生成状态

**操作按钮**：
| 按钮 | 功能 |
|------|------|
| 编辑 | 编辑产品信息 |
| 设计完成 | 标记设计完成状态 |
| 预览 | 预览3D模型 |
| 包装箱 | 查看包装方案 |
| 生成分享链接 | 生成可分享的链接 |
| 导出XML | 导出产品数据 |
| JdDXML | 导出特定格式 |
| 包装方案 | 查看/编辑包装方案 |
| 安装方案 | 查看/编辑安装方案 |

**与现有项目对应**：
- 已有产品列表页面 `/products`
- 已有 `ShareLink` 分享功能
- 需要新增：导出XML、状态管理、更多操作按钮

---

### 2.7 分享与导出

**目标**：方便与客户沟通

**功能**：
1. 生成分享链接
2. 导出 XML 数据
3. 下载安装动画（MP4）
4. 截图分享

**与现有项目对应**：
- 已有 `ShareLink` 模型和功能
- 需要新增：XML导出、视频下载

---

## 三、技术实现说明

### 3.1 现有技术栈

| 技术 | 用途 |
|------|------|
| Next.js 16 + React 19 | 前端框架 |
| Three.js + @react-three/fiber | 3D 渲染 |
| GSAP | 动画引擎 |
| Prisma + PostgreSQL | 数据库 |
| Tailwind CSS | 样式（使用项目自己的设计系统） |

### 3.2 关键技术挑战

1. **视频录制与导出**
   - 需要将 Three.js canvas 录制为视频
   - 可选方案：MediaRecorder API、CCapture.js、ffmpeg.wasm

2. **板件排版算法**
   - 二维装箱问题（2D Bin Packing）
   - 需要考虑板件尺寸、厚度、重量限制

3. **爆炸图实现**
   - 计算各板件的爆炸位置
   - 平滑动画过渡

---

## 四、优先级规划

### P0 - 核心功能（优先实现）

1. **3D 模型展示增强**
   - [ ] 板件编号渲染
   - [ ] 爆炸图视图
   - [ ] 360度旋转控制优化

2. **安装动画增强**
   - [ ] 动画播放控制完善
   - [ ] 动画录制为视频
   - [ ] 视频下载功能

3. **BOM 清单页面**
   - [ ] 板材清单展示
   - [ ] 小板信息展示
   - [ ] 五金配件清单

### P1 - 重要功能

4. **包装方案系统**
   - [ ] 板件排版可视化
   - [ ] 箱体尺寸计算
   - [ ] 成本计算

5. **产品信息展示**
   - [ ] 报价信息展示页面
   - [ ] 多视图切换（外观图、爆炸图、五金透视图）

### P2 - 扩展功能

6. **导出功能**
   - [ ] XML 导出
   - [ ] 图纸生成
   - [ ] 孔位预览

7. **产品列表增强**
   - [ ] 更多操作按钮
   - [ ] 状态管理
   - [ ] 批量操作

---

## 五、UI/视觉说明

> **重要提示**：功能参考方案设定的截图，但 **UI 和视觉效果使用项目自己的设计系统**

### 5.1 现有设计系统

项目已有完整的设计系统，位于 `src/lib/design-tokens/`：
- `colors.ts` - 颜色系统
- `spacing.ts` - 间距系统
- `typography.ts` - 排版系统
- `animations.ts` - 动画系统

### 5.2 现有组件

项目已有的 UI 组件可直接复用：
- `src/components/auth/` - 认证相关
- `src/components/common/` - 通用组件（LazyImage、LazyLoadWrapper）
- `src/components/assembly/` - 装配相关（AssemblyPlayer、AssemblyStepEditor）
- `src/components/packaging/` - 包装相关（PackagingEditor）
- `src/components/panels/` - 板件相关（PanelEditor）

---

## 六、数据模型对照

### 6.1 已有模型（可直接使用）

| 模型 | 对应功能 |
|------|---------|
| Product | 产品信息 |
| ProductSKU | SKU 规格 |
| Panel | 板件信息 |
| AssemblyStep | 装配步骤 |
| PackagingPlan | 包装方案 |
| ShareLink | 分享链接 |

### 6.2 需要新增/扩展的模型

| 模型 | 用途 |
|------|------|
| Hardware | 五金配件（螺丝、滑轨等） |
| EdgeBanding | 封边条信息 |
| 扩展 Panel | 增加颜色、材质字段 |
| 扩展 Product | 增加报价相关字段 |

---

## 七、下一步行动

1. **确认优先级**：与用户确认先做哪些功能
2. **技术调研**：视频录制方案选型
3. **数据模型设计**：确定需要新增的数据库字段
4. **原型开发**：从 P0 功能开始逐步实现

---

## 八、参考资料

- 方案设定截图：`方案设定/` 目录（1.jpg - 31.jpg）
- 项目文档：`furniture-3d-system/docs/`
- 设计系统：`furniture-3d-system/src/lib/design-tokens/`
- 规划文档：`.kiro/specs/`

---

**文档版本**：v1.0  
**最后更新**：2026-01-29