# 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