chore[litemall-wx-api]: 代码注释清理。

2018-11-22 22:12:30 +08:00
parent d20894284b
commit 5905fdd74c
18 changed files with 214 additions and 545 deletions
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxAddressController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxAddressController.java
@@ -19,6 +19,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 用户收货地址服务
+ */
@RestController
@RequestMapping("/wx/address")
@Validated
@@ -35,13 +38,6 @@ public class WxAddressController {
     *
     * @param userId 用户ID
     * @return 收货地址列表
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(@LoginUser Integer userId) {
@@ -72,29 +68,8 @@ public class WxAddressController {
     * 收货地址详情
     *
     * @param userId 用户ID
-     * @param id     收获地址ID
+     * @param id     收货地址ID
     * @return 收货地址详情
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * id: xxx,
-     * name: xxx,
-     * provinceId: xxx,
-     * cityId: xxx,
-     * areaId: xxx,
-     * mobile: xxx,
-     * address: xxx,
-     * isDefault: xxx,
-     * version: xxx
-     * provinceName: xxx,
-     * cityName: xxx,
-     * areaName: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("detail")
    public Object detail(@LoginUser Integer userId, @NotNull Integer id) {
@@ -182,8 +157,6 @@ public class WxAddressController {
     * @param userId  用户ID
     * @param address 用户收货地址
     * @return 添加或更新操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("save")
    public Object save(@LoginUser Integer userId, @RequestBody LitemallAddress address) {
@@ -217,10 +190,8 @@ public class WxAddressController {
     * 删除收货地址
     *
     * @param userId  用户ID
-     * @param address 用户收货地址
-     * @return 删除结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @param address 用户收货地址，{ id: xxx }
+     * @return 删除操作结果
     */
    @PostMapping("delete")
    public Object delete(@LoginUser Integer userId, @RequestBody LitemallAddress address) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxAuthController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxAuthController.java
@@ -35,6 +35,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 鉴权服务
+ */
@RestController
@RequestMapping("/wx/auth")
@Validated
@@ -56,18 +59,6 @@ public class WxAuthController {
     * @param body    请求内容，{ username: xxx, password: xxx }
     * @param request 请求对象
     * @return 登录结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * token: xxx,
-     * tokenExpire: xxx,
-     * userInfo: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("login")
    public Object login(@RequestBody String body, HttpServletRequest request) {
@@ -113,18 +104,6 @@ public class WxAuthController {
     * @param wxLoginInfo 请求内容，{ code: xxx, userInfo: xxx }
     * @param request     请求对象
     * @return 登录结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * token: xxx,
-     * tokenExpire: xxx,
-     * userInfo: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("login_by_weixin")
    public Object loginByWeixin(@RequestBody WxLoginInfo wxLoginInfo, HttpServletRequest request) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java
@@ -17,6 +17,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 专题服务
+ */
@RestController
@RequestMapping("/wx/brand")
@Validated
@@ -32,17 +35,6 @@ public class WxBrandController {
     * @param page 分页页数
     * @param size 分页大小
     * @return 品牌列表
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * brandList: xxx,
-     * totalPages: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(@RequestParam(defaultValue = "1") Integer page,
@@ -63,16 +55,6 @@ public class WxBrandController {
     *
     * @param id 品牌ID
     * @return 品牌详情
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * brand: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("detail")
    public Object detail(@NotNull Integer id) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCartController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCartController.java
@@ -19,6 +19,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 用户购物车服务
+ */
@RestController
@RequestMapping("/wx/cart")
@Validated
@@ -37,21 +40,10 @@ public class WxCartController {
    private LitemallGrouponRulesService grouponRulesService;

    /**
-     * 购物车
+     * 用户购物车信息
     *
     * @param userId 用户ID
-     * @return 购物车
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * cartList: xxx,
-     * cartTotal: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 用户购物车信息
     */
    @GetMapping("index")
    public Object index(@LoginUser Integer userId) {
@@ -86,20 +78,14 @@ public class WxCartController {
    }

    /**
-     * 添加商品加入购物车
-     * 如果已经存在购物车货品，则添加数量；
+     * 加入商品到购物车
+     * <p>
+     * 如果已经存在购物车货品，则增加数量；
     * 否则添加新的购物车货品项。
     *
     * @param userId 用户ID
     * @param cart   购物车商品信息， { goodsId: xxx, productId: xxx, number: xxx }
     * @return 加入购物车操作结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("add")
    public Object add(@LoginUser Integer userId, @RequestBody LitemallCart cart) {
@@ -157,22 +143,15 @@ public class WxCartController {
    }

    /**
-     * 立即购买商品
+     * 立即购买
     * <p>
-     * 和 前面一个方法add的区别在于
+     * 和add方法的区别在于：
     * 1. 如果购物车内已经存在购物车货品，前者的逻辑是数量添加，这里的逻辑是数量覆盖
     * 2. 添加成功以后，前者的逻辑是返回当前购物车商品数量，这里的逻辑是返回对应购物车项的ID
     *
     * @param userId 用户ID
     * @param cart   购物车商品信息， { goodsId: xxx, productId: xxx, number: xxx }
-     * @return 即购买操作结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 立即购买操作结果
     */
    @PostMapping("fastadd")
    public Object fastadd(@LoginUser Integer userId, @RequestBody LitemallCart cart) {
@@ -230,14 +209,11 @@ public class WxCartController {
    }

    /**
-     * 更新指定的购物车信息
-     * 目前只支持修改商品的数量
+     * 修改购物车商品货品数量
     *
     * @param userId 用户ID
     * @param cart   购物车商品信息， { id: xxx, goodsId: xxx, productId: xxx, number: xxx }
-     * @return 更新购物车操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 修改结果
     */
    @PostMapping("update")
    public Object update(@LoginUser Integer userId, @RequestBody LitemallCart cart) {
@@ -290,19 +266,13 @@ public class WxCartController {
    }

    /**
-     * 购物车商品勾选
+     * 购物车商品货品勾选状态
+     * <p>
     * 如果原来没有勾选，则设置勾选状态；如果商品已经勾选，则设置非勾选状态。
     *
     * @param userId 用户ID
     * @param body   购物车商品信息， { productIds: xxx, isChecked: 1/0 }
     * @return 购物车信息
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("checked")
    public Object checked(@LoginUser Integer userId, @RequestBody String body) {
@@ -362,18 +332,12 @@ public class WxCartController {
    }

    /**
-     * 购物车商品数量
+     * 购物车商品货品数量
+     * <p>
     * 如果用户没有登录，则返回空数据。
     *
     * @param userId 用户ID
-     * @return 购物车商品数量
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 购物车商品货品数量
     */
    @GetMapping("goodscount")
    public Object goodscount(@LoginUser Integer userId) {
@@ -391,36 +355,17 @@ public class WxCartController {
    }

    /**
-     * 购物车下单信息
+     * 购物车下单
     *
     * @param userId    用户ID
-     * @param cartId    购物车商品ID
+     * @param cartId    购物车商品ID：
     *                  如果购物车商品ID是空，则下单当前用户所有购物车商品；
     *                  如果购物车商品ID非空，则只下单当前购物车商品。
-     * @param addressId 收货地址ID
+     * @param addressId 收货地址ID：
     *                  如果收货地址ID是空，则查询当前用户的默认地址。
-     * @param couponId  优惠券ID
+     * @param couponId  优惠券ID：
     *                  目前不支持
-     * @return 购物车下单信息
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * addressId: xxx,
-     * checkedAddress: xxx,
-     * couponId: xxx,
-     * checkedCoupon: xxx,
-     * goodsTotalPrice: xxx,
-     * freightPrice: xxx,
-     * couponPrice: xxx,
-     * orderTotalPrice: xxx,
-     * actualPrice: xxx,
-     * checkedGoodsList: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 购物车操作结果
     */
    @GetMapping("checkout")
    public Object checkout(@LoginUser Integer userId, Integer cartId, Integer addressId, Integer couponId, Integer grouponRulesId) {
@@ -512,26 +457,4 @@ public class WxCartController {
        data.put("checkedGoodsList", checkedGoodsList);
        return ResponseUtil.ok(data);
    }
-
-    /**
-     * 商品优惠券列表
-     * 目前不支持
-     *
-     * @param userId 用户ID
-     * @return 商品优惠券信息
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
-     */
-    @GetMapping("checkedCouponList")
-    public Object checkedCouponList(@LoginUser Integer userId) {
-        if (userId == null) {
-            return ResponseUtil.unlogin();
-        }
-        return ResponseUtil.unsupport();
-    }
 }
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCatalogController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCatalogController.java
@@ -18,6 +18,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 类目服务
+ */
@RestController
@RequestMapping("/wx/catalog")
@Validated
@@ -28,26 +31,14 @@ public class WxCatalogController {
    private LitemallCategoryService categoryService;

    /**
-     * 分类栏目
+     * 分类详情
     *
-     * @param id   分类类目ID
+     * @param id   分类类目ID。
     *             如果分类类目ID是空，则选择第一个分类类目。
     *             需要注意，这里分类类目是一级类目
     * @param page 分页页数
     * @param size 分页大小
-     * @return 分类栏目
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * categoryList: xxx,
-     * currentCategory: xxx,
-     * currentSubCategory: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 分类详情
     */
    @GetMapping("index")
    public Object index(Integer id,
@@ -79,9 +70,9 @@ public class WxCatalogController {
    }

    /**
-     * 一次性获取全部分类数据
+     * 所有分类数据
     *
-     * @return
+     * @return 所有分类数据
     */
    @GetMapping("all")
    public Object queryAll() {
@@ -127,17 +118,6 @@ public class WxCatalogController {
     *
     * @param id 分类类目ID
     * @return 当前分类栏目
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * currentCategory: xxx,
-     * currentSubCategory: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("current")
    public Object current(@NotNull Integer id) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCollectController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCollectController.java
@@ -20,6 +20,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 用户收藏服务
+ */
@RestController
@RequestMapping("/wx/collect")
@Validated
@@ -36,21 +39,9 @@ public class WxCollectController {
     *
     * @param userId 用户ID
     * @param type   类型，如果是0则是商品收藏，如果是1则是专题收藏
-     *               目前没有使用
     * @param page   分页页数
     * @param size   分页大小
     * @return 用户收藏列表
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * collectList: xxx,
-     * totalPages: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(@LoginUser Integer userId,
@@ -89,29 +80,18 @@ public class WxCollectController {

    /**
     * 用户收藏添加或删除
+     * <p>
+     * 如果商品没有收藏，则添加收藏；如果商品已经收藏，则删除收藏状态。
     *
     * @param userId 用户ID
-     * @param body   请求内容
+     * @param body   请求内容，{ type: xxx, valueId: xxx }
     * @return 操作结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * type: xxx,
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("addordelete")
    public Object addordelete(@LoginUser Integer userId, @RequestBody String body) {
        if (userId == null) {
            return ResponseUtil.unlogin();
        }
-        if (body == null) {
-            return ResponseUtil.badArgument();
-        }

        Byte type = JacksonUtil.parseByte(body, "type");
        Integer valueId = JacksonUtil.parseInteger(body, "valueId");
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCommentController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCommentController.java
@@ -22,6 +22,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 用户评论服务
+ */
@RestController
@RequestMapping("/wx/comment")
@Validated
@@ -82,13 +85,6 @@ public class WxCommentController {
     * @param userId  用户ID
     * @param comment 评论内容
     * @return 发表评论操作结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("post")
    public Object post(@LoginUser Integer userId, @RequestBody LitemallComment comment) {
@@ -111,17 +107,6 @@ public class WxCommentController {
     * @param type    类型ID。 如果是0，则查询商品评论；如果是1，则查询专题评论。
     * @param valueId 商品或专题ID。如果type是0，则是商品ID；如果type是1，则是专题ID。
     * @return 评论数量
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * allCount: xxx,
-     * hasPicCount: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("count")
    public Object count(@NotNull Byte type, @NotNull Integer valueId) {
@@ -142,18 +127,6 @@ public class WxCommentController {
     * @param page     分页页数
     * @param size     分页大小
     * @return 评论列表
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * data: xxx,
-     * count: xxx，
-     * currentPage: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(@NotNull Byte type,
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxFeedbackController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxFeedbackController.java
@@ -18,6 +18,8 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;

 /**
+ * 意见反馈服务
+ *
 * @author Yogeek
 * @date 2018/8/25 14:10
 */
@@ -60,7 +62,11 @@ public class WxFeedbackController {
    }

    /**
-     * 意见反馈
+     * 添加意见反馈
+     *
+     * @param userId   用户ID
+     * @param feedback 意见反馈
+     * @return 操作结果
     */
    @PostMapping("submit")
    public Object submit(@LoginUser Integer userId, @RequestBody LitemallFeedback feedback) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxGoodsController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxGoodsController.java
@@ -23,6 +23,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 商品服务
+ */
@RestController
@RequestMapping("/wx/goods")
@Validated
@@ -66,23 +69,6 @@ public class WxGoodsController {
     * @param userId 用户ID
     * @param id     商品ID
     * @return 商品详情
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * info: xxx,
-     * userHasCollect: xxx,
-     * issue: xxx,
-     * comment: xxx,
-     * specificationList: xxx,
-     * productList: xxx,
-     * attribute: xxx,
-     * brand: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("detail")
    public Object detail(@LoginUser Integer userId, @NotNull Integer id) {
@@ -165,23 +151,9 @@ public class WxGoodsController {

    /**
     * 商品分类类目
-     * <p>
-     * TODO 可能应该合并到WxCatalogController中
     *
     * @param id 分类类目ID
     * @return 商品分类类目
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * currentCategory: xxx,
-     * parentCategory: xxx,
-     * brotherCategory: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("category")
    public Object category(@NotNull Integer id) {
@@ -210,29 +182,17 @@ public class WxGoodsController {
     * 1. 这里的前五个参数都是可选的，甚至都是空
     * 2. 用户是可选登录，如果登录，则记录用户的搜索关键字
     *
-     * @param categoryId 分类类目ID
-     * @param brandId    品牌商ID
-     * @param keyword    关键字
-     * @param isNew      是否新品
-     * @param isHot      是否热买
+     * @param categoryId 分类类目ID，可选
+     * @param brandId    品牌商ID，可选
+     * @param keyword    关键字，可选
+     * @param isNew      是否新品，可选
+     * @param isHot      是否热买，可选
     * @param userId     用户ID
     * @param page       分页页数
     * @param size       分页大小
-     * @param sort       排序方式
+     * @param sort       排序方式，支持"add_time", "retail_price"或"name"
     * @param order      排序类型，顺序或者降序
     * @return 根据条件搜素的商品详情
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * goodsList: xxx,
-     * filterCategoryList: xxx,
-     * count: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(Integer categoryId, Integer brandId, String keyword, Boolean isNew, Boolean isHot,
@@ -272,21 +232,9 @@ public class WxGoodsController {
    }

    /**
-     * 新品首发页面的横幅数据
-     * <p>
-     * TODO 其实可以删除
+     * 新品首发页面的横幅
     *
-     * @return 新品首发页面的栏目数据
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * bannerInfo: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 新品首发页面的横幅
     */
    @GetMapping("new")
    public Object newGoods() {
@@ -301,21 +249,9 @@ public class WxGoodsController {
    }

    /**
-     * 人气推荐页面的横幅数据
-     * <p>
-     * TODO 其实可以删除
+     * 人气推荐页面的横幅
     *
-     * @return 人气推荐页面的栏目数据
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * bannerInfo: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 人气推荐页面的横幅
     */
    @GetMapping("hot")
    public Object hotGoods() {
@@ -329,19 +265,10 @@ public class WxGoodsController {
    }

    /**
-     * 商品页面推荐商品
+     * 商品详情页面“大家都在看”推荐商品
     *
-     * @return 商品页面推荐商品
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * goodsList: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @param id, 商品ID
+     * @return 商品详情页面推荐商品
     */
    @GetMapping("related")
    public Object related(@NotNull Integer id) {
@@ -365,16 +292,6 @@ public class WxGoodsController {
     * 在售的商品总数
     *
     * @return 在售的商品总数
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * goodsCount: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("count")
    public Object count() {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxGrouponController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxGrouponController.java
@@ -24,6 +24,11 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 团购服务
+ * <p>
+ * 需要注意这里团购规则和团购活动的关系和区别。
+ */
@RestController
@RequestMapping("/wx/groupon")
@Validated
@@ -47,24 +52,12 @@ public class WxGrouponController {
    @Autowired
    private LitemallGrouponRulesService grouponRulesService;

-
    /**
-     * 专题列表
+     * 团购规则列表
     *
     * @param page 分页页数
     * @param size 分页大小
-     * @return 专题列表
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * data: xxx,
-     * count: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 团购规则列表
     */
    @GetMapping("list")
    public Object list(@RequestParam(defaultValue = "1") Integer page,
@@ -79,6 +72,13 @@ public class WxGrouponController {
        return ResponseUtil.ok(data);
    }

+    /**
+     * 团购活动详情
+     *
+     * @param userId    用户ID
+     * @param grouponId 团购活动ID
+     * @return 团购活动详情
+     */
    @GetMapping("detail")
    public Object detail(@LoginUser Integer userId, @NotNull Integer grouponId) {
        if (userId == null) {
@@ -171,6 +171,12 @@ public class WxGrouponController {
        return ResponseUtil.ok(result);
    }

+    /**
+     * 参加团购
+     *
+     * @param grouponId 团购活动ID
+     * @return 操作结果
+     */
    @GetMapping("join")
    public Object join(@NotNull Integer grouponId) {
        LitemallGroupon groupon = grouponService.queryById(grouponId);
@@ -195,6 +201,13 @@ public class WxGrouponController {
        return ResponseUtil.ok(result);
    }

+    /**
+     * 用户开团或入团情况
+     *
+     * @param userId 用户ID
+     * @param showType 显示类型，如果是0，则是当前用户开的团购；否则，则是当前用户参加的团购
+     * @return 用户开团或入团情况
+     */
    @GetMapping("my")
    public Object my(@LoginUser Integer userId, @RequestParam(defaultValue = "0") Integer showType) {
        if (userId == null) {
@@ -265,6 +278,12 @@ public class WxGrouponController {
        return ResponseUtil.ok(result);
    }

+    /**
+     * 商品所对应的团购规则
+     *
+     * @param goodsId 商品ID
+     * @return 团购规则详情
+     */
    @GetMapping("query")
    public Object query(@NotNull Integer goodsId) {
        LitemallGoods goods = goodsService.findById(goodsId);
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxHomeController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxHomeController.java
@@ -19,6 +19,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 首页服务
+ */
@RestController
@RequestMapping("/wx/home")
@Validated
@@ -51,25 +54,9 @@ public class WxHomeController {
    }

    /**
-     * app首页
+     * 首页数据
     *
-     * @return app首页相关信息
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * banner: xxx,
-     * channel: xxx,
-     * newGoodsList: xxx,
-     * hotGoodsList: xxx,
-     * topicList: xxx,
-     * grouponList: xxx,
-     * floorGoodsList: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 首页数据
     */
    @GetMapping("/index")
    public Object index() {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxIndexController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxIndexController.java
@@ -6,11 +6,19 @@ import org.linlinjava.litemall.core.util.ResponseUtil;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;

+/**
+ * 测试服务
+ */
@RestController
@RequestMapping("/wx/index")
 public class WxIndexController {
    private final Log logger = LogFactory.getLog(WxIndexController.class);

+    /**
+     * 测试数据
+     *
+     * @return 测试数据
+     */
    @RequestMapping("/index")
    public Object index() {
        return ResponseUtil.ok("hello world, this is wx service");
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxOrderController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxOrderController.java
@@ -45,22 +45,26 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

-/*
- * 订单设计
+/**
+ * 订单服务
 *
+ * <p>
 * 订单状态：
 * 101 订单生成，未支付；102，下单后未支付用户取消；103，下单后未支付超时系统自动取消
 * 201 支付完成，商家未发货；202，订单生产，已付款未发货，但是退款取消；
 * 301 商家发货，用户未确认；
 * 401 用户确认收货； 402 用户没有确认收货超过一定时间，系统自动确认收货；
 *
+ * <p>
+ * 用户操作：
 * 当101用户未付款时，此时用户可以进行的操作是取消订单，或者付款操作
 * 当201支付完成而商家未发货时，此时用户可以取消订单并申请退款
 * 当301商家已发货时，此时用户可以有确认收货的操作
 * 当401用户确认收货以后，此时用户可以进行的操作是删除订单，评价商品，或者再次购买
 * 当402系统自动确认收货以后，此时用户可以删除订单，评价商品，或者再次购买
 *
- * 目前不支持订单退货和售后服务
+ * <p>
+ * 注意：目前不支持订单退货和售后服务
 */
@RestController
@RequestMapping("/wx/order")
@@ -116,26 +120,15 @@ public class WxOrderController {
     * 订单列表
     *
     * @param userId   用户ID
-     * @param showType 订单信息
-     *                 0， 全部订单
-     *                 1，待付款
-     *                 2，待发货
-     *                 3，待收货
-     *                 4，待评价
+     * @param showType 订单信息：
+     *                 0，全部订单；
+     *                 1，待付款；
+     *                 2，待发货；
+     *                 3，待收货；
+     *                 4，待评价。
     * @param page     分页页数
     * @param size     分页大小
-     * @return 订单操作结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * data: xxx ,
-     * count: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 订单列表
     */
    @GetMapping("list")
    public Object list(@LoginUser Integer userId,
@@ -192,19 +185,8 @@ public class WxOrderController {
     * 订单详情
     *
     * @param userId  用户ID
-     * @param orderId 订单信息
-     * @return 订单操作结果
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * orderInfo: xxx ,
-     * orderGoods: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @param orderId 订单ID
+     * @return 订单详情
     */
    @GetMapping("detail")
    public Object detail(@LoginUser Integer userId, @NotNull Integer orderId) {
@@ -254,16 +236,16 @@ public class WxOrderController {

    /**
     * 提交订单
-     * 1. 根据购物车ID、地址ID、优惠券ID，创建订单表项
-     * 2. 购物车清空
-     * 3. TODO 优惠券设置已用
-     * 4. 商品货品数量减少
+     * <p>
+     * 1. 创建订单表项和订单商品表项;
+     * 2. 购物车清空;
+     * 3. TODO 优惠券设置已用;
+     * 4. 商品货品库存减少;
+     * 5. 如果是团购商品，则创建团购活动表项。
     *
     * @param userId 用户ID
-     * @param body   订单信息，{ cartId：xxx, addressId: xxx, couponId: xxx }
-     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功', data: { orderId: xxx } }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @param body   订单信息，{ cartId：xxx, addressId: xxx, couponId: xxx, message: xxx, grouponRulesId: xxx,  grouponLinkId: xxx}
+     * @return 提交订单操作结果
     */
    @PostMapping("submit")
    public Object submit(@LoginUser Integer userId, @RequestBody String body) {
@@ -455,15 +437,16 @@ public class WxOrderController {

    /**
     * 取消订单
-     * 1. 检测当前订单是否能够取消
-     * 2. 设置订单取消状态
-     * 3. 商品货品数量增加
+     * <p>
+     * 1. 检测当前订单是否能够取消；
+     * 2. 设置订单取消状态；
+     * 3. 商品货品库存恢复；
+     * 4. TODO 优惠券；
+     * 5. TODO 团购活动。
     *
     * @param userId 用户ID
     * @param body   订单信息，{ orderId：xxx }
-     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 取消订单操作结果
     */
    @PostMapping("cancel")
    public Object cancel(@LoginUser Integer userId, @RequestBody String body) {
@@ -531,9 +514,7 @@ public class WxOrderController {
     *
     * @param userId 用户ID
     * @param body   订单信息，{ orderId：xxx }
-     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '模拟付款支付成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 支付订单ID
     */
    @PostMapping("prepay")
    public Object prepay(@LoginUser Integer userId, @RequestBody String body, HttpServletRequest request) {
@@ -602,18 +583,17 @@ public class WxOrderController {
    }

    /**
-     * 付款成功回调接口
-     * 1. 检测当前订单是否是付款状态
-     * 2. 设置订单付款成功状态相关信息
-     * 3. 响应微信支付平台
-     *
-     * @param request
-     * @param response
-     * @return 订单操作结果
-     * 成功则 WxPayNotifyResponse.success的XML内容
-     * 失败则 WxPayNotifyResponse.fail的XML内容
+     * 微信付款成功或失败回调接口
     * <p>
-     * 注意，这里pay-notify是示例地址，开发者应该设立一个隐蔽的回调地址
+     * 1. 检测当前订单是否是付款状态;
+     * 2. 设置订单付款成功状态相关信息;
+     * 3. 响应微信支付平台.
+     * <p>
+     *  注意，这里pay-notify是示例地址，建议开发者应该设立一个隐蔽的回调地址
+     *
+     * @param request 请求内容
+     * @param response 响应内容
+     * @return 操作结果
     */
    @PostMapping("pay-notify")
    public Object payNotify(HttpServletRequest request, HttpServletResponse response) {
@@ -718,14 +698,13 @@ public class WxOrderController {

    /**
     * 订单申请退款
-     * 1. 检测当前订单是否能够退款
-     * 2. 设置订单申请退款状态
+     * <p>
+     * 1. 检测当前订单是否能够退款；
+     * 2. 设置订单申请退款状态。
     *
     * @param userId 用户ID
     * @param body   订单信息，{ orderId：xxx }
-     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 订单退款操作结果
     */
    @PostMapping("refund")
    public Object refund(@LoginUser Integer userId, @RequestBody String body) {
@@ -765,14 +744,13 @@ public class WxOrderController {

    /**
     * 确认收货
-     * 1. 检测当前订单是否能够确认订单
-     * 2. 设置订单确认状态
+     * <p>
+     * 1. 检测当前订单是否能够确认收货；
+     * 2. 设置订单确认收货状态。
     *
     * @param userId 用户ID
     * @param body   订单信息，{ orderId：xxx }
     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("confirm")
    public Object confirm(@LoginUser Integer userId, @RequestBody String body) {
@@ -810,14 +788,13 @@ public class WxOrderController {

    /**
     * 删除订单
-     * 1. 检测当前订单是否删除
-     * 2. 设置订单删除状态
+     * <p>
+     * 1. 检测当前订单是否可以删除；
+     * 2. 删除订单。
     *
     * @param userId 用户ID
     * @param body   订单信息，{ orderId：xxx }
     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("delete")
    public Object delete(@LoginUser Integer userId, @RequestBody String body) {
@@ -850,14 +827,12 @@ public class WxOrderController {
    }

    /**
-     * 可以评价的订单商品信息
+     * 待评价订单商品信息
     *
     * @param userId  用户ID
     * @param orderId 订单ID
     * @param goodsId 商品ID
-     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功', data: xxx }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 待评价订单商品信息
     */
    @GetMapping("goods")
    public Object goods(@LoginUser Integer userId,
@@ -882,13 +857,12 @@ public class WxOrderController {

    /**
     * 评价订单商品
-     * 确认商品收货后7天内可以评价
+     * <p>
+     * 确认商品收货或者系统自动确认商品收货后7天内可以评价，过期不能评价。
     *
     * @param userId 用户ID
     * @param body   订单信息，{ orderId：xxx }
     * @return 订单操作结果
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("comment")
    public Object comment(@LoginUser Integer userId, @RequestBody String body) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxRegionController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxRegionController.java
@@ -14,6 +14,9 @@ import org.springframework.web.bind.annotation.RestController;
 import javax.validation.constraints.NotNull;
 import java.util.List;

+/**
+ * 区域服务
+ */
@RestController
@RequestMapping("/wx/region")
@Validated
@@ -31,13 +34,6 @@ public class WxRegionController {
     *
     * @param pid 父区域ID
     * @return 区域数据
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(@NotNull Integer pid) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxSearchController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxSearchController.java
@@ -18,6 +18,11 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 商品搜索服务
+ * <p>
+ * 注意：目前搜索功能非常简单，只是基于关键字匹配。
+ */
@RestController
@RequestMapping("/wx/search")
@Validated
@@ -32,22 +37,11 @@ public class WxSearchController {
    /**
     * 搜索页面信息
     * <p>
-     * 如果用户已登录，则给出用户历史搜索记录。
+     * 如果用户已登录，则给出用户历史搜索记录；
+     * 如果没有登录，则给出空历史搜索记录。
     *
-     * @param userId 用户ID
+     * @param userId 用户ID，可选
     * @return 搜索页面信息
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * defaultKeyword: xxx,
-     * historyKeywordList: xxx,
-     * hotKeywordList: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("index")
    public Object index(@LoginUser Integer userId) {
@@ -78,13 +72,6 @@ public class WxSearchController {
     *
     * @param keyword 关键字
     * @return 合适的关键字
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("helper")
    public Object helper(@NotEmpty String keyword,
@@ -100,14 +87,10 @@ public class WxSearchController {
    }

    /**
-     * 关键字清理
-     * <p>
-     * 当用户输入关键字一部分时，可以推荐系统中合适的关键字。
+     * 清除用户搜索历史
     *
     * @param userId 用户ID
     * @return 清理是否成功
-     * 成功则 { errno: 0, errmsg: '成功' }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @PostMapping("clearhistory")
    public Object clearhistory(@LoginUser Integer userId) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxStorageController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxStorageController.java
@@ -20,6 +20,9 @@ import java.io.IOException;
 import java.util.HashMap;
 import java.util.Map;

+/**
+ * 对象存储服务
+ */
@RestController
@RequestMapping("/wx/storage")
@Validated
@@ -57,6 +60,12 @@ public class WxStorageController {
        return ResponseUtil.ok(data);
    }

+    /**
+     * 访问存储对象
+     *
+     * @param key 存储对象key
+     * @return
+     */
    @GetMapping("/fetch/{key:.+}")
    public ResponseEntity<Resource> fetch(@PathVariable String key) {
        LitemallStorage litemallStorage = litemallStorageService.findByKey(key);
@@ -76,6 +85,12 @@ public class WxStorageController {
        return ResponseEntity.ok().contentType(mediaType).body(file);
    }

+    /**
+     * 访问存储对象
+     *
+     * @param key 存储对象key
+     * @return
+     */
    @GetMapping("/download/{key:.+}")
    public ResponseEntity<Resource> download(@PathVariable String key) {
        LitemallStorage litemallStorage = litemallStorageService.findByKey(key);
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxTopicController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxTopicController.java
@@ -22,6 +22,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+/**
+ * 专题服务
+ */
@RestController
@RequestMapping("/wx/topic")
@Validated
@@ -39,17 +42,6 @@ public class WxTopicController {
     * @param page 分页页数
     * @param size 分页大小
     * @return 专题列表
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data:
-     * {
-     * data: xxx,
-     * count: xxx
-     * }
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("list")
    public Object list(@RequestParam(defaultValue = "1") Integer page,
@@ -69,13 +61,6 @@ public class WxTopicController {
     *
     * @param id 专题ID
     * @return 专题详情
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("detail")
    public Object detail(@NotNull Integer id) {
@@ -97,13 +82,6 @@ public class WxTopicController {
     *
     * @param id 专题ID
     * @return 相关专题
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
     */
    @GetMapping("related")
    public Object related(@NotNull Integer id) {
--- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxUserController.java
+++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxUserController.java
@@ -14,6 +14,9 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.HashMap;
 import java.util.Map;

+/**
+ * 用户服务
+ */
@RestController
@RequestMapping("/wx/user")
@Validated
@@ -24,17 +27,12 @@ public class WxUserController {
    private LitemallOrderService orderService;

    /**
-     * 用户信息
+     * 用户个人页面数据
+     * <p>
+     * 目前是用户订单统计信息
     *
     * @param userId 用户ID
-     * @return 用户信息
-     * 成功则
-     * {
-     * errno: 0,
-     * errmsg: '成功',
-     * data: xxx
-     * }
-     * 失败则 { errno: XXX, errmsg: XXX }
+     * @return 用户个人页面数据
     */
    @GetMapping("index")
    public Object list(@LoginUser Integer userId) {