## File: README.md

# litemall

又一个小商场系统。

litemall = Spring Boot后端 + Vue管理员前端 + 微信小程序用户前端 + Vue用户移动端

* [文档](https://linlinjava.gitbook.io/litemall)
* [贡献](https://linlinjava.gitbook.io/litemall/contribute)
* [FAQ](https://linlinjava.gitbook.io/litemall/faq)
* [API](https://linlinjava.gitbook.io/litemall/api)

## 项目代码

* [码云](https://gitee.com/linlinjava/litemall)
* [GitHub](https://github.com/linlinjava/litemall)

## 项目架构


## 技术栈

> 1. Spring Boot
> 2. Vue
> 3. 微信小程序



## 功能

### 小商城功能

* 首页
* 专题列表、专题详情
* 分类列表、分类详情
* 品牌列表、品牌详情
* 新品首发、人气推荐
* 优惠券列表、优惠券选择
* 团购
* 搜索
* 商品详情、商品评价、商品分享
* 购物车
* 下单
* 订单列表、订单详情、订单售后
* 地址、收藏、足迹、意见反馈
* 客服

### 管理平台功能

* 会员管理
* 商城管理
* 商品管理
* 推广管理
* 系统管理
* 配置管理
* 统计报表

## 快速启动

1. 配置最小开发环境：
    * [MySQL](https://dev.mysql.com/downloads/mysql/)
    * [JDK1.8或以上](http://www.oracle.com/technetwork/java/javase/overview/index.html)
    * [Maven](https://maven.apache.org/download.cgi)
    * [Nodejs](https://nodejs.org/en/download/)
    * [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
    
2. 数据库依次导入litemall-db/sql下的数据库文件
    * litemall_schema.sql
    * litemall_table.sql
    * litemall_data.sql

3. 启动小商场和管理后台的后端服务

    打开命令行，输入以下命令
    ```bash
    cd litemall
    mvn install
    mvn clean package
    java -Dfile.encoding=UTF-8 -jar litemall-all/target/litemall-all-0.1.0-exec.jar
    ```
    
4. 启动管理后台前端

    打开命令行，输入以下命令
    ```bash
    cd litemall/litemall-admin
    npm install --registry=https://registry.npm.taobao.org
    npm run dev
    ```
    此时，浏览器打开，输入网址`http://localhost:9527`, 此时进入管理后台登录页面。
    
5. 启动小商城前端
   
   这里存在两套小商场前端litemall-wx和renard-wx，开发者可以分别导入和测试：
   
   1. 微信开发工具导入litemall-wx项目;
   2. 项目配置，启用“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”
   3. 点击“编译”，即可在微信开发工具预览效果；
   4. 也可以点击“预览”，然后手机扫描登录（但是手机需开启调试功能）。
      
   注意：
   > 这里只是最简启动方式，而小商场的微信登录、微信支付等功能需开发者设置才能运行，
   > 更详细方案请参考[文档](https://linlinjava.gitbook.io/litemall/project)。

6. 启动轻商城前端

    打开命令行，输入以下命令
    ```bash
    cd litemall/litemall-vue
    npm install --registry=https://registry.npm.taobao.org
    npm run dev
    ```
    此时，浏览器（建议采用chrome 手机模式）打开，输入网址`http://localhost:6255`, 此时进入轻商场。

    注意：
    > 现在功能很不稳定，处在开发阶段。

## 警告

> 1. 本项目仅用于学习练习
> 2. 本项目还不完善，仍处在开发中，不承担任何使用后果
> 3. 本项目代码开源[MIT](./LICENSE)，项目文档采用 [署名-禁止演绎 4.0 国际协议许可](https://creativecommons.org/licenses/by-nd/4.0/deed.zh)

## 致谢

本项目基于或参考以下项目：

1. [nideshop-mini-program](https://github.com/tumobi/nideshop-mini-program)

   项目介绍：基于Node.js+MySQL开发的开源微信小程序商城（微信小程序）

   项目参考：
   
   1. litemall项目数据库基于nideshop-mini-program项目数据库；
   2. litemall项目的litemall-wx模块基于nideshop-mini-program开发。

2. [vue-element-admin](https://github.com/PanJiaChen/vue-element-admin)
  
   项目介绍： 一个基于Vue和Element的后台集成方案
  
   项目参考：litemall项目的litemall-admin模块的前端框架基于vue-element-admin项目修改扩展。

3. [mall-admin-web](https://github.com/macrozheng/mall-admin-web)

   项目介绍：mall-admin-web是一个电商后台管理系统的前端项目，基于Vue+Element实现。

   项目参考：litemall项目的litemall-admin模块的一些页面布局样式参考了mall-admin-web项目。

4. [biu](https://github.com/CaiBaoHong/biu)

   项目介绍：管理后台项目开发脚手架，基于vue-element-admin和springboot搭建，前后端分离方式开发和部署。

   项目参考：litemall项目的权限管理功能参考了biu项目。

5. [vant--mobile-mall](https://github.com/qianzhaoy/vant--mobile-mall)

   项目介绍：基于有赞 vant 组件库的移动商城。

   项目参考：litemall项目的litemall-vue模块基于vant--mobile-mall项目开发。

## 推荐

1. [Flutter_Mall](https://github.com/youxinLu/mall)
   
   项目介绍：Flutter_Mall是一款Flutter开源在线商城应用程序。
   
2. [Taro_Mall](https://github.com/jiechud/taro-mall)

    项目介绍：Taro_Mall是一款多端开源在线商城应用程序，后台是基于litemall基础上进行开发，前端采用Taro框架编写。


## License

[MIT](https://github.com/linlinjava/litemall/blob/master/LICENSE)
Copyright (c) 2018-present linlinjava

---

## File: deploy/README.md

## deploy

### 项目打包

1. 在服务器或者开发机打包项目到deploy；
    ```
    cd litemall
    cat ./litemall-db/sql/litemall_schema.sql > ./deploy/db/litemall.sql
    cat ./litemall-db/sql/litemall_table.sql >> ./deploy/db/litemall.sql
    cat ./litemall-db/sql/litemall_data.sql >> ./deploy/db/litemall.sql
    
    cd ./litemall-admin
    npm install --registry=https://registry.npm.taobao.org
    npm run build:dep
    
    cd ..
    mvn clean package
    cp -f ./litemall-all/target/litemall-all-*-exec.jar ./deploy/litemall/litemall.jar
    ```
    这里的工作是：
    1. 把数据库文件拷贝到deploy/db文件夹
    2. 编译litemall-admin项目
    3. 编译litemall-all模块，同时把litemall-admin编译得到的静态文件拷贝到
       litemall-all模块的static目录
       
2. 修改litemall文件夹下面的*.yml外部配置文件，当litemall-all模块启动时会
    加载外部配置文件，而覆盖默认jar包内部的配置文件。
    例如，配置文件中一些地方需要设置成远程服务器的IP地址
    
此时deploy部署包结构如下：

* bin

存放远程服务器运行的脚本，包括deploy.sh脚本和reset.sh脚本

* db

存放litemall数据库文件

* litemall

存放远程服务器运行的代码，包括litemall-all二进制可执行包和litemall外部配置文件

* util
存放开发服务器运行的脚本，包括package.sh脚本和lazy.sh脚本。
由于是本地开发服务器运行，因此开发者可以不用上传到远程服务器。

### 项目部署

1. 远程服务器环境（MySQL和JDK1.8）已经安装好，请确保云服务器的安全组已经允许相应的端口。
2. 导入db/litemall.sql
    ```bash
    cd /home/ubuntu/deploy/db
    mysql -h localhost -u $ROOT -p$PASSWORD < litemall.sql
    ```
3. 启动服务
    ```bash
    sudo service litemall stop
    sudo ln -f -s /home/ubuntu/deploy/litemall/litemall.jar /etc/init.d/litemall
    sudo service litemall start
    ```
4. 测试是否部署成功(xxx.xxx.xxx.xxx是云服务器IP）：
    ```
    http://xxx.xxx.xxx.xxx:8080/wx/index/index
    http://xxx.xxx.xxx.xxx:8080/admin/index/index
    http://xxx.xxx.xxx.xxx:8080/#/login
    ```

### 项目辅助脚本

在前面的项目打包和项目部署中都是采用手动命令来部署。
这里可以写一些脚本简化：

* util/packet.sh

在开发服务器运行可以自动项目打包

* util/lazy.sh

在开发服务器运行可以自动项目打包、项目上传远程服务器、自动登录系统执行项目部署脚本。
    
注意：
> 1. 开发者需要在util/lazy.sh中设置相应的远程服务器登录账号和密钥文件路径。
> 2. 开发者需要在bin/reset.sh设置远程服务器的MySQL的root登录账户。
    
* bin/deploy.sh

在远程服务器运行可以自动部署服务

* bin/reset.sh

在远程服务器运行可以自动项目导入数据、删除本地上传图片、再执行bin/deploy.sh部署服务。

注意：
> 开发者需要在bin/reset.sh设置远程服务器的MySQL的root登录账户。

总结，当开发者设置好配置信息以后，可以在本地运行lazy.sh脚本自动一键部署:
```bash
cd litemall
./deploy/util/lazy.sh
```

不过由于需要设置的信息会包含敏感安全信息，强烈建议开发者参考这里的deploy文件夹，
然后实现自己的deploy文件夹，妥善处置外部配置文件和脚本中的敏感安全信息!!!

---

## File: doc/FAQ.md

# 常见问题

## 1 小商城

这里主要是指litemall-wx-api、litemall-wx和renard-wx三个模块的相关问题。

### 1.1 小程序微信登录失败

现象：

小程序微信登录失败

原因：

小程序未上线之前，开发者必须设置自己申请的appid，否则微信登录肯定会失败。

解决：

1. 如果只是体验商品购买流程，开发者可以采用账号注册登录方式。
2. 开发者在litemall-wx、renard-wx和litemall-core模块的appid信息设置成自己申请的信息。

### 1.2 appid已经修改，微信登陆仍然失败

现象：

微信开发者工具修改了开发者自己申请的appid，后端也更新了相应信息，但是微信登录仍然报错。

原因：

这里可能是缓存问题，虽然修改了appid，但是微信开发者工具未及时更新。

解决：

微信开发者工具中修改appid以后，请关闭litemall-wx项目或者微信开发者工具，重新启动导入litemall-wx。

### 1.3 手机真机测试不正常

现象：

微信开发者工具打开正常，但是手机真机扫描加载小商场以后，只有页面结构，没有数据和图片。

原因：

数据或者图片不可访问。

解决：

1. 确保小商场后端服务可以访问，可以通过手机浏览器访问后端服务地址测试
   * 小商场的后端服务地址是localhost，则手机不可访问；
   * 小商场的后端服务地址是局域网地址，而手机不在局域网中（例如不是相同wifi，或者手机是移动网络）
   * 小商场的后端服务未启动
2. 手机小商场的**调试功能**开启

### 1.4 第三方手机测试不正常

现象：

开发者自己手机测试正常，而第三者手机测试不正常。

解决：

1. 确保小商场后端服务可以访问，可以通过第三者手机浏览器访问后端服务地址测试
2. 第三者手机小商场的**调试功能**开启
3. 在微信小程序平台设置第三者的微信账号是**体验者**

### 1.5 微信支付失败

现象：

小商场不能支付，或者点击支付总是报错

原因：

开发者必须拥有商户支付权限，然后设置好以下信息：
```
litemall.wx.app-id=
litemall.wx.app-secret=
litemall.wx.mch-id=
litemall.wx.mch-key=
litemall.wx.notify-url=
```

解决：

参考`3.0 小商场环境`，设置相应支付配置信息

### 1.6 支付成功，但商品仍未付款

现象：

在微信开发者工具中已经成功支付，但是返回订单页面时商品订单仍然显示`未付款`状态。

原因是：

微信平台支付成功以后，会把支付结果推送到`wx.notify-url`所指定的地址。
因此，开发者必须确定`wx.notify-url`所指向的访问链接是可以成功访问，同时
能够返回正常的响应结果。

解决：

1. 如果开发者是在微信开发者工具中测试支付，那么需要采用一些内网穿透工具，
把`WxOrderController.payNotify`所代表的本地地址，例如`http://localhots/wx/order/pay-notify`,
转换成外网可以访问的地址，例如`http://xxx.com/wx/order/pay-notify`，最后
设置`wx.notify-url`指向该地址。

2. 如果开发者已经上线服务，请确认`wx.notify-url`所指向的访问链接可以正常工作。

## 2. 管理后台

这里主要是指litemall-admin-api和litemall-admin两个模块的相关问题。

### 2.1 登录连接超时，联系管理员

现象：

管理后台登录时，出现报错信息：登录连接超时

原因：

1. 首先，需要明白这是前后端分离项目，前端会向后端发送请求；
2. 其次，需要明白报错的地方，是litemall-admin/src/utils/request.js文件中;
3. 最后，连接超时是说发送给后端的请求长时间未反应。这里存在两个可能性：
    * 真连接超时，目前request.js文件中设置请求超时时间是5s，因此真的可能5s后端
    未及时返回数据；
    * 假连接超时，例如向一个不存在的地址请求数据，那自然是返回连接失败。

解决：

通常是开发者设置不正确引起的假连接超时。

1. 首先，用chrome的开发者工具查看登录页面向后端请求的具体地址；
2. 然后，测试后端的服务是否已启动，请求地址是否可以访问。
3. 最后，如果设置正确，用chrome的开发者工具查看登录页面向后端请求返回数据信息；
如果设置不正确，请启动相应的后端服务。

### 2.2 安装失败/启动不成功

现象：

执行`npm install`失败

原因：

可能下载依赖失败。

解决：

清空node_modules，重新执行`npm 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模块三个模块的相关问题。


### 3.1 Invalid bound statement

现象：

有时（特别是采用mybatis generator重新生成代码）后端服务报错

```
org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): org.linlinjava.litemall.db.dao.XXXX
```

原因：

应该是自动生成的新的XML文件没有及时更新到编译文件夹target中，造成了target中mybatis的Java代码和XML文件不对应。

解决：

采用maven命令或者插件先清理项目再重新编译打包，例如
```bash
mvn clean
mvn package
```

### 3.2 Unknown Column

现象：

```
Error querying database. Cause: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown column 'add_time' in 'field list'
The error may exist in org/linlinjava/litemall/db/dao/LitemallSystemMapper.xml
The error may involve org.linlinjava.litemall.db.dao.LitemallSystemMapper.selectByExample-Inline
The error occurred while setting parameters
SQL: select id, key_name, key_value, add_time, update_time, deleted from litemall_system
Cause: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown column 'add_time' in 'field list'
```

原因：

系统处在开发中，所以数据库表根据业务会不断调整，因此如果开发者更新代码以后直接运行，有可能导致当前代码
操作数据库失败，因为开发者当前的数据库表已经过时。

解决：

如果出现数据库方面的报错，建议开发者重新导入数据库。

### 3.3 数据库导入失败

现象：

开发者直接（或使用Navicat）运行litemall_schema.sql时运行失败。

原因：

可能是`drop user if exists`在MySQL低版本不支持，也可能是Navicat不支持。

解决:

首先，请开发者请直接打开litemall_schema.sql文件，可以看到
```
drop database if exists litemall;
drop user if exists 'litemall'@'localhost';
create database litemall default character set utf8mb4 collate utf8mb4_unicode_ci;
use litemall;
create user 'litemall'@'localhost' identified by 'litemall123456';
grant all privileges on litemall.* to 'litemall'@'localhost';
flush privileges;
```

可以看到，这里主要是完成三个工作
* 创建数据库
* 创建数据库用户
* 分配该用户所有操作权限

因此，如果开发者运行litemall_schema.sql失败，开发者可以自行使用
相关SQL命令或者使用SQL工具创建数据库、用户和分配权限工作。

此外实际上，**开发者也不应该在部署或者上线阶段运行litemall_schema.sql**

## 4. 项目

这里主要是指其他项目开发相关问题。

### 4.1 项目导入IDEA时卡顿

现象：

IDEA导入项目时，非常耗时间，或者卡断，或者一直疯狂运行。

原因：

应该是litemall-admin模块和litemall-vue模块的node_modules文件夹导致的。
node_modules是litemall-admin和litemall-vue模块所依赖的项目库，可能有近200M的文件。
而IDEA如果没有设置，则可能尝试对该文件夹进行解析索引，从而导致卡断。

解决方案：

1. 先关闭IDEA，然后删除litemall-admin和litemall-vue模块内的node_modules文件夹；
2. 然后分别创建空的node_modules文件夹；
3. 重新打开IDEA，分别设置litemall-admin模块和litemall-vue模块的node_modules文件夹Excluded状态。

---

## File: doc/how to implement best admin.md

# 最佳管理后台开发实践

很多开源项目和商业项目本质上就是一个业务管理后台，因此开源项目或者商业项目都会开发一个剥离业务的通用管理后台。
但是从本人开发和使用经验出发，希望解决以下问题：

1. 什么是最佳管理后台

   目前有很多优秀的开源管理后台项目，文档都写了如何使用、如何开发，但是没有文档详细讨论为什么需要这个功能、
   这个功能到底完成什么功能。当然，很多功能其实的确是不言自明的，但是本节希望从管理后台的使用者和管理员角度
   来系统性地阐述讨论通用的管理后台的一些需求分析。

2. 如何开发最佳管理后台

   对于一个功能，不能的开源项目给出了不同的解决方案，有的解决方案基本是一样的，有的还是有些出入，不同的实现方案
   中是否能够有最佳方案，以及不同的方案如何来评判优劣。本节希望从管理后台的入门开发者角度来讨论如何开发一个
   最佳管理后台。

注意：

1. 当然，在没有限定条件下来讨论最佳管理后台，最后可能是被人各种喷。本人也的确没有参与过大型项目或者互联网项目的管理后台开发，
给不出业界企业级的管理后台开发经验。因此本节仅仅给出一个中、小、微规模的最佳基础通用管理后台的纸上谈兵文档。

2. 本节不讨论任何技术细节，不限定具体的技术框架，而是讨论管理后台的业务需求。

## 1. 最佳管理后台是什么？

* 用户管理（管理员管理）
* 部门管理
* 角色管理
* 权限管理
* 配置管理
* 定时任务
* 消息管理
* 操作日志
* 系统日志
* 菜单管理
* 国际化
* 代码生成
* 字典管理
* 上传下载

### 1.1 用户管理


1. 不要以性能指标来评判管理后台

2. 

## 权限管理

权限管理是一个管理后台的核心功能，不同的人员存在不同的权限。

但是具体应该呈现什么效果？

有没有遇到过这种场景：
> 某天业务人员找你授权，说别人存在某个页面“AA”或者某个按钮“BB”，他现在也需要；
> 作为系统管理员，你点击打开授权页面，然后看到了各种权限。
> 然后问题来了，各种权限没有任何名字是和“AA”、“BB”相关的，请问系统管理员如何授权？
> 最后系统管理员只能从管理后台的开发或者维护工程师才能问到。

从功能上来说，这个管理后台的确实现了权限功能，但是从实际场景出发，这里的权限管理
实现的非常糟糕。开发工程师或者产品经理根本没有从使用者角度出发来考虑权限管理。

原则1：
> 假定权限列表的每一项是（AA，BB），则AA是权限所对应的页面，BB是权限所对应页面的操作按钮。

管理员授权时看到（AA，BB），就非常直观地了解当前权限会产生的效果，即授权BB则AA页面的
BB按钮出现，回收BB则AA页面的BB按钮会消失。



## 代码生产

## 参数管理

## 字典管理

字典是什么

## 菜单管理

很多管理后台都实现了菜单管理，从个人管理后台的使用角度出发，其实不是很理解菜单管理的意义。
也许来一个调查，多少管理后台的管理员会使用或者使用过菜单管理功能。

当然，菜单管理可能想实现的功能是分配不同的角色不能的前端操作页面。

## 定时任务

定时任务需要吗？

当然需要，很多功能都依赖定时任务定时完成。

但是管理后台的前端页面真的需要定时任务吗？

很奇怪，很多项目都存在定时任务菜单，而具体的页面则提供定时任务的创建、修改、删除等功能。

仔细看一下定时任务的创建效果，需要管理员设置CLASS方法、cron表达式。

让我们思考一下，

一个普通的业务管理员能看懂这个页面是做什么的吗，CLASS方法？，cron表达式？

好吧，换成懂点技术的系统管理员，也许看的懂这个页面，只是他需要这个页面做什么？他怎么设置CLASS方法？

个人觉得，如果从使用者角度来考虑，定时任务的设计有点伪需求，这个功能根本没有使用场景，或者说
定时任务的创建、删除等功能没有使用场景。

进一步考虑，如果设计定时任务，那么管理后台应该如何设计，以下是个人的一些想法：

1. 和需求方交流是否需要定时操作的一些使用场景，是否需要控制定时任务。
2. 

## 国际化

国际化看起来似乎是必要的，毕竟说不定开发的管理后台有可能要被全世界的人使用。
不过个人觉得这个概率是较小的，因此开发初期似乎是没有必要支持国际化。

此外，为了支持国际化，通常做法是代码中使用key，然后创建对应value的多个资源文件，最后根据配置
动态解析国际化文字。这种两步骤的开发方式可以很好地支持国际化。但是，如果项目使用场景真的不需要
国际化，那么默认内置国际化支持的管理后台其实反而降低了开发体验和速度。

* 开发时需要考虑key怎么合理化命名（有可能有上百个），
* 开发需要写一点包装key的代码，例如前端页面可能是`$t(key)`
* 调试也不直观，代码和页面中都是key

因此，个人觉得一个最佳管理后台默认不支持国际化可能是最佳的。

## 代码生成



因此，经过以上讨论，

* 用户管理：需开发
* 部门管理：需开发
* 角色管理：需开发
* 权限管理：需开发
* 配置管理：需开发
* 定时任务：不开发
* 消息管理：可开发
* 操作日志：需开发
* 系统日志：需开发
* 菜单管理：不开发
* 字典管理：不开发
* 上传下载：需开发

## 2. 管理后台后端开发

* 文件上传下载
* 事务管理
* 分页管理
* 异常处理
* 操作权限
* 数据权限

## 2.1 性能

首先提出的第一条规则就是：

不要过早优化性能，也不要追求性能极限，或者说理解管理员的需求极限。

从一个管理平台的使用者角度出发，点击页面以后如果在秒级响应，本人是可以接收的，极限容忍时间可以是十秒（当然这样的页面不能太多）。

也就是和京东、天猫这些面向大众用户的系统不同，一个普通的业务管理系统使用者在使用时对系统的可容忍度较高。

当然，这里不是说性能不重要，而是觉得对性能的开发时间和精力可以分配较小。

##

## 3. 管理后台前端开发

* 文件预览
* 图片预览


## 4. 业务管理模块

* 列表展示
* 增删改查
* 分页
* Excel导入导出
* 业务统计

---

## File: doc/note.md

# 项目笔记

记录本项目开发中一些关键技术点。

注意：
> 这些技术并不是绝对正确或者唯一，而是目前项目所采用。

## 1. 前后端交互技术

## 2. 错误码