# 商城消费者端 - 积分与评价功能完善需求文档

## 一、项目概述

### 1.1 项目背景
本项目为商城消费者端应用，当前积分和评价功能已有基础实现，但存在部分功能缺失和体验优化空间。本文档旨在明确积分和评价功能的完善需求。

### 1.2 当前实现状态

| 功能模块 | 当前状态 | 说明 |
|---------|---------|------|
| 消费者端积分页面 | ✅ 已完成 | 显示积分余额、积分明细列表 |
| 积分兑换商城 | ❌ 未实现 | 点击"积分兑换"提示"开发中" |
| 消费者端商品评价 | ✅ 已完成 | 支持评分、文字、图片、匿名评价 |
| 消费者端店铺评价 | ✅ 已完成 | 支持描述/物流/服务三维评分 |
| 商家端评价管理 | ✅ 已完成 | 支持查看、筛选、回复评价 |

---

## 二、积分功能完善需求

### 2.1 功能架构图

```
┌─────────────────────────────────────────────────────────────┐
│                      积分系统架构                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │  积分获取   │    │  积分使用   │    │  积分管理   │    │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤    │
│  │ • 注册赠送  │    │ • 积分兑换  │    │ • 积分查询  │    │
│  │ • 每日签到  │    │ • 订单抵扣  │    │ • 明细记录  │    │
│  │ • 购物奖励  │    │ • 积分抽奖  │    │ • 过期处理  │    │
│  │ • 评价奖励  │    │             │    │ • 积分规则  │    │
│  │ • 邀请好友  │    │             │    │             │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 前端功能需求

#### 2.2.1 积分首页优化

**页面路径**: `pages/mall/consumer/points/index.uvue`

**需求描述**:
1. **积分概览卡片**
   - 显示当前可用积分
   - 显示即将过期积分（30天内）
   - 显示历史累计积分
   - 积分趋势图表（近7天/30天）

2. **快捷入口**
   - 签到入口（带签到状态提示）
   - 积分兑换入口
   - 积分规则说明

3. **积分明细列表**
   - 支持按类型筛选（获取/消费/过期）
   - 支持按时间范围筛选
   - 下拉刷新、上拉加载更多

#### 2.2.2 每日签到功能（新增）

**页面路径**: `pages/mall/consumer/points/signin.uvue`

**需求描述**:
1. **签到日历**
   - 显示当月签到记录
   - 连续签到天数统计
   - 签到奖励预览

2. **签到奖励规则**
   - 每日签到：+5积分
   - 连续签到7天：额外+20积分
   - 连续签到30天：额外+100积分

3. **签到弹窗**
   - 签到成功动画
   - 显示获得积分
   - 连续签到进度提示

#### 2.2.3 积分兑换商城（新增）

**页面路径**: `pages/mall/consumer/points/exchange.uvue`

**需求描述**:
1. **兑换商品列表**
   - 优惠券兑换
   - 实物商品兑换
   - 虚拟商品兑换（会员权益等）

2. **商品详情**
   - 商品图片、名称、描述
   - 兑换所需积分
   - 库存状态
   - 兑换记录

3. **兑换流程**
   - 积分不足提示
   - 确认兑换弹窗
   - 兑换成功/失败反馈
   - 物流跟踪（实物商品）

#### 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 接口详细设计

**签到接口**
```typescript
// 请求
POST /api/points/signin
Response: {
  success: boolean
  points: number          // 本次获得积分
  continuous_days: number // 连续签到天数
  bonus_points: number    // 额外奖励积分
  total_points: number    // 当前总积分
}
```

**积分兑换接口**
```typescript
// 请求
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)**
```sql
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)**
```sql
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)**
```sql
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)**
```sql
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)**
```sql
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)**
```sql
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. **评价表单优化**
   - 支持视频上传（限1个，30秒内）
   - 支持图片拖拽排序
   - 添加评价标签选择（质量好/物流快/服务好等）
   - 添加商品满意度维度（质量/包装/性价比）

2. **追加评价功能**
   - 订单完成后7天内可追加评价
   - 追加评价入口（订单详情页）
   - 追加评价表单

3. **评价预览**
   - 提交前预览评价效果
   - 匿名评价预览效果

#### 3.2.2 商品评价列表（新增）

**页面路径**: `pages/mall/consumer/product-reviews.uvue`

**需求描述**:
1. **评价统计概览**
   - 好评率百分比
   - 评分分布图（1-5星）
   - 标签云（高频评价关键词）

2. **评价列表**
   - 支持按评分筛选
   - 支持按时间/点赞数排序
   - 支持只看有图/有视频评价
   - 评价点赞功能
   - 评价举报功能

3. **评价详情**
   - 点击评价查看详情
   - 查看商家回复
   - 查看追加评价

#### 3.2.3 我的评价页面（新增）

**页面路径**: `pages/mall/consumer/my-reviews.uvue`

**需求描述**:
1. **评价列表**
   - 显示已评价商品
   - 显示待评价商品
   - 显示可追加评价商品

2. **评价操作**
   - 编辑评价（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 接口详细设计

**获取商品评价列表**
```typescript
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
  }]
}
```

**获取评价统计**
```typescript
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)**
```sql
-- 添加新字段
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)**
```sql
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)**
```sql
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)**
```sql
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 积分系统技术要点

1. **积分并发安全**
   - 使用数据库事务保证积分变动原子性
   - 添加乐观锁防止超扣

2. **积分过期处理**
   - 定时任务每日检查过期积分
   - 过期前7天推送提醒通知

3. **签到防刷**
   - 限制每日只能签到一次
   - 记录签到IP，检测异常行为

### 5.2 评价系统技术要点

1. **评价数据统计**
   - 使用触发器自动更新商品评分统计
   - 缓存热门商品评价数据

2. **图片/视频处理**
   - 图片压缩后上传
   - 视频转码处理
   - CDN加速访问

3. **敏感词过滤**
   - 评价内容敏感词检测
   - 自动替换或人工审核

---

## 六、测试要点

### 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 参考文档

- [Supabase 官方文档](https://supabase.com/docs)
- [uni-app x 开发文档](https://doc.dcloud.net.cn/uni-app-x/)
- [UTS 语法指南](https://doc.dcloud.net.cn/uni-app-x/uts/)

---

**文档版本**: v1.0  
**创建日期**: 2026-03-05  
**最后更新**: 2026-03-05