269 lines
8.0 KiB
Markdown
269 lines
8.0 KiB
Markdown
# FLNXI素材库 - 项目说明
|
||
|
||
## 📋 项目概述
|
||
|
||
这是一个现代化的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 表（用户）
|
||
```prisma
|
||
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 表（素材）
|
||
```prisma
|
||
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`: 苹果风格卡片
|
||
|
||
## 🔐 安全特性
|
||
|
||
1. **密码加密**: bcryptjs (10 rounds)
|
||
2. **JWT认证**: NextAuth.js会话管理
|
||
3. **路由保护**: Next.js middleware
|
||
4. **CSRF保护**: NextAuth内置
|
||
5. **SQL注入防护**: Prisma ORM参数化查询
|
||
6. **XSS防护**: React自动转义
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式1: 使用安装脚本（推荐）
|
||
```bash
|
||
./install.sh
|
||
./start.sh
|
||
```
|
||
|
||
### 方式2: 手动安装
|
||
```bash
|
||
# 1. 安装依赖
|
||
npm install
|
||
|
||
# 2. 生成Prisma Client
|
||
npm run prisma:generate
|
||
|
||
# 3. 推送数据库模式
|
||
npm run prisma:push
|
||
|
||
# 4. 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
### 创建管理员账号
|
||
1. 访问 http://localhost:3000/register 注册账号
|
||
2. 运行 `npm run prisma:studio`
|
||
3. 在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 |
|
||
|
||
## 🔧 常用命令
|
||
|
||
```bash
|
||
# 开发
|
||
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检查
|
||
```
|
||
|
||
## 📊 性能优化
|
||
|
||
1. **图片优化**: Next.js Image组件自动优化
|
||
2. **代码分割**: Next.js自动代码分割
|
||
3. **缓存策略**:
|
||
- 静态资源: 长期缓存
|
||
- API响应: 无缓存（实时数据）
|
||
4. **懒加载**: 组件按需加载
|
||
|
||
## 🐛 常见问题
|
||
|
||
### 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模型
|
||
|
||
## 📞 技术支持
|
||
|
||
如有技术问题，请检查：
|
||
1. Node.js版本 >= 18
|
||
2. 环境变量配置正确
|
||
3. 数据库连接正常
|
||
4. S3服务可访问
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
|