【UrShop 专属】对接 UrShop（urshop.cn）后端的小程序商城开发规范

使用边界（先读这段，避免选错技能）

> ⚠️ 本技能只在用户明确要求对接 UrShop（urshop.cn / 优社电商）后端时使用，端点前缀 /v1/...、返回体 Code/Data（大写）。
>
> 它与 Ushopun（优社云AI，dev.ushopun.com，端点前缀 /api/v2、返回体 code/content/data 小写）是两套完全不同的后端。若用户只是泛泛说「小程序商城 / 商城小程序 / 电商小程序」，或提到 Ushopun / 优社云 / dev.ushopun.com，请改用技能 miniprogram-mall-ushopun-official，不要用本技能生成代码。

概述

本 Skill 用于开发对接 UrShop（优社电商） 后端的微信小程序商城前端。UrShop 是一套成熟的电商后端系统，提供标准 RESTful API，本 Skill 涵盖了所有核心 API 接口说明、数据格式、调用方式及前端页面实现规范。

> 获取 UrShop 后端：请访问 UrShop 官网或联系优社电商获取后端部署包，包含数据库脚本、API 服务、管理后台。

项目结构

miniProgram/
├── api/
│   ├── conf.js          # UrShop API 端点常量（完整接口清单）
│   └── api.js           # HTTP 请求封装（自动注入鉴权、店铺上下文）
├── pages/               # 页面
│   ├── index/           # 首页
│   ├── category/        # 分类
│   ├── subcategory/     # 二级分类
│   ├── detail/          # 商品详情
│   ├── search/          # 搜索
│   ├── cart/            # 购物车
│   ├── checkout/        # 结算下单
│   ├── order/           # 订单管理
│   ├── orderList/       # 订单列表
│   ├── checkoutdetail/  # 订单详情
│   ├── payFinish/       # 支付成功
│   ├── my/              # 个人中心
│   ├── login/           # 登录
│   ├── address/         # 地址管理
│   ├── address-edit/    # 地址编辑
│   ├── collect/         # 收藏
│   ├── comment/         # 评价
│   ├── distribution/    # 分销中心
│   ├── youhuijuan/      # 优惠券
│   ├── available_coupon/# 可用优惠券
│   ├── usedcunpond/     # 选择优惠券
│   ├── recharge/        # 充值
│   ├── point/           # 积分
│   ├── cashout/         # 提现
│   ├── warrant/         # 授权
│   ├── supplier/        # 供应商
│   ├── partner/         # 合伙人
│   ├── returnrequests/  # 售后申请
│   ├── returndetail/    # 售后详情
│   ├── wuliuxinxi/      # 物流信息
│   ├── sharepage/       # 分享页
│   ├── salePage/        # 销售页
│   ├── saleOrder/       # 销售订单
│   ├── myCustomer/      # 我的客户
│   ├── myinvitre/       # 我的邀请
│   ├── bonusDetail/     # 分红详情
│   ├── dividend/        # 分红
│   ├── question/        # 常见问题
│   ├── questionList/    # 问题列表
│   ├── platform/        # 平台
│   ├── idcar/           # 身份证
│   ├── pwdset/          # 密码设置
│   └── welcome/         # 欢迎页
├── templates/           # 可复用模板
├── style/               # 公共样式
├── utils/               # 工具函数
├── images/              # 图片
├── libs/                # 第三方库（腾讯地图SDK等）
├── wxParse/             # 富文本解析
├── data/                # 静态数据
├── app.js
├── app.json
└── app.wxss

一、UrShop API 对接规范

1.1 基础配置

// app.js globalData
host: 'https://your-domain.urshop.cn/api'  // UrShop API 地址

1.2 请求封装（api/api.js）

所有请求统一入口，自动注入鉴权和店铺上下文：

const app = getApp()
const request = (url, options) => {
  return new Promise((resolve, reject) => {
    var shopId = 0
    if (wx.getStorageSync('adress')) { 
      shopId = wx.getStorageSync('adress').Id
    }
    url = `${app.globalData.host}${url}`
    wx.request({
      url: url,
      method: options.method,
      data: options.method === 'GET' ? options.data : JSON.stringify(options.data),
      header: {
        'Content-Type': 'application/json; charset=UTF-8',
        guid: wx.getStorageSync('guid'),          // 用户唯一标识
        authorization: wx.getStorageSync('token'), // 鉴权 Token
        shopId: shopId                             // 店铺/分店 ID
      },
      success(request) {
        if (request.data.Code === 200) {
          resolve(request.data)
        } else if (request.data.Code === 401) {
          resolve(request.data)  // 未授权，由调用方处理跳转登录
        } else {
          reject(request.data)   // 业务错误，Content 字段含错误描述
        }
      },
      fail(error) { reject(error.data) }
    })
  })
}

const get    = (url, options = {}) => request(url, { method: 'GET', data: options })
const post   = (url, options) => request(url, { method: 'POST', data: options })
const put    = (url, options) => request(url, { method: 'PUT', data: options })
const remove = (url, options) => request(url, { method: 'DELETE', data: options })

module.exports = { get, post, put, remove }

1.3 响应格式

UrShop 所有 API 统一返回格式：

{
  "Code": 200,
  "Data": { ... },
  "Content": "错误描述（Code != 200 时）"
}

二、UrShop API 接口全览（按模块）

2.1 用户认证模块（AUTH）

登录流程：

1. wx.login() → 获取 code
2. api.get(weixinopenlogin, { code, guid, encryptedData, iv, state })
   → 返回 { Data: { guid, token, openId } }
3. wx.setStorageSync('guid', data.guid)
4. wx.setStorageSync('token', data.token)
5. api.get(getcustomer) → 获取完整用户信息（邀请码、头像等）

获取手机号：

// WXML 按钮
<button open-type="getPhoneNumber" bindgetphonenumber="getPhoneNumber">授权手机号</button>

// JS 处理
getPhoneNumber(e) {
  wx.login({
    success(res) {
      api.get(weixinopenphonenumber, {
        code: res.code,
        encryptedData: e.detail.encryptedData,
        iv: e.detail.iv
      }).then(res => {
        wx.setStorageSync('phone', res.Data.phone)
      })
    }
  })
}

2.2 首页模块（HOME）

2.3 商品模块（PRODUCT）

商品详情 Data 关键字段：

{
  "Id": 1234,
  "Name": "商品名称",
  "Price": "￥99.00",
  "OldPrice": "￥199.00",
  "ProductCost": "￥50.00",
  "StockQuantity": 100,
  "SaleVolume": 500,
  "Published": true,
  "IsSpecialProduct": false,
  "SpecialStartDate": "2024-01-01 00:00:00",
  "SpecialEndDate": "2024-12-31 23:59:59",
  "Pictures": [{ "BigUrl": "https://...", "NormalUrl": "https://..." }],
  "AttrValueList": [{ "Id": 1, "AttributesXml": "颜色:红色[S]", "Price": "￥99.00", "Qty": 50 }],
  "Full": "<p>商品详情HTML</p>",
  "PushSystem": false,
  "RebateAmount": 10.00,
  "ShippingAddress": "全国包邮",
  "IsIDUpload": false
}

SKU 多属性联动解析：

// getproductattr 返回的 tables 结构
// { attrs: [{ name: "颜色", attrValArr: [{ name: "红色", value: "红色" }, ...] }, ...],
//   tables: [{ info: { qty: 50, price: 99, sku: "R001" }, arrs: [{ value: "红色" }, { value: "M" }] }] }
// 需要转换为键值对形式用于快速匹配

2.4 分类模块（CATEGORY）

2.5 搜索模块（SEARCH）

2.6 购物车模块（CART）

购物车 Item 结构：

{
  "Id": 1,
  "Name": "商品名",
  "ProductType": "新品",
  "Picture": { "NormalUrl": "https://..." },
  "UnitPrice": "￥99.00",
  "Qty": 2,
  "Selected": true,
  "Warnings": ["库存不足"]
}

2.7 收藏/心愿单模块（FAVORITES）

2.8 结算/下单模块（CHECKOUT）

submitcheckout 参数说明：

2.9 支付模块（PAYMENT）

完整支付流程：

// 1. 提交订单
api.post(submitcheckout, { AddressId, PaymentMethod, Balance, Remark, CouponId })
  .then(res => {
    const orderId = res.Data.OrderId
    // 2. 处理子订单（如果有）
    if (res.Data.SubOrders) {
      // 展示子订单列表，逐个支付
    } else {
      // 3. 发起支付
      pay(orderId)
    }
  })

function pay(orderId) {
  api.get(paymentweixinwap, { orderId, paytype: 'Order' })
    .then(res => {
      const rep = res.Data.KeyValue
      wx.requestPayment({
        timeStamp: rep.timeStamp,
        nonceStr: rep.nonceStr,
        package: rep.package,
        signType: rep.signType,
        paySign: rep.paySign,
        success() { /* 跳转支付成功页 */ },
        fail()    { /* 提示支付失败 */ }
      })
    })
}

2.10 订单模块（ORDER）

订单状态映射：

2.11 地址模块（ADDRESS）

2.12 物流模块（LOGISTICS）

2.13 钱包/账户模块（WALLET）

2.14 优惠券模块（COUPON）

2.15 评价模块（REVIEW）

2.16 分销/代理模块（DISTRIBUTION）

三、核心业务流程

3.1 用户登录授权流程

┌─────────────┐
│ wx.login()  │ → 获取临时 code
└──────┬──────┘
       ↓
┌──────────────────────────────────┐
│ wx.getUserProfile() 获取用户信息  │ → encryptedData, iv
└──────┬───────────────────────────┘
       ↓
┌──────────────────────────────────────────────────┐
│ api.get(weixinopenlogin, { code, guid,            │
│   encryptedData, iv, state })                     │
│ → 返回 { guid, token, openId }                    │
│ → 存储 guid, token 到 Storage                     │
└──────┬───────────────────────────────────────────┘
       ↓
┌────────────────────────┐
│ api.get(getcustomer)   │ → 获取完整用户信息 + 邀请码
└──────┬─────────────────┘
       ↓
┌──────────────────────────────────────────────┐
│ <button open-type="getPhoneNumber">           │
│ → api.get(weixinopenphonenumber)             │
│ → 存储 phone 到 Storage                       │
└──────────────────────────────────────────────┘

3.2 商品购买完整流程

详情页 → 选择规格SKU → 加入购物车 / 立即购买
                          ↓
                    购物车列表 → 勾选商品 → 去结算
                          ↓
                    结算页(选择地址、优惠券、支付方式)
                          ↓
                    提交订单(submitcheckout)
                          ↓
                  ┌──────┴──────┐
                  ↓              ↓
             无子订单        有子订单(SubOrders)
                  ↓              ↓
          微信支付调用      逐个展示子订单
                  ↓              ↓
          支付成功          逐个子订单支付
                  ↓              ↓
        跳转成功页       全部支付完成

3.3 分销推广流程

用户A 分享小程序（携带邀请码 code）
      ↓
用户B 通过分享链接进入
      ↓
wx.setStorageSync('code', code) → 存储推荐码
      ↓
用户B 完成登录授权
      ↓
api.get(referrerauto) → 自动绑定推荐关系
      ↓
用户B 下单消费 → 用户A 获得佣金/分红

3.4 代理申请流程

个人中心 → 点击"成为合伙人"
      ↓
api.get(agentsupgrade)
      ↓
Code=200 → 已是代理，直接进入分销中心
Code=220 → 未申请/审核中 → 弹出表单
      ↓
填写真实姓名 + 手机号 → api.post(agentspostinfo, { RealName, Phone })
      ↓
提交成功 → 等待审核

四、页面实现要点

4.1 首页（index）

• 轮播图：api.get(banner, { name: 'homehotbanner' }) → res.Data.Items[].Picture.BigUrl
• 分类入口：api.get(homecategories) → 网格展示
• 热卖商品：api.get(productbytag, { tagName: '热卖', tagshow: true }) → 横向滚动
• 分类商品：先 api.get(hotcategory) 获取热门分类，再对每个分类调用 api.get(searCate, { cid, size: 3 })
• 分店切换：展示 app.globalData.currentAdress，点击跳转 options 页面

4.2 商品详情（detail）

• 商品信息：api.get(productId, { id }) → 完整商品数据
• 富文本：使用 wxParse 渲染 res.Data.Full
• SKU 面板：api.get(getproductattr, { pId }) → 多属性联动
• 加入购物车：api.post(producttocart, { PId, Qty, AttrValue })
• 立即购买：api.post(producttocheckout, { PId, Qty, AttrValue }) → 跳转 checkout
• 收藏切换：api.post(favoritessubmits, { ProductId }) / api.post(remove + '?id=' + id)
• 特价倒计时：解析 SpecialStartDate / SpecialEndDate，setTimeout 每秒刷新

4.3 购物车（cart）

• 列表：api.get(getShoppingcart) → res.Data.Items
• 选中切换：api.post(updatecartitem, { Id, Quantity, Selected: !selected })
• 数量修改：api.post(updatecartitem, { Id, Quantity, Selected })
• 全选：api.post(cartallselected + '?selected=' + flag, {})
• 删除：api.post(removecartitem + '?id=' + id, {})
• 结算：api.get(checkminsubtotal) 检查后跳转 checkout

4.4 结算页（checkout）

• 结算数据：api.get(getcheckout) → 商品清单、地址、运费、合计
• 可用优惠券：api.get(usablecoupon, { orderTotal })
• 钱包余额：api.get(wallet) → res.Data.AvailAmount
• 提交订单：api.post(submitcheckout, { AddressId, PaymentMethod, Balance, Remark, CouponId, RentDays, PushSystem })
• 支付：api.get(paymentweixinwap, { orderId, paytype: 'Order' }) → wx.requestPayment
• 租赁：isrent=true 时需填写租赁天数，计算 rentPrice = rentUnitPrice × days

4.5 订单（order）

• 列表：api.get(orderList, { orderstatus, page }) → 分页加载
• 取消：api.post(ordercancel, { OrderGuid })
• 确认收货：api.post(orderconfirm)
• 支付：直接对未支付订单调用 pay(orderId) 流程

4.6 个人中心（my）

• 用户信息：api.get(getcustomer) → 头像、昵称、手机号、邀请码
• 钱包：api.get(wallet) → 余额
• 邀请码：api.get(myinvitecode) → 展示 + 复制到剪贴板
• 代理申请：api.get(agentsupgrade) → Code=200 进入分销 / Code=220 弹出表单

五、对接 UrShop 后端的启动步骤

1. 部署 UrShop 后端：从 UrShop 获取后端服务包，部署到服务器
2. 配置 API 地址：修改 app.js 中 globalData.host 为你的 UrShop API 地址
3. 配置小程序 AppID：在 project.config.json 中填写你的小程序 AppID
4. 配置地图 Key：在 app.js 中替换腾讯地图 SDK 的 key
5. 配置微信支付：在 UrShop 管理后台配置微信支付商户信息
6. 发布上线：使用微信开发者工具上传代码，提交审核

六、开发注意事项

1. 所有 API 端点必须在 conf.js 中定义为常量，禁止硬编码 URL
2. 请求 header 自动携带 guid（用户标识）、authorization（Token）、shopId（店铺ID）
3. 响应码 Code === 200 为成功，Code === 401 需跳转登录授权
4. 错误时 reject() 的 data 对象 .Content 字段包含业务错误描述
5. 使用 this.setData() 更新视图，数组项更新使用字符串路径 ['arr['+i+']']
6. 特殊状态码：220（需审核）、250（特殊业务成功）
7. 购物车数量上限 99
8. 金额字段保留两位小数，使用 toFixed(2)
9. 分页统一每页 12 条
10. 图片使用 mode="widthFix" 自适应