371 lines
11 KiB
Markdown
371 lines
11 KiB
Markdown
# 小程序商城 (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 审核（通过 / 驳回）
|
||
- 订单修改金额与备注
|
||
- 上传发货凭证
|
||
- 门店会员管理（搜索 / 筛选 / 禁用启用）
|
||
|
||
### 营销活动
|
||
- 拼团（单独成团 / 参团）
|
||
- 秒杀（限时抢购）
|
||
- 优惠券（领取中心 / 下单核销）
|
||
- 赛事报名
|
||
- 预约订单
|
||
- 礼品卡（购买 / 兑换 / 余额查询）
|
||
- 文章资讯 / 公告通知
|
||
|
||
### 其他
|
||
- 浏览历史记录（服务端去重累加）
|
||
- 商品收藏
|
||
- 客服会话
|
||
- 数据统计看板（销售 / 用户）
|
||
- 微信隐私协议授权弹窗
|
||
- 订阅消息推送（新订单提醒）
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 开发模式
|
||
|
||
```bash
|
||
# 微信小程序（主要目标平台）
|
||
pnpm dev:weapp
|
||
|
||
# H5
|
||
pnpm dev:h5
|
||
```
|
||
|
||
### 生产构建
|
||
|
||
```bash
|
||
pnpm build:weapp
|
||
pnpm build:h5
|
||
```
|
||
|
||
### 代码检查
|
||
|
||
```bash
|
||
# 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 组件
|
||
|
||
```tsx
|
||
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
|
||
|
||
```tsx
|
||
<View className="p-4 bg-white">
|
||
<Text className="text-lg font-bold text-gray-800">商品名称</Text>
|
||
</View>
|
||
```
|
||
|
||
### 使用 VIP 状态 Hook
|
||
|
||
```tsx
|
||
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
|
||
|
||
```tsx
|
||
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,
|
||
})
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 网络请求
|
||
|
||
```tsx
|
||
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 官方文档](https://docs.taro.zone/)
|
||
- [React 官方文档](https://react.dev/)
|
||
- [NutUI React Taro 文档](https://nutui.jd.com/taro/react/2x/)
|
||
- [TailwindCSS 文档](https://tailwindcss.com/docs)
|
||
- [TypeScript 文档](https://www.typescriptlang.org/docs/)
|
||
- [微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
|