小程序商城 (shop-taro)

基于 Taro + React + TypeScript 的微信小程序商城系统，支持多门店、VIP 会员、拼团秒杀、积分商城、分销裂变等完整电商业务场景。

作者: 科技小王子
版本: 1.0.0
License: MIT

---

技术栈

分类	技术	版本	说明
跨端框架	Taro	4.1.11	支持微信/H5/支付宝等多端编译
UI 框架	React	18.3.1	函数组件 + Hooks
类型系统	TypeScript	5.7.2	严格模式
组件库	NutUI React Taro	2.7.4	京东风格组件库
原子化 CSS	TailwindCSS	3.4.17	含 weapp-tailwindcss 适配
CSS 预处理	Sass	^1.81.0
日期处理	Day.js	^1.11.13
加密	Crypto-js	^4.2.0	AES / MD5
图表	ECharts Taro3 React	^1.0.13	数据可视化
二维码	weapp-qrcode	^1.0.0	小程序码生成

Node 版本要求: >= 18

---

核心业务功能

商城交易

• 商品浏览 / 搜索 / 分类筛选
• 商品详情 + 多规格 SKU 选择
• 购物车（合并加购、批量操作）
• 下单结算（普通订单 / 拼团 / 秒杀）
• 订单管理（待付款 / 待发货 / 待收货 / 已完成）
• 售后退款申请与进度跟踪
• 发票申请与抬头管理

会员体系

• 手机号授权登录（微信一键 + 短信验证码降级）
• VIP 会员申请与审核（门店店员审核）
• VIP 专享价（dealerPrice）
• 会员权益包兑换
• 积分系统（签到 / 积分商品兑换 / 积分明细）
• 用户余额（充值 / 消费 / 提现）

分销与裂变

• 邀请下级注册
• 分销佣金记录
• 分享海报（Canvas 绘制 + 小程序码）
• 朋友圈分享 / 复制链接
• 邀请归因追踪

门店管理（店员端）

• 门店中心（订单 / 商品 / 用户管理）
• VIP 审核（通过 / 驳回）
• 订单修改金额与备注
• 上传发货凭证
• 门店会员管理（搜索 / 筛选 / 禁用启用）

营销活动

• 拼团（单独成团 / 参团）
• 秒杀（限时抢购）
• 优惠券（领取中心 / 下单核销）
• 赛事报名
• 预约订单
• 礼品卡（购买 / 兑换 / 余额查询）
• 文章资讯 / 公告通知

其他

• 浏览历史记录（服务端去重累加）
• 商品收藏
• 客服会话
• 数据统计看板（销售 / 用户）
• 微信隐私协议授权弹窗
• 订阅消息推送（新订单提醒）

---

快速开始

安装依赖

pnpm install

开发模式

# 微信小程序（主要目标平台）
pnpm dev:weapp

# H5
pnpm dev:h5

生产构建

pnpm build:weapp
pnpm build:h5

代码检查

# ESLint 修复
pnpm lint

# TypeScript 类型检查
pnpm type-check

构建产物在 dist/ 目录，使用微信开发者工具打开该目录进行预览和调试。

---

项目结构

shop-taro/
├── config/                        # Taro 编译配置
│   ├── index.ts                   # 主配置
│   ├── dev.ts                     # 开发环境
│   └── prod.ts                    # 生产环境
├── src/
│   ├── app.tsx                    # 应用入口
│   ├── app.config.ts              # 路由 / tabBar / 全局配置
│   ├── app.scss                   # 全局样式
│   ├── pages/                     # 页面目录
│   │   ├── index/                 # 首页（tabBar）
│   │   ├── shop/                  # 商城（分类/详情/购物车/结算/拼团/秒杀）
│   │   ├── user/                  # 用户中心（tabBar）
│   │   ├── points/                # 积分商城
│   │   ├── order/                 # 订单管理
│   │   ├── store/                 # 门店管理（店员端）
│   │   ├── after-sale/            # 售后退款
│   │   ├── activity/              # 营销活动
│   │   ├── event/                 # 赛事报名
│   │   ├── booking/               # 预约订单
│   │   ├── message/               # 消息通知
│   │   ├── gift-card/             # 礼品卡
│   │   ├── invoice/               # 发票
│   │   ├── share/                 # 分享返利
│   │   ├── rebate/                # 返利记录
│   │   └── statistics/            # 数据统计
│   ├── passport/                  # 登录/注册/短信登录/扫码登录
│   ├── components/                # 公共组件
│   │   ├── business/              # 业务组件
│   │   ├── common/                # 通用组件
│   │   ├── layout/                # 布局组件
│   │   ├── NavBar/                # 导航栏
│   │   ├── SharePoster/           # 分享海报
│   │   ├── PrivacyModal/          # 隐私协议弹窗
│   │   └── ErrorBoundary.tsx      # 错误边界
│   ├── contexts/                  # 全局状态 Context
│   │   ├── AppContext.tsx         # 应用上下文
│   │   ├── UserContext.tsx        # 用户信息
│   │   └── CartContext.tsx        # 购物车
│   ├── hooks/                     # 自定义 Hooks
│   │   ├── useUser.ts             # 用户信息
│   │   ├── useVipStatus.ts        # VIP 状态（响应式）
│   │   ├── useShare.ts            # 分享/朋友圈/复制链接
│   │   ├── usePayment.ts          # 支付
│   │   ├── useAddress.ts          # 收货地址
│   │   ├── useNewOrderDetector.ts # 新订单轮询检测
│   │   ├── useCountDown.ts        # 倒计时
│   │   ├── usePagination.ts       # 分页
│   │   ├── useRequest.ts          # 请求封装
│   │   └── ...
│   ├── api/                       # 后端接口封装
│   │   ├── shop/                  # 商城业务接口（50+ 模块）
│   │   ├── system/                # 系统接口（文件上传等）
│   │   ├── passport/              # 认证接口
│   │   ├── cms/                   # 内容管理
│   │   └── share.ts               # 分享相关
│   ├── utils/                     # 工具函数
│   │   ├── request.ts             # 网络请求封装
│   │   ├── auth.ts                # 用户禁用拦截
│   │   ├── vip.ts                 # VIP 状态判断
│   │   ├── privacy.ts             # 隐私授权管理
│   │   ├── invite.ts              # 邀请参数解析
│   │   ├── server.ts              # 服务器地址
│   │   ├── image.ts               # 图片处理
│   │   ├── geofence.ts            # 地理围栏
│   │   └── common.ts              # 通用工具
│   ├── types/                     # TypeScript 类型定义
│   ├── styles/                     # 全局样式
│   └── assets/                    # 静态资源（tabBar 图标等）
├── package.json
├── tsconfig.json
├── tailwind.config.js
├── postcss.config.js
├── project.config.json            # 小程序项目配置
└── README.md

---

tabBar 配置

Tab	页面路径	图标	说明
首页	pages/index/index	home	商城首页、Banner、快捷入口
分类	pages/shop/index	category	商品分类与列表
购物车	pages/shop/cart	cart	购物车管理
我的	pages/user/user	user	个人中心

---

关键技术实现

VIP 会员价格体系

商品价格字段约定：

字段	含义
product.price	到手价（主价格）
product.salePrice	市场价（划线价）
product.dealerPrice	VIP 会员专享价
product.memberStorePrice	会员价

• 使用 useVipStatus Hook 实现响应式 VIP 状态更新
• VIP 状态通过异步校验缓存，组件挂载时自动刷新

微信隐私协议（基础库 3.16.1+）

• 调用 chooseImage / getPhoneNumber 等敏感 API 前预检授权
• app.tsx 注册 onNeedPrivacyAuthorization 回调
• PrivacyModal 组件展示授权弹窗

手机号登录降级方案

• 微信 getPhoneNumber 被拒绝后自动降级到短信验证码登录
• 统一错误处理弹窗，引导跳转短信登录页

分享裂变

• useShare Hook 一次注册 useShareAppMessage + useShareTimeline
• 分享链接自动追加 inviter 参数做归因
• SharePoster 组件用 Canvas 2D 绘制海报 + 小程序码

用户禁用机制

• User.status 字段：0 正常 / 1 禁用
• 多层级拦截：UserContext 启动校验 + 登录检查 + 页面入口检查

---

代码示例

使用 NutUI 组件

import { Button, Cell, CellGroup } from '@nutui/nutui-react-taro'

export default function MyPage() {
  return (
    <CellGroup>
      <Cell title="标题" description="描述" />
      <Button type="primary" block>提交</Button>
    </CellGroup>
  )
}

使用 TailwindCSS

<View className="p-4 bg-white">
  <Text className="text-lg font-bold text-gray-800">商品名称</Text>
</View>

使用 VIP 状态 Hook

import { useVipStatus } from '@/hooks/useVipStatus'

export default function ProductCard({ product }) {
  const { isVip } = useVipStatus()

  const displayPrice = isVip ? product.dealerPrice : product.price

  return <Text className="text-red-500">¥{displayPrice}</Text>
}

使用分享 Hook

import { useShare } from '@/hooks/useShare'

export default function ProductDetail({ product }) {
  useShare({
    title: product.name,
    path: '/pages/shop/product-detail',
    query: { id: product.id },
    enableTimeline: true,
    enableCopyUrl: true,
  })
  // ...
}

网络请求

import { getShopOrderList } from '@/api/shop/shopOrder'

const { data } = await getShopOrderList({ status: 'pending', page: 1 })

---

开发规范

文件命名

• 页面目录：kebab-case（如 product-detail/）
• 组件文件：PascalCase（如 ProductCard.tsx）
• 工具文件：camelCase（如 formatDate.ts）

代码风格

• 2 空格缩进
• 单引号优先
• 分号结尾
• ESLint + @typescript-eslint 检查

提交规范

feat:     新功能
fix:      修复 bug
docs:     文档更新
style:    代码格式调整
refactor: 代码重构
test:     测试相关
chore:    构建/工具配置

---

常见问题

TailwindCSS 样式在小程序中不生效？

检查 postcss.config.js 和 tailwind.config.js 配置，确保已安装 weapp-tailwindcss 并正确配置 content 路径。

NutUI 组件样式丢失？

确保在 app.scss 中引入了 NutUI 样式文件。

TypeScript 路径别名 @/* 报错？

检查 tsconfig.json 的 paths 配置，并确保 IDE（VS Code）正确识别。

隐私协议报错 errno:112？

小程序后台需配置用户隐私保护指引，声明相册/摄像头/手机号等权限。

---

相关文档

• Taro 官方文档
• React 官方文档
• NutUI React Taro 文档
• TailwindCSS 文档
• TypeScript 文档
• 微信小程序文档