From e09ee606b796887780d931e2d56798e91dc42e6a Mon Sep 17 00:00:00 2001 From: Junling Bu Date: Thu, 9 May 2019 18:03:06 +0800 Subject: [PATCH] doc --- doc/FAQ.md | 38 ++++++++++++++++++++++++++ doc/api.md | 60 ++++++++++++++++++++++++++++++++++++++++ doc/project.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 169 insertions(+), 3 deletions(-) diff --git a/doc/FAQ.md b/doc/FAQ.md index aa881a7d..42509a36 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -133,6 +133,44 @@ litemall.wx.notify-url= 3. 最后，如果设置正确，用chrome的开发者工具查看登录页面向后端请求返回数据信息； 如果设置不正确，请启动相应的后端服务。 +### 2.2 安装失败/启动不成功 + +现象： + +执行`cnpm install`失败 + +原因： + +可能下载依赖失败。 + +解决： + +清空node_modules，重新执行`cnpm install`命令，或者自行百度、Google。 + +### 2.3 分页数据返回不正常 + +现象： + +如果管理后台点击很大的分页页数（实际已超过当时数据最大页数），后端仍然能够返回数据。 + +原因： + +这个不是BUG，而是开发者对于查询页面超过实际页面后应该产生何种效果的不同理解。 +* 返回最后一页数据可能是合理的； +* 返回空数据可能也是合理的。 + +解决： + +litemall-db模块的application-db.yaml资源文件中reasonable是true + + pagehelper: + helperDialect: mysql + reasonable: true + supportMethodsArguments: true + params: count=countSql + +开发者可以尝试设置reasonable为false，然后检查是否能够解决问题。 + ## 3. 基础系统 这里主要是指litemall-db、litemall-core和litemall-all模块三个模块的相关问题。 diff --git a/doc/api.md b/doc/api.md index 3d380fcc..f315c038 100644 --- a/doc/api.md +++ b/doc/api.md @@ -139,10 +139,70 @@ list是对象数组，total是总的数量。 #### 1.3.1 系统通用错误码 +系统通用错误码包括4XX和5XX + +* 4xx，前端错误，说明前端开发者需要重新了解后端接口使用规范： + * 401，参数错误，即前端没有传递后端需要的参数； + * 402，参数值错误，即前端传递的参数值不符合后端接收范围。 + +* 5xx，后端系统错误，除501外，说明后端开发者应该继续优化代码，尽量避免返回后端系统错误码： + * 501，验证失败，即后端要求用户登录； + * 502，系统内部错误，即没有合适命名的后端内部错误； + * 503，业务不支持，即后端虽然定义了接口，但是还没有实现功能； + * 504，更新数据失效，即后端采用了乐观锁更新，而并发更新时存在数据更新失效； + * 505，更新数据失败，即后端数据库更新失败（正常情况应该更新成功）。 + #### 1.3.2 商场业务错误码 +* AUTH_INVALID_ACCOUNT = 700 +* AUTH_CAPTCHA_UNSUPPORT = 701 +* AUTH_CAPTCHA_FREQUENCY = 702 +* AUTH_CAPTCHA_UNMATCH = 703 +* AUTH_NAME_REGISTERED = 704 +* AUTH_MOBILE_REGISTERED = 705 +* AUTH_MOBILE_UNREGISTERED = 706 +* AUTH_INVALID_MOBILE = 707 +* AUTH_OPENID_UNACCESS = 708 +* AUTH_OPENID_BINDED = 709 +* GOODS_UNSHELVE = 710 +* GOODS_NO_STOCK = 711 +* GOODS_UNKNOWN = 712 +* GOODS_INVALID = 713 +* ORDER_UNKNOWN = 720 +* ORDER_INVALID = 721 +* ORDER_CHECKOUT_FAIL = 722 +* ORDER_CANCEL_FAIL = 723 +* ORDER_PAY_FAIL = 724 +* ORDER_INVALID_OPERATION = 725 +* ORDER_COMMENTED = 726 +* ORDER_COMMENT_EXPIRED = 727 +* GROUPON_EXPIRED = 730 +* COUPON_EXCEED_LIMIT = 740 +* COUPON_RECEIVE_FAIL= 741 +* COUPON_CODE_INVALID= 742 + #### 1.3.3 管理后台业务错误码 +* ADMIN_INVALID_NAME = 601 +* ADMIN_INVALID_PASSWORD = 602 +* ADMIN_NAME_EXIST = 602 +* ADMIN_ALTER_NOT_ALLOWED = 603 +* ADMIN_DELETE_NOT_ALLOWED = 604 +* ADMIN_INVALID_ACCOUNT = 605 +* GOODS_UPDATE_NOT_ALLOWED = 610 +* GOODS_NAME_EXIST = 611 +* ORDER_CONFIRM_NOT_ALLOWED = 620 +* ORDER_REFUND_FAILED = 621 +* ORDER_REPLY_EXIST = 622 +* USER_INVALID_NAME = 630 +* USER_INVALID_PASSWORD = 631 +* USER_INVALID_MOBILE = 632 +* USER_NAME_EXIST = 633 +* USER_MOBILE_EXIST = 634 +* ROLE_NAME_EXIST = 640 +* ROLE_SUPER_SUPERMISSION = 641 +* ROLE_USER_EXIST = 642 + ### 1.4 Token 前后端采用token来验证访问权限。 diff --git a/doc/project.md b/doc/project.md index da480805..7061cc0a 100644 --- a/doc/project.md +++ b/doc/project.md @@ -1139,7 +1139,7 @@ http://www.example.com 这样可以避免开发者对模块内部的开发配置文件造成修改； 3. 管理后台前端litemall-admin模块`config/prod.env.js`中的`BASE_API`设置管理后台后端服务的服务地址。 -### 1.6.5 项目评估和调整 +### 1.6.5 项目评估 本项目只是参考项目，项目代码质量和功能不可能符合开发者的最终需求， 因此开发者**请务必仔细评估项目代码**。 @@ -1178,6 +1178,69 @@ litemall-admin编译得到的前端文件在第一次加载时相当耗时，这 建议开发者根据自己业务或架构情况优化。 +### 1.6.7 项目安全 + +项目一旦正式上线，即对外正式服务。但是服务同时，可能会存在安全隐患甚至黑客攻击。 + +本节仅列举一些注意事项，欢迎开发者补充和完善。 + +#### 1.6.7.1 账户安全 + +这里的账号安全，既包括商城端用户账户，也包括管理后台端管理员账户。 + +目前账号安全还缺乏一点的保护措施，例如 + +* 用户密码失败超过阈值，则显示验证码； +* 用户密码失败超过阈值，则取消登录； +* 用户密码失败超过阈值，则需要手机验证码； + +#### 1.6.7.2 关键业务记录 + +有关订单或者金钱相关的操作，建议开发者尽可能记录在数据库中，以便以后回溯。 + +#### 1.6.7.3 API统一调整 + +本项目公布了参考API接口，如果出现BUG可能会被黑客作为入口。 +建议开发者上线之前可以统一调整接口，以减少安全隐患。 + +#### 1.6.7.4 对账 + +本项目管理后台没有对账功能，建议开发者可以开发对账比对商场的状态是否正常。 + +#### 1.6.7.5 取消或者限制退款 + +本项目不支持自动退款功能，而是在管理后台通过管理员点击退款按钮来人工退款。 +但是仍然可能存在隐患，例如黑客通过漏洞进入管理后台从而进行不合理的退款操作。 + +因此建议开发者可以取消管理后台的退款按钮，而仅仅保持退款信息，管理员可以登录 +微信官方支付平台进行退款操作。 + +或者建议开发者基于一定的业务逻辑或场景限制管理后台的退款功能。例如，设置当天 +退款限额从而保证不会产生无限退款操作。 + +#### 1.6.7.6 资源限制访问 + +一些API操作涉及到后端服务器资源，因此需要做一定的限制，防止有限资源被恶意消耗。 + +有限资源可能包括： + +* 验证码 +* 图片上传 + +一些限制措施可能包括： + +* 限制单个IP的访问频率 +* 限制用户上传图片数量 + +#### 1.6.7.n 跟踪本项目进展 + +一旦有开发者反馈BUG，本项目会优先解决并及时上传补丁。 +因此建议开发者跟踪本项目进展，留意每次BUG修复的commit。 + +同时也希望开发者发现任何BUG都及时反馈。 + +目前还不存在LTS版本，未来业务稳定后可能会发布。 + ## 1.7 项目管理 这里简述一些当前项目开发的要点。 @@ -1194,6 +1257,8 @@ litemall-admin编译得到的前端文件在第一次加载时相当耗时，这 * litemall-all/.gitignore * .gitignore +开发者可以采用单一.gitignore文件。 + ### 1.7.2 项目自动部署 #### 1.7.2.1 deploy部署 @@ -1333,8 +1398,8 @@ application配置文件中，但是问题就是数据库信息一旦改变则其 * 503，业务不支持，即后端虽然定义了接口，但是还没有实现功能； * 504，更新数据失效，即后端采用了乐观锁更新，而并发更新时存在数据更新失效； * 505，更新数据失败，即后端数据库更新失败（正常情况应该更新成功）。 -* 6xx，小商城后端业务错误码，具体见litemall-admin-api模块的`AdminResponseCode`类。 -* 7xx，管理后台后端业务错误码，具体见litemall-wx-api模块的`WxResponseCode`类。 +* 6xx，管理后台后端业务错误码，具体见litemall-admin-api模块的`AdminResponseCode`类。 +* 7xx，小商城后端业务错误码，具体见litemall-wx-api模块的`WxResponseCode`类。 需要指出的是，小商场后端可能返回4xx、5xx和6xx错误码；管理后台后端则可能返回4xx、5xx和7xx错误码。 这样设计原因是方便小商场前端和管理后台前端区别对待。 @@ -1356,6 +1421,9 @@ application配置文件中，但是问题就是数据库信息一旦改变则其 和小商场前端类似，管理后台前端处理后端响应错误码也存在三种类似的处理方式。 +注意： +> 这里的4xx和5xx错误码，和HTTP中的4xx和5xx状态码不是一个概念。 + ### 1.7.7 TODO 本项目存在一些TODO，**强烈建议**开发者上线前仔细审阅是否存在问题和做相应调整。