收银台服务程序开发文档

# 1.   文档说明

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

# 2.   项目目标

由于乐的文化的营业系统是要是以Web系统方式进行开发和使用的，以方便后期在问题处理、新功能开发发布的成本控制方便。同时在某一些业务上，Web方式却又是不可以完成的，此时只能通过一些中间转换处理的方式来达到实现需求的目的。即在营业期间收银员在通过浏览器操作系统时，是无法直接通过浏览器与“扫码器”，“POS机”等硬件设备进行数据交互；此时可以通过开发客户端程序使用WebSocket技术来进行程序与浏览器间进行数据交互，再由客户端程序与硬件设备进行交互，将交互结果数据再通过WebSocket连接发送到浏览器上，Web系统收到数据后可再进行其业务处理。

# 3.数据表设计

| 表 名    |            |                            |          |          |       |
| -------- | ---------- | :------------------------: | -------- | -------- | ----- |
| 中文描述 |            |                            |          |          |       |
| 建立日期 | 2023/01/03 |                            | 修改日期 |          |       |
| 列 名    | 中文描述   | 数据类型<br />（数度范围） | 空/非空  | 是否主键 | 备 注 |
|          |            |                            |          |          |       |
| 补充说明 |            |                            |          |          |       |

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

## 4.1 数据字典

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

## 4.2 全局变量

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

# 5.接口设计

## 5.1 零币-银行卡支付

调用：

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

入参：

| **参 数 名** | **类  型** | **说  明**                             | **备  注** |
| ------------------ | ---------------- | -------------------------------------------- | ---------------- |
| Data               | string           | 订单数据，信息包含购买产品信息，支付信息等。 |                  |
| Method             | string           | 数据处理接口名称（lb_mispos_payment）        |                  |

出参：

| **参数名** | **类 型** | **说 明** |
| ---------------- | --------------- | --------------- |
| Json             | Object          | 订单处理结果    |

## 5.2 套餐-银行卡支付

调用：

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

入参：

| **参数名** | **类 型** | **说 明**                              | **备 注** |
| ---------------- | --------------- | -------------------------------------------- | --------------- |
| Data             | string          | 订单数据，信息包含购买产品信息，支付信息等。 |                 |
| Method           | string          | 数据处理接口名称（xx_mispos_payment）        |                 |

出参：

| **参数名** | **类 型** | **说 明** |
| ---------------- | --------------- | --------------- |
| Json             | Object          | 订单处理结果    |

## 5.3 杂项-银行卡支付

调用：

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

入参：

| **参数名** | **类 型** | **说 明**                              | **备 注** |
| ---------------- | --------------- | -------------------------------------------- | --------------- |
| Data             | string          | 订单数据，信息包含购买产品信息，支付信息等。 |                 |
| Method           | string          | 数据处理接口名称（zx_mispos_payment）        |                 |

出参：

| **参数名** | **类 型** | **说 明** |
| ---------------- | --------------- | --------------- |
| Json             | Object          | 订单处理结果    |

## 5.4 银行卡支付-撤销

调用：

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

入参：

| **参数名** | **类 型** | **说 明**                              | **备 注** |
| ---------------- | --------------- | -------------------------------------------- | --------------- |
| Data             | string          | 订单数据，信息包含购买产品信息，支付信息等。 |                 |
| Method           | string          | 数据处理接口名称（mispos_return_insert）     |                 |

出参：

| **参数名** | **类 型** | **说 明** |
| ---------------- | --------------- | --------------- |
| Json             | Object          | 订单处理结果    |

# 6.实施内容

## 6.1 概况描述

会员/非会员客户到门店收银台购买商品或游玩项目时，收银员在营业系统中作收银操作的过程中，会使用到多种收银或销售设备，此时的营业系统是无法直接与收银设备或销售设备进行数据交互，此时只能通过客户端程序做中间桥梁，将营业系统与收银设备和销售设备进行“连接”，以此来达到“营业系统”与“收银设备”和“销售设备”间的数据交互。

## 6.2 程序初始化
### 6.2.1 模块名称：程序初始化
### 6.2.2 模块路径：收银台服务程序 > 程序初始化
### 6.2.3 逻辑描述：

1. 程序运行前，还需要在程序当前目录下的“bank”目录中的“Pos.ini”配置文件中配置POS机所连接取端口号，以及当前门店POS收银的银行信息等；
2. 程序启动时，将读取与程序同名的ini类型配置文件（配置项有：是否打印POS机消费小票，是否打印POS机退款小票，程序连接数据库）；

* 自动连接POS机，进行签到操作，成功或失败将在程序界面给出提示，如签到成功后即可使用POS进行收银刷卡操作；
* 将自动尝试连接“提币机”和“扫码头”，成功或失败将在程序界面给出提示，如果连接成功，后继将可以使用“提币机”和“扫码头”；
* 启动Websocket服务，端口固定为3000，侦听Websocket端口，对数据进行识别，数据为标准的json格式数据;

a)、method属性为“mispos”则为POS机收银请求，此时程序将调用POS机插件进入刷卡提示，客户此时可进行银行卡刷卡支付操作；在执行完POS刷卡操作之后将会自动调取远程服务接口，将订单信息同步处理，支付完成和订单处理完成后，程序将会根据配置来决定是否需要打印POS收银小票信息，将结果返回到业务系统显示；

b)、method属性为“getCoin”则为二维码扫码操作，即扫码提币，提币时会验证本次提币数量范围，在1-999之间，超过范围提示反馈到前端，提币数据验证通过后，发送提币命令到提币机，提币机出币，完成提币，将结果返回到业务系统显示；

c)、method属性为“speker”则为语音播报功能，程序将会直接语音播报接收到数据的“msg”属性信息；
* 启动“扫码头”读取服务和“提币机”状态监测处理服务；

a)、提币机-服务以每秒10次的频率检测提币机状态，如有异常，则提示到程序界面，并反馈到业务前端，提币业务不可能，需要即时处理；

b)、扫码头-扫码头的可以实现“二维码”、“IC卡”和“RFID设备”的识别；

二维码：程序将读取扫码头设备的“二维码”数据，验证数据格式为乐的系统生成的二维码，返回数据type参数为：qrcode（如：{"type":"qrcode","errCode":0,
  "errMsg":"","data":"codeDdata"}）；验证数据格式为特斯拉系统生成的二维码，返回数据type参数为：tsl（如：{"type":"tsl","errCode":0,
  "errMsg":"","data":"codeDdata"}），再通过Websoket连接发送到前端业务系统进行后续业务处理；

IC卡/RFID设备：程序会将扫码头读取到的数据进行解析识别，长度为7位的，即为IC卡的卡号数据；长度为18位的，即为RFID设备芯片数据；最后通过Websoket连接发送到前端业务系统进行后续业务处理；

3. POS机，IC卡,RFID设备读取的数据处理结果均会在服务程序界面做输出显示提示；
4. 在进入程序配置界面时，需要输入管理密码：
   * 输入密码窗口居中显示，提示用户输入管理密码；
   * 输入完成后，可以直接按“回车”键确认或点击“确认”按钮；
   * 密码输入正确，则直接进入配置界面；密码输入错误，输入框则密码红色闪烁提示；

5.在配置界面，可以对POS机刷卡完成或退款完成时的小票是否打印进行设置。