chore[litemall-wx, litemall-wx-api]: 品牌商API调整及文档

doc/api.md

@@ -27,7 +27,7 @@
 或者
     
     GET /goods/list?page=1&limit=10
-        
+
 #### 1.1.2 POST更新
     
     POST API_URL
@@ -46,10 +46,44 @@
         id: 1
     }
 
+#### 1.1.3 分页请求参数
+
+当GET请求后端获取数组数据时，需要传递分页参数。
+
+例如
+
+    GET /goods/list?page=1&limit=10&sort=add_time&order=desc
+    
+本项目的通用分页请求参数统一传递四个：
+
+    page: 请求页码
+    limit: 每一页数量
+    sort: 排序字段
+    order: 升序降序
+
+* page, 和通常计算机概念中数组下标从0开始不同，这里的page参数应该从1开始，
+1即代表第一页数据.
+* limit
+* sort, 例如'add_time'或者'id'.
+* order, 只能是"desc"或者'asc'.
+
+此外，这里四个参数是可选的，后端应该设置默认参数，因此即使前端不设置，
+后端也会自动返回合适的对象数组响应数据。
+
+注意:
+> 这里的参数是需要后端支持的，在一些场景下，例如数组对象是组装而成，
+> 有可能sort和order不支持。
+
+讨论：
+> 有些请求后端是所有数据，这里page和limit可能设置是无意义的。但是
+> 仍然建议加上两个参数，例如page=1, limit=1000。
+
+也就是说，请求后端数组数据时，同一传递四个分页参数，可能是比较良好的做法。
 
 ### 1.2 响应格式
 
     Content-Type: application/json;charset=UTF-8
+    
     {
         body
     }
@@ -69,8 +103,11 @@
         errno: xxx,
         errmsg: xxx
     }
+
+* errno是错误码，具体语义见1.3节。
+* errmsg是错误信息。
     
-#### 1.2.1 操作成功
+#### 1.2.2 操作成功
 
     {
         errno: 0,
@@ -85,20 +122,18 @@
         data: {}
     }
     
-#### 1.2.3 对象数组
+#### 1.2.4 数组对象
 
     {
         errno: 0,
         errmsg: "成功",，
         data: {
             list: [],
-            page: xxx,
-            limit: xxx,
-            total: xxx
-         }
+            total: XX
+        }
     }
 
-list是数组，page、limit和total是分页信息。
+list是对象数组，total是总的数量。
 
 ### 1.3 错误码
 
@@ -116,24 +151,94 @@ list是数组，page、limit和total是分页信息。
 
 #### 1.4.3 管理后台Header
 
-### 1.5 API文档格式
+### 1.5 版本控制
 
-接下来会分别从用户层面和管理员层面构建商场API服务和管理后台API服务。
+API应该存在版本控制，以保证兼容性。
+
+由于仍处于开发中，因此目前未引入版本控制。
+
+### 1.6 API格式
 
 这里定义一个API的格式：
 
-* 应用场景
-* 接口链接
-* 请求参数
-* 响应内容
-* 错误码
+应用场景
+
+    xxx
+    
+接口链接
+
+    xxx
+    
+请求参数
+
+    xxx
+    
+响应内容
+
+    xxx
+    
+错误码
+
+    xxx
+
+### 1.7 API预览
+
+接下来会分别从用户层面和管理员层面构建商场API服务和管理后台API服务。
+
+商场API服务涉及
+
+* 安全服务
+* 首页服务
+* 类目服务
+* 商品服务
+* 购物车服务
+* 订单服务
+* 会员服务
+* 收货地址服务
+* 品牌商服务
+* 收藏服务
+* 评论服务
+* 优惠券服务
+* 反馈服务
+* 足迹服务
+* 团购服务
+* 帮助服务
+* 搜索服务
+* 专题服务
+* 对象存储服务
+
+
+管理后台API服务涉及:
+* 略
 
 ## 2 商城API服务
 
 ### 2.1 安全服务
 
+#### 2.1.1 注册
+
+#### 2.1.2 登录
+
+#### 2.1.3 账号信息
+
+#### 2.1.4 退出
+
+#### 2.1.5 注册验证码
+
+#### 2.1.6 验证码
+
+#### 2.1.7 账号密码修改
+
+#### 2.1.8 微信手机号码绑定
+
+#### 2.1.9 手机号码修改
+
+#### 2.1.10 账号信息修改
+
 ### 2.2 首页服务
 
+#### 2.2.1 首页数据
+
 ### 2.3 类目服务
 
 ### 2.4 商品服务
@@ -216,6 +321,148 @@ list是数组，page、limit和total是分页信息。
     	
 ### 2.9 品牌商服务
 
+#### 2.9.1 品牌商列表
+
+应用场景
+
+    访问品牌商列表信息
+    
+接口链接
+
+    GET /wx/brand/list
+
+请求参数
+    
+    page: 请求页码
+    limit: 每一页数量
+    sort: 排序字段
+    order: 升序降序
+    
+响应内容
+
+    {
+      "errno": 0,
+      "data": {
+        "total": 49,
+        "pages": 5,
+        "limit": 10,
+        "page": 1,
+        "list": [
+          {
+            "id": 1024000,
+            "name": "WMF制造商",
+            "desc": "严选找寻德国百年高端厨具WMF的制造商，\n选择拥有14年经验的不锈钢生产工厂，\n为你甄选事半功倍的优质厨具。",
+            "picUrl": "http://yanxuan.nosdn.127.net/2018e9ac91ec37d9aaf437a1fd5d7070.png",
+            "floorPrice": 9.90
+          },
+          {
+            "id": 1024001,
+            "name": "OBH制造商",
+            "desc": "严选寻找OBH品牌的制造商，打造精致厨具，\n韩国独资工厂制造，严格质检，品质雕琢\n力求为消费者带来全新的烹饪体验。",
+            "picUrl": "http://yanxuan.nosdn.127.net/bf3499ac17a11ffb9bb7caa47ebef2dd.png",
+            "floorPrice": 39.00
+          },
+          {
+            "id": 1024003,
+            "name": "Stoneline制造商",
+            "desc": "严选找寻德国经典品牌Stoneline的制造商，\n追踪工艺，考量细节，亲自试用，\n为你甄选出最合心意的锅具和陶瓷刀，下厨如神。",
+            "picUrl": "http://yanxuan.nosdn.127.net/3a44ae7db86f3f9b6e542720c54cc349.png",
+            "floorPrice": 9.90
+          },
+          {
+            "id": 1024006,
+            "name": "KitchenAid制造商",
+            "desc": "严选寻访KitchenAid品牌的制造商，\n采用德国LFGB认证食品级专用不锈钢，\n欧式简约设计，可靠安心，尽享下厨乐趣。",
+            "picUrl": "http://yanxuan.nosdn.127.net/e11385bf29d1b3949435b80fcd000948.png",
+            "floorPrice": 98.00
+          },
+          {
+            "id": 1034001,
+            "name": "Alexander McQueen制造商",
+            "desc": "为制造精致实用的高品质包包，\n严选团队选择Alexander McQueen制造商，\n严格筛选，带来轻奢优雅体验。",
+            "picUrl": "http://yanxuan.nosdn.127.net/db7ee9667d84cbce573688297586699c.jpg",
+            "floorPrice": 69.00
+          },
+          {
+            "id": 1023000,
+            "name": "PetitBateau小帆船制造商",
+            "desc": "为打造适合宝宝的婴童服装，\n严选团队寻找PetitBateau小帆船的品牌制造商，\n无荧光剂，国家A类标准，让宝宝穿的放心。",
+            "picUrl": "http://yanxuan.nosdn.127.net/1a11438598f1bb52b1741e123b523cb5.jpg",
+            "floorPrice": 36.00
+          },
+          {
+            "id": 1001000,
+            "name": "MUJI制造商",
+            "desc": "严选精选了MUJI制造商和生产原料，\n用几乎零利润的价格，剔除品牌溢价，\n让用户享受原品牌的品质生活。",
+            "picUrl": "http://yanxuan.nosdn.127.net/1541445967645114dd75f6b0edc4762d.png",
+            "floorPrice": 12.90
+          },
+          {
+            "id": 1001002,
+            "name": "内野制造商",
+            "desc": "严选从世界各地挑选毛巾，最终选择了为日本内野代工的工厂，追求毛巾的柔软度与功能性。品质比肩商场几百元的毛巾。",
+            "picUrl": "http://yanxuan.nosdn.127.net/8ca3ce091504f8aa1fba3fdbb7a6e351.png",
+            "floorPrice": 29.00
+          },
+          {
+            "id": 1001003,
+            "name": "Adidas制造商",
+            "desc": "严选找到为Adidas等品牌制造商，\n选取优质原材料，与厂方一起设计，\n为你提供好的理想的运动装备。",
+            "picUrl": "http://yanxuan.nosdn.127.net/335334d0deaff6dc3376334822ab3a2f.png",
+            "floorPrice": 49.00
+          },
+          {
+            "id": 1033003,
+            "name": "Armani制造商",
+            "desc": "严选团队携手国际标准化专业生产厂家，\n厂家长期为Armani、Alexander wang等知名品牌代工，\n专业进口设备，精密质量把控，精于品质居家体验。",
+            "picUrl": "http://yanxuan.nosdn.127.net/981e06f0f46f5f1f041d7de3dd3202e6.jpg",
+            "floorPrice": 199.00
+          }
+        ]
+      },
+      "errmsg": "成功"
+    }
+
+错误码
+    
+    略
+    
+#### 2.9.2 品牌商信息
+
+应用场景
+
+    访问单个品牌商信息
+    
+接口链接
+
+    GET /wx/brand/detail
+
+请求参数
+    
+    id: 品牌商ID，例如1001020
+    
+响应内容
+
+    {
+      "errno": 0,
+      "data": {
+        "id": 1001020,
+        "name": "Ralph Lauren制造商",
+        "desc": "我们与Ralph Lauren Home的制造商成功接洽，掌握先进的生产设备，传承品牌工艺和工序。追求生活品质的你，值得拥有。",
+        "picUrl": "http://yanxuan.nosdn.127.net/9df78eb751eae2546bd3ee7e61c9b854.png",
+        "sortOrder": 20,
+        "floorPrice": 29.00,
+        "addTime": "2018-02-01 00:00:00",
+        "updateTime": "2018-02-01 00:00:00",
+        "deleted": false
+      },
+      "errmsg": "成功"
+    }    
+
+错误码
+    
+    略
+    
 ### 2.10 收藏服务
 
 ### 2.11 评论服务
@@ -232,9 +479,9 @@ list是数组，page、limit和total是分页信息。
 
 ### 2.17 搜索服务
 
-### 2.18专题服务
+### 2.18 专题服务
 
-### 2.18 对象存储服务
+### 2.19 对象存储服务
 
 
 ## 3 管理后台API服务

litemall-db/src/main/java/org/linlinjava/litemall/db/service/LitemallBrandService.java

@@ -18,18 +18,18 @@ public class LitemallBrandService {
     private LitemallBrandMapper brandMapper;
     private Column[] columns = new Column[]{Column.id, Column.name, Column.desc, Column.picUrl, Column.floorPrice};
 
-    public List<LitemallBrand> queryVO(int offset, int limit) {
+    public List<LitemallBrand> query(Integer page, Integer limit, String sort, String order) {
         LitemallBrandExample example = new LitemallBrandExample();
         example.or().andDeletedEqualTo(false);
-        example.setOrderByClause("add_time desc");
-        PageHelper.startPage(offset, limit);
+        if (!StringUtils.isEmpty(sort) && !StringUtils.isEmpty(order)) {
+            example.setOrderByClause(sort + " " + order);
+        }
+        PageHelper.startPage(page, limit);
         return brandMapper.selectByExampleSelective(example, columns);
     }
 
-    public int queryTotalCount() {
-        LitemallBrandExample example = new LitemallBrandExample();
-        example.or().andDeletedEqualTo(false);
-        return (int) brandMapper.countByExample(example);
+    public List<LitemallBrand> query(Integer page, Integer limit) {
+        return query(page, limit, null, null);
     }
 
     public LitemallBrand findById(Integer id) {

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java

@@ -3,6 +3,8 @@ package org.linlinjava.litemall.wx.web;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.linlinjava.litemall.core.util.ResponseUtil;
+import org.linlinjava.litemall.core.validator.Order;
+import org.linlinjava.litemall.core.validator.Sort;
 import org.linlinjava.litemall.db.domain.LitemallBrand;
 import org.linlinjava.litemall.db.service.LitemallBrandService;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -38,16 +40,11 @@ public class WxBrandController {
      */
     @GetMapping("list")
     public Object list(@RequestParam(defaultValue = "1") Integer page,
-                       @RequestParam(defaultValue = "10") Integer limit) {
-
-        List<LitemallBrand> brandList = brandService.queryVO(page, limit);
-        int total = brandService.queryTotalCount();
-        int totalPages = (int) Math.ceil((double) total / limit);
-
-        Map<String, Object> data = new HashMap<String, Object>();
-        data.put("brandList", brandList);
-        data.put("totalPages", totalPages);
-        return ResponseUtil.ok(data);
+                       @RequestParam(defaultValue = "10") Integer limit,
+                       @Sort @RequestParam(defaultValue = "add_time") String sort,
+                       @Order @RequestParam(defaultValue = "desc") String order) {
+        List<LitemallBrand> brandList = brandService.query(page, limit, sort, order);
+        return ResponseUtil.okList(brandList);
     }
 
     /**
@@ -63,8 +60,6 @@ public class WxBrandController {
             return ResponseUtil.badArgumentValue();
         }
 
-        Map<String, Object> data = new HashMap<String, Object>();
-        data.put("brand", entity);
-        return ResponseUtil.ok(data);
+        return ResponseUtil.ok(entity);
     }
 }

litemall-wx/pages/brand/brand.js

@@ -19,12 +19,12 @@ Page({
     let that = this;
     util.request(api.BrandList, {
       page: that.data.page,
-      size: that.data.size
+      limit: that.data.size
     }).then(function(res) {
       if (res.errno === 0) {
         that.setData({
-          brandList: that.data.brandList.concat(res.data.brandList),
-          totalPages: res.data.totalPages
+          brandList: that.data.brandList.concat(res.data.list),
+          totalPages: res.data.pages
         });
       }
       wx.hideLoading();

litemall-wx/pages/brandDetail/brandDetail.js

@@ -27,7 +27,7 @@ Page({
     }).then(function(res) {
       if (res.errno === 0) {
         that.setData({
-          brand: res.data.brand
+          brand: res.data
         });
 
         that.getGoodsList();
@@ -45,7 +45,7 @@ Page({
       .then(function(res) {
         if (res.errno === 0) {
           that.setData({
-            goodsList: res.data.goodsList
+            goodsList: res.data.list
           });
         }
       });

renard-wx/pages/brand/brand.js

@@ -19,12 +19,12 @@ Page({
     let that = this;
     util.request(api.BrandList, {
       page: that.data.page,
-      size: that.data.size
+      limit: that.data.size
     }).then(function(res) {
       if (res.errno === 0) {
         that.setData({
-          brandList: that.data.brandList.concat(res.data.brandList),
-          totalPages: res.data.totalPages
+          brandList: that.data.brandList.concat(res.data.list),
+          totalPages: res.data.pages
         });
       }
       wx.hideLoading();

renard-wx/pages/brandDetail/brandDetail.js

@@ -26,7 +26,7 @@ Page({
     }).then(function(res) {
       if (res.errno === 0) {
         that.setData({
-          brand: res.data.brand
+          brand: res.data
         });
 
         that.getGoodsList();
@@ -44,7 +44,7 @@ Page({
       .then(function(res) {
         if (res.errno === 0) {
           that.setData({
-            goodsList: res.data.goodsList
+            goodsList: res.data.list
           });
         }
       });