WuYongJie/gongxiangp2

Fork 0

chenpei caa3d66c0a Initial commit: 共享平台项目

2025-10-26 09:11:04 +08:00

8.0 KiB

Raw Blame History

由壹点3D素材 - 项目说明

📋 项目概述

这是一个现代化的3D素材分享平台，用户可以上传和下载3D素材文件。项目严格遵循苹果官方UI设计规范，提供优雅的用户体验。

🎯 核心功能

用户功能

✅ 用户认证: 注册、登录、JWT会话管理
✅ 素材上传:
- 上传预览图（250x175px固定尺寸显示）
- 输入商品型号、场景名称、作者花名
- 上传压缩包文件
✅ 素材浏览: 网格布局展示所有素材
✅ 素材下载: 一键下载压缩包

管理员功能

✅ 系统设置入口: 顶部导航栏可见
✅ 素材管理: 查看、编辑、删除素材
✅ 用户管理: 查看、删除用户

🏗️ 技术架构

前端技术栈

框架: Next.js 14 (App Router)
UI库: React 18 + TypeScript
样式: TailwindCSS (苹果设计规范)
认证: NextAuth.js
日期处理: date-fns

后端技术栈

运行时: Node.js
API: Next.js API Routes
数据库: PostgreSQL
ORM: Prisma
文件上传: Formidable

存储方案

预览图: MinIO S3 云存储
- Endpoint: https://s3.1080p.hk
- Bucket: jsxiangche
- Path: 由壹点AI/
压缩包: 服务器本地存储 (./uploads目录)

📁 项目结构

gongxiangp2/
├── app/                        # Next.js App Router
│   ├── api/                   # API路由
│   │   ├── auth/             # 认证API
│   │   │   ├── [...nextauth]/route.ts  # NextAuth配置
│   │   │   └── register/route.ts       # 注册API
│   │   ├── materials/        # 素材API
│   │   │   ├── route.ts      # 获取/删除素材
│   │   │   ├── upload/route.ts         # 上传素材
│   │   │   └── download/route.ts       # 下载素材
│   │   └── admin/            # 管理员API
│   │       └── users/route.ts          # 用户管理
│   ├── login/                # 登录页面
│   │   └── page.tsx
│   ├── register/             # 注册页面
│   │   └── page.tsx
│   ├── admin/                # 管理员页面
│   │   └── page.tsx
│   ├── page.tsx              # 首页
│   ├── layout.tsx            # 根布局
│   ├── providers.tsx         # Context Providers
│   └── globals.css           # 全局样式
├── components/               # React组件
│   ├── Header.tsx           # 头部导航
│   └── UploadModal.tsx      # 上传模态框
├── lib/                      # 工具库
│   ├── prisma.ts            # Prisma客户端
│   ├── auth.ts              # NextAuth配置
│   └── s3.ts                # S3存储服务
├── prisma/                   # Prisma配置
│   └── schema.prisma        # 数据库模式
├── types/                    # TypeScript类型定义
│   └── next-auth.d.ts       # NextAuth类型扩展
├── uploads/                  # 本地上传文件
├── .env.local               # 环境变量（已配置）
├── package.json             # 项目依赖
├── tsconfig.json            # TypeScript配置
├── tailwind.config.ts       # TailwindCSS配置
├── next.config.js           # Next.js配置
├── middleware.ts            # Next.js中间件（路由保护）
├── install.sh               # 一键安装脚本
├── start.sh                 # 启动脚本
├── README.md                # 项目说明
├── SETUP.md                 # 部署指南
└── PROJECT_INFO.md          # 项目信息（本文件）

🗄️ 数据库设计

User 表（用户）

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  username  String   @unique
  password  String   // bcrypt加密
  role      Role     @default(USER)  // USER | ADMIN
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  materials Material[]
}

Material 表（素材）

model Material {
  id            String   @id @default(uuid())
  previewUrl    String   // S3 URL
  productModel  String   // 商品型号
  sceneName     String   // 场景名称
  authorName    String   // 作者花名
  zipFileName   String   // 压缩包文件名
  zipFilePath   String   // 本地路径
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
  userId        String
  user          User     @relation(...)
}

🎨 UI设计规范（苹果风格）

设计原则

简洁: 清晰的布局，充足的留白
一致性: 统一的圆角、阴影、间距
响应式: 适配各种屏幕尺寸
流畅动画: 所有交互都有平滑过渡

设计元素

圆角: 12px (border-radius: 12px)
阴影:
- 小阴影: 0 4px 12px rgba(0,0,0,0.08)
- 大阴影: 0 8px 24px rgba(0,0,0,0.12)
主色调: 蓝色系 (#0ea5e9)
字体: Inter (Google Fonts)
过渡: 200ms ease

组件样式

.btn-apple: 苹果风格按钮基础类
.btn-primary: 主要操作按钮
.btn-secondary: 次要操作按钮
.input-apple: 苹果风格输入框
.card-apple: 苹果风格卡片

🔐 安全特性

密码加密: bcryptjs (10 rounds)
JWT认证: NextAuth.js会话管理
路由保护: Next.js middleware
CSRF保护: NextAuth内置
SQL注入防护: Prisma ORM参数化查询
XSS防护: React自动转义

🚀 快速开始

方式1: 使用安装脚本（推荐）

./install.sh
./start.sh

方式2: 手动安装

# 1. 安装依赖
npm install

# 2. 生成Prisma Client
npm run prisma:generate

# 3. 推送数据库模式
npm run prisma:push

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

创建管理员账号

访问 http://localhost:3000/register 注册账号
运行 npm run prisma:studio
在Prisma Studio中将用户的role改为ADMIN

📝 环境变量说明

变量名	说明	示例
DATABASE_URL	PostgreSQL连接字符串	postgresql://...
NEXTAUTH_SECRET	NextAuth密钥	随机字符串
NEXTAUTH_URL	网站URL	http://localhost:3000
S3_ENDPOINT	S3服务端点	https://s3.1080p.hk
S3_BUCKET	S3存储桶	jsxiangche
S3_ACCESS_KEY_ID	S3访问密钥	AEvT...
S3_SECRET_ACCESS_KEY	S3密钥	u8nz...
S3_PUBLIC_DOMAIN	S3公共域名	https://s3.1080p.hk/...
S3_FILE_PATH	S3文件路径前缀	由壹点AI/
UPLOAD_DIR	本地上传目录	./uploads

🔧 常用命令

# 开发
npm run dev              # 启动开发服务器
npm run build            # 构建生产版本
npm start                # 启动生产服务器

# 数据库
npm run prisma:generate  # 生成Prisma Client
npm run prisma:push      # 推送数据库模式
npm run prisma:studio    # 打开Prisma Studio

# 代码质量
npm run lint             # ESLint检查

📊 性能优化

图片优化: Next.js Image组件自动优化
代码分割: Next.js自动代码分割
缓存策略:
- 静态资源: 长期缓存
- API响应: 无缓存（实时数据）
懒加载: 组件按需加载

🐛 常见问题

Q: 数据库连接失败

A: 检查DATABASE_URL是否正确，确保PostgreSQL服务运行中

Q: S3上传失败

A: 检查S3配置，确保MinIO服务可访问

Q: 图片显示404

A: 检查next.config.js中的images配置，确保域名在remotePatterns中

Q: 上传大文件失败

A: 已在next.config.js中配置100MB限制，可根据需要调整

📈 未来扩展

可能的功能扩展：

素材分类和标签
搜索和筛选功能
用户收藏功能
评论和评分系统
统计和分析面板
批量上传功能
在线预览3D模型

📞 技术支持

如有技术问题，请检查：

Node.js版本 >= 18
环境变量配置正确
数据库连接正常
S3服务可访问

📄 许可证

MIT License

8.0 KiB Raw Blame History Unescape Escape