update[doc]: 添加FAQ文档。

2018-05-11 22:58:16 +08:00
parent e4056f8084
commit f88b193b8f
7 changed files with 134 additions and 23 deletions
--- a/CONTRIBUTE.md
+++ b/CONTRIBUTE.md
@@ -86,10 +86,4 @@ litemall的设计受众是小微型企业，而不是互联网企业，因此lit

 * 在提交issue之前，请搜索是否存在相关问题。
 * 提交的Issue请尽可能给出详细信息
-* 建议Issue基于最新的代码
-
-### QQ群提问
-
-不建议开发者在QQ群讨论遇到的Bug或者问题，而是应该在Issue中提交。
-
-当然，如果仍然坚持，那么请先看看[提问的智慧](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/master/README-zh_CN.md)
+* 建议Issue基于最新的代码
--- a/README.md
+++ b/README.md
@@ -101,11 +101,12 @@ litemall
 ==

 1. [系统架构](doc/1.md)
-2. [基础子系统](doc/2.md)
-3. [小商场子系统](doc/3.md)
-4. [管理后台子系统](doc/4.md)
-5. [商场子系统](doc/5.md)
+2. [基础平台](doc/2.md)
+3. [小商场](doc/3.md)
+4. [管理后台](doc/4.md)
+5. [商场](doc/5.md)
 6. [下一步计划](doc/6.md)
+7. [FAQ](doc/7.md)

 文档内容采用 [署名-禁止演绎 4.0 国际协议许可](https://creativecommons.org/licenses/by-nd/4.0/deed.zh)

@@ -175,8 +176,13 @@ V 3.0.0 完成以下目标：
 开发者有问题或者好的建议可以用Issues反馈交流，请给出详细信息，本人会尽可能解决。
 * 如果问题是共性问题（如代码bug或文档不全），本人会及时解决。
 * 如果问题是个人问题（如开发者了解不深入或者没有相关技术），请见谅（本人也是百度和谷歌）。
- * 请教问题，
- 
+ * 如果真的需要QQ群里提问，请在提问前先完成以下过程：
+    * 请仔细阅读本项目文档，特别是是[**FAQ**](./doc/7.md)，查看能否解决；
+    * 请阅读[提问的智慧](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/master/README-zh_CN.md)；
+    * 请百度或谷歌相关技术；
+    * 请查看相关技术的官方文档，例如微信小程序的官方文档；
+    * 请提问前尽可能做一些DEBUG或者思考分析，然后提问时给出详细的错误相关信息以及个人对问题的理解。
+     
 贡献
 ==

@@ -187,4 +193,9 @@ V 3.0.0 完成以下目标：
 注意:
 > * 如果开发者开发使用中有问题，建议采用Issue来报告问题和解决问题。
 > * 在开发交流群中应讨论开发、业务和合作问题。
-> * 交流结果如果是共识性的则在文档中记录，如果是开放性的则会在Issue中记录。
+> * 交流结果如果是共识性的则在文档中记录，如果是开放性的则会在Issue中记录。
+
+相关项目
+====
+
+[HubertYoung](https://github.com/HubertYoung)正在开发Android端[Litemall-Android](https://github.com/HubertYoung/Litemall-Android)
--- a/doc/1.md
+++ b/doc/1.md
@@ -181,6 +181,7 @@ litemall是一个简单的商场系统，基于现有的开源项目，重新实
 > 此外，可能有人会认为需要存在测试阶段置于dev和dep之间。
 > 但是，本人认为测试过程存在于三个不同阶段内部可能更为适宜，
 > 即项目测试过程这里不会作为独立的一个阶段。
+> 当然，这里也可以把dep阶段理解成是一种测试阶段。

 讨论：
 > 对于内网IP，例如"192.168.0.1"，是应该认为属于开发阶段的配置，还是应该认为属于部署阶段的配置？
@@ -333,6 +334,18 @@ litemall是一个简单的商场系统，基于现有的开源项目，重新实
 3. 编译前，请确定litemall-wx-api模块已经运行，而litemall-wx模块的config文件夹中的api.js已经设置正确的后台数据服务地址；
 4. 点击`编译`，如果出现数据和图片，则运行正常

+注意：
+> 1. 开发者编译以后，可以看到图片和数据，但是采用微信登录是肯定会失败的。
+>    原因是这里的appid是本人申请的，而开发者不是本人app的开发者或体验者，
+>    因此微信登录导致后台服务向微信服务器交互时会失败。
+> 2. 有的开发者可能认为把litemall-wx模块的appid设置成开发者自己的appid就可以，
+>    但是实际上，由于小商场的云主机后台服务的appid仍然是本人appid，
+>    因此微信登录时仍然会失败。
+> 3. 开发者可以在litemall-wx和litemall-wx-api中设置自己的appid，以及部署自己的后台服务，
+>    相关内容请阅读章节3。
+>    或者，开发者可以采用账号登录的方式登录后台服务，然后体验商品购买下单的方式。
+> 4. 由于没有设置商户支付信息，因此开发者在付款时会失败。相关内容阅读章节3。
+
 ### 1.4.3 Vue开发环境

 1. 安装npm（或者cnpm）
--- a/doc/2.md
+++ b/doc/2.md
@@ -1,5 +1,4 @@
-
-# 2 litemall基础系统
+# 2 litemall基础平台

 目前litemall基础系统主要由litemall数据库、litemall-core模块、litemall-db模块、
 litemall-os-api模块和litemall-all模块组成。
@@ -118,7 +117,11 @@ litemall.sql数据库基于nideshop中的[nideshop.sql](https://github.com/tumob
 ### 2.1.3 行政区域设计
 
 原nideship.sql中存在region数据，但是litemall.sql的region数据则来自
-[Administrative-divisions-of-China](https://github.com/modood/Administrative-divisions-of-China)项目。从该项目中导入数据到litemall.sql的litemall-province、litemall-city、litemall-area和litemall-street四个表，然后重新生成一个新的litemall-region表。
+[Administrative-divisions-of-China](https://github.com/modood/Administrative-divisions-of-China)项目。
+
+从该项目中导入数据到litemall.sql的litemall-province、litemall-city、litemall-area和litemall-street四个临时表；
+然后按照项目的要求采用一定的代码重新生成一个新的litemall-region表；
+最后删除四个临时表。

 ### 2.1.4 订单设计

--- a/doc/3.md
+++ b/doc/3.md
@@ -11,11 +11,6 @@


 目前发现存在的一些问题：
-
-* `严重`支付功能
-  
-  注意
-  > 这里之所以没有实现，是因为本人没有商户支付能力。
  
 * `严重`账号登录和注册中验证码

@@ -45,6 +40,58 @@
 * `功能`个人页面支持帮助中心
 * `功能`推荐功能，基于用户的一些信息，在合适的页面给出推荐商品

+## 3.0 小商场环境
+
+开发者小商场开发环境以后，启动后台服务，小程序端可以
+显示数据和图片，但是微信登录会失败，因为appid不是
+开发者自己的，这里进一步介绍开发者需要设置的小商场环境。
+
+### 3.0.1 微信小程序信息
+
+开发者在微信小程序官网申请以后，可以有app-id和app-secret信息。
+
+1. 在litemall-wx-api模块的src/main/resources的资源文件中设置
+```
+wx.app-id=开发者申请的app-id
+wx.app-secret=开发者申请的app-secret
+```
+
+2. 在litemall-wx模块的project.config.json文件中设置
+```
+"appid": "开发者申请的app-id",
+```
+
+3. 启动后台服务
+
+4. 建议开发者关闭当前项目，重新打开（因为此时litemall-wx模块的appid可能未更新）。
+   编译运行，尝试微信登录
+
+### 3.0.2 微信商户支付信息
+
+开发者在微信支付平台申请以后，可以有app-id和app-secret信息。
+
+1. 在litemall-wx-api模块的src/main/resources的资源文件中设置
+
+    ```
+    wx.mch-id=开发者申请的mch-id
+    wx.mch-key=开发者申请的mch-key
+    wx.notify-url=开发者部署服务的微信支付成功回调地址
+    ```
+
+    注意
+    > 1. notify-url是微信支付平台向小商场后台服务发送支付结果的地址。
+    >    因此这就要求该地址是可访问的。
+    > 2. 目前小商场后台服务的默认request mapping是`/wx/order/pay-notify`（见WxOrderController类的payNotify）,
+    >    因此notify-url应该设置的地址类似于`http://www.example.com/wx/order/pay-notify`
+    > 3. 当开发者真正上线后台服务时，强烈建议默认request mapping要重新命名，不能对外公开。
+
+2. 启动后台服务
+
+3. 部署后台服务到云主机
+
+4. litemall-wx的api.js设置云主机的公网IP。
+   编译运行，尝试微信支付。
+   
 ## 3.1 litemall-wx-api

 ### 3.1.1 授权服务
--- a/doc/4.md
+++ b/doc/4.md
@@ -1,4 +1,3 @@
-
 # 4 litemall管理后台

 这里的后台管理业务参考了[platform](https://gitee.com/fuyang_lipengjun/platform).
--- a/doc/7.md
+++ b/doc/7.md
@@ -0,0 +1,44 @@
+# 7. 常见问题
+
+## 7.1 小商城
+
+### 7.1.1 为什么小程序微信登录失败
+
+原因：
+
+目前账号的appid是本人申请，同时小程序未上线，因此开发者如果微信登录肯定会失败。
+
+解决方案：
+
+1. 如果只是体验商品购买流程，开发者可以采用账号注册登录方式。
+2. 开发者在litemall-wx和litemall-wx-api模块的appid等信息设置成自己申请的信息。
+
+#### 7.1.2 为什么开发者工具运行正常，但是手机真机测试不正常？
+
+现象：
+
+手机真机扫描加载小商场以后，只有页面结构，没有数据和图片。
+
+原因：
+
+数据或者图片不可访问。
+
+解决方案：
+
+1. 确保小商场后台服务可以访问，可以通过手机浏览器访问后台服务地址测试
+   * 小商场的后台服务地址是localhost，则手机不可访问；
+   * 小商场的后台服务地址是局域网地址，而手机不在局域网中（例如不是相同wifi，或者手机是移动网络）
+   * 小商场的后台服务未启动
+2. 手机小商场的**调试功能**开启
+
+#### 7.1.3 为什么本人手机测试正常，而第三者手机测试不正常？
+
+解决方案：
+
+1. 确保小商场后台服务可以访问，可以通过第三者手机浏览器访问后台服务地址测试
+2. 第三者手机小商场的**调试功能**开启
+3. 在微信小程序平台设置第三者的微信账号是**体验者**
+
+### 管理后台
+
+### 基础平台