# 小程序商城 (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/)