卡头服务程序开发文档

# 1.   文档说明

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

# 2.   项目目标

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

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

# 3.数据表设计

| 表 名      | machine_deivce_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) |         |          |      |
| 补充说明   |                         |             |         |          |      |

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

## 4.1 数据字典

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

## 4.2 全局变量

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

# 5.接口设计

### 5.1 卡头虚币虚票数据保存

**说明：**

调用：

| **调用URL** | https://cash.melands.cn/cardApiBatch |
| ----------------- | ----------------------------------------- |

入参：

| **参数名** | **类型** | **说明**                                   | **备注** |
| ---------------- | -------------- | ------------------------------------------------ | -------------- |
| Type             | string         |                                                  |                |
| Mac              | string         | 卡头mac                                          |                |
| Pc_name          | String         | 运行卡头服务程序的电脑名称                       |                |
| Leagno           | String         | 加密卡号                                         |                |
| Entity_id        | String         | 实体卡号                                         |                |
| Card_no          | String         | 会员卡号                                         |                |
| Cardtype         | String         | 会员卡类型                                       |                |
| Num              | Int            | 数量                                             | 虚拟币或票     |
| Method           | string         | 数据处理接口名称（outTicket,outTicketN,getCoin） |                |

出参：

| **参数名** | **类型** | **说明**                           |
| ---------------- | -------------- | ---------------------------------------- |
| Object           | Json           | 处理结果（结果代码、结果提示、返回数据） |

# 6.实施内容

## 6.1 概况描述

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

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

## 6.2 卡头数据服务程序

### （1）模块名称：卡头数据服务程序

### （2）模块路径：卡头数据服务程序

### （3）逻辑描述：

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

2：程序在运行时会启动监听系统指定的端口号（“卡头”访问些服务器时的端口传输数据），端口号通过配置文件（LEDI.ini）配置，同时数据提交接口的服务器连接协议、地址、固件推送批次大小、单个推送等待时长、最大自动推送轮数等参数进行配置;

3：系统启动后，会实时接收“卡头”连接，通过“卡头”传送的mac号，在系统中进行其身份验证，判断验证它是否为平台系统中的合法设备，同时并将结果显示到服务程序界面和以及反馈到远程门店的卡头上显示；

4：当“卡头”的“授权”验证通过后，卡头即可以向服务程序发送机台产生的数据（授权，心跳，实币，实票，虚币，虚票，解绑等）；

5：“卡头服务程序”收到“卡头”传送的数据后，会识别其数据类型（授权，心跳，实币，实票，虚币，虚票，解绑），生成相对应的命令，以备后续与系统接口或数据库进行数据交互保存；

授权：判断“卡头”传输数据的“method”参数为“check”值，程序将实时处理，并将结果返回到“卡头”显示以及呈现在程序界面；如果“卡头”未在系统中有记录，则自动为其添加记录，返回结果为已入库，需要为其绑定指定门店及指定机台；如“卡头”在系统中为已存在，再判断它是否为已启用，是否绑定机台，是否设置好参数等；

心跳：判断“卡头”传输数据的“method”参数为“heart”值，程序将直接返回成功信息到卡头，以表示“卡头”与“服务程序”间连接为正常状态；

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

虚币：判断“卡头”传输数据的“method”参数为“getCoin”和“vcoinN”值时，程序将生成一条“虚拟币”命令，添加到“虚拟币”数据集合中，然后在虚拟币处理服务中将会以每5个命令创建一个批次，并发方式提交到系统的接口进行统一处理。同时更新程序界面该卡头的“虚拟币”数据，并将结果返回到远程“卡头”显示；

虚票：判断“卡头”传输数据的“method”参数为“dataN”值，服务程序会先验证收到的数据中的时间戳，如果数据“时间戳”未更新（即与前一次接收数据相同），则此条数据被认为是重复传输的，将会被服务程序丢弃；判断“虚拟票”的值大于0时，则程序将生成一条“虚拟票”命令，添加到“虚拟票”数据集合中，然后在“虚拟票”处理服务中将会以每5个命令创建一个批次，并发方式提交到系统的接口进行统一处理。同时更新程序界面该卡头的“虚拟票”数据，并将结果返回到远程“卡头”显示；

解绑：判断“卡头”传输数据的“method”参数为“unBound”值，程序将生成一条“解绑”命令，添加到公共命令集合中，然后在处理服务中将会实时进行统一处理。同时更新程序界面该“卡头”的“状态”数据，并将结果返回到远程“卡头”显示；

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

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

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

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

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

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