第3方接口说明

首要声明：
只要采用了第3方财务软件，雷石系统就只提供点歌功能(开台关台由第3方软件控制或者用雷石吧台管理系统开台关台，但严禁共用第3方软件和雷石吧台管理系统进行开台关台)。
只要采用了第3方财务软件，则点播终端酒水数据的来源是第3方软件，点酒水之后保存在第3方数据库为雷石创建的FoodCarts表中。
只要采用了第3方财务软件，雷石吧台管理系统就只能用于管理房台，禁止使用其它功能(这些功能应由第3方软件提供)。

0. 基本原理
原理图参见3rd.jpg
0.1 雷石DBAss服务通过ODBC连接第3方软件数据库。
0.2 雷石DBAss服务读取C:\thunder\ktv\ktvsvr\3rdSQL\下的SQL脚本文件，在第3方软件数据库中执行并获取返回的记录集(酒水大类、类别、明细、账单、已点酒水等)。
0.3 雷石DBAss服务把记录集反馈给雷石点播终端。
0.4 雷石点播终端把所点酒水发送给雷石DBAss服务
0.5 雷石DBAss服务保存、落单所点酒水到第3方软件数据库的中间表FoodCarts。
0.6 第3方软件把落单酒水转移到自己的数据库表。
0.7 第3方软件提供在雷石机顶盒查找酒水的存储过程供客人查询，如果直接使用雷石自带的GetBills.txt，则必须把在第3方软件中所点的酒水插入到FoodCarts表，把退的酒水从FoodCarts表删除。

1. 系统要求
要求雷石系统必须是8.82及以后的有酒水版本。

2. 文件列表
2.1 3rdtables.sql 创建在第3方软件数据库中，用于保存雷石客户端点的酒水，FoodCarts必须是个实体表。
2.2 CleanRoom.dll和cleanroom.txt 发送开台、关台指令给机顶盒DLL(9.2以及9.2以前使用)
2.3 ThunderTools.Dll 发送开台、关台指令给机顶盒COM组件(9.3以及9.3以后版本使用)
2.4 房台接口----简单.htm 说明sp_3rd_CloseRoom、sp_3rd_OpenRoom存储过程如何调用。

3. 使用方法

3.1 配置好雷石数据库服务器。

3.2 在第3方程序PC上创建雷石运行环境，以便CleanRoom.dll或者ThunderTools.Dll可以正常运行
3.2.1 在第3方程序PC上的C盘创建Thunder目录。
3.2.2 把雷石数据库服务器上C:\thunder\system\ocx\整个目录复制到每个第3方软件的吧台机C:\thunder\system\ocx\。
3.2.3 每个第3方软件的吧台机双击C:\thunder\system\ocx\register.bat注册控件
3.2.4 把雷石数据库服务器上的C:\thunder\thunder.ini复制到每个第3方软件的吧台机C:\thunder\下。
3.2.5 把雷石数据库服务器上的C:\thunder\ktv\ktvsvr\复制到每个第3方软件的吧台机C:\thunder\ktv\ktvsvr\下。
3.2.6 每个第3方软件的吧台机运行C:\thunder\ktv\ktvsvr\Broadcast.exe -i并查看服务中是否出现了Broadcast服务。
3.2.7 (9.3以及9.3以后版本)用附件test发送开台、关台指令看机顶盒是否受控制。
3.2.8 (9.3以及9.3以后版本)参考附件的代码把发送开台

、关台指令集成到第3方软件。


3.3 在第3方的程序上加入房台，设置IP和编号，在雷石的吧台管理软件上加入同样IP和编号的房台，并且雷石吧台中房台的消费方式必须是夜总会方式。

3.4 如果在机顶盒落单不需要验证密码，那么请在雷石吧台管理软件中点击【初始化设置】，【机顶盒设置】。在“房台酒水设置”中设置为“不使用密码”。

3.5 如果在机顶盒落单需要验证密码，那么请在雷石吧台管理软件中点击【初始化设置】，【机顶盒设置】。在“房台酒水设置”中设置为“提交点单时使用密码”。并修改3rdSQL\CheckLogin.txt提供验证机制。

3.6 配置雷石软件连接第3方数据库的帐号、密码、系统ODBC数据源等，目的是为了让雷石的Dbass可以访问第3方的数据库。
3.6.1 在第3方数据库中加入Thunder3rd帐号，赋予相应表、存储过程等的执行和读、写权限。
3.6.2 在雷石的数据库服务器上和所有视频服务器上使用【控制面板】【管理工具】【数据源(ODBC)】创建ODBC数据源(必须是系统数据源/系统DSN)，并且不能是Windows身份验证。
3.6.3 在雷石的数据库服务器上和所有视频服务器上，根据第3方提供的数据库帐号、密码和ODBC数据源名称，用雷石系统中的“第3方财务软件设置工具”(3rdSettings.exe)来设置并测试设置。
以下两点需要郑重的向客户相关管理人员声明：

3.7 如果第3方软件修改了给雷石的帐号、密码，必须用雷石提供的“第3方财务软件设置工具”来重新设置，设置完毕之后必须重启DBAss服务,否则点不了酒水。

3.8 如果在第3方软件软件中修改了房台的编号和IP，必须用雷石的吧台管理软件设定新的编号和IP，以保证一一对应，否则酒水可能点不上或者点到别的房台上。

4. 第3方软件开发流程
4.1 参考C:\thunder\ktv\ktvsvr\3rdSQL\说明.txt文件，修改C:\thunder\ktv\ktvsvr\3rdSQL\下的SQL脚本文件，要求对这些脚本涉及到的数据库对象，第3方软件提供的帐号都必须有相应的权限。并且把这些文件都复制到所有安装DBAss服务的服务器上。
4.2 程序开始调用CleanRoom.dll的CreateLink函数(9.2以及9.2以前)。
4.3 开台调用sp_3rd_OpenRoom，连接雷石的数据库karaok，用户名是3rd,密码为空，目的是修改吧台在雷石数据库中的状态。VB例子如下(关台类似，只需要修改存储过程名称)：

Dim GCon As ADODB.Connection
Set GCon = Nothing
Set GCon = New ADODB.Connection
GCon.ConnectionTimeout = 120
GCon.CursorLocation = adUseClient
GCon.Open "DRIVER={SQL Server};SERVER=192.168.0.160;UID=3rd;PWD=;DATABASE=karaok;" '打开连接--192.168.0.160请更换为实际使用的雷石数据库服务器IP地址

On Error Resume Next
Dim Cmd

As New mand
Dim Prm As New ADODB.Parameter
Dim retCode As Integer
Dim strIP As String

strIP = "192.168.0.100" '房台IP
Cmd.ActiveConnection = GCon
mandText = "sp_3rd_OpenRoom"
mandType = adCmdStoredProc
mandTimeout = 15

Set Prm = Cmd.CreateParameter("Return", adInteger, adParamReturnValue, , -1)
Cmd.Parameters.Append Prm
Set Prm = Cmd.CreateParameter("@room_id", adInteger, adParamInput, 4, NULL)
Cmd.Parameters.Append Prm
Set Prm = Cmd.CreateParameter("@room_serialno ", adVarWChar, adParamInput, 10, Null)
Cmd.Parameters.Append Prm
Set Prm = Cmd.CreateParameter("@room_ip", adVarWChar, adParamInput, 100, strIP)
Cmd.Parameters.Append Prm

Cmd.Execute

retCode = -1
retCode = Cmd(0) '获取返回值
If retCode<>0 Then '开台失败
End If
(9.3以及9.3以后版本)调用ThunderTools组件的SendMessage2STB("房台IP", MESSAGE_TO_STB_OPEN_ROOM)发送开台指令给机顶盒机顶盒才能点歌和点菜。

4.4 当FoodCarts表的FoodCart_Status由'S'更新为'C'的时候，第3方应该使用触发器或者程序把'S'更新为'C'的酒水转到自己的数据库中。
4.5 结帐前的退单，可直接修改FoodCarts表中的数量或者删除，只应该对FoodCart_Status为'C'的进行退单。结帐后的退单只在第3方软件中进行处理。
4.6 结帐把FoodCarts表上对应房台的酒水删除。
4.7 关台调用sp_3rd_CloseRoom，改变房台在雷石数据库中的状态为空闲。9.2以及之前版本要调用CleanRoom.dll的SendCloseMsg2STB函数，目的是为了清除机顶盒上的点单和点歌信息，否则会记入到下一客人。9.3以及之后版本调用ThunderTools组件的SendMessage2STB("房台IP", MESSAGE_TO_STB_CLOSE_ROOM)
4.8 9.2以及之前版本程序退出调用CleanRoom.dll的CloseLink函数。
4.9 转台的处理
4.9.1 第3方软件对目标房台进行开台，开台步骤和正常的房台开台一致。
4.9.2 第3方软件把FoodCarts表中的源房台对应的酒水的IP修改为目标房台的IP。
4.9.3 第3方软件关闭源房台，步骤和正常的房台关台一致。
4.10 后台点酒水、修改酒水数量和退酒水的处理
直接修改FoodCarts中已落单(状态为'C')的酒水的数据或者删除，然后机顶盒先回到主界面，再进入已点酒水就可以相应的显示。
4.11 赠送的处理
把赠送的酒水再建一项，例如原有名称为xxx,新的项名字为XXX(赠)，价格为0，这样就可以实现。固定赠送项目，开台时向FoodCarts表中写赠送项目，FoodCart_Status为'C'即可。
4.12 转台和并台歌曲转入目标房台(这步可不做)
4.12.1 必须在调用sp_3rd_CloseRoom关闭源房台之前完成。
4.12.2 修改表MediasMenu中的数据，MediasMenu结构如下：
create table MediasMenu
(
MediaMenu_ID normalid not null,
MediaMenu_Media_ID

normalid null,
MediaMenu_Customer_ID normalid null,
/*房台ID，转台或者并台时，把此ID修改为目标房台的ID，此ID可用以下之一语句获取，替换其中的“房台编号”和“房台IP地址”为实际房台编号和房台IP地址
SELECT TOP 1 Room_ID FROM Rooms WHERE Room_SerialNo = '房台编号'
或者
SELECT TOP 1 Room_ID FROM Rooms WHERE Room_IpAddress = '房台IP地址'
*/ MediaMenu_Room_ID normalid null,
/*歌曲播放优先级，数越大，则在播放列表中越靠前，转台或者并台时，把源房台的MediaMenu_Priority按MediaMenu_Priority由大到小顺序逐个排在目标房台中MIN(MediaMenu_Priority)后面，
例如如果目标房台点了两首歌，MediaMenu_Priority 分别为1000和999,源房台点了2首歌，MediaMenu_Priority 分别为10011和9999，则应改为998和997
重新启动目标房台机顶盒，则源房台歌曲将会附加到目标房台后面。
*/
MediaMenu_Priority queue default(10000000000000),
MediaMenu_IsPlaying judge default(0)
)
4.12.3 修改MediasMenu表中源房台的MediaMenu_Priority，按MediaMenu_Priority由大到小顺序逐个排在目标房台中MIN(MediaMenu_Priority)后面
4.12.4 修改MediasMenu源房台的MediaMenu_Room_ID为目标房台的Room_ID
4.12.5 关闭源房台
4.12.6 重新启动目标房台的机顶盒。

5 设置完毕之后重启DBAss服务。

6 在开发过程中使用查询分析器和事件探查器可以对您的开发有很大好处。


7. 常见问题
7.1 问：为什么第3方软件无法控制雷石的房台状态？
答：有两种可能：
(1)第3方软件没有连接上雷石数据库。
在雷石数据库服务器上运行事件探查器，当第3方软件开台后点击红色停止按钮，如果在所有行的TextData列都找不到sp_3rd_OpenRoom，则表示是这种情况。
请查一下连接雷石数据库的字符串，对ADO可参考4.3中的
DRIVER={SQL Server};SERVER=192.168.0.160;UID=3rd;PWD=;DATABASE=karaok;
192.168.0.160请更换为实际使用的雷石数据库服务器IP地址。
(2)排除了(1)的可能后，对8.9.0版本需要打数据库补丁。
(3)要开台、关台的房台和第3方软件设置的房台IP不对应。

7.2 问：为什么机顶盒无法查找到酒水大类信息？
答：请把所有运行DBAss服务的服务器关掉，只保留其中一台开着，方便找原因。有两种可能：
(1)雷石DBAss服务没有连接上第3方数据库。
如果第3方软件是SQL Server，在机顶盒上退出大类查找页面，在第3方数据库服务器上运行事件探查器，在机顶盒上进入大类查找页面，点击红色停止按钮，如果在所有行的Application列都找不到DBAssistant，则表示是这种情况。
请检查是否按照3.4步骤一一做完了。
排除问题之后可在每台运行DBAss服务的服务器上进行同样的配置。
(2)C:\Thunder\ktv\ktvsvr\3rdSQL\LookupRecipeChannels.txt语句写的有问题。
排

除了1的可能之后，请检查LookupRecipeChannels.txt在第3方数据库的查询分析器上运行是否正确。只有该语句正确DBAss才可以查找到对应的大类。另外列的别名、数据类型必须和样本脚本中的一致。
排除问题之后可在每台运行DBAss服务的服务器上进行同样的配置。

只要7.1和7.2都解决了,说明双方程序的连接已经没有问题。那么其它问题都可以检查C:\Thunder\ktv\ktvsvr\3rdSQL\的文件用7.2类似的办法使用查询分析器和事件探查器辅助解决。

7.3 问：为什么机顶盒可以查看到到酒水大类、小类和酒水信息，但无法点酒水？
答：有以下两种情况：
(1)FoodExists.txt中的SQL语句写得不正确，导致DBAss服务判断要点的酒水不存在。
(2)房台状态不是使用状态，只有在使用状态下的房台才可以点酒水，否则就会导致本来不是客人点的酒水也算到客人的头上。

7.4 为什么有些机顶盒可以查找到酒水大类信息，但有些不行？
原因是没有在每台DBAss运行的服务器上配置好，只要7.1和7.2都解决之后在每台运行DBAss服务的服务器上进行同样的配置就可以解决。

7.5 为什么雷石系统中房台状态已经变为使用，但机顶盒无法点歌？
请检查调用CleanRoom.dll(9.2和之前版本)或者ThunderTools.Dll(9.3和之后版本)的步骤是否正确。