用户控制层-API.md

OSS 用户控制层部分编程接口

参数传递全部使用字符串，所以接口参数类型不再标注。

• OSS 用户控制层部分编程接口
  • 模板
    • [接口描述]
  • 登录
    • 检测用户登录信息
  • 注册
    • 检测用户名是否可用
    • 检测手机号是否可用
    • 添加新用户
  • 页面共享
    • 获取购物车中商品数量
    • 退出登录
    • 收藏商品
  • 首页
    • 获取分类信息
    • 获取商品图像通过一级分类
  • 商品列表页
    • 通过分类获取商品基本信息
    • 通过关键词获取商品基本信息
  • 商品详情页
    • 获取商品详细信息
    • 获取商品所在店铺信息
  • 购物车管理
    • 获取购物车信息（所有商品）
    • 添加到购物车
    • 删除购物车中商品
    • 直接修改商品数量
  • 结算页
    • 收货人管理
    • 确认下单
  • 收银页
    • 确认支付
    • 取消订单
  • 个人中心
    • 个人信息管理
      • 获取用户信息
      • 更新头像
      • 更新昵称
      • 更新手机号
      • 更新性别
      • 更新生日
    • 订单管理
      • 通过订单状态获取订单
      • 通过订单号获取订单详情
      • 更新订单状态
    • 收藏管理
      • 获取已收藏商品
      • 获取已收藏店铺
      • 删除已收藏商品
      • 删除已收藏店铺
    • 收货人管理
      • 获取所有收货人信息
      • 添加收货人
      • 修改收货人信息
      • 删除收货人

---

模板

[接口描述]

• url: [url]
• parameter list:
  1. [parameter name] ; [parameter description]
  2. [parameter name] ; [parameter description]
  3. [parameter name] ; [parameter description]
• return:
  1. [dataItem] ; [description]
  2. [dataItem] ; [description]
  3. [dataItem] ; [description]
• option:
  • JSON: //TODO: 后端开发人员给出一个示例

登录

检测用户登录信息

• url: /checkUserLogin.action
• parameter list:
  1. username / phone ; 用户名 / 手机号
  2. password ; 密码
• return:
  1. 成功后重定向至网站首页
  2. 失败后重定向会登录页面
• side-effect:
  • 登录成功后，设置 session 属性
    1. userLoginStatus = "true"
    2. shopHasOpend = "true" //若该用户已开店
    3. userId = ".." //实际用户 id
    4. nickname = ".." //昵称
    5. shopId = ".." //shopHasOpend = "false" 时无意义
    6. userAvatarAddr = "" //用户头像地址
  • 登录失败后，设置 session 属性
    1. userLoginStatus = "false"

注册

检测用户名是否可用

• url: /checkUsername.action
• parameter list:
  1. username ; 用户名
• return:
  1. result ; "true" 可用, "false" 不可用
• option:
  • JSON: {"result":"true"}

检测手机号是否可用

• url: /checkPhone.action
• parameter list:
  1. phone ; 手机号
• return:
  1. result ; "true" 可用, "false" 不可用
• option:
  • JSON: {"result":"true"}

添加新用户

• url: /addNewUser.action
• parameter list:
  1. username ; 用户名
  2. phone ; 手机号
  3. password ; 密码
• return:
  1. 成功后重定向至网站首页
  2. 失败后重定向至注册页面
• side-effect:
  • 添加成功后，设置 session 属性
    1. userLoginStatus = "true"
    2. shopHasOpend = "true" //若该用户已开店
    3. userId = ".." //实际用户 id
    4. nickname = ".." //昵称
    5. shopId = ".." //shopHasOpend = false 时无意义

页面共享

获取购物车中商品数量

• url: /getGoodsNumInShoppingCart.action
• parameter list:
• return:
  • goodsNum ; 商品数量
• option:
  • JSON: {"goodsNum":"3"}

退出登录

• url: /userLogout.action
• parameter list:
• return:
  1. session 属性 userLoginStatus = "setAttr" //设置为垃圾值
  2. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

收藏商品

• url: /addGoodsToFavorite.action
• parameter list:
  • goodsId
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

首页

获取分类信息

• url: /getCategory.action
• parameter list:
• return:
  • levelOne[] ; 第一级分类数组
    • name ; 第一级分类名
    • levelTwo[] ; 该一级分类下的二级分类数组
      • name ; 二级分类名

获取商品图像通过一级分类

• url: /getGoodsImagesByLevelOne.action
• parameter list:
  1. levelOne ; 一级分类名
  2. imageNum ; 需要的图像数量，选销量最高的商品的图像
• return:
  1. goods[]
     • goodsId ; 商品编号
     • imageAddr ; 商品图像
• option:
  • JSON:

商品列表页

通过分类获取商品基本信息

• url: /getGoodsBriefByCategory.action
• parameter list:
  1. levelOne ; 一级分类
  2. levelTwo ; 二级分类（可选）
  3. maxNumInOnPage ; 一页中最多含有的商品数量
  4. pageNum ; 要获取的页码
  5. sortByPrice ; 'true' 先按价格，再按销量排序；'false' 按销量由高到低排序
  6. priceUp ; sortByPrice = 'true' 时有效。priceUp = 'true' 时由低到高排序，'false' 时相反
• return:
  • goods[]
    • goodsId ; 商品编号
    • attributeId (随便一个即可) ; 属性编号
    • goodsName ; 商品名
    • goodsDescribe ; 商品描述
    • imageAddr ; 图像地址
    • sales ; 销量
    • price ; 价格
• option:
  • JSON:

通过关键词获取商品基本信息

• url: /getGoodsBriefByKeyword.action
• parameter list:
  1. keyword ; 关键词
  2. maxNumInOnPage ; 一页中最多含有的商品数量
  3. pageNum ; 要获取的页码
  4. sortByPrice ; 'true' 先按价格，再按销量排序；'false' 按销量由高到低排序
  5. priceUp ; sortByPrice = 'true' 时有效。priceUp = 'true' 时由低到高排序，'false' 时相反
• return:
  • goods[]
    • goodsId ; 商品编号
    • attributeId (随便一个即可) ; 属性编号
    • goodsName ; 商品名
    • goodsDescribe ; 商品描述
    • imageAddr ; 图像地址
    • sales ; 销量
    • price ; 价格
• option:
  • JSON:

商品详情页

获取商品详细信息

• url: /getGoodsDetail.action
• parameter list:
  • goodsId ; 商品编号
• return:
  • goods
    • goodsId ; 商品编号
    • goodsName ; 商品名称
    • goodsDescribe ; 商品描述
    • discountDeadline ; 打折截止时间
    • discountRate ; 打折比例
    • attributes[]
      • attributeId ; 属性编号
      • attributeValue ; 属性值
      • price ; 价格
      • inventory ; 库存
    • images[]
      • imageAddr ; 图像地址
    • levelOne ; 所在一级分类
    • levelTwo ; 所在二级分类
• option:
  • JSON:

获取商品所在店铺信息

• url: /getShopInfoByGoodsId.action
• parameter list:
  • goodsId ; 商品编号
• return:
  1. shopName ; 店铺名称
  2. shopId ; 店铺编号
• option:
  • JSON:

购物车管理

获取购物车信息（所有商品）

按 shopId 排序

• url: /getShoppingCart.action
• parameter list: none
• return:
  • shop[] ; 购物车中商品所在店铺数组
    1. shopId ; 店铺编号
    2. shopName ; 店铺名称
    3. goodsInThisShop[] ; 购物车中商品在店铺 shopId 中的商品数组
       1. id ; 购物车记录编号
       2. goods
          • goodsId ; 商品编号
          • goodsName ; 商品名
          • goodsDescribe ; 商品描述
          • imageAddr ; 图像地址
          • goodsAttrs[] ; 商品属性数组
            • attributeId ; 商品属性编号
            • attributeValue ; 商品属性值
            • price ; 商品价格，打折以后的
            • inventory ; 库存量
       3. attributeId ; 欲购属性编号
       4. goodsNum ; 欲购数量
• option:
  • JSON:

添加到购物车

• url: /addToShoppingCart.action
• parameter list:
  1. goodsId ; 商品编号
  2. attributeId ; 属性编号
  3. goodsNum ; 商品数量
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

删除购物车中商品

• url: /deleteFromShoppingCart.action
• parameter list:
  1. id ; 购物车记录编号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

直接修改商品数量

• url: /updateGoodsNumInShoppingCart.action
• parameter list:
  1. id ; 购物车记录编号
  2. goodsNum ; 新的商品数量
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

结算页

收货人管理

见个人中心收货人管理

确认下单

• url: /confirmOrder.action
• parameter list:
  • orders[] ; 订单列表
    • shopId ; 店铺编号
    • annotation ; 给商家的留言
    • id[] ; 购物车编号
  • receiverId ; 收货人 id
  • payMethod ; 付款方式
• return:
  1. orderId[] ; 订单编号列表
     • orderId ; 订单编号

收银页

确认支付

• url: /payOrder.action
• parameter list:
  • orderId[] ; 订单编号
• return:
  1. success ; 支付成功的个数
  2. fail ; 支付失败的个数
• option:
  • JSON: {"success":"3","fail":"1"}

取消订单

• url: /cancelOrder.action
• parameter list:
  • orderId ; 订单编号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

个人中心

个人信息管理

####　获取用户信息

• url: /getUserInfo.action
• parameter list:
• return:
  1. username
  2. nickname
  3. phone
  4. sex
  5. birthday
• option:
  • JSON:

更新头像

• url: /updateAvatar.action
• parameter list:
  1. avatar ; 新头像（图片）
• return:
  1. avatar ; 头像地址
• option:
  • JSON: {"avatar":"avatars/xxx.jpg"}

更新昵称

• url: /updateNickname.action
• parameter list:
  1. nickname ; 新昵称
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

更新手机号

• url: /updatePhone.action
• parameter list:
  1. phone ; 手机号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

更新性别

• url: /updateSex.action
• parameter list:
  1. sex ; 性别
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

更新生日

• url: /updateBirthday.action
• parameter list:
  1. birthday ; 生日
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

订单管理

通过订单状态获取订单

• url: /getOrderByStatus.action
• parameter list:
  1. orderStatus
     • ; 为待收货时请求待发货和待收货两个状态订单
     • ; 为已完成时请求已完成和已取消两个状态订单
  2. maxNumInOnPage
  3. pageNum
• return:
  • []
    1. orderId
    2. shopName
    3. orderStatus
• option:
  • JSON: //TODO: 后端开发人员给出一个示例

通过订单号获取订单详情

• url: /getOrderById.action
• parameter list:
  1. orderId ; 订单号
• return:
  1. orderId ; 订单号
  2. trackingNumber ; 运单号
  3. orderStatus ; 订单状态
  4. username ; 下单用户用户名
  5. receiver ; 收货人
     • name
     • address
     • phone
  6. goodsInOrder[] ; 订单中商品数组
     • goods
       • goodsId ; 商品编号
       • goodsName ; 商品名
       • goodsDescribe ; 商品描述
       • imageAddr ; 图像地址
     • attributeValue ; 商品属性值
     • goodsNum ; 购买数量
     • actualPrice ; 成交价
  7. payMethod ; 支付方式
  8. orderTime ; 下单时间
  9. completeTime ; 完成时间
  10. annotation ; 备注
  11. total ; 总金额
• option:
  • JSON:

更新订单状态

• url: /updateOrderStatus.action
• parameter list:
  1. orderId ; 订单编号
  2. orderStatus ; 新的订单状态
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

收藏管理

获取已收藏商品

以时间排序（收藏编号），最近的优先。

• url: /getGoodsFavorite.action
• parameter list:
  1. maxNumInOnPage ; 一页中最多含有的商品数量
  2. pageNum ; 要获取的页码
• return:
  • goods[]
    • goodsId ; 商品编号
    • goodsName ; 商品名
    • goodsDescribe ; 商品描述
    • imageAddr ; 图像地址
    • sales ; 销量
    • price ; 价格
• option:
  • JSON:

获取已收藏店铺

以时间排序（收藏编号），最近的优先。

• url: /getShopFavorite.action
• parameter list:
  1. maxNumInOnPage ; 一页中最多含有的店铺数量
  2. pageNum ; 要获取的页码
• return:
  • shops[]
    • shopId ; 商品编号
    • shopName ; 商品名
• option:
  • JSON:

删除已收藏商品

• url: /deleteGoodsFromFavorite.action
• parameter list:
  1. goodsId ; 商品编号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

删除已收藏店铺

• url: /deleteGoodsFromFavorite.action
• parameter list:
  1. shopId ; 商品编号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

收货人管理

获取所有收货人信息

• url: /getReceivers.action
• parameter list:
• return:
  • receivers[]
    1. receiverId ; 收货人编号
    2. receiverName ; 收货人姓名
    3. receiverAddress ; 收货人地址
    4. receiverPhone ; 收货人手机号
• option:
  • JSON:

添加收货人

• url: /addReceiver.action
• parameter list:
  1. receiverName ; 收货人姓名
  2. receiverAddress ; 收货人地址
  3. receiverPhone ; 收货人手机号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

修改收货人信息

• url: /modifyReceiver.action
• parameter list:
  1. receiverId ; 收货人编号
  2. receiverName ; 收货人姓名
  3. receiverAddress ; 收货人地址
  4. receiverPhone ; 收货人手机号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}

####　删除收货人

• url: /deleteReceiver.action
• parameter list:
  1. receiverId ; 收货人编号
• return:
  1. result ; "true" 成功, "false" 失败
• option:
  • JSON: {"result":"true"}