Skip to content
GitLab
Commit 60d9e621 authored by Junling Bu's avatar Junling Bu
Browse files

更新文档

parent 97011e15
Hide whitespace changes
Inline Side-by-side
doc/platform.md
View file @ 60d9e621
......@@ -254,7 +254,7 @@ litemall_region表保存了行政区域信息，包括省级、市级、县级
小商城接收返回的预支付信息后，会在小程序端出现支付页面。
如果用户放弃支付，则不会出现任何效果，不会向小商场后台服务发送任何信息。
如果用户支付，则会导致微信支付平台向小商场后台服务推送支付结果。
如果用户支付，则会导致微信商户平台向小商场后台服务推送支付结果。
* 101 -> 102
......@@ -271,7 +271,7 @@ litemall_region表保存了行政区域信息，包括省级、市级、县级
* 101 -> 201
如果用户支付，微信支付平台会向小商场后台服务推送支付结果。
如果用户支付，微信商户平台会向小商场后台服务推送支付结果。
而响应结果表示支付成功，则订单状态信息设置201，表示支付成功。
所对应的后台服务方法是litemall-wx-api模块的`WxOrderController.payNotify`
......@@ -279,7 +279,7 @@ litemall_region表保存了行政区域信息，包括省级、市级、县级
* 201 -> 202
当用户支付以后，管理员未发货前，用户可以点击`退款`申请退款取消订单。
通常用户点击退款以后系统可以基于微信支付平台的退款接口实现自动退款，
通常用户点击退款以后系统可以基于微信商户平台的退款接口实现自动退款，
但是这里考虑到安全原因，不支持系统自动退款操作。
相应地，这里小商场后台服务只是设置订单状态，表示退款申请中。
......@@ -287,7 +287,7 @@ litemall_region表保存了行政区域信息，包括省级、市级、县级
* 202 -> 203
这里退款操作是由管理员在微信支付平台手动退款，然后在本项目的
这里退款操作是由管理员在微信商户平台手动退款，然后在本项目的
管理平台里面点击`退款确认`按钮，此时订单状态会设置成203，表明
退款已经成功，同时系统会自动恢复订单商品数量。
......
doc/project.md
View file @ 60d9e621
......@@ -426,10 +426,10 @@ litemall:
notify-url: https://www.example.com/wx/order/pay-notify
```
这里的`mch-id`和`mch-key`需要开发者在[微信支付平台](https://pay.weixin.qq.com/)注册获取。
这里的`mch-id`和`mch-key`需要开发者在[微信商户平台](https://pay.weixin.qq.com/)注册获取。
而这里的`notify-url`则应该是项目上线以后微信支付回调地址，当微信支付成功或者失败，
微信支付平台将向回调地址发生成功或者失败的数据，因此需要确保该地址是
微信商户平台将向回调地址发生成功或者失败的数据，因此需要确保该地址是
litemall-wx-api模块的WxOrderController类的payNotify方法所服务的API地址。
开发阶段可以采用一些技术实现临时外网地址映射本地，开发者可以百度关键字“微信 内网穿透”自行学习。
......@@ -773,7 +773,7 @@ sudo apt-get install mysql-server
sudo apt-get install mysql-client
```
### 1.5.1.4 项目打包
#### 1.5.1.4 项目打包
1. 在主机或者开发机打包项目到deploy；
```
......@@ -815,7 +815,7 @@ sudo apt-get install mysql-client
存放开发主机运行的脚本，包括package.sh脚本和lazy.sh脚本。
由于是本地开发主机运行，因此开发者可以不用上传到远程主机。
### 1.5.1.5 项目部署
#### 1.5.1.5 项目部署
1. 远程主机环境（MySQL和JDK1.8）已经安装好，请确保云主机的安全组已经允许相应的端口。
2. 导入db/litemall.sql
......@@ -836,7 +836,7 @@ sudo apt-get install mysql-client
http://xxx.xxx.xxx.xxx:8080/#/login
```
### 1.5.1.6 项目辅助脚本
#### 1.5.1.6 项目辅助脚本
在前面的项目打包和项目部署中都是采用手动命令来部署。
这里可以写一些脚本简化：
......@@ -876,7 +876,7 @@ cd litemall
### 1.5.2 单机多服务部署方案
### 1.5.2 集群式云部署方案
### 1.5.3 集群式云部署方案
由于本项目是面向微小型企业的小商城系统，因此预期的分布式部署方案是
......@@ -1049,7 +1049,7 @@ http://www.example.com
1. litemall-wx-api模块的WxOrderController类的payNotify方法的链接换成合适的地址。
注意：
> 换成什么地址都可以，但是这里不应该暴露出来。也就是说这个地址是微信支付平台
> 换成什么地址都可以，但是这里不应该暴露出来。也就是说这个地址是微信商户平台
> 和这里的小商场后端服务之间的交互API，对外公开会存在安全隐患。
2. litemall-core模块需要配置application-core.yml
......@@ -1080,9 +1080,12 @@ http://www.example.com
这样可以避免开发者对模块内部的开发配置文件造成修改；
3. 管理后台前端litemall-admin模块`config/prod.env.js`中的`BASE_API`设置管理后台后端服务的服务地址。
### 1.6.5 上线脚本
### 1.6.5 项目评估和调整
本项目目前没有上线脚本，不过可以参考1.5.1节中的部署脚本。
本项目只是参考项目，项目代码质量和功能不可能符合开发者的最终需求，
因此开发者**请务必仔细评估项目代码**。
此外，请阅读1.7.7节，了解项目当前所有的TODO事项，特别是“演示平台TODO”。
### 1.6.6 项目优化
......@@ -1245,7 +1248,86 @@ application配置文件中，但是问题就是数据库信息一旦改变则其
注意
> 目前项目校验思路是这样，但是实际代码的校验还不完善，
> 例如前端校验很好
> 例如前端校验代码不完善，导致用户体验较差。
### 1.7.6 后端响应错误码
后端服务的响应结果是：
```
{
errno： 错误码，
errmsg：错误消息，
data： 响应数据
}
```
当errno是0时，则data保存业务数据；
当error是非0时，则业务失败，errmsg保存具体错误信息。
目前，errno存在四种形式：
* 4xx，前端错误，说明前端开发者需要重新了解后端接口使用规范：
* 401，参数错误，即前端没有传递后端需要的参数；
* 402，参数值错误，即前端传递的参数值不符合后端接收范围。
* 5xx，后端系统错误，除501外，说明后端开发者应该继续优化代码，尽量避免返回后端系统错误码：
* 501，验证失败，即后端要求用户登录；
* 502，系统内部错误，即没有合适命名的后端内部错误；
* 503，业务不支持，即后端虽然定义了接口，但是还没有实现功能；
* 504，更新数据失效，即后端采用了乐观锁更新，而并发更新时存在数据更新失效；
* 505，更新数据失败，即后端数据库更新失败（正常情况应该更新成功）。
* 6xx，小商城后端业务错误码，具体见litemall-admin-api模块的`AdminResponseCode`类。
* 7xx，管理后台后端业务错误码，具体见litemall-wx-api模块的`WxResponseCode`类。
需要指出的是，小商场后端可能返回4xx、5xx和6xx错误码；管理后台后端则可能返回4xx、5xx和7xx错误码。
这样设计原因是方便小商场前端和管理后台前端区别对待。
小商城前端处理后端响应错误码，存在三种处理方式：
* 如果是4xx，说明前端开发者请求后端API时使用方式存在问题。
例如，后端需要参数“name”，但是前端却没有传值，这个时候后端返回”用户名不对“
没有任何意义，因为这里前端使用错误。相反，简单地返回“参数不对”反而会及早提醒
前端开发者使用出现了问题。
* 如果是5xx，（除501外）说明后端系统出现错误，后端开发者应该修复或者优化，此外
前端可以在请求响应处统一处理5xx错误，而不是把错误信息返回到具体页面。
例如，后端返回“更新数据失败”，说明数据库更新时出现异常，因此前端请求响应处
统一简单报错“系统出错，联系管理员”，这样管理员可以及时联系后端开发者。而后端开发者
则需要评估具体错误码和错误信息，例如这里的“更新数据失败”很可能是数据表调整字段
导致Java代码的模型对象和数据库表不一致，此时后端开发者就可以及时修复。
此外，对于501验证失败，则前端请求响应处可以统一处理跳转登录页面。
* 如果是6xx，则说明是具体业务错误，此时前端需要在业务具体页面显示错误信息即可，同时
这里也要求后端开发者书写良好友好的业务错误信息，因为会向最终用户显示。
和小商场前端类似，管理后台前端处理后端响应错误码也存在三种类似的处理方式。
### 1.7.7 TODO
本项目存在一些TODO，**强烈建议**开发者上线前仔细审阅是否存在问题和做相应调整。
开发者可以使用IDE找到这些TODO。
下面列出一些重要的TODO：
#### 1.7.7.1 演示平台TODO
管理后台部署以后，有开发者在演示平台修改密码，导致其他开发者不能登录演示平台。
因此在修改密码后端服务代码中加了限制代码，不允许用户修改userId=1的超级管理员密码。
因此如果开发者上线管理后台，请**务必删除**这些代码。
见`AdminProfileController`类和`AdminAdminController`类。
#### 1.7.7.2 微信退款TODO
管理后台管理员点击退款按钮时，管理后台会通过微信退款API请求微信商户平台退款。
但是从安全角度考虑，**强烈建议**开发者删除微信退款代码，而登录微信商户平台手动退款。
或者开发者添加安全相关代码，例如实现短信验证码。
见`AdminOrderController`类
再次提醒，本项目不承担任何使用后果。
#### 1.7.7.3 未完善TODO
有些业务只是实现基本功能，因此这里TODO提醒开发者自行思考。
### 1.7.6 后端校验返回码
#### 1.7.7.4 重构TODO
有些业务需求不是很清晰，导致实现时可能存在不合理地方，这里TODO提醒
开发者审阅代码逻辑。
\ No newline at end of file
doc/wxmall.md
View file @ 60d9e621
......@@ -39,42 +39,45 @@
显示数据和图片，但是微信登录会失败，因为appid不是
开发者自己的，这里进一步介绍开发者需要设置的小商场环境。
### 3.0.1 微信小程序信息
### 3.0.1 微信小程序配置
开发者在微信小程序官网申请以后，可以有app-id和app-secret信息。
1. 在litemall-core模块的src/main/resources的资源文件中设置
```
litemall
wx
app-id=开发者申请的app-id
app-secret=开发者申请的app-secret
```
1. 在litemall-core模块的src/main/resources的application-core.yml资源文件中设置
```
litemall
wx
app-id: 开发者申请的app-id
app-secret: 开发者申请的app-secret
```
2. 在litemall-wx模块的project.config.json文件中设置
```
"appid": "开发者申请的app-id",
```
```
"appid": "开发者申请的app-id",
```
3. 启动后台服务
4. 建议开发者关闭当前项目，重新打开（因为此时litemall-wx模块的appid可能未更新）。
4. 建议开发者关闭当前项目或者直接关闭微信开发者工具，重新打开（因为此时litemall-wx模块的appid可能未更新）。
编译运行，尝试微信登录
### 3.0.2 微信商户支付信息
### 3.0.2 微信商户支付配置
开发者在微信支付平台申请以后，可以有app-id和app-secret信息。
开发者在微信商户平台申请以后，可以有app-id和app-secret信息。
1. 在litemall-wx-api模块的src/main/resources的资源文件中设置
1. 在litemall-core-api模块的src/main/resources的application-core.yml资源文件中设置
```
wx.mch-id=开发者申请的mch-id
wx.mch-key=开发者申请的mch-key
wx.notify-url=开发者部署服务的微信支付成功回调地址
litemall
wx
mch-id: 开发者申请的mch-id
mch-key: 开发者申请的mch-key
notify-url: 开发者部署服务的微信支付成功回调地址
```
注意
> 1. notify-url是微信支付平台向小商场后台服务发送支付结果的地址。
> 1. notify-url是微信商户平台向小商场后台服务发送支付结果的地址。
> 因此这就要求该地址是可访问的。
> 2. 目前小商场后台服务的默认request mapping是`/wx/order/pay-notify`（见WxOrderController类的payNotify）,
> 因此notify-url应该设置的地址类似于`http://www.example.com/wx/order/pay-notify`
......@@ -87,6 +90,29 @@ litemall
4. litemall-wx的api.js设置云主机的域名。
编译运行，尝试微信支付。
### 3.0.3 微信商户退款配置
目前管理平台的退款功能需要进行维修商户退款配置
1. 从微信商户平台下载商户证书（或者叫做API证书），保存到合适位置，
请阅读[文档](https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=4_3)
2. 在litemall-core-api模块的src/main/resources的application-core.yml资源文件中设置
```
litemall
wx
key-path: 证书文件访问路径
```
3. 启动小程序前端和后端，进行下单、支付、申请退款操作
4. 启动管理后台前端和后端，进行订单退款操作，然后验证手机是否收到退款。
注意：
> 虽然这里管理后台退款接入了微信退款API，但是从安全角度考虑，**强烈建议**
> 开发者删除管理后台微信退款代码，然后分成两个步骤实现管理员退款操作：
> 1. 管理员登录微信平台进行退款操作；
> 2. 管理员登陆管理后台点击退款按钮，进行订单退款状态变更和商品库存回库。
## 3.1 litemall-wx-api
本节介绍小商场的后台服务模块。
......
litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxOrderController.java
View file @ 60d9e621
......@@ -511,7 +511,7 @@ public class WxOrderController {
* 付款订单的预支付会话标识
* <p>
* 1. 检测当前订单是否能够付款
* 2. 微信支付平台返回支付订单ID
* 2. 微信商户平台返回支付订单ID
* 3. 设置订单付款状态
*
* @param userId 用户ID
......@@ -589,7 +589,7 @@ public class WxOrderController {
* <p>
* 1. 检测当前订单是否是付款状态;
* 2. 设置订单付款成功状态相关信息;
* 3. 响应微信支付平台.
* 3. 响应微信商户平台.
* <p>
* 注意，这里pay-notify是示例地址，建议开发者应该设立一个隐蔽的回调地址
*
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment