furniture-3d-system-Wu/docs

3D 家具安装展示系统 - 文档中心

📚 文档导航

核心文档

• 实施计划 - 完整的开发计划和时间表
• 权限系统设计 - 组织架构和权限设计
• 认证系统设计 - 用户注册和登录设计
• 上传功能文档 - 产品上传 API 使用指南

已完成功能

• 上传功能完成报告 - 产品上传功能实现总结

---

🎯 项目概述

项目定位

一个面向家具制造企业的私有部署产品管理和 3D 展示系统

核心价值

1. 简化产品管理：统一管理产品型号、SKU、3D 模型
2. 提升客户体验：通过 3D 可视化和装配动画帮助客户理解产品
3. 降低沟通成本：分享链接代替传统的纸质说明书
4. 数据安全保障：完善的权限控制和离职交接机制

---

🏗️ 技术架构

技术栈

• 前端：Next.js 16 + React 19 + TypeScript
• 3D 渲染：Three.js + React Three Fiber
• 动画：GSAP
• 样式：Tailwind CSS + Apple HIG 2025 设计系统
• 后端：Next.js API Routes
• 数据库：PostgreSQL + Prisma ORM
• 存储：MinIO (S3 兼容)
• 认证：JWT Token

部署模式

• 私有部署：每个企业独立部署到自己的服务器
• 企业隔离：企业之间数据完全独立
• 一键部署：Docker Compose 一键启动

---

👥 组织架构

角色层级

超级管理员 (SUPER_ADMIN)
    ↓
管理员 (ADMIN)
    ↓
部门管理员 (DEPARTMENT_MANAGER)
    ↓
组长 (TEAM_LEADER)
    ↓
设计师 (DESIGNER)
    ↓
查看者 (VIEWER)

组织结构

公司
├── 部门
│   ├── 小组
│   │   ├── 成员
│   │   └── 成员
│   └── 小组
└── 部门

---

📦 核心功能

1. 用户认证

• ✅ 邮箱 + 姓名/花名注册
• ✅ 支持邮箱或姓名登录
• ✅ 超级管理员首次登录强制修改信息
• ✅ 密码强度验证
• ✅ JWT Token 认证

2. 权限管理

• 6 种角色，职责明确
• 部门和小组两级管理
• 细粒度权限控制
• 权限检查中间件

3. 产品管理

• Product-SKU 结构
• 产品协作者（多人协作）
• SKU 负责人（单人负责）
• 产品可见性控制

4. 离职交接

• 自动检测离职
• SKU 批量交接
• 交接历史记录
• 通知相关人员

5. 问题反馈

• 查看者可提交反馈
• 自动分配给负责人
• 反馈处理流程
• 优先级管理

6. 3D 展示

• 交互式 3D 模型查看
• 装配动画演示
• 分享链接生成
• 客户无需注册即可查看

---

🚀 快速开始

环境要求

• Node.js 18+
• PostgreSQL 14+
• MinIO (或 S3 兼容存储)
• 8GB+ 内存（推荐）

安装步骤

1. 克隆项目

   git clone <repository-url>
   cd furniture-3d-system
   

2. 安装依赖

   npm install
   

3. 配置环境变量

   cp .env.example .env
   # 编辑 .env 文件，配置数据库和 MinIO
   

4. 初始化数据库

   npm run prisma:push
   

5. 启动开发服务器

   npm run dev
   

6. 首次登录

   • 访问 http://localhost:3000
   • 使用默认账号登录：
     • 邮箱：admin@company.com
     • 姓名：admin
     • 密码：Admin@123456
   • 首次登录后强制修改信息

---

📅 开发进度

已完成 ✅

• 项目架构设计
• Apple 风格 UI 设计系统
• 主题系统（深色/浅色）
• 产品上传功能（UI + API）
• 分享页面（3D 查看器）
• 权限系统设计
• 认证系统设计

进行中 🚧

• 数据库模型重构
• 认证系统实现
• 权限系统实现

待开始 📋

• 组织架构实现
• 产品归属实现
• 离职交接实现
• 问题反馈实现
• 数据安全与日志

---

📖 开发指南

目录结构

furniture-3d-system/
├── src/
│   ├── app/                # Next.js App Router
│   │   ├── api/           # API 路由
│   │   ├── (public)/      # 公开页面（分享页面）
│   │   └── ...
│   ├── components/         # React 组件
│   │   ├── 3d/            # 3D 相关组件
│   │   ├── products/      # 产品相关组件
│   │   └── ui/            # UI 组件
│   ├── lib/               # 工具库
│   │   ├── prisma.ts      # Prisma 客户端
│   │   ├── storage.ts     # 文件存储
│   │   └── auth.ts        # 认证工具
│   └── types/             # TypeScript 类型
├── prisma/                # 数据库模式
│   └── schema.prisma
├── docs/                  # 文档
│   ├── architecture/      # 架构设计
│   └── ...
└── public/                # 静态资源

开发命令

npm run dev              # 开发服务器
npm run build            # 生产构建
npm run type-check       # 类型检查
npm run prisma:studio    # 数据库管理
npm run prisma:push      # 推送数据库变更

代码规范

• 使用 TypeScript 严格模式
• 遵循 ESLint 规则
• 使用 Prettier 格式化
• 组件使用 PascalCase
• 函数使用 camelCase
• 文件名使用 kebab-case

---

🎨 设计系统

Apple HIG 2025 风格

• 毛玻璃效果：backdrop-filter: blur(20px)
• 大圆角：20px border-radius
• 流畅动画：cubic-bezier 缓动
• 多层阴影：立体感
• CSS 变量主题：支持深色/浅色模式

颜色系统

--color-blue: #007AFF
--color-green: #34C759
--color-orange: #FF9500
--color-red: #FF3B30
--color-purple: #AF52DE

---

🔒 安全性

认证安全

• 密码加密存储（bcrypt）
• JWT Token 认证
• Token 过期机制
• 首次登录强制修改

权限安全

• 细粒度权限控制
• API 路由保护
• 前端权限控制
• 操作日志记录

数据安全

• 软删除机制
• 数据备份
• 离职交接
• 审计报表

---

📞 支持

文档

• 实施计划
• 权限系统设计
• 认证系统设计

问题反馈

如果遇到问题，请：

1. 查看相关文档
2. 查看代码注释
3. 查看操作日志
4. 提交 Issue

---

📄 许可证

[待定]

---

让我们开始构建这个系统吧！ 🚀