421 lines
9.5 KiB
Markdown
421 lines
9.5 KiB
Markdown
# 素材卡片增强功能说明 v2.2
|
||
|
||
## 📅 更新日期：2025-10-17
|
||
|
||
---
|
||
|
||
## ✨ 新增功能概览
|
||
|
||
### 1. 📊 下载次数统计
|
||
- **自动计数**：每次下载自动增加计数
|
||
- **实时显示**：卡片上显示下载次数图标和数字
|
||
- **数据库持久化**：所有统计数据保存在数据库
|
||
|
||
### 2. ❤️ 点赞功能
|
||
- **一键点赞**：点击红心按钮即可点赞
|
||
- **取消点赞**：再次点击可取消点赞
|
||
- **唯一性**：每个用户对每个素材只能点赞一次
|
||
- **实时反馈**：点赞后立即更新UI状态
|
||
|
||
### 3. 🎨 卡片信息优化
|
||
- **SPU标签**：图片上叠加显示SPU
|
||
- **彩色标签**：店铺（蓝色）和场景类别（绿色）标签
|
||
- **文件信息**：显示完整的压缩包文件名
|
||
- **统计图标**：下载和点赞次数带图标显示
|
||
- **视觉优化**：更现代的布局和配色
|
||
|
||
---
|
||
|
||
## 🗄️ 数据库变更
|
||
|
||
### Material模型新增字段
|
||
|
||
```prisma
|
||
model Material {
|
||
// ... 原有字段 ...
|
||
downloadCount Int @default(0) // 下载次数
|
||
likeCount Int @default(0) // 点赞次数
|
||
likes MaterialLike[] // 点赞关系
|
||
|
||
@@index([downloadCount])
|
||
@@index([likeCount])
|
||
}
|
||
```
|
||
|
||
### 新增MaterialLike模型
|
||
|
||
```prisma
|
||
model MaterialLike {
|
||
id String @id @default(uuid())
|
||
materialId String
|
||
userId String
|
||
createdAt DateTime @default(now())
|
||
|
||
material Material @relation(fields: [materialId], references: [id], onDelete: Cascade)
|
||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||
|
||
@@unique([materialId, userId]) // 确保一个用户只能点赞一次
|
||
@@map("material_likes")
|
||
@@index([materialId])
|
||
@@index([userId])
|
||
}
|
||
```
|
||
|
||
### User模型更新
|
||
|
||
```prisma
|
||
model User {
|
||
// ... 原有字段 ...
|
||
materials Material[]
|
||
likes MaterialLike[] // 新增点赞关系
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API更新
|
||
|
||
### 1. GET /api/materials
|
||
**更新内容**：返回数据包含点赞状态
|
||
|
||
**响应数据**：
|
||
```json
|
||
[
|
||
{
|
||
"id": "uuid",
|
||
"productModel": "SPU-001",
|
||
"categoryName": "天猫旗舰店",
|
||
"sceneName": "客厅",
|
||
"authorName": "设计师A",
|
||
"zipFileName": "zip-xxxx-素材名称.zip",
|
||
"downloadCount": 25,
|
||
"likeCount": 10,
|
||
"isLiked": true, // ← 新增：当前用户是否点赞
|
||
// ... 其他字段
|
||
}
|
||
]
|
||
```
|
||
|
||
**逻辑改进**：
|
||
- 获取session判断是否登录
|
||
- 如果登录，查询当前用户的所有点赞记录
|
||
- 为每个素材添加`isLiked`字段
|
||
|
||
### 2. POST /api/materials/like
|
||
**新增API**：处理点赞/取消点赞
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"materialId": "uuid"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"liked": true, // true=点赞成功，false=取消点赞
|
||
"message": "点赞成功"
|
||
}
|
||
```
|
||
|
||
**功能**：
|
||
- 检查用户是否已点赞
|
||
- 如果未点赞：创建点赞记录，likeCount +1
|
||
- 如果已点赞：删除点赞记录，likeCount -1
|
||
- 使用唯一索引确保数据一致性
|
||
|
||
### 3. GET /api/materials/download
|
||
**更新内容**：自动增加下载次数
|
||
|
||
**新增逻辑**：
|
||
```typescript
|
||
// 增加下载次数
|
||
await prisma.material.update({
|
||
where: { id },
|
||
data: {
|
||
downloadCount: {
|
||
increment: 1
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 UI设计详解
|
||
|
||
### 卡片布局结构
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 预览图 (200px高度) │
|
||
│ ┌───────────────┐ │
|
||
│ │ SPU标签(左上) │ │
|
||
│ └───────────────┘ │
|
||
├─────────────────────────────┤
|
||
│ 【店铺标签】【场景标签】 │
|
||
│ │
|
||
│ 作者：xxx │
|
||
│ 文件：xxx.zip │
|
||
│ 时间：2025-10-17 12:00 │
|
||
│ │
|
||
│ ───────────────────────── │
|
||
│ 📥 25 ❤️ 10 │
|
||
│ ───────────────────────── │
|
||
│ │
|
||
│ [❤️] [📥 下载] │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
### 配色方案
|
||
|
||
#### 店铺标签
|
||
- **亮色模式**：蓝色背景 (#DBEAFE) + 蓝色文字 (#1D4ED8)
|
||
- **暗色模式**：深蓝背景 (blue-900/30) + 浅蓝文字 (#93C5FD)
|
||
|
||
#### 场景类别标签
|
||
- **亮色模式**：绿色背景 (#D1FAE5) + 绿色文字 (#047857)
|
||
- **暗色模式**：深绿背景 (green-900/30) + 浅绿文字 (#6EE7B7)
|
||
|
||
#### 点赞按钮
|
||
- **未点赞**：灰色背景，空心图标
|
||
- **已点赞**：红色背景 (#EF4444)，实心图标
|
||
|
||
---
|
||
|
||
## 💡 功能特性
|
||
|
||
### 点赞功能
|
||
|
||
#### 1. 防重复点赞
|
||
- 数据库层面：`@@unique([materialId, userId])`
|
||
- 应用层面：查询后再执行操作
|
||
|
||
#### 2. 状态同步
|
||
- 点赞后自动刷新列表
|
||
- 实时更新点赞数量和状态
|
||
- UI即时反馈
|
||
|
||
#### 3. 视觉反馈
|
||
```typescript
|
||
// 已点赞
|
||
className="bg-red-500 text-white hover:bg-red-600"
|
||
fill="currentColor" // 实心
|
||
|
||
// 未点赞
|
||
className="bg-gray-100 text-gray-700 hover:bg-gray-200"
|
||
fill="none" // 空心
|
||
```
|
||
|
||
### 下载统计
|
||
|
||
#### 1. 自动计数
|
||
- 每次成功下载文件前计数 +1
|
||
- 使用数据库increment操作确保原子性
|
||
- 不受前端刷新影响
|
||
|
||
#### 2. 实时显示
|
||
- 下载后立即刷新列表
|
||
- 显示更新后的下载次数
|
||
|
||
---
|
||
|
||
## 📱 响应式设计
|
||
|
||
### 网格布局
|
||
- **Mobile (sm)**：1列
|
||
- **Tablet (lg)**：3列
|
||
- **Desktop (xl)**：4列
|
||
|
||
### 卡片尺寸
|
||
- **预览图高度**：200px
|
||
- **卡片宽度**：自适应 (grid布局)
|
||
- **间距**：gap-6 (1.5rem)
|
||
|
||
---
|
||
|
||
## 🚀 用户交互流程
|
||
|
||
### 点赞流程
|
||
```
|
||
用户点击点赞按钮
|
||
↓
|
||
发送POST请求到 /api/materials/like
|
||
↓
|
||
服务器检查点赞状态
|
||
↓
|
||
├─ 未点赞 → 创建记录 + likeCount++
|
||
└─ 已点赞 → 删除记录 + likeCount--
|
||
↓
|
||
返回新状态
|
||
↓
|
||
前端刷新列表
|
||
↓
|
||
UI更新（图标填充、颜色、数量）
|
||
```
|
||
|
||
### 下载流程
|
||
```
|
||
用户点击下载按钮
|
||
↓
|
||
发送GET请求到 /api/materials/download
|
||
↓
|
||
服务器 downloadCount++
|
||
↓
|
||
读取文件并返回
|
||
↓
|
||
浏览器下载文件
|
||
↓
|
||
前端刷新列表（显示新的下载次数）
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 用户体验提升
|
||
|
||
### Before vs After
|
||
|
||
| 功能 | 之前 | 现在 |
|
||
|------|------|------|
|
||
| 信息显示 | 基本信息 | **完整信息**（SPU、店铺、场景、文件名） |
|
||
| 统计数据 | 无 | **下载次数**、**点赞次数** |
|
||
| 互动功能 | 仅下载 | 下载 + **点赞** |
|
||
| 视觉设计 | 简单列表 | **彩色标签**、**图标**、**分层布局** |
|
||
| 用户反馈 | 下载后无变化 | **实时更新统计数据** |
|
||
|
||
### 数据洞察
|
||
- ✅ 了解哪些素材最受欢迎（点赞数）
|
||
- ✅ 了解哪些素材使用最多（下载数）
|
||
- ✅ 用户可以收藏喜欢的素材（点赞）
|
||
- ✅ 提供数据支持运营决策
|
||
|
||
---
|
||
|
||
## 🔧 部署步骤
|
||
|
||
### 1. 数据库迁移
|
||
|
||
```bash
|
||
ssh root@192.168.58.20
|
||
cd /mnt/tank/apps/youyidian-3d
|
||
|
||
# 运行数据库迁移
|
||
docker compose exec app npx prisma db push
|
||
```
|
||
|
||
**迁移内容**：
|
||
- 添加 `downloadCount` 字段（默认0）
|
||
- 添加 `likeCount` 字段（默认0）
|
||
- 创建 `material_likes` 表
|
||
- 创建索引
|
||
|
||
### 2. 重新部署代码
|
||
|
||
```bash
|
||
# 本地打包
|
||
cd /Users/lanmu/Desktop/gongxiangp2
|
||
./update-deploy.sh
|
||
```
|
||
|
||
或手动部署：
|
||
|
||
```bash
|
||
# 打包
|
||
tar -czf update.tar.gz --exclude='node_modules' --exclude='.next' .
|
||
|
||
# 上传
|
||
scp update.tar.gz root@192.168.58.20:/mnt/tank/apps/youyidian-3d/
|
||
|
||
# 部署
|
||
ssh root@192.168.58.20
|
||
cd /mnt/tank/apps/youyidian-3d
|
||
tar -xzf update.tar.gz
|
||
docker compose down
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 3. 初始化现有数据（可选）
|
||
|
||
如果有旧数据，下载和点赞次数会默认为0。可以手动初始化：
|
||
|
||
```bash
|
||
docker compose exec -T app npx prisma db execute --schema=/app/prisma/schema.prisma --stdin <<< "
|
||
-- 所有现有素材设置默认值
|
||
UPDATE materials
|
||
SET \"downloadCount\" = 0, \"likeCount\" = 0
|
||
WHERE \"downloadCount\" IS NULL OR \"likeCount\" IS NULL;
|
||
"
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 测试清单
|
||
|
||
### 功能测试
|
||
- [ ] 查看首页，卡片显示完整信息
|
||
- [ ] 点击点赞按钮，按钮变红
|
||
- [ ] 再次点击，取消点赞，按钮变灰
|
||
- [ ] 点赞次数实时更新
|
||
- [ ] 下载素材，下载次数 +1
|
||
- [ ] 刷新页面，点赞状态保持
|
||
- [ ] 多个用户对同一素材点赞，计数正确
|
||
|
||
### UI测试
|
||
- [ ] 标签颜色正确显示
|
||
- [ ] SPU标签在图片左上角
|
||
- [ ] 图标正常显示
|
||
- [ ] 黑暗模式下样式正常
|
||
- [ ] 响应式布局正常
|
||
|
||
### 边界测试
|
||
- [ ] 未登录用户点赞（应提示登录）
|
||
- [ ] 重复点赞（应正常切换）
|
||
- [ ] 大量点赞/下载（性能正常）
|
||
- [ ] 网络异常（显示错误提示）
|
||
|
||
---
|
||
|
||
## 📊 数据示例
|
||
|
||
### 热门素材排行
|
||
|
||
**按点赞数排序**：
|
||
```sql
|
||
SELECT "productModel", "categoryName", "likeCount"
|
||
FROM materials
|
||
ORDER BY "likeCount" DESC
|
||
LIMIT 10;
|
||
```
|
||
|
||
**按下载数排序**：
|
||
```sql
|
||
SELECT "productModel", "categoryName", "downloadCount"
|
||
FROM materials
|
||
ORDER BY "downloadCount" DESC
|
||
LIMIT 10;
|
||
```
|
||
|
||
---
|
||
|
||
## 🎉 效果展示
|
||
|
||
### 卡片信息完整度
|
||
✅ **之前**：仅显示基本信息
|
||
✅ **现在**：
|
||
- SPU标签（图片上）
|
||
- 店铺标签（蓝色）
|
||
- 场景类别标签（绿色）
|
||
- 作者信息
|
||
- 文件名
|
||
- 创建时间
|
||
- 下载次数（带图标）
|
||
- 点赞次数（带图标）
|
||
- 点赞按钮（可交互）
|
||
- 下载按钮（带图标）
|
||
|
||
---
|
||
|
||
**功能完成！准备部署！** 🚀
|
||
|