21 KiB
21 KiB
商城消费者端 - 积分与评价功能完善需求文档
一、项目概述
1.1 项目背景
本项目为商城消费者端应用，当前积分和评价功能已有基础实现，但存在部分功能缺失和体验优化空间。本文档旨在明确积分和评价功能的完善需求。
1.2 当前实现状态
| 功能模块 | 当前状态 | 说明 |
|---|---|---|
| 消费者端积分页面 | ✅ 已完成 | 显示积分余额、积分明细列表 |
| 积分兑换商城 | ❌ 未实现 | 点击"积分兑换"提示"开发中" |
| 消费者端商品评价 | ✅ 已完成 | 支持评分、文字、图片、匿名评价 |
| 消费者端店铺评价 | ✅ 已完成 | 支持描述/物流/服务三维评分 |
| 商家端评价管理 | ✅ 已完成 | 支持查看、筛选、回复评价 |
二、积分功能完善需求
2.1 功能架构图
┌─────────────────────────────────────────────────────────────┐
│ 积分系统架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 积分获取 │ │ 积分使用 │ │ 积分管理 │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ • 注册赠送 │ │ • 积分兑换 │ │ • 积分查询 │ │
│ │ • 每日签到 │ │ • 订单抵扣 │ │ • 明细记录 │ │
│ │ • 购物奖励 │ │ • 积分抽奖 │ │ • 过期处理 │ │
│ │ • 评价奖励 │ │ │ │ • 积分规则 │ │
│ │ • 邀请好友 │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
2.2 前端功能需求
2.2.1 积分首页优化
页面路径: pages/mall/consumer/points/index.uvue
需求描述:
-
积分概览卡片
- 显示当前可用积分
- 显示即将过期积分（30天内）
- 显示历史累计积分
- 积分趋势图表（近7天/30天）
-
快捷入口
- 签到入口（带签到状态提示）
- 积分兑换入口
- 积分规则说明
-
积分明细列表
- 支持按类型筛选（获取/消费/过期）
- 支持按时间范围筛选
- 下拉刷新、上拉加载更多
2.2.2 每日签到功能（新增）
页面路径: pages/mall/consumer/points/signin.uvue
需求描述:
-
签到日历
- 显示当月签到记录
- 连续签到天数统计
- 签到奖励预览
-
签到奖励规则
- 每日签到：+5积分
- 连续签到7天：额外+20积分
- 连续签到30天：额外+100积分
-
签到弹窗
- 签到成功动画
- 显示获得积分
- 连续签到进度提示
2.2.3 积分兑换商城（新增）
页面路径: pages/mall/consumer/points/exchange.uvue
需求描述:
-
兑换商品列表
- 优惠券兑换
- 实物商品兑换
- 虚拟商品兑换（会员权益等）
-
商品详情
- 商品图片、名称、描述
- 兑换所需积分
- 库存状态
- 兑换记录
-
兑换流程
- 积分不足提示
- 确认兑换弹窗
- 兑换成功/失败反馈
- 物流跟踪（实物商品）
2.2.4 积分规则页面（新增）
页面路径: pages/mall/consumer/points/rules.uvue
需求描述:
- 积分获取规则说明
- 积分使用规则说明
- 积分有效期说明
- 常见问题FAQ
2.3 后端API需求
2.3.1 新增API接口
| 接口名称 | 请求方法 | 接口路径 | 说明 |
|---|---|---|---|
| 签到 | POST | /api/points/signin |
用户每日签到 |
| 获取签到记录 | GET | /api/points/signin-records |
获取月度签到记录 |
| 获取兑换商品列表 | GET | /api/points/exchange-products |
获取可兑换商品 |
| 积分兑换 | POST | /api/points/exchange |
兑换商品 |
| 获取兑换记录 | GET | /api/points/exchange-records |
获取兑换历史 |
| 积分过期提醒 | GET | /api/points/expiring |
获取即将过期积分 |
2.3.2 接口详细设计
签到接口
// 请求
POST /api/points/signin
Response: {
success: boolean
points: number // 本次获得积分
continuous_days: number // 连续签到天数
bonus_points: number // 额外奖励积分
total_points: number // 当前总积分
}
积分兑换接口
// 请求
POST /api/points/exchange
Body: {
product_id: string // 兑换商品ID
quantity: number // 兑换数量
address_id?: string // 收货地址（实物商品）
}
Response: {
success: boolean
exchange_id: string // 兑换记录ID
points_used: number // 消耗积分
remaining_points: number // 剩余积分
}
2.4 数据库设计
2.4.1 现有表结构
用户积分表 (ml_user_points)
CREATE TABLE IF NOT EXISTS ml_user_points (
user_id UUID NOT NULL PRIMARY KEY REFERENCES auth.users(id),
points INT DEFAULT 0 NOT NULL, -- 当前可用积分
total_earned INT DEFAULT 0, -- 历史累计获得积分
total_used INT DEFAULT 0, -- 历史累计使用积分
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- 添加索引
CREATE INDEX idx_user_points_user_id ON ml_user_points(user_id);
积分记录表 (ml_point_records)
CREATE TABLE IF NOT EXISTS ml_point_records (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
user_id UUID NOT NULL REFERENCES auth.users(id),
points INT NOT NULL, -- 变动积分 (正/负)
balance INT NOT NULL, -- 变动后余额
type VARCHAR(50) NOT NULL, -- 类型
reference_id UUID, -- 关联ID（订单ID/兑换ID等）
description TEXT,
expires_at TIMESTAMPTZ, -- 过期时间
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- 添加索引
CREATE INDEX idx_point_records_user_id ON ml_point_records(user_id);
CREATE INDEX idx_point_records_type ON ml_point_records(type);
CREATE INDEX idx_point_records_created_at ON ml_point_records(created_at);
2.4.2 新增表结构
签到记录表 (ml_signin_records)
CREATE TABLE IF NOT EXISTS ml_signin_records (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
user_id UUID NOT NULL REFERENCES auth.users(id),
signin_date DATE NOT NULL, -- 签到日期
points_earned INT DEFAULT 0, -- 获得积分
bonus_points INT DEFAULT 0, -- 奖励积分
continuous_days INT DEFAULT 1, -- 当次连续签到天数
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(user_id, signin_date) -- 每用户每天只能签到一次
);
-- 添加索引
CREATE INDEX idx_signin_records_user_id ON ml_signin_records(user_id);
CREATE INDEX idx_signin_records_date ON ml_signin_records(signin_date);
积分兑换商品表 (ml_point_products)
CREATE TABLE IF NOT EXISTS ml_point_products (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
name VARCHAR(200) NOT NULL, -- 商品名称
description TEXT, -- 商品描述
image_url VARCHAR(500), -- 商品图片
product_type VARCHAR(50) NOT NULL, -- 类型: coupon/physical/virtual
points_required INT NOT NULL, -- 所需积分
original_price DECIMAL(10,2), -- 原价（展示用）
stock INT DEFAULT 0, -- 库存
status INT DEFAULT 1, -- 状态: 0=下架, 1=上架
sort_order INT DEFAULT 0, -- 排序
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
积分兑换记录表 (ml_point_exchanges)
CREATE TABLE IF NOT EXISTS ml_point_exchanges (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
user_id UUID NOT NULL REFERENCES auth.users(id),
product_id UUID NOT NULL REFERENCES ml_point_products(id),
quantity INT DEFAULT 1, -- 兑换数量
points_used INT NOT NULL, -- 消耗积分
status INT DEFAULT 0, -- 状态: 0=待处理, 1=已发货, 2=已完成, 3=已取消
tracking_no VARCHAR(100), -- 物流单号
address_id UUID, -- 收货地址
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
积分规则配置表 (ml_point_rules)
CREATE TABLE IF NOT EXISTS ml_point_rules (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
rule_type VARCHAR(50) NOT NULL, -- 规则类型
rule_name VARCHAR(100) NOT NULL, -- 规则名称
points INT NOT NULL, -- 积分值
description TEXT, -- 规则说明
config JSONB, -- 扩展配置
status INT DEFAULT 1, -- 状态
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- 初始化规则数据
INSERT INTO ml_point_rules (rule_type, rule_name, points, description) VALUES
('register', '注册赠送', 100, '新用户注册赠送积分'),
('signin_daily', '每日签到', 5, '每日签到获得积分'),
('signin_continuous_7', '连续签到7天奖励', 20, '连续签到7天额外奖励'),
('signin_continuous_30', '连续签到30天奖励', 100, '连续签到30天额外奖励'),
('shopping', '购物奖励', 1, '每消费1元获得1积分'),
('review', '评价奖励', 10, '完成商品评价获得积分'),
('review_with_image', '带图评价奖励', 20, '带图评价额外奖励');
三、评价功能完善需求
3.1 功能架构图
┌─────────────────────────────────────────────────────────────┐
│ 评价系统架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 评价提交 │ │ 评价展示 │ │ 评价管理 │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ • 商品评价 │ │ • 商品详情 │ │ • 商家回复 │ │
│ │ • 店铺评价 │ │ • 评价列表 │ │ • 评价统计 │ │
│ │ • 配送评价 │ │ • 评分统计 │ │ • 违规处理 │ │
│ │ • 追加评价 │ │ • 筛选排序 │ │ • 评价审核 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
3.2 前端功能需求
3.2.1 评价页面优化
页面路径: pages/mall/consumer/review.uvue
需求描述:
-
评价表单优化
- 支持视频上传（限1个，30秒内）
- 支持图片拖拽排序
- 添加评价标签选择（质量好/物流快/服务好等）
- 添加商品满意度维度（质量/包装/性价比）
-
追加评价功能
- 订单完成后7天内可追加评价
- 追加评价入口（订单详情页）
- 追加评价表单
-
评价预览
- 提交前预览评价效果
- 匿名评价预览效果
3.2.2 商品评价列表（新增）
页面路径: pages/mall/consumer/product-reviews.uvue
需求描述:
-
评价统计概览
- 好评率百分比
- 评分分布图（1-5星）
- 标签云（高频评价关键词）
-
评价列表
- 支持按评分筛选
- 支持按时间/点赞数排序
- 支持只看有图/有视频评价
- 评价点赞功能
- 评价举报功能
-
评价详情
- 点击评价查看详情
- 查看商家回复
- 查看追加评价
3.2.3 我的评价页面（新增）
页面路径: pages/mall/consumer/my-reviews.uvue
需求描述:
-
评价列表
- 显示已评价商品
- 显示待评价商品
- 显示可追加评价商品
-
评价操作
- 编辑评价（24小时内）
- 删除评价
- 追加评价
3.2.4 配送员评价（完善）
页面路径: pages/mall/delivery/ratings.uvue
需求描述:
- 对接真实API（当前使用Mock数据）
- 配送员评分统计
- 配送评价列表
3.3 后端API需求
3.3.1 新增API接口
| 接口名称 | 请求方法 | 接口路径 | 说明 |
|---|---|---|---|
| 获取商品评价列表 | GET | /api/reviews/product/:productId |
分页获取商品评价 |
| 获取评价统计 | GET | /api/reviews/stats/:productId |
获取商品评分统计 |
| 追加评价 | POST | /api/reviews/append |
追加评价内容 |
| 评价点赞 | POST | /api/reviews/like/:id |
点赞评价 |
| 获取我的评价 | GET | /api/reviews/my |
获取用户评价列表 |
| 编辑评价 | PUT | /api/reviews/:id |
编辑评价（24小时内） |
| 删除评价 | DELETE | /api/reviews/:id |
删除评价 |
| 评价举报 | POST | /api/reviews/report/:id |
举报违规评价 |
3.3.2 接口详细设计
获取商品评价列表
GET /api/reviews/product/:productId?page=1&limit=10&rating=5&has_image=true
Response: {
total: number
page: number
limit: number
data: [{
id: string
user_name: string
user_avatar: string
rating: number
content: string
images: string[]
videos: string[]
tags: string[]
like_count: number
is_liked: boolean
reply: {
content: string
created_at: string
}
append_content?: {
content: string
created_at: string
}
created_at: string
}]
}
获取评价统计
GET /api/reviews/stats/:productId
Response: {
total_count: number
avg_rating: number
good_rate: number // 好评率
rating_distribution: { // 评分分布
1: number
2: number
3: number
4: number
5: number
}
tags: [{ // 高频标签
name: string
count: number
}]
}
3.4 数据库设计
3.4.1 现有表结构优化
商品评价表 (ml_product_reviews)
-- 添加新字段
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS videos JSONB DEFAULT '[]';
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS tags JSONB DEFAULT '[]';
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS like_count INT DEFAULT 0;
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS is_edited BOOLEAN DEFAULT false;
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS append_content TEXT;
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS append_at TIMESTAMPTZ;
ALTER TABLE ml_product_reviews ADD COLUMN IF NOT EXISTS append_images JSONB DEFAULT '[]';
3.4.2 新增表结构
评价点赞表 (ml_review_likes)
CREATE TABLE IF NOT EXISTS ml_review_likes (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
review_id UUID NOT NULL REFERENCES ml_product_reviews(id),
user_id UUID NOT NULL REFERENCES auth.users(id),
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(review_id, user_id) -- 每用户对每条评价只能点赞一次
);
CREATE INDEX idx_review_likes_review_id ON ml_review_likes(review_id);
评价举报表 (ml_review_reports)
CREATE TABLE IF NOT EXISTS ml_review_reports (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
review_id UUID NOT NULL REFERENCES ml_product_reviews(id),
user_id UUID NOT NULL REFERENCES auth.users(id),
reason VARCHAR(200) NOT NULL, -- 举报原因
description TEXT, -- 详细说明
status INT DEFAULT 0, -- 状态: 0=待处理, 1=已处理, 2=已驳回
handle_result TEXT, -- 处理结果
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
配送员评价表 (ml_delivery_ratings)
CREATE TABLE IF NOT EXISTS ml_delivery_ratings (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
order_id UUID NOT NULL REFERENCES ml_orders(id),
delivery_user_id UUID NOT NULL, -- 配送员ID
user_id UUID NOT NULL REFERENCES auth.users(id),
rating INT CHECK (rating >= 1 AND rating <= 5),
content TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(order_id) -- 每订单只能评价一次
);
四、开发优先级
4.1 第一阶段（高优先级）
| 序号 | 功能 | 模块 | 预估工时 |
|---|---|---|---|
| 1 | 每日签到功能 | 积分 | 2天 |
| 2 | 积分兑换商城 | 积分 | 3天 |
| 3 | 商品评价列表展示 | 评价 | 2天 |
| 4 | 我的评价页面 | 评价 | 1天 |
4.2 第二阶段（中优先级）
| 序号 | 功能 | 模块 | 预估工时 |
|---|---|---|---|
| 1 | 积分规则配置 | 积分 | 1天 |
| 2 | 追加评价功能 | 评价 | 1天 |
| 3 | 评价点赞功能 | 评价 | 0.5天 |
| 4 | 配送员评价对接 | 评价 | 1天 |
4.3 第三阶段（低优先级）
| 序号 | 功能 | 模块 | 预估工时 |
|---|---|---|---|
| 1 | 积分过期提醒 | 积分 | 0.5天 |
| 2 | 评价视频上传 | 评价 | 1天 |
| 3 | 评价举报功能 | 评价 | 0.5天 |
| 4 | 管理端完善 | 综合 | 2天 |
五、技术要点
5.1 积分系统技术要点
-
积分并发安全
- 使用数据库事务保证积分变动原子性
- 添加乐观锁防止超扣
-
积分过期处理
- 定时任务每日检查过期积分
- 过期前7天推送提醒通知
-
签到防刷
- 限制每日只能签到一次
- 记录签到IP，检测异常行为
5.2 评价系统技术要点
-
评价数据统计
- 使用触发器自动更新商品评分统计
- 缓存热门商品评价数据
-
图片/视频处理
- 图片压缩后上传
- 视频转码处理
- CDN加速访问
-
敏感词过滤
- 评价内容敏感词检测
- 自动替换或人工审核
六、测试要点
6.1 积分功能测试
- 签到功能：每日签到、连续签到奖励
- 积分兑换：积分不足、库存不足、兑换成功
- 积分过期：自动过期、过期提醒
- 并发测试：同时兑换、同时签到
6.2 评价功能测试
- 评价提交：文字、图片、视频、匿名
- 评价展示：列表、筛选、排序
- 评价操作：编辑、删除、追加、点赞
- 边界测试：空内容、超长内容、敏感词
七、附录
7.1 相关文件路径
pages/
├── mall/
│ └── consumer/
│ ├── points/
│ │ ├── index.uvue # 积分首页（已有）
│ │ ├── signin.uvue # 签到页面（新增）
│ │ ├── exchange.uvue # 兑换商城（新增）
│ │ └── rules.uvue # 积分规则（新增）
│ ├── review.uvue # 评价页面（已有）
│ ├── product-reviews.uvue # 商品评价列表（新增）
│ └── my-reviews.uvue # 我的评价（新增）
│
└── user/
└── login.uvue # 登录页面
utils/
└── supabaseService.uts # API服务
types/
└── mall-types.uts # 类型定义
doc_mall/
└── consumer/
└── sql/
├── 01_wallet_and_points.sql
└── add_reviews_tables.sql
7.2 参考文档
文档版本: v1.0
创建日期: 2026-03-05
最后更新: 2026-03-05