卡头服务程序（MQTT协议版本）开发文档

# 1. 文档说明

本文档作为乐的文化管理系统的卡头服务程序的开发文档，对项目中使用的技术标准和技术开发方案进行描述。

# 2. 项目目标

由于在整个门店的经营过程中，在传统方式是客户在店内玩耍时，只能通过以投掷实物币的方式来进行，开启游戏；而在现代化科技进步过程中，移动终端，已经深入到我们生活中的各方面的使用，就以现在来说，其中有很大一部分的客户他们会选择以通过以移动智能手机“二维码”或“NFC”等方式来代替传统的“实币投掷”方式投币，并可以实时提示客户账户当前余额情况，以此可以减少客户在游玩过程中的“实币兑换”过程，可以节约出更多的时间。从运营企业角度来考虑，也想知道每日随时的一个经营情况。所以通过“卡头”来实时将会员客户或非会员客户在门店中的游戏玩耍情况实时查看，在以往传统无法满足，所以在游戏机台上加装“卡头设备”，来记录客户实时投币情况，并实时发送到服务器作记录保存。实时掌握机台情况，并即时做出相对应调整等。

通过以上目标的实现，最终建立起门店的“投币”情况的实时性，完整性、统一性、安全性、可追溯性机制，从而满足工作需要，提高工作效率。

# 3.数据表设计

| 表 名      | machine_device_card_log |             |         |          |      |
| ---------- | ----------------------- | ----------- | ------- | -------- | ---- |
| 中文描述   | 卡头数据记录表          |             |         |          |      |
| 建立日期   | 2022/12/28              |             |         |          |      |
| 列 名      | 中文描述                | 数据类型    | 空/非空 | 是否主键 | 备注 |
| id         | 主键 id                 | varchar(13) | 非空    | 是       |      |
| store_id   | 门店 ID                 | varchar(13) | 非空    |          |      |
| device_id  | 卡头 ID                 | varchar(13) | 非空    |          |      |
| machine_id | 机台 ID                 | varchar(13) | 非空    |          |      |
| mac        | 卡头 mac                | varchar(13) | 非空    |          |      |
| log_type   | 记录类型                | varchar(2)  | 非空    |          |      |
| num        | 数量                    | Decimal     | 非空    |          |      |
| m_id       | 会员 ID                 | varchar(13) | 非空    |          |      |
| card_id    | 会员卡 ID               | varchar(13) | 非空    |          |      |
| assets_id  | 资产 ID                 | varchar(13) | 非空    |          |      |
| Remark     | 备注信息                | varchar(13) |         |          |      |
| 补充说明   |                         |             |         |          |      |

| 表 名      | machine_device_card |             |         |          |      |
| ---------- | ----------------------- | ----------- | ------- | -------- | ---- |
| 中文描述   | 卡头信息表          |             |         |          |      |
| 建立日期   | 2022/12/28              |             |         |          |      |
| 列 名      | 中文描述                | 数据类型    | 空/非空 | 是否主键 | 备注 |
| mac  | 卡头 MAC                 | varchar(13) | 非空    |          |      |
| isonline | 是否在线                 | bool | 非空    |          |      |

# 4.数据字典/全局变量

## 4.1 数据字典

| **字典名称** | **类  型** | **键** | **值** |
| ------------------ | ---------------- | ------------ | ------------ |
|                    |                  |              |              |

## 4.2 全局变量

| 变量名称 | 访问路径 | 值 | 说明 |
| -------- | -------- | -- | ---- |
|          |          |    |      |

# 5.接口设计

### 5.1

**说明：**

调用：

| **调用 URL** |  |
| ------------------ | ------------------------------------ |

入参：

| **参数名** | **类型** | **说明**                                   | **备注** |
| ---------------- | -------------- | ------------------------------------------------ | -------------- |
|              |          |                                                  |                |

出参：

| **参数名** | **类型** | **说明**                           |
| ---------------- | -------------- | ---------------------------------------- |
|            |            |  |

# 6.实施内容

## 6.1 概况描述

由于全国所有门店中的卡头数量较大，如果所有通过直接与数据库或接口访问，进行数据的交互处理，对服务器的压力可见一斑，高峰时段最后可能会出现异常，导致数据无法处理。

固此，加入中间服务程序，将所有卡头数据进行处理，将多条数据组合成为一条数据，减少直接访问，减小后台系统的交互压力，最后将数据保存系统，以保证数据的完整性，准确性。

该文档说明卡头数据的实币票数据处理部分，因为虚币票数据实时性要求，数据将不通过服务程序进行转发处理。

## 6.2 卡头数据服务程序
### （1）模块名称：卡头数据服务程序
### （2）模块路径：卡头数据服务程序
### （3）逻辑描述：

1：“卡头服务程序”主要是负责对所有“卡头数据”（实币，实票）的接收处理，将可以多个数据进行合并数据进行组包合并（如：一段时间内的多次投币数据组合为一条数据后进行保存）；

2：服务程序在前，将通过配置文件（LEDI.ini）配置信息（数据库指向，MQTT服务地址，MQTT服务端口，卡头区域，日志存储天数，数据保存失败次数）;

3：服务启动时，将会通过服务器信息到业务系统中提取MQTT连接认证信息，以供后面与MQTT服务连接交互时认证使用；

4：将通过配置文件中定义的MQTT服务地址及端口创建客户端连接，同时将连接凭证附带到连接中，用于MQTT服务端对其进行鉴权验证；

5：连接成功后，将自动订阅主题：“{card_region}/real/data/+”，“{card_region}/online/+”，“{card_region}/offline/+”，订阅主题之后，将会收到关心的主题数据；注：{card_region}为卡头区域，如单服务器处理能力不足时，对服务器处理数据分流使用；

6：卡头获取到MQTT连接信任凭证，建立MQTT连接，连接成功后MQTT服务将会发布连接成功主题：“{card_region}/online/{device1}”；卡头连接断开后MQTT服务将会发布主题：“{card_region}/offline/{device1}”；机台获取到实币票数据，卡头发布主题(实币票数据)：“{card_region}/real/data/{device1}”；

7：卡头服务程序获取主题：“{card_region}/real/data/{device1}” 数据内容（卡头上传的实币票数据信息），提取MAC所对应的缓存数据，将缓存数据与新接收到数据进行计算（新增/更新），计算完成后再更新回写到缓存中；

8：MQTT服务收到卡头设备的连接，将会发布主题：“{card_region}/online/{device1}”，卡头服务程序收到订阅主题内容后将对应的卡头标识为在线状态；
   MQTT服务收到卡头设备的断开，将会发布主题：“{card_region}/offline/{device1}” 卡头服务程序收到订阅主题内容后将对应的卡头标识为离线状态；

9：实币、实票：服务程序会先验证收到的数据中的时间戳，如果数据“时间戳”未更新（即与前一次接收数据相同），则此条数据被认为是重复传输的，将会被服务程序丢弃；判断“实币”或“实票”的值大于 0 时，则程序将生成一条“实币实票”命令，添加到“实币实票”数据集合中，然后在“实币实票”处理服务中将会以每 50 个命令创建一个批次，定时（参数设定）以并发方式与数据库直接进行交互保存，保存不成功命令，将会转到下一次继续执行；

10：定时提交数据（实币，实票）：在提交数据时，需要对缓存数据进行锁定，避免同一份数据在多个地方被更新，造成数据错误。

11：当“卡头硬件程序”有缺陷或者是有新功能发布时，此时需要将所有在线的卡头进行硬件程序进行在线升级；

硬件程序存放：将发布的最新硬件程序放在“卡头服务程序”目录下的“bin”文件夹中，文件夹中可能会有多个版本的程序文件，但是“卡头服务程序”只会获取文件名称版本最新的卡头硬件程序文件；

硬件程序刷新：当硬件程序文件已经放置好后，“卡头服务程序”需要重新加载最新版本的程序文件，此时只需要点击程序界面左上角的“刷新固件版本号”的按钮即可，同时按钮右边的显示框也会更新当前最新版本号，最后程序会自动重新打开“Powershell”重新启动“nodejs”服务，以提供“卡头硬件程序”的下载，此时在“Powershell”窗口中也可以看见当前已加载的程序版本名称；

硬件程序推送：新硬件程序发布后，需要即时升级到最新时，需要点击程序界面的“固件升级-Ver”按钮，通过以推送的方式来升级“卡头硬件程序”，推送是按一批次推送后等待一段时间，具体参数配置在第 2 步中有说明；推送时，会逐个判断当前“卡头程序”的版本是否与服务器程序中的最新版本一致，如果则不推送给该卡头进行升级；在推送过程中，有部分卡头连接状态可能处于断开或已经关机状态，无法将升级命令发送到卡头，此时程序有多轮推送机制，推送轮次可通过本地配置文件配置，在第 2 步中有说明；此时可以程序界面状态栏中可以展示当前最新版本推送进度及升级百分比；

12：当服务程序在运行过程中，可以点击“保存表格数据”按钮，保存程序当前所有连接过的卡头的数据到 Excel 表格中，后期可以用它来做一些数据所统计分析或数据备份保存等；

13：程序在每天早上“05:00”时，会自动将程序表格中的数据全部保存到 Excel 表格中，然后将“系统内存”，**“缓存数据”**和“程序界面”数据进行清理，使“卡头服务程序”每天的数据更干净整洁；

![](https://picgo.melands.cn/img/2023/12/18/%E5%8D%A1%E5%A4%B4%E5%AE%9E%E5%B8%81%E9%80%BB%E8%BE%91%E6%B5%81%E7%A8%8B%E5%9B%BE_20231218145925450854.png)