huangzhenbao/medical-mall

Fork 0

Files

cyh666666 7b5801a72b 增加推销模式

2026-03-06 17:30:50 +08:00

21 KiB

Raw Blame History

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

一、项目概述

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

21 KiB Raw Blame History Unescape Escape

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

一、项目概述

1.1 项目背景

1.2 当前实现状态

二、积分功能完善需求

2.1 功能架构图

2.2 前端功能需求

2.2.1 积分首页优化

2.2.2 每日签到功能（新增）

2.2.3 积分兑换商城（新增）

2.2.4 积分规则页面（新增）

2.3 后端API需求

2.3.1 新增API接口

2.3.2 接口详细设计

2.4 数据库设计

2.4.1 现有表结构

2.4.2 新增表结构

三、评价功能完善需求

3.1 功能架构图

3.2 前端功能需求

3.2.1 评价页面优化

3.2.2 商品评价列表（新增）

3.2.3 我的评价页面（新增）

3.2.4 配送员评价（完善）

3.3 后端API需求

3.3.1 新增API接口

3.3.2 接口详细设计

3.4 数据库设计

3.4.1 现有表结构优化

3.4.2 新增表结构

四、开发优先级

4.1 第一阶段（高优先级）

4.2 第二阶段（中优先级）

4.3 第三阶段（低优先级）

五、技术要点

5.1 积分系统技术要点

5.2 评价系统技术要点

六、测试要点

6.1 积分功能测试

6.2 评价功能测试

七、附录

7.1 相关文件路径

7.2 参考文档

21 KiB

Raw Blame History