进销存小程序（三）接口设计

系列文章清单：
进销存小程序（一）项目整体功能和设计
进销存小程序（二）数据库设计
进销存小程序（三）接口设计

1. 接口清单

• 登陆流程接口
• 查询当前用户所属店铺
• 创建店铺
• 搜索店铺
• 加入店铺(申请)
• 商品分类管理（创建商品）
• 入库管理
• 查询商品的规格属性
• 出库管理
• 根据分类查询去重的品牌列表
• 根据分类&品牌查询去重的货号列表
• 根据分类&品牌&货号查询属性概览列表
• 商品信息修改
• 库存查询
• 查询申请加入店铺的申请清单
• 申请加入店铺的审批
• 更新用户昵称nickname

2. 接口说明

2.1. 登陆流程接口

2.1.1. 说明

登陆过程，是先在小程序端，通过wx.login静默获取用户一次性的code，然后code提交到后台系统，再由后台系统调用微信的code2Session接口：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/login/auth.code2Session.html
流程简单说明如下：
小程序获取code -> 后台系统提交code -> 微信服务端验证code，并给出openid
小程序缓存sessionId <- 后台系统获取到openid，生成会话sessionId给小程序 <- 微信服务端返回openid

2.1.2. 入参：

{
    "code": "wxcode from wxjs"
}

入参说明：
code是小程序端通过wx.login获取到的，提交给后台系统

2.1.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
        "sessionId": "session_id_to_wxjs"
    }
}

返参说明：
后台系统根据code，从微信服务端换取openid后，将openid与用户关联，并且为这个会话生成sessionId返回给小程序端。
小程序端需要缓存这个sessionId，在后续的请求中，将这个sessionId放在header中一并提交，这样后台系统就可以知道是同一个会话了。

2.2. 查询当前用户所属店铺

2.2.1. 说明

这个接口，是为了确定用户是否加入了店铺，如果没有加入任何的店铺，不允许做入库、出库等操作。并且会提示用户先去加入店铺。

2.2.2. 入参：

{}

入参说明：
无需任何参数，因为根据sessionId，后台系统是可以获取到当前用户信息的。

2.2.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
      "total": 2,
      "count": 2,
      "rows": [
        {
          "shopId": 1,
          "shopName": "演示店铺"
        },
        {
          "shopId": 2,
          "shopName": "我的店铺"
        }
      ]
    }
  }

返参说明：
返回的是店铺总数和店铺简略信息。

2.3. 创建店铺

2.3.1. 说明

用户可以自行创建店铺。
用户创建的店铺，默认就是这个店铺的掌柜，即shopOwnerId就是这个用户的id。

2.3.2. 入参：

{
    "shopName": "我的店铺名称",
    "mobile": "17711112222",
    "shopDesc": "店铺简介"
}

入参说明：
无。

2.3.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
      "shopId": 1,
      "shopName": "演示店铺"
    }
}

返参说明：
成功的话success为true。并且会返回shopId。

2.4. 搜索店铺

2.4.1. 说明

可以根据店铺名称进行搜索。为了防止出现遍历或恶意搜索加入，这里名称必须要是完全匹配。

2.4.2. 入参：

{
    "shopName": "我的店铺名称"
}

入参说明：

2.4.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
      "shopId": 1,
      "shopName": "演示店铺"
    }
}

返参说明：
返回shopId，在后续加入店铺(申请)的时候用到。

2.5. 加入店铺(申请)

2.5.1. 说明

申请加入某个店铺。

2.5.2. 入参：

{
    "shopId": 1
}

入参说明：
只需要提交shopId，后台可以获取当前登陆的用户id。

2.5.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {}
}

返参说明：
success为true表示提交成功。

2.6. 商品分类管理（创建商品）

2.6.1. 说明

同一分类、品牌、款号项下，如果属性相同（属性顺序可不同），那么不允许创建。
商品已经区分了店铺，不同店铺下，商品信息可以相同。

2.6.2. 入参：

{
    "goodsCategory": "手机",
    "goodsBrand": "华为",
    "goodsModel": "P40",
    "goodsDesc": "这是华为的一款手机",
    "goodsProperties":"内存:64:G,存储:128:G,屏幕尺寸:6.5:英寸,颜色:星空灰:"
}

入参说明：
goodsProperties：在一个分类、品牌、款号项下，“内存:64:G,存储:256:G”与“内存:64:G,存储:128:G”这2种属性规格，代表的是不同的商品；多个属性之间用逗号分隔，依次是“属性名称1:属性值1:属性单位1,属性名称2:属性值2:属性单位2”。

2.6.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
      "id": 1
    }
}

返参说明：
success为true表示提交成功。

2.7. 入库管理

2.7.1. 说明

在提交之前，有让用户选择商品的过程，选择了具体哪种规格属性，即可唯一确定goodsId。

2.7.2. 入参：

{
    "goodsId": 1,
    "checkinAmount": 2,
    "checkinTotalPrice": 20000,
    "comment": "这是苹果的一款手机，今天入库2台，总价20000"
}

入参说明：
在提交之前，有让用户选择商品的过程，选择了具体哪种规格属性，即可唯一确定goodsId。

2.7.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": true
}

返参说明：
success为true表示提交成功。

2.8. 查询商品的规格属性

2.8.1. 说明

这个是用于当用户选择了分类、品牌、款号之后，查询此对应的商品信息，返回的goodsPropertiesSummary用于简要说明商品属性信息。

2.8.2. 入参：

{
    "goodsCategory": "手机",
    "goodsBrand": "苹果",
    "goodsModel": "iPhoneXS MAX"
}

入参说明：
3个信息都是必传的

2.8.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": {
      "goodsPropertyData": [
        {
          "goodsId": 1,
          "goodsCategory": "手机",
          "goodsBrand": "苹果",
          "goodsModel": "iPhoneXS MAX",
          "goodsPropertiesSummary": "64G,128G,6.5英寸,星空灰"
        },
        {
          "goodsId": 8,
          "goodsCategory": "手机",
          "goodsBrand": "苹果",
          "goodsModel": "iPhoneXS MAX",
          "goodsPropertiesSummary": "星空灰,6.5英寸,64G,256G"
        }
      ]
    }
}

返参说明：
goodsPropertiesSummary用于简要说明商品属性信息。

2.9. 出库管理

2.9.1. 说明

跟入库逻辑相同。

2.9.2. 入参：

{
    "goodsId": 1,
    "checkoutType": "销售开单",
    "checkoutAmount": 1,
    "checkoutTotalPrice": 10000,
    "comment": "这是苹果的一款手机，今天出库2台，总价20000，均价10000"
}

入参说明：
checkoutType，目前只支持：销售开单、移库、其他。

2.9.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {}
}

返参说明：
success为true表示提交成功。

2.10. 根据分类查询去重的品牌列表

2.10.1. 说明

根据分类，查询此分类下的品牌列表

2.10.2. 入参：

{
    "goodsCategory": "手机"
}

入参说明：

2.10.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
        "goodsBrand": [
            "苹果",
            "华为"
        ]
    }
}

返参说明：
返回品牌列表。

2.11. 根据分类&品牌查询去重的货号列表

2.11.1. 说明

如题。

2.11.2. 入参：

{
    "goodsCategory": "手机",
    "goodsBrand": "苹果"
}

入参说明：
都为必传。

2.11.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
        "goodsModel": [
            "iPhoneXS MAX"
        ]
    }
}

返参说明：
货号列表。

2.12. 根据分类&品牌&货号查询属性概览列表

2.12.1. 说明

如题。

2.12.2. 入参：

{
    "goodsCategory": "手机",
    "goodsBrand": "苹果",
    "goodsModel": "iPhoneXS MAX"
}

入参说明：
都是必传。

2.12.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": {
        "goodsAndPropertiesSummary": [
            {
                "goodsId": 1,
                "goodsStock": 2.00,
                "goodsPropertiesSummary": "星空灰,6.5英寸,129G,256G",
                "goodsPropertiesFull": "颜色:星空灰:,屏幕尺寸:6.5:英寸,内存:129:G,存储:256:G",
                "goodsDesc": "这是苹果的一款手机11111"
            },
            {
                "goodsId": 8,
                "goodsStock": 2.00,
                "goodsPropertiesSummary": "星空灰,6.5英寸,64G,256G",
                "goodsPropertiesFull": "颜色:星空灰:,屏幕尺寸:6.5:英寸,内存:64:G,存储:256:G",
                "goodsDesc": "这是苹果的一款手机"
            }
        ]
    }
}

返参说明：

• goodsStock：商品库存。
• goodsPropertiesSummary：属性简略信息
• goodsPropertiesFull：属性完整信息。

2.13. 商品信息修改

2.13.1. 说明

根据提交的goodsId，修改其对应的商品信息。

2.13.2. 入参：

{
    "goodsId": 1,
    "goodsCategory": "手机",
    "goodsBrand": "华为",
    "goodsModel": "P40",
    "goodsDesc": "这是华为的一款手机",
    "goodsProperties":"内存:64:G,存储:128:G,屏幕尺寸:6.5:英寸,颜色:星空灰:"
}

入参说明：

• goodsId：商品id是依据，检索这个项目，修改对应的其他信息。

2.13.3. 返参：

{
    "success": true,
    "msg": "成功",
    "data": {
      "id": 1
    }
}

返参说明：
success为true表示提交成功。
id为此次修改的商品id。

2.14. 库存查询

2.14.1. 说明

2.14.2. 入参：

{
    "goodsId": 1,
    "goodsCategory": "手机",
    "goodsBrand": "苹果",
    "goodsModel": "iPhoneXS MAX"
}

入参说明：

• goodsId：当传了goodsId，则根据goodsId进行查询
• 当没有传goodsId，剩下的分类、品牌、款号任意选填。

2.14.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": {
        "goodsAndPropertiesSummary": [
            {
                "goodsId": 13,
                "goodsModel": "P40",
                "goodsStock": 1.00,
                "goodsPropertiesSummary": "星空灰,6.5英寸,64G,128G,",
                "goodsPropertiesFull": "颜色:星空灰:,屏幕尺寸:6.5:英寸,内存:64:G,存储:128:G,",
                "goodsDesc": "这是华为的一款手机"
            },
            {
                "goodsId": 14,
                "goodsModel": "P40",
                "goodsStock": 0.00,
                "goodsPropertiesSummary": "星空灰,6.5英寸,64G,256G,",
                "goodsPropertiesFull": "颜色:星空灰:,屏幕尺寸:6.5:英寸,内存:64:G,存储:256:G,",
                "goodsDesc": "这是华为的一款手机"
            }
        ]
    }
}

返参说明：
无特殊说明。

2.15. 查询申请加入店铺的申请清单

2.15.1. 说明

查询待处理的申请列表

2.15.2. 入参：

{}

入参说明：
查询登陆人作为店铺owner的，对应店铺的申请加入的申请清单。

2.15.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": {
        "applyList": [
            {
                "userId": 2,
                "nickName": "testName",
                "realName": "testRealName",
                "shopId": 1,
                "shopName": "演示店铺",
                "shopDesc": "演示店铺简介"
            }
        ]
    }
}

返参说明：

• applyList：申请加入的用户信息。

2.16. 申请加入店铺的审批

2.16.1. 说明

申请信息的审批。后台会校验是否是当前用户可审批的内容，防止被爆破。

2.16.2. 入参：

{
    "userId": 2,
    "shopId": 1,
    "pass": true
}

入参说明：

2.16.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": true
}

返参说明：
success为true表示提交成功。

2.17. 更新用户昵称nickname

2.17.1. 说明

用于提交用户的昵称。这个比较变态，小程序如果想获取用户昵称，需要用户点击button进行授权。
具体获取的办法，参考：https://developers.weixin.qq.com/miniprogram/dev/api/open-api/user-info/wx.getUserInfo.html

2.17.2. 入参：

{
    "nickName": "刘坤"
}

入参说明：

2.17.3. 返参：

{
    "success": true,
    "errorCode": null,
    "code": 1000000,
    "msg": "处理成功",
    "data": true
}

返参说明：
success为true表示提交成功。