WuYongJie/furniture-3d-system-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
furniture-3d-system-Wu/README.md

6.4 KiB
Raw Blame History

3D 家具安装展示系统

现代化的 3D 家具装配展示与管理系统，支持交互式装配动画、版本回溯与分享协作

项目状态：生产基础能力已具备，当前进入结构化数据与装配体验持续收口阶段
最后更新：2026-03-13

🏗️ 企业级架构与统一视觉标准（强制）

企业级架构（后端）

本项目后端统一遵循：API Route -> Service -> Repository -> Database

  • API Route：只做参数接收、鉴权入口、调用 Service、统一返回
  • Service：负责权限校验、业务规则、缓存策略、DTO 组装、事务编排
  • Repository：只负责数据访问，不承载业务逻辑分支
  • 错误与响应：统一 AppError + ErrorCode、handleRequest/jsonSuccess/jsonError
  • 架构治理：优先做系统性收口，不做临时补丁式修补

统一视觉标准（前端）

  • UI 必须优先复用 src/components/ui/ 元组件（Button/Input/Modal/Select/Toast 等）
  • 保持苹果风格视觉体系，遵循设计令牌，不随意改全局样式
  • 品牌色固定：#008D74（浅色）/ #00B896（深色）
  • 排版统一：font-apple-system + tracking-apple-*

规则文件（必须阅读）

  • .cursor/rules/core-standards.mdc
  • .cursor/rules/backend.mdc
  • .cursor/rules/frontend.mdc
  • .cursor/rules/checklist.mdc
  • docs/设计规范/苹果风格视觉标准.md

🚀 快速开始

环境要求

  • Node.js 18+
  • PostgreSQL 14+
  • Redis（可选，推荐）
  • MinIO / S3 兼容对象存储（必需）

安装步骤

# 1. 安装依赖
npm install

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库与 MinIO/S3

# 3. 初始化数据库
npx prisma migrate dev
npx prisma db seed

# 4. 启动开发服务器
npm run dev

访问 http://localhost:3000

本地依赖（Docker）

# 启动 Postgres / Redis / MinIO
docker-compose -f docker-compose.dev.yml up -d

# 如需 DWG 转换服务（可选，ODA 方案）
docker-compose -f docker-compose.dev.yml --profile dwg build dwg-converter
docker-compose -f docker-compose.dev.yml --profile dwg up -d dwg-converter

生产部署

# Windows
.\scripts\deploy.ps1

# Linux/Mac
./scripts/deploy.sh

更多细节见：

  • docs/部署指南.md
  • docs/运维指南.md

🎯 核心功能（基于代码）

  • 认证与权限：JWT + Cookie、首次登录引导、RBAC 6 角色
  • 组织架构：部门/小组/成员管理与归属
  • 产品与 SKU：产品/SPU、SKU 规格、协作与可见性、回收站与恢复
  • 装配系统：装配步骤、版本管理、版本恢复、装配 PDF 输出
  • 板件/孔位/五金件：板件管理、孔位检测、五金件库、自动匹配与映射记忆
  • 材质与主题：材质库、材质分类、主题配置与激活
  • 包装方案：包装方案与箱体明细管理
  • 分享与协作：分享链接、访问统计
  • 审计与报表：操作日志、审计报表、导出
  • 文件上传：GLB/GLTF 上传、DWG 转换（需转换服务）

🔄 当前迭代重点

  • SKU 级结构数据：板件 / 孔位 / 五金件 / 装配步骤已逐步收口到 SKU 维度，减少产品级串数据
  • CAD 导入链路：持续以 CAD 导出结构数据作为高优先级数据来源，完善导入、绑定和回填
  • 装配编辑器与回放：重点优化板材点选、孔位高亮、爆炸视图、安装顺序生成与镜头调度
  • 分享与鉴权：已补齐分享页 SKU 作用域、/users 页面认证状态复用等关键链路
  • 回收站与软删除：已恢复删除 / 回收站主链路，继续做边界回归

当前主线不是“继续堆新页面”，而是把 导入 -> 结构数据 -> 装配编辑 -> 3D 回放 -> 分享 这条链路做稳定。

⚠️ 当前重点风险 / 待终验项

  • 真实 SKU 下的板材点选、孔位高亮、折角线仍需持续人工终验
  • 装配播放链路虽然已经开始收口到共享播放模型，但背面安装、镜头调度仍需真实样例回归
  • generate-from-order 已完成主链路收口，仍需继续补限频、幂等和异常场景联调

🧭 生产就绪能力（Phase 10）

  • 备份与恢复：scripts/backup-db.*、scripts/backup-files.*、scripts/backup-all.*、scripts/restore.*
  • 健康检查：GET /api/health 与 /system-health 页面
  • 配置校验：scripts/validate-config.*
  • 部署脚本：scripts/deploy.*、scripts/remote-deploy.sh
  • 生产配置：docker-compose.prod.yml / docker-compose.standard.yml / docker-compose.lightweight.yml

🛠️ 技术栈（以代码为准）

  • 框架：Next.js 16.1.6 + React 19.2.4 + TypeScript 5
  • 3D：Three.js 0.182.0 + React Three Fiber 9.5.0 + Drei 10.7.7
  • 动画：GSAP 3.12.5
  • 数据库：PostgreSQL + Prisma 7.3.0
  • 样式：Tailwind CSS 4.1.18
  • 状态管理：Zustand 5.0.2
  • 表单/校验：React Hook Form 7.54.2 + Zod 4.3.6
  • 对象存储：MinIO / S3 兼容

📂 目录结构（简要）

src/
├── app/                # Next.js App Router（页面与 API）
├── components/         # 业务与 UI 组件
├── server/             # 服务端逻辑（service/repo/validator）
├── lib/                # 通用工具（存储、3D、设计系统）
├── hooks/              # React Hooks
├── stores/             # Zustand
├── types/              # 类型定义

prisma/                 # Prisma schema + seed
scripts/                # 备份/部署/校验/测试工具脚本
tests/                  # Jest 测试（API/组件/安全/性能）

🧪 测试

npm test
npm run test:watch
npm run test:coverage

测试框架：Jest + React Testing Library，覆盖率阈值在 jest.config.js 中配置。

📖 文档导航

  • 项目总览：docs/项目总览.md
  • 文档导航：docs/README.md
  • 项目长期记忆：docs/agent-memory/README.md
  • 部署指南：docs/部署指南.md
  • 运维指南：docs/运维指南.md
  • Phase 10 完成报告：docs/Phase10完成报告.md

🔧 常用命令

# 开发
npm run dev
npm run build
npm run start

# 数据库
npm run prisma:generate
npm run prisma:push
npm run prisma:studio
npm run prisma:seed

# 质量与测试
npm run type-check
npm run lint
npm test

项目版本：v1.1
最后更新：2026-03-13
维护者：开发团队