shop/说明文档.md

一、核心功能模块

1.1 商品管理系统

1.1.1 商品基础信息 2.1商品属性2.1: 名称、描述、价格、原价、图片、分类、标签 2.1库存管理2.1: 库存数量、销量统计、商品状态 2.1分类体系2.1: 花香调(floral)、草本调(herbal)等香调分类

1.1.2 商品展示 2.1多视图模式2.1: 网格视图、列表视图切换 2.1商品卡片2.1: 包含价格、折扣、评分、评论数、点赞数 2.1商品详情2.1: 详细描述、用户评价、相关推荐

1.2 拼团购买系统

1.2.1 拼团配置 2.1阶梯拼团2.1: 3人团：7折优惠，团长获得200积分 5人团：5折优惠，团长获得300积分 2.1时间限制2.1: 默认24小时拼团时间 2.1每日限量2.1: 支持设置每日拼团限量

1.2.2 拼团流程 2.1发起拼团2.1: 用户选择商品和拼团规模 2.1邀请参团2.1: 分享拼团链接邀请好友 2.1实时进度2.1: 显示当前参团人数和剩余时间 2.1自动成团2.1: 达到目标人数自动成团 2.1溯源码2.1: 成功拼团生成唯一溯源码

1.2.3 秒杀功能 2.1秒杀配置2.1: 特定时间点(如10:00)开启秒杀 2.1限量抢购2.1: 设置秒杀库存和价格 2.1防刷机制2.1: 避免恶意刷单

1.3 订阅盲盒系统

1.3.1 订阅计划 2.1月度订阅2.1: 每月配送香水盲盒 2.1季度订阅2.1: 每季度配送，享受更多优惠 2.1配送设置2.1: 用户可选择配送频率和日期

1.3.2 盲盒机制 2.1香调排除2.1: 用户可排除不喜欢的香调 2.1解锁系统2.1: 逐步解锁新香调 2.1个性化推荐2.1: 基于用户偏好推荐

1.3.3 会员折扣 2.1探索会员2.1: 95折优惠 2.1品鉴会员2.1: 85折优惠 2.1调香会员2.1: 专属折扣和服务

1.4 会员积分体系

1.4.1 积分获取 2.1购买获得2.1: 消费金额的一定比例 2.1拼团奖励2.1: 团长额外积分奖励 2.1分销奖励2.1: 推广订单获得积分 2.1UGC内容2.1: 发布评价、教程等获得积分

1.4.2 会员等级 2.1探索会员2.1: 无门槛，享受基础权益 2.1品鉴会员2.1: 累计消费满500元，享受更多优惠 2.1调香会员2.1: 累计消费满2000元，享受VIP服务

1.4.3 积分使用 2.1商品兑换2.1: 积分兑换商品或优惠券 2.1线下体验2.1: 积分兑换线下调香体验 2.1会员升级2.1: 积分加速会员等级提升

1.5 分销推广系统

1.5.1 分销员体系 2.1等级制度2.1: 探索、品鉴、调香三级分销员 2.1佣金比例2.1: 直接推广: 10%佣金 间接推广: 5%佣金 2.1团队管理2.1: 查看下级分销员和业绩

1.5.2 推广工具 2.1分享链接2.1: 生成专属推广链接 2.1素材库2.1: 提供推广图片和文案 2.1数据统计2.1: 实时查看推广效果

1.5.3 佣金结算 2.1结算周期2.1: 订单完成后进入结算流程 2.1提现功能2.1: 支持佣金提现到账户 2.1税务处理2.1: 符合相关税务规定

1.6 用户生成内容系统

1.6.1 内容类型 2.1商品评价2.1: 用户购买后的使用体验分享 2.1使用教程2.1: 香水使用技巧和搭配指南 2.1香水故事2.1: 个人香水使用故事和心得

1.6.2 激励机制 2.1积分奖励2.1: 发布优质内容获得积分奖励 2.1精选推荐2.1: 优质内容获得平台首页推荐 2.1专家认证2.1: 优秀创作者获得专家标识

1.6.3 内容管理 2.1审核机制2.1: 内容发布前进行质量审核 2.1互动功能2.1: 支持点赞、评论、分享功能 2.1数据统计2.1: 查看内容浏览量和互动数据

1.7 订单管理系统

1.7.1 订单流程 2.1下单2.1: 选择商品、数量、配送信息 2.1支付2.1: 支持多种支付方式 2.1发货2.1: 商家发货并提供物流信息 2.1收货2.1: 用户确认收货完成交易

1.7.2 订单状态 2.1待支付2.1: 订单创建等待支付 2.1已支付2.1: 支付完成等待发货 2.1已发货2.1: 商品已发出在途中 2.1已完成2.1: 用户确认收货 2.1已取消2.1: 订单被取消

1.7.3 售后服务 2.1退换货2.1: 支持7天无理由退换货 2.1客服支持2.1: 在线客服解决问题 2.1投诉处理2.1: 完善的投诉处理机制

二、用户角色与权限

2.1 普通用户 浏览商品、参与拼团 购买商品、管理订单 参与订阅服务 发布UGC内容 查看积分和会员信息

2.2 分销员 普通用户所有权限 生成推广链接 查看推广数据 管理下级分销员 佣金提现

2.3 管理员 商品管理 订单管理 用户管理 数据统计 系统配置

三、进度记录

• 2024-01-10：初始化项目结构，完成基础页面搭建（首页、商品详情页、拼团页、订阅页、会员页、分销页）。

• 2024-01-12：完成分销模块基础功能（分销仪表盘、团队成员卡片、基础统计）。

• 2024-01-14：引入 WebSocket 实时消息通道（server.ts + src/lib/socket.ts），实现基础连接与欢迎消息下发。

• 2024-01-15：修复本地构建问题（移除 next/font 用法、globals.css 语法修正、postcss.config.mjs 配置清理）。

• 2024-01-16：停止本地开发尝试，转向远程部署方案（Vercel/Node/Docker），并更新部署计划。

• 2024-01-16（追加）：修复分销订单页构建错误 missing-suspense-with-csr-bailout。

  • 原因：页面顶层直接使用 useSearchParams（客户端）导致预渲染期间 CSR Bailout，缺少 Suspense 边界。
  • 方案：将 src/app/distribution/orders/page.tsx 改为服务端页面，引入 <Suspense> 包裹新的客户端子组件 member-orders-client.tsx。
  • 结果：npm run build 构建通过；使用 next start 启动生产服务器后可正常预览。
  • 影响：页面 UI 保持一致，渲染策略优化以满足 Next.js 官方要求。

• 2025-11-04：修复开发环境 ERR_INVALID_URL_SCHEME 与自定义服务器冲突。

  • 原因：使用 nodemon + tsx server.ts 启动导致 Next.js 构建链路（CSS/PostCSS 与 URL 解析）在 ESM 钩子下解析失败，触发 The URL must be of scheme file。
  • 方案：
    • package.json：将 dev 改为 next dev，start 改为 next start；
    • 移除 src/app/layout.tsx 中 next/font 的导入与变量，避免在非官方服务器下的 URL 解析问题；
    • 保留 /distribution/orders 的服务端包装与 <Suspense> 客户端子组件结构。
  • 验证：
    • pnpm run dev 正常启动；http://localhost:3000/ 无错误；
    • 访问 http://localhost:3000/distribution/orders 页面正常，只有开发模式 HMR 的资源 404 与全量重载提示，不影响功能；
    • 终端未再出现 ERR_INVALID_URL_SCHEME 或 next/font 相关错误。
  • 结果：开发与预览稳定，后续统一使用官方 next dev/next start。

• 2025-11-04：新增完整购买流程与支付页面。

  • 内容：
    • 新增组件 src/components/purchase-dialog.tsx，引导填写收货信息、选择配送与支付方式、确认下单；
    • 产品详情页 src/app/product/[id]/page.tsx 集成“立即购买”触发对话框；
    • 新增支付页 src/app/order/payment/page.tsx，支持支付宝/微信二维码与银行卡表单的模拟支付；
    • 更新订单成功页 src/app/order/success/page.tsx 展示支付状态（已支付/待支付）。
  • 流程：点击“立即购买”→ 对话框确认下单 → 跳转支付页 → 确认支付 → 成功页展示摘要与状态。
  • 结果：开发环境验证通过，交互与 UI 正常；支付为模拟流程（本地存储），后续可接入真实支付 SDK/网关。