# Sports_cloud

**Repository Path**: code_bug_error/sports_cloud

## Basic Information

- **Project Name**: Sports_cloud
- **Description**: 雄奕户外用品电商小程序
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<br />
<div align="center">
    <img src="https://qcloudimg.tencent-cloud.cn/raw/f97dc74fbf9af5d7b2b3d8bc0a4e91d4.png" alt="Logo" width="400">

  <h1 align="center">云开发电商模板</h1>

  <p align="center">
  一键创建零售商城
    <br />
  </p>
</div>

## 说明

本项目为云开发电商模板的小程序，提供首页、购物车、订单、个人中心、商品详情等页面，并扩展了**结伴购（押金模式）**功能。

本项目默认使用体验数据运行，同时也能够使用真实数据。配置好云开发后端后，即可一键切换至真实数据。

注：体验数据通过本地 Mock 数据实现。

本项目的后端可前往<https://tcb.cloud.tencent.com/cloud-template/detail?appName=electronic-business&from=wxide_tcb_shop>安装。

## 项目架构

### 技术栈

| 层 | 技术 |
|---|---|
| 前端框架 | 微信小程序原生 (WXML + WXSS + JS) |
| UI 组件库 | TDesign MiniProgram (`tdesign-miniprogram` v1.6.0) |
| 后端 | Tencent CloudBase 云函数 (Node.js 18.15) |
| 数据库 | CloudBase MongoDB（类 MongoDB） |
| 支付 | 微信支付 V3（`WECHATPAY2-SHA256-RSA2048` 签名） |
| 工具库 | dayjs（日期处理）、lodash（工具函数） |

### 目录结构

```
.
├── app.js / app.json / app.wxss   # 小程序入口、注册、全局样式
├── cloudbaserc.json               # 云开发配置（函数列表、环境变量）
├── project.config.json            # 微信开发者工具配置
│
├── cloudfunctions/                # 云函数（40+ 个，全部 Node.js 18.15）
│   ├── shop_catalog/              #   商品目录（SPU/SKU/分类查询）
│   ├── shop_cart_gateway/         #   购物车 CRUD
│   ├── shop_order_*/              #   订单（提交、列表、详情、更新）
│   ├── shop_pay / shop_refund /   #   支付与退款
│   │   └── payment_callback_gateway/
│   ├── campaign_create_group/     #   结伴购：创建团
│   ├── campaign_join_group/       #   结伴购：参团
│   ├── campaign_confirm_group/    #   结伴购：提前成团
│   ├── campaign_get_group/        #   结伴购：团详情
│   ├── campaign_get_rule/         #   结伴购：规则查询
│   ├── campaign_list_user/        #   结伴购：用户团列表
│   ├── campaign_cancel_order/     #   结伴购：取消订单
│   ├── campaign_refund_scheduler/ #   结伴购：定时退押金
│   └── campaign_expire_scheduler/ #   结伴购：定时过期处理
│
├── pages/                         # 页面层（8 个页面分组，约 37 个页面）
│   ├── home/                      #   首页（轮播、商品推荐）
│   ├── goods/                     #   商品（分类、列表、详情、搜索、评价）
│   ├── cart/                      #   购物车
│   ├── order/                     #   订单（确认、列表、详情、售后）
│   ├── campaign/                  #   结伴购（创建、邀请、列表、订单详情）
│   ├── coupon/                    #   优惠券
│   ├── usercenter/                #   个人中心（地址、信息编辑）
│   └── promotion-detail/          #   活动详情
│
├── services/                      # 服务层（桥接页面与云函数/数据库）
│   ├── good/                      #   商品服务调用
│   ├── cart/                      #   购物车服务
│   ├── order/                     #   订单服务
│   ├── campaign/                  #   结伴购服务（含支付、错误映射）
│   ├── pay/                       #   支付服务
│   ├── address/                   #   地址服务
│   ├── repository/                #   仓储层（云函数优先+DB 降级）
│   │   ├── base.js                #     基础封装：callCloudFunction、fallback
│   │   ├── goodsRepository.js     #     商品仓储
│   │   ├── cartRepository.js      #     购物车仓储
│   │   ├── orderRepository.js     #     订单仓储
│   │   └── campaignRepository.js  #     结伴购仓储
│   └── _utils/                    #   工具函数（model、delay、timeout）
│
├── components/                    # 可复用组件（11 个）
│   ├── price/                     #   价格显示（分->元格式化）
│   ├── goods-card/                #   商品卡片
│   ├── goods-list/                #   商品列表（含分页）
│   ├── filter-popup/              #   筛选弹窗
│   ├── loading-content/           #   骨架屏加载
│   └── ...
│
├── config/                        # 应用配置
│   ├── index.js                   #   功能开关、环境变量、Mock 模式
│   └── model.js                   #   实体与集合名映射
│
├── utils/                         # 工具函数
│   ├── util.js                    #   核心工具（formatTime、priceFormat、cosThumb）
│   └── campaign/status.js         #   结伴购状态文案
│
├── style/                         # 全局样式
│   └── global.wxss                #   CSS 变量、通用类、布局工具
│
├── model/ / data/                 # Mock 数据与种子数据
└── docs/                          # 文档
```

## 数据流架构

```
页面 (WXML/WXSS/JS)
  │
  │ 调用服务层函数
  ▼
服务层 (services/*/)
  │
  ├── config/index.js 检查功能开关 isDataLayerEnabled()
  │
  ├── [主路径 - 仓储层] repository/base.js: callCloudFunction()
  │       │
  │       │ wx.cloud.callFunction()
  │       ▼
  │   云函数 (cloudfunctions/*/index.js)
  │       │
  │       │ wx-server-sdk: cloud.database()
  │       ▼
  │   CloudBase 数据库 (MongoDB collections)
  │
  └── [降级路径 - 云函数失败时]
          │
          │ wx.cloud.database() 直连
          ▼
      CloudBase 数据库
```

### 核心设计模式

1. **双路径数据访问**：每次数据操作优先调用云函数，云函数失败后自动降级为前端直连数据库，兼顾服务端逻辑优势与容错性。

   ```
   try { cloudFunction() } catch { directDB() }
   ```

2. **渐进式仓储层**：通过 `config/index.js` 中的 `dataLayerSwitches` 开关（goods/cart/order/campaign），逐步从旧版 Data Model SDK 迁移到新的 Repository 模式。

3. **统一错误映射**：结伴购等模块将后端错误码统一映射为中文提示，见 `services/campaign/errorMap.js`。

4. **全量价格以分为单位**：数据库统一存储整数分，展示时通过 `priceFormat()` 转为元。

## 核心业务流程

### 结伴购（押金模式）

```
发起人选规格 → 创建团（付全额押金）→ 分享邀请链接
                                          │
                              好友点击链接 → 选规格/地址 → 参团支付
                                          │
                              人数达标 → 自动成团 / 发起人手动确认成团
                                          │
                              锁单期 → 到期自动退押金
```

关键设计：
- **阶梯折扣**：2人 9折 / 3人 8折 / 4人 7折 / 5人 6折，发起人创建时自选目标人数
- **提前成团**：已支付人数 >= 2 时发起人可手动"确认成团"，立即进入锁单期
- **24小时邀请有效期**：超过创建时间 24 小时的邀请链接自动过期
- **参团必选规格**：好友点击链接后必须重新选择商品规格与收货地址，不继承发起人选择

### 支付流程

```
页面请求支付 → shop_pay 云函数生成 prepay_id
    → 返回微信支付参数 → 前端 wx.requestPayment()
    → 微信异步通知 → payment_callback_gateway
    → pay_notify_handler 更新订单状态
```

## 数据库集合

| 集合 | 用途 |
|---|---|
| `shop_spu` | 商品主数据 |
| `shop_sku` | SKU（规格、价格、库存） |
| `shop_spu_cate` | 分类树 |
| `shop_attr_value` | 属性值 |
| `shop_cart_item` | 购物车 |
| `shop_order` | 订单 |
| `shop_comment` | 评价 |
| `shop_delivery_info` | 收货地址 |
| `user_info` | 用户信息 |
| `campaign_group` | 结伴团 |
| `campaign_member` | 团成员 |
| `campaign_rule` | 结伴购规则 |

## 社区

欢迎添加企微群沟通交流：

<div>
    <img src="https://qcloudimg.tencent-cloud.cn/raw/bbb904f6fd6da01aa677e8a31e37651d.jpg" style="width:30%;">
</div>

## 安装依赖

1. 安装 npm 依赖

```shell
npm install
```

 如果安装失败，请检查是否有足够权限执行命令，或尝试用更高权限安装依赖：

 ```shell
 sudo npm install
 ```

2. 构建 npm
点击微信开发者工具菜单栏中的「工具」->「构建 npm」

## 运行小程序

在微信开发者工具中导入本项目即可运行，若想配合后端运行完整应用，请前往<https://tcb.cloud.tencent.com/cloud-template/detail?appName=electronic-business&from=wxide_tcb_shop>安装。

## 部署云函数

```shell
# 部署单个云函数
npx tcb functions:deploy <function-name>

# 部署所有云函数
npx tcb functions:deploy
```

## 结伴购文档

- `docs/campaign-cloud-schema.md` — 数据库集合与索引配置
- `docs/rest-to-cloudfunction-mapping.md` — REST to 云函数迁移映射
- `docs/campaign-rule-seed.example.json` — 规则种子数据
- `docs/campaign-e2e-checklist.md` — 端到端验收清单