dp2library 增加了新的读者同步接口

[DigitalPlatform]

dp2library 目前版本中，已经提供了一种向卡中心请求读者数据的接口，要求第三方提供一个 .NET Remoting 服务器，然后 dp2library 在 library.xml 通过配置 patronReplication 元素，让 dp2library 在需要的时候调用这个 .NET Remoting 接口(每轮一次或多次请求)，获得卡中心的全部当前读者数据。

这个接口对第三方要求较高：首先要熟悉 .NET Remoting 概念，另外也限制了能使用的编程语言；并且要组织好每轮 API 前后次之间的分页。另外 dp2library 这一端请求的时候也比较复杂，要处理分页。

最新版增加了一种新的读者同步接口，要求第三方提供一个 Console 程序即可，按照调用参数约定，在一个 XML 文件中返回全部读者数据即可。对第三方的要求降低了，dp2library 这一端也不需要处理分页问题。

这种新型接口在 library.xml 的配置方法如下：

    <patronReplication exePath="c:\interface\interface.exe" patronDbName="同步读者" idElementName="barcode" idFromName="证条码号" />

注意 exePath 属性取代了旧的接口方式的 interfaceUrl 属性。

(patronReplication 元素还增加了一个属性 mergeStyle，属性值为空或者 "simple")

接口调试的一种方法

把 interface.exe 获取成功的 XML 文件，比如名叫 test.xml 文件，拷贝到 dp2library 数据目录下的 patronReplication 子目录下。
然后配置 library.xml:

    <patronReplication exePath="!copy %datadir%/patronReplication/test.xml" patronDbName="同步读者" idElementName="barcode" idFromName="证条码号" />

这样当 dp2library 有关模块请求同步数据的时候，不会真正调用 interface.exe 接口程序，而是利用上述 test.xml 文件里面的内容，进行同步写入相关读者库的操作。这个方法用于验证 test.xml 文件中的内容被程序正常理解和处理。

第三方在开发接口程序 interface.exe 的过程中，首先应当确认它需要输出的确切数据格式，可以用上述方法来验证确认。

XML 数据文件中的特殊属性

dprms:missing 属性表示这个元素卡中心原本没有提供。dp2library 在遇到有这样属性的元素时，会对当前读者库内对应的记录，做删除此元素的操作。

dprms:default 属性表示当同步过来的数据用于第一次创建一条新读者记录的时候，使用这个元素的内容(需去掉 dprms:default 属性再用到记录中)。然而当读者库中已经有一条这样的记录(打算从卡中心获得的数据中更新某些字段)时，带有 dprms:default 属性的元素会被弃用，不会更新到读者库中对应的记录里。

(注: 上述两个属性，都是用“存在此属性”表达一种状态。有没有属性值、属性值是什么，dp2library 不会在意。也就是说最好的用法是只有属性名，不要有属性值)

[DigitalPlatform]

某用户单位部署新型同步接口的步骤

(2024/11/21 编写)

一、升级 dp2installer 到最新测试版

在服务器上，先卸载 dp2installer，然后重新安装 dp2installer 测试版。

安装页面地址为：
https://dp2003.com/dp2installer/v3_dev/publish.htm

二、升级 dp2circulation 到最新测试版

在用户单位老师的前端电脑上，先卸载 dp2circulation，然后重新安装 dp2circulation 测试版：

安装页面地址为；
https://dp2003.com/dp2circulation/v3_dev/publish.htm

三、启动 dp2circulation 访问 dp2library 服务器

进行一些基本的检索操作，观察系统是否运行正常。

dp2library 在启动以后，会花一定时间自动处理读者库和实体库中的所有记录，修改某些字段。要等待自动升级数据完成，再进行其它配置和修改系统的操作。

如何观察自动升级数据是否完成？到 dp2library 模块所在的服务器上，检查当天错误日志文件，里面有文字表明升级数据完成。

(注: 当时的 dp2library 版本有个小 bug，错误日志文件中显示的处理读者记录数为零。已改正)

四、创建“同步读者”读者库

利用内务的系统管理窗，创建一个新的，专用于存储从企业微信同步过来的读者记录的读者库。
(注意这个读者库“参与流通”)

五、为所有读者库增配 qywx 字段

注意，也包括刚才新创建的“同步读者”读者库。

建议利用内务的系统管理窗的“内核”属性页进行。

为所有读者库增配一个“企业微信”检索点：
keys 文件片段:

	<key>
		<xpath>*/qywx</xpath>
		<from>qywx</from>
		<table ref="qywx" />
	</key>
	<table name="qywx" id="20">
		<convert>
			<string style="upper,split" />
		</convert>
		<convertquery>
			<string style="upper" />
		</convertquery>
		<caption lang="zh-CN">企业微信</caption>
		<caption lang="en">Qiye Wexin</caption>
	</table>

为所有读者库的 browse 配置文件增加一列 qywx:

  <col title="企业微信">
    <xpath>*/qywx</xpath>
  </col>

(建议加在“证条码号”后面)

六、第一次修改 library.xml 配置文件

6.1 请先停止 dp2library 实例。(dp2installer 的实例对话框可以完成此操作)

6.2 在服务器上，利用记事本修改 dp2library 数据目录下的 library.xml 文件。

library.xml 中 circulation 元素内增加或修改属性值:

    patronReplicationFields="qywx" 
    patronAdditionalFields="qywx"
    acceptBlankReaderBarcode="true" (注: 如果为 false，则同步的时候会报错说创建记录不允许证条码号为空)

修改完成后，保存 library.xml。

(注: 这一步在实际操作的时候踩坑了。维护人员没有意识到用户单位服务器上的文件管理器界面隐藏了所有文件的扩展名显示，因此误把 library.xml.bak 当作 library.xml 进行编辑修改，然后走到合并读者记录一步的时候，发现保存回读者库的记录中，qywx 元素没有保存进去)

6.3 然后在 dp2installer 实例对话框中重新启用唯一的 dp2library 实例。

七、给现有读者记录合并增添企业微信 ID

在内务前端中打开一个读者查询窗。
启动从 Excel 导入合并功能。在对话框中，载入预先准备好的 merge.xlsx 文件。注意删除第一行内容。注意选择“姓名”作为合并的 Key 字段。qywx 列名需要手动输入。完成对话框。
接下来有先后两个对话框，分别询问搜索用的读者库名，和追加用的读者库名。前者选“<全部>”(注意复选 list 的操作有些奇怪)，后者选“同步读者”。
然后接下来可能会有对话框询问搜索不到姓名的记录如何处理，要选“跳过”。
接下来会有对话框询问命中多条的读者姓名，可以根据上面提示的单位信息进行甄别选择。如果列出来的都不是合适的，要点“取消”按钮。
直到全部选择完成。

最后保存全部修改到读者库。(注: 如前注释的，这一步实际上保存后发现 qywx 元素没有保存进去)

八、第二次修改 library.xml 配置文件，启用读者同步

8.1 请先停止 dp2library 实例。(dp2installer 的实例对话框可以完成此操作)

8.2 把(从企业微信同步读者信息的)接口程序 xxxPatronReplication.exe 拷贝到 C: 盘一个专门的文件夹，比如 c:\interface。

8.2 在服务器上，利用记事本修改 dp2library 数据目录下的 library.xml 文件。

library.xml 中根元素下增加：

    <patronReplication exePath="c:\interface\xxxPatronReplication.exe" patronDbName="同步读者" idElementName="qywx" idFromName="企业微信" mergeStyle="simple" />

library.xml 中 monitors 元素下添加:

        <patronReplication startTime="23:00" />

注意 patronReplication 元素名里面没有 Monitor 字样。

修改完成后，保存 library.xml。

8.4 然后在 dp2installer 实例对话框中重新启用唯一的 dp2library 实例。

8.5 在前端电脑上用内务的批处理任务窗，启动读者同步任务，并观察一下读者同步任务的输出信息。确认同步任务正常进行。

8.6 等一轮读者同步任务完成后，在内务中用读者查询窗可以检索到“同步读者”库中新增了一批记录。检查一下这些记录的内容，应该有 qywx 姓名 单位 电话号码这几个字段和内容。

九、配置内务前端，以允许读者窗编辑 qywx 字段内容

为了让内务读者窗的编辑器中可以直接编辑扩展的 qywx 字段，需要
在内务的用户文件夹中，创建一个名为 patron_extend.xml 的文本文件，内容如下：

<editor>
  <field element="qywx">
    <caption lang="zh">企业微信</caption>
  </field>
</editor>

(注：实际操作中这一步也踩坑了，由于文件夹显示文件名时隐藏了扩展名，实际上用记事本创建的文件的文件名是 patron_extend.xml.txt)

然后打开一个读者窗，观察“企业微信”字段是否可以编辑了。

十、复盘

10.1 一定要注意用户服务器桌面上 Windows 文件管理器里面显示的文件名，要确认显示了扩展名。

10.2 如果可能，尽量用内务访问 dp2library 服务器，用内务的“系统管理窗”的“内核”属性页观察、编辑修改 library.xml 文件，这样也可以规避 Windows 文件管理器中操作的一些坑。不过前提条件是 dp2library 是正常启动状态。

10.3 使用 Windows 的 notepad 创建 XML 文件的时候，注意保存的时候，对话框里面的文件类型一定要选择 .，这样可以有效避免 notepad 在保存时偷偷给输入的文件名后面添加 .txt 部分。

10.4 利用 notepad 创建 XML 文件的时候，最好带上 prolog，并小心指定正确的 encoding(notepad 本身并没有针对 XML 文件格式确保 prolog 中 encoding 正确的能力)。如果没有 prolog，所产生的不带 BOM 的 UTF-8 编码方式的文件和 ANSI 编码方式的文件，一些应用程序可能无法准确区分。

10.5 内务前端的读者窗在保存时遇到部分字段被拒绝的情况会弹出对话框报错，然而读者查询窗在保存修改时遇到同样情况则不会报错。建议改进读者查询窗中的保存修改功能，遇到同样情况要弹出对话框显示错误，允许操作者选择后续处理方式。

10.7 从卡中心获取的 XML 读者记录文件中，每条读者记录，有些元素是卡中心缺乏的，从卡中心过来的 XML 记录覆盖到读者库中的读者记录上时，可能会覆盖掉读者记录中原有的这些元素。如果要保留这些元素，可以有两个办法：1) 一个是在从卡中心获取的 XML 读者记录中，为不打算覆盖的、卡中心空缺的元素，放一个空内容元素，包含一个属性 dprms:missing，意思是卡中心缺乏这个元素、但想保留读者库中的这个同名元素内容。2) 为 library.xml 的 patronReplication 元素增配一个 mergeStyle="simple" 属性，这样凡是从卡中心过来的 XML 记录中缺乏的元素，都会保留读者库记录中同名的元素内容。
显然，第一个方法比较繁琐，需要在根据卡中心数据构造 XML 文件记录的时候，给每个不希望覆盖的元素名都写入一个空元素(包含 dprms:missing 属性)，穷举这些元素是费力的，而且将来这些元素可能会扩充，扩充的时候就要修改从卡中心获取 XML 文件的接口程序。第二个方法比较简单自然。(注意第二个方法，如果确实想要把读者记录中的某个元素删除，那就在从卡中心过来的 XML 记录中包含一个空内容元素即可)。