epp/README.md

# Epidemic prevention platform

> 基于微服务的社区疫情防控系统

代码仓库：[GitHub](https://github.com/coder-xiaomo/epp)  [Gitee](https://gitee.com/coder-xiaomo/epp)  [自建](https://git.only4.work/coder-xiaomo/epp)

本项目采用 monorepo 单仓库模式进行维护，项目完整代码均在此仓库中。



## 简介

新冠疫情的出现，给人们的工作和生活带来了较大影响，也对社区疫情防控相关工作做了更高的要求。如何准确、快速、有效的落实疫情防控相关工作是对社区工作能力的一次全方位检验。基于此背景，结合社区疫情防控主要特点及核心要求，在对社区疫情管控模式进行充分分析后，开发了该基于微服务的社区疫情防控系统。

本系统采用微服务架构进行开发，充分发挥架构优势，围绕社区人员进出入、体温上报、买菜团购、药品购置四个社区疫情防控核心需求展开，为社区疫情防控工作保驾护航。



## 功能

对社区疫情管控模式进行分析，针对社区人员进出入、体温上报、买菜团购、药品购置等日常生活物资的调控与管理进行分析。深入了解微服务架构，设计并实现社区疫情防控系统



## 要求

1.分析社区疫情管控模式需求；

2.深入理解微服务架构思想；

3.设计并实现社区疫情防控各模块；

4.撰写论文



## 数据库字典

> 微服务：一个服务对应一个数据库，同一个信息可能存在不同的数据库

TODO



## 需要注意

### 写在最前

这个项目是我的本科毕设项目，所以部分功能做的比较粗糙，并不能保证数据安全及抗住并发，不建议直接部署到真实场景使用。

如果你想要拿我的项目作为毕设，我有义务先让你知晓，我并不保证这个项目在你演示的时候不出任何问题，也没有义务免费帮你答疑、安装环境和调试等。当然，如果我有空，可以付费咨询，我不保证付费就能解决你的问题，但如果没有解决你的问题，我不会收你一分钱。



### 不允许

- ⚠不允许使用这个项目进行广告营销

- ⚠不允许提供本项目第三方下载渠道（例如网盘分享等）

- ⚠不允许以任何形式二次出售卖钱。如果你想拿我的项目进行包装后收费卖给其他人，那么这里不欢迎你
- ⚠不允许拿本项目去申请版权、著作权等相关权属证明



### 一些说明

微信小程序支付功能如果没有微信支付商户号无法开发&测试，我没有商户号，所以微信小程序的支付功能是假的支付。



## 环境配置（使用技术栈）

### 安装运行环境

项目运行需要如下环境。[检查环境是否安装成功及国内镜像源配置](./docs/EnvCheck.md)

| 类型           | 项目        | 名称及版本                                                   | 部署环境  | 说明                                                         |
| -------------- | ----------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
| 系统           |             | Windows 10/11 或<br />Ubuntu Desktop 22.04 LTS               | 开发      |                                                              |
| 系统           |             | Ubuntu Server 22.04 LTS                                      | 生产      |                                                              |
| 环境           | 代码管理    | [Git](https://git-scm.com/download)                          | 开发      | 代码管理                                                     |
| 环境           | 前端 门禁端 | [**Node.js 14.18.0**](https://nodejs.org/zh-cn/)             | 开发 生产 | 开源、跨平台的 JavaScript 运行时环境                         |
| 依赖管理       | 前端 门禁端 | **npm 9.5.1**                                                | 开发      | 安装 node 时会自带 npm                                       |
| 环境           | 前端        | [Vue 3](https://cn.vuejs.org/guide/quick-start.html)         | 开发      | 渐进式 JavaScript 框架                                       |
| UI 组件库      | 前端        | [Element Plus](https://element-plus.gitee.io/zh-CN/)         | 开发      | 一个 Vue 3 UI 框架                                           |
| 环境           | 门禁端      | [**cnpm**](https://npmmirror.com/)                           | 开发      |                                                              |
| 环境           | 门禁端      | [**Electron**](https://www.electronjs.org/)                  | 开发      | 跨平台桌面 GUI 应用开发                                      |
| 开发语言       | 后端        | Java 11                                                      | 开发 生产 |                                                              |
| 环境           | 后端        | [**OpenJDK 11**](https://jdk.java.net/java-se-ri/11)         | 开发 生产 | **需要配置 JDK 环境变量**；                                  |
| 依赖管理       | 后端        | [**Maven 3.6.3**](https://maven.apache.org/download.cgi)     | 开发 生产 | **需要配置 Maven 环境变量、国内镜像源**                      |
| 微服务框架     | 后端        | SpringCloud                                                  | 开发 生产 | 微服务                                                       |
| 持久层框架     | 后端        | MyBatis                                                      | 开发 生产 | 持久层框架                                                   |
| 数据库连接池   | 后端        | Druid                                                        | 开发 生产 | 数据库连接池                                                 |
| RPC远程调用    | 后端        | Spring Cloud OpenFeign                                       | 开发 生产 | 声明式、模板化的HTTP客户端                                   |
| 网关           | 后端        | Spring Cloud Gateway                                         | 开发 生产 | Spring Cloud API 网关                                        |
| 负载均衡       | 后端        | Spring Cloud Load Balancer                                   | 开发 生产 | 负载均衡                                                     |
| 请求           | 后端        | OkHttp                                                       | 开发 生产 | HTTP 网络请求（用于调用微信Api）                             |
| JSON 解析      | 后端        | Fastjson                                                     | 开发 生产 | JSON 解析器和生成器                                          |
| 环境           | 后端        | [**nacos server 2.2.0**](https://github.com/alibaba/nacos/releases/tag/2.2.0) | 开发 生产 | 微服务注册中心（服务注册与发现）                             |
| 环境           | 服务端      | Nginx                                                        | 开发 生产 | 可选；Server端反向代理，SSL证书配置                          |
| 内网穿透       | ——          | rathole                                                      | 开发      | 可选，本地调试使用；内网穿透                                 |
| 环境           | 数据库      | [**MySQL 8.0.x**](https://downloads.mysql.com/archives/community/) | 开发 生产 | 数据存储                                                     |
| 数据库管理工具 | 数据库      | [Navicat](http://www.navicat.com.cn/products/navicat-premium) | 开发      | 可选；需要激活，可使用其他数据库管理工具代替                 |
| 开发工具       | 小程序端    | [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html) | 开发      | 微信小程序打包工具（小程序端为原生开发）                     |
| 开发工具       | 前端 后端   | [VSCode](https://code.visualstudio.com/#alt-downloads)       | 开发      | 代码编辑器。建议安装扩展：<br />[EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)；<br />[Vue Language Features (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) |
| 开发工具       | 后端        | [Intellij IDEA Ultimate](https://www.jetbrains.com/zh-cn/idea/download/) | 开发      | 集成开发环境。需要激活                                       |
| 小程序测试     | 手机应用    | [微信](https://weixin.qq.com/)                               | 开发      | 用于测试微信小程序                                           |
| 接口测试       | 接口测试    | [Postman](https://www.postman.com/downloads/)                | 开发      | 可选；接口测试工具                                           |
| 👇不再使用      |             |                                                              |           |                                                              |
| 缓存           | 后端        | <del>Redis</del>                                             |           | 缓存（待定）                                                 |
| 小程序跨端     | 小程序端    | <del>Taro 3.x</del>                                          |           | 小程序跨端解决方案（小程序已经重构，不再使用）               |
|                | 小程序端    | <del>小程序开发工具</del>                                    |           | 支付宝小程序打包工具（小程序已经重构，不再使用）             |



### 克隆项目代码到本地

```bash
# 克隆项目代码到本地
git clone https://github.com/coder-xiaomo/epp
# 或者选择以下地址
# git clone https://gitee.com/coder-xiaomo/epp
# git clone https://git.only4.work/coder-xiaomo/epp
# 进入项目根目录
cd epp

# 切换到 production 分支
git checkout production
```



### 项目配置

#### 创建腾讯云存储桶

在这里创建一个存储桶：https://console.cloud.tencent.com/cos/bucket

##### 存储桶设置

参考文档：https://cloud.tencent.com/document/product/436/11488#.E8.AE.BE.E7.BD.AE-cors

配置如下（可自行修改，用于解决 CORS）

```
来源 Origin
*

操作 Methods
✅PUT ✅GET ✅POST ✅DELETE ✅HEAD

Allow-Headers
*

Expose-Headers
(保持默认)

超时 Max-Age
5

返回 Vary: ✅Origin
```



##### 后端设置

后端修改这个文件中的配置：`backend/microservice-common/src/main/java/com/cxyxiaomo/epp/TencentCloud/QCloudCosStsClient.java`

```java
        // 用户的 SecretId
        String secretId = "SecretId";
        // 用户的 SecretKey
        String secretKey = "SecretKey";
        // bucket
        String bucket = "xxxxxx-xxxxxxx";
        // bucket 所在地区
        String region = "ap-xxxxxx";
        // 临时密钥有效时长，单位是秒
        Integer durationSeconds = 1800;
```



#### 导入数据库

导入数据库SQL（SQL文件在 `database` 目录下）



#### 安装依赖

代码克隆下来后，第一次需要安装依赖

```bash
# ############
# 后端依赖
# ############
# 进入 backend 目录
cd backend
mvn clean install
# 回到项目根目录下
cd ../

# ############
# 门禁端依赖
# ############
# Electron
cd client-entrance-guard
cnpm install
# 回到项目根目录下
cd ../

# ############
# 前端依赖
# ############
# 进入 frontend 目录
cd frontend
npm install
# 回到项目根目录下
cd ../
```



#### 小程序配置 & 打包

##### 配置业务域名

1.修改 `weixin-miniprogram/app.js` 文件

```javascript
// app.js
App({
  ...
  globalData: {
    ...
    baseUrl: "⚠此处修改为你的 Api 请求域名(不带最后的/)",
    ...
  }
})
```

2.配置服务域名

- 小程序：在[微信小程序后台](https://mp.weixin.qq.com/) - 左侧最下方**开发** - **开发管理** - 右侧上方**开发设置** - **服务器域名** 添加 `https://` 开头的**request合法域名**
- 小程序测试号：在[微信小程序后台](https://mp.weixin.qq.com/) - **服务器域名** 添加 `https://` 开头的**request合法域名**（注意不是业务域名）

##### 配置微信小程序appid

> ❓在哪里找appid？
>
> 如果没有注册小程序，可以申请小程序测试号进行测试，申请地址：https://mp.weixin.qq.com/wxamp/sandbox
>
> 如果已经注册过小程序，可以在此处微信扫码登录：https://mp.weixin.qq.com/ ，然后左侧菜单最后一项【设置】，滑到最下面【帐号信息】，<u>AppID(小程序ID)</u>一栏就是appid

修改 `weixin-miniprogram/project.config.json` 文件

```json
{
    ...
    "appid": "⚠此处修改为你的微信小程序appid",
    ...
}
```

##### 设置小程序最低基础库

> 参考：https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/userProfile.html

设置小程序最低基础库为 2.21.3 或更高

##### 打包微信小程序

打开**微信开发者工具**，小程序目录选择 `weixin-miniprogram` 目录，按照正常的小程序发布流程进行发布即可。发布前记得测试小程序各功能是否正常。



#### 门禁端配置 & 打包

##### 配置业务域名

修改 `client-entrance-guard/html/index.html` 文件

```html
...
<body>
    <iframe src="https://【⚠此处修改为你的 Api 请求域名】/access/index.html?inElectron=true" frameborder="0"></iframe>
    ...
</body>
...
```

##### 打包

> 参考文档：https://www.electronjs.org/docs/latest/tutorial/tutorial-packaging

使用**管理员身份**打开命令行，然后运行以下命令：

```bash
npm run package
# npm run make
```

`npm run make` 等于先执行 `npm run package`（即 *Import project into Forge*），再 *Create distributable*



#### 管理员前端项目打包并嵌入后端

```
cd frontend
npm run build
```

然后将 `frontend/dist` 文件夹移动到 `backend/microservice-gateway/src/main/resources/static` 文件夹下，并修改文件夹名称 `dist` 为 `manage`



#### 后端配置

##### 配置业务域名

修改 `backend/microservice-provider-access-8002/src/main/resources/static/access/renderer.js` 文件

```
const baseUrl = "https://【⚠此处修改为你的业务域名】/" // 以 / 结尾，例如：https://epp.only4.work/

// 或者也可使用相对路径，例如：
const baseUrl = "/"
```



修改 `backend/microservice-provider-access-8002/src/main/resources/static/access/assets/js/websocket.js` 文件

```
window.wsUrl = 'ws://【⚠此处修改为你的业务域名】/access/websocket/';
```

> 注意，如果使用了 SSL 证书，那么 ws:// 要换成 wss://



##### 配置小程序 APPID 与 APPSECRET

修改 `backend/microservice-provider-access-8002/src/main/java/com/cxyxiaomo/epp/access/service/WeChatTokenServiceImpl.java` 文件

```
    // 小程序信息
    final String APPID = "【⚠此处修改为你的小程序 APPID】";
    final String APPSECRET = "【⚠此处修改为你的小程序 APPSECRET】";
```



##### 配置门禁端生成的小程序码环境

修改 `backend/microservice-provider-access-8002/src/main/resources/static/access/renderer.js` 文件

```
const envVersion = "【⚠此处修改为当前小程序环境】" // 正式版为 "release"，体验版为 "trial"，开发版为 "develop"
```



##### 配置 Gateway 限流策略（可选）

> 如果你不懂这是在做什么，请直接跳过这一步

修改 `backend/microservice-gateway/src/main/resources/application.yml` 文件中 `routes` 中各个微服务的 `filters` 例如：

```yml
          filters: # 路由过滤器，使用自定义的限流过滤器工厂
            - name: RateLimitByIp # 设置每秒允许5个请求，每次请求需要1个令牌
              args:
                rate: 5.0
                permits: 1
```



##### 打 jar 包

> 打包需要一起打包，每个项目单独打包可能会提示找不到 microservice-common 相关依赖

IDEA 中右侧 Maven 双击 Lifestyle 的 package（建议先 clean 一下，并点击选中 Maven 的跳过测试，再进行 package），打包完成后的 jar 包可在以下位置找到

- backend/microservice-gateway/target/microservice-gateway-0.0.1-SNAPSHOT.jar
- backend/microservice-provider-user-8001/target/microservice-provider-user-8001-0.0.1-SNAPSHOT.jar
- backend/microservice-provider-access-8002/target/microservice-provider-access-8002-0.0.1-SNAPSHOT.jar
- backend/microservice-provider-shop-8003/target/microservice-provider-shop-8003-0.0.1-SNAPSHOT.jar



#### Nacos 配置

> nacos 后台地址：http://127.0.0.1:8488/nacos/index.html

1. 进入 ，修改 nacos 登录密码（可选）

   > 左侧 **权限控制** → **用户列表** → **修改**

2. 修改 nacos 端口为 8488（与后端项目配置文件中保持一致）

   > nacos/conf/application.properties 中的端口号 port 改为 8488

3. 创建两个命名空间（命名空间ID分别为 `develop` 和 `production`）

   > 左侧 **命名空间** → **新建命名空间**

| 命名空间名称     | 命名空间ID | 描述       | 配置数 | 操作         |
| :--------------- | :--------- | :--------- | :----- | :----------- |
| public(保留空间) |            |            | 0      | 详情删除编辑 |
| develop          | develop    | develop    | 0      | 详情删除编辑 |
| production       | production | production | 0      | 详情删除编辑 |

##### 新版 Nacos 需要配置密钥

**若使用的 Nacos 版本小于或等于 Nacos 2.2.0，不需要进行如下配置。**

🌟若使用的 Nacos 版本大于或等于 Nacos 2.2.0.1，则需要配置自定义密钥：

```properties
# 密钥值可以自己指定，此处的自定义密钥来自 nacos 官网
nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=
```

参考：https://nacos.io/zh-cn/docs/v2/guide/user/auth.html



#### nginx 代理配置

##### 反向代理（可选）

配置文件在 `nginx-conf` 目录下（不能直接拿来用，需要根据自己的实际情况来改）

> 以下配置仅供参考

```conf
server
{
    server_name epp.only4.work;           # ⚠ Api 业务域名
    listen 80;
    listen 443 ssl http2;

    # 并发限制 限制当前站点最大并发数
    limit_conn perserver 50;
    # 单IP限制 限制单个IP访问最大并发数
    limit_conn perip 10;
    # 流量限制 限制每个请求的流量上限（单位：KB）
    limit_rate 8192k;

    # 核心配置
    location / {
        proxy_pass http://127.0.0.1:5203; # ⚠ Gateway 微服务项目本地运行的端口

        # websocket                       # ⚠ 门禁端用户扫码后通过 websocket 推送到门禁端完成开门
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

    # ⚠ 日志相关，根据自己实际情况配置
    access_log  /dev/null;
    error_log  /dev/null;
}
```

##### SSL证书配置（可选）

如果域名配置为 https:// 则需要配置 SSL 证书。SSL证书可在 nginx 中进行配置，具体配置方法此处省略。



## 启动项目

### Step0: [开发] 启动项目开发环境

- 启动开发工具：IDEA Ultimate、VSCode、微信开发者工具

- 拉取项目仓库最新代码 & 切换到对应分支

- 启动数据库及可视化工具：MySQL、Navicat

- 启动后端微服务注册中心：nacos

- 在本地启动 Gateway 及各个微服务项目

- 在服务器端启动内网穿透 Server 端，在本地启动内网穿透 Client 端

  ```bash
  cd ./intranet-penetration/bin
  # server
  rathole ../conf/server.toml
  # client
  rathole.exe ../conf/client.toml
  ```

- 启动接口测试工具：Postman

- 本地运行门禁端：`client-entrance-guard` 目录下启动命令行：`npm run start`



### Step1. 启动项目后端

#### [部署&开发] 启动 nacos

> standalone 代表着单机模式运行，非集群模式
>

```bash
cd nacos/bin
# Windows
startup.cmd -m standalone
# Linux/Unix/Mac
# sh startup.sh -m standalone
# bash startup.sh -m standalone
```

Nacos 后台地址为：http://localhost:8848/nacos/index.html，默认用户名密码都是：**nacos**

#### [部署&开发] 启动 MySQL

```
# Ubuntu 下
sudo systemctl start mysql
```

#### [部署&开发] 启动各个微服务

开发环境：Windows下

> 直接在 IDEA 中启动即可
>
> 若系统内存够用，可以适当调大内存参数，如：-Xmx1024M -Xms256M

```bash
# 启动 Gateway
java -jar -Xmx512M -Xms128M -Dspring.profiles.active=develop ./microservice-gateway-0.0.1-SNAPSHOT.jar

# 启动 UserProvider
java -jar -Xmx512M -Xms128M -Dspring.profiles.active=develop ./microservice-provider-user-8001-0.0.1-SNAPSHOT.jar

# 启动 AccessProvider
java -jar -Xmx512M -Xms128M -Dspring.profiles.active=develop ./microservice-provider-access-8002-0.0.1-SNAPSHOT.jar

# 启动 ShopProvider
java -jar -Xmx512M -Xms128M -Dspring.profiles.active=develop ./microservice-provider-shop-8003-0.0.1-SNAPSHOT.jar
```



生产环境：Ubuntu下

> 假设生产环境已有如下配置：
>
> - JDK 中 java 可执行文件所在路径为：/www/wwwroot/env/jdk-11/bin/java
> - jar 包所在路径为：/www/wwwroot/workspace/
>
> 若系统内存够用，可以适当调大内存参数，如：-Xmx1024M -Xms256M

```bash
# 启动 Gateway
/www/wwwroot/env/jdk-11/bin/java -jar -Xmx512M -Xms128M -Dspring.profiles.active=production -Dserver.port=8000 /www/wwwroot/workspace/microservice-gateway-0.0.1-SNAPSHOT.jar

# 启动 UserProvider
/www/wwwroot/env/jdk-11/bin/java -jar -Xmx512M -Xms128M -Dspring.profiles.active=production /www/wwwroot/workspace/microservice-provider-user-8001-0.0.1-SNAPSHOT.jar

# 启动 AccessProvider
/www/wwwroot/env/jdk-11/bin/java -jar -Xmx512M -Xms128M -Dspring.profiles.active=production /www/wwwroot/workspace/microservice-provider-access-8002-0.0.1-SNAPSHOT.jar

# 启动 ShopProvider
/www/wwwroot/env/jdk-11/bin/java -jar -Xmx512M -Xms128M -Dspring.profiles.active=production /www/wwwroot/workspace/microservice-provider-shop-8003-0.0.1-SNAPSHOT.jar
```

#### [可选] 启动 nginx

```bash
# Ubuntu 下
sudo systemctl start nginx
```



### Step2. 启动项目前端

#### [开发] 启动后台管理项目

在 `frontend` 目录下运行

```bash
npm run serve
```

> ps: 生产环境直接打包为静态文件部署



### Step3. 启动项目门禁端

编译并运行 `client-entrance-guard` 目录下 `electron` 项目即可



## 项目相关地址

### 门禁端网页

https://epp.only4.work/access/index.html

Nacos 注册中心

http://106.75.217.14:8488/nacos/index.html


## 停止项目

这个应该不用多说吧



## 相关链接

- [相关文档链接](./docs/RelatedLinks.md)
- [遇到的问题及对应的解决方案](./docs/Solutions.md)
- 【TODO】[参考](./docs/Reference.md)、[开发步骤记录](./docs/开发步骤记录.md)、[功能拆分](./docs/功能拆分.md)