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

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) {

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) {

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) {

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();
-    }
 }

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) {

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");

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,

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) {

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() {

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);

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() {

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");

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>
+     * 1. 检测当前订单是否是付款状态;
+     * 2. 设置订单付款成功状态相关信息;
+     * 3. 响应微信支付平台.
      * <p>
-     * 注意，这里pay-notify是示例地址，开发者应该设立一个隐蔽的回调地址
+     *  注意，这里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) {

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) {

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) {

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);

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) {

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) {