星翰电子回单二开指导

栏目：云星瀚知识作者：金蝶来源：金蝶云社区发布：2024-09-22浏览：1

星翰电子回单二开指导

1. 银行插件元数据ebg-receipt-banks-moc.zip

插件元数据属性字段说明：

字段名	说明	默认值	示例
host	前置机IP地址配置
port	前置机端口配置
protocol	前置机通信协议	http
timeout	前置机读取流超时（min）	3
charset	前置机编码字符集	GBK
bankShortName	银行名称英文简称		ABC
bankName	银行名称		中国农业银行
bankVersionID	银行版本标识		ABC_DC
bankVersionName	银行版本名称		中国农业银行公网版
description	银行插件描述信息		中国农业银行
keyNames	同行匹配关键字		"中国农业银行", "农业银行", "农行"
concurrentCount	前置机并发数量	1

插件元数据方法说明：

方法名称	说明
baseConfigInit	预置前置机基本属性值：protocol、timeout、charset
metaDataInit	预置插件描述信息：bankShortName、bankName、bankVersionID、bankVersionName、description、keyNames、concurrentCount
getBankLoginExtraConfig	前置机额外业务关联配置，如：前置机账号、密码等，可不重写
getFrontProxyConfig	金蝶前置机代理连接配置项，如：金蝶代理程序端口、协议类型等，可不重写
getBizImplClasses	注册开发的银行接口实现类
getBatchSeqIDClasses	银行付款批次流水号生成器（银企框架默认为16位），可不重写
getDetailSeqIDClasses	银行付款明细流水号生成器（银企框架默认为8位），可不重写
getPropertyConfig	银行级别业务配置项
getDetailNoRule	设置回单匹配码规则，可不重写

2. 开发环境搭建

1、本地搭建windows版轻量级苍穹平台，登录苍穹平台官网查看具体安装步骤；

图1 苍穹平台官网

2、使用IntelliJ IDEA创建gradle工程，步骤如下：

填写银行插件名称

GroupId固定填写：kd.ebg.receipt

ArtifactId命名规则：ebg-receipt-banks-custom，其中custom代表具体银行版本

Version填写：1.0

创建完成后等待预置处理，系统自动下载gradle6.3依赖，需要停止下载，前往idea的settings，搜索gradle配置默认gradle home，选取安装苍穹轻量级环境下的gradle目录。

3、按照下面配置信息，修改build.gradle文件，注意修改仓库目录为苍穹平台安装目录：

apply plugin: 'java'

apply plugin: 'maven'

sourceCompatibility=1.8

group = 'kd.ebg.receipt'

version = '1.0'

tasks.withType(JavaCompile) {

options.encoding = "UTF-8"

}

def trd= 'D:/ierp3.0/mservice-cosmic/lib/trd'

def bos= 'D:/ierp3.0/mservice-cosmic/lib/bos'

def biz= 'D:/ierp3.0/mservice-cosmic/lib/biz'

dependencies {

compile fileTree(dir: bos, include: '*.jar')

compile fileTree(dir: trd, include: '*.jar')

compile fileTree(dir: biz, include: '*.jar')

}

task sourcesJar(type: org.gradle.jvm.tasks.Jar, dependsOn: build) {

classifier = 'sources'

from sourceSets.main.allSource

}

task copyJarTodir(type: Copy){

from 'build/libs'

into '/home/local/bos'

exclude '**/*.class'

}

test.ignoreFailures true

打开右侧栏gradle进行编译、打包，确认在项目工程输出ebg-receipt-banks-custom-1.0.jar

至此，开发环境搭建完成。

4、demo工程导入

File -> Open直接找开demo工程所在目录，找出并选中build.gradle，点击OK

5、开发环境启动银企云：

在DebugServer启动类中追加配置

System.setProperty("appstarter.config","aqap=kd.ebg.aqap.mservice.boot.appstarter.EBGAppStarter,receipt=kd.ebg.receipt.mservice.boot.appstarter.EBGReceiptAppStarter,note=kd.ebg.note.mservice.boot.appstarter.EBGAppStarter");

3. 银行插件开发

1、目录结构：

插件包必须按照kd.ebg.receipt.banks作为开头，后面拼接银行版本，例如：kd.ebg.receipt.banks.moc.dc

插件包内部结构主要分为四个部分：

kd.ebg.receipt.banks.*

|-- /constants 静态变量

|-- /service 实现回单业务接口

|-- BankBusinessConfig 银行参数配置

|-- MetaDataImpl 银行插件元数据

2、银行插件元数据

默认套用FBEMetaDataTemplate模板，实现BankMetaDataCollector接口

public class MocTestMetaDataImpl

extends FBEMetaDataTemplate implements BankMetaDataCollector {

@Override

public void baseConfigInit(){

setExchangeProtocol(BankLoginConfigUtil.PROTOCOL_HTTP);

setTimeOut(3);

setCharSet(BankLoginConfigUtil.CHARSET_GBK);

}

@Override

public void metaDataInit() {

setBankName("客户化开发银行");

setBankVersionID(MocTestConstants.BANK_VERSION_ID);

setBankShortName("MOC");

setBankVersionName("客户化开发银行测试版本");

setDescription("客户化开发银行");

setKeyNames(Lists.newArrayList("客户化开发银行"));

}

/**

* 前置机额外配置项，前置机特有配置项

* @return

@Override

public List<BankLoginConfig> getBankLoginExtraConfig(){

return Lists.newArrayList(

BankLoginConfigUtil.getBankLoginConfig("moc_login_config1", "企业机构编号"),

BankLoginConfigUtil.getBankLoginConfig("moc_login_config2", "操作员编号"),

BankLoginConfigUtil.getBankLoginConfig("moc_login_config3","测试开关，是否启用", "", Lists.newArrayList("true", "false"), "false", false, false,false),

BankLoginConfigUtil.getBankLoginConfig("moc_login_config4","测试服务器日期格式yyyy-MM-dd", "正式环境不要配置" ,"", false, true),

BankLoginConfigUtil.getBankLoginConfig("moc_login_config5", "流读取过程中等待间隔(ms)", "500").set2Nullable()

);

}

/**

* 电子回单类型配置项

* @return

@Override

public List<BankLoginConfig> getBankLoginReceiptBaseConfig(){

return Lists.newArrayList(

BankLoginConfigUtil.getBankLoginConfig(customNo, "回单客户号", "回单客户号", "", false, true)

);

}

/**

* 注册接口实现类

* @return

@Override

public List<Class<? extends IBankService>> getBizImplClasses() {

return Lists.newArrayList(

kd.ebg.receipt.business.receipt.query.FileReceiptImpl,

kd.ebg.receipt.banks.moc.dc.service.receipt.fetch.ReceiptFetchListImpl.class, kd.ebg.receipt.banks.moc.dc.service.receipt.download.ReceiptDownloadImpl.class

);

}

/**

* 注册插件业务配置项

* @return

@Override

public BankPropertyConfig getPropertyConfig() {

return new BankBusinessConfig();

}

3、银行参数配置

public class BankBusinessConfig extends BankPropertyConfig {

@Override

public String getBankVersionID() {

return MocTestConstants.BANK_VERSION_ID;

}

@Override

public List<PropertyConfigItem> getAllPropertyConfigItems() {

// 账号基本属性配置项

List<PropertyConfigItem> list = getBankAddtionalPropertyConfigItems();

list.addAll(Lists.newArrayList(

MOC_BUSINESS_CONFIG

));

return list;

}

private static final PropertyConfigItem MOC_BUSINESS_CONFIG =

PropertyConfigItem.builder()

.key("moc_business_config")

.name("示例业务配置项")

.desc("示例业务配置项（公共参数）")

.minValueNum(0)

.maxValueNum(200)

.type(BankPropertyConfigType.COMMON_PARAM.getName())

.build();

}

4、实现银行业务接口：

service

|-- receipt 回单下载接口类

|-- fetch 回单创建->预处理完成处理类

|-- download回单预处理完成->下载完成处理类

|-- api 调用银行接口类

|-- info 回单文件名解析类

|-- config 回单业务配置类

|-- utils 工具类

Service层通常实现上述这几类银行接口，其中

fetch需要实现银企框架接口：IBankReceiptHandle

继承业务框架抽象类AbstractBankReceiptHandleImpl 需要重写match方法，参考demo即可

这一步是请求银行接口获取回单相关信息将从银行接口获取到的信息返回，要将相关信息放到fileLink和fileName字段返回

download需要实现银企框架接口：IBankReceiptHandle

继承业务框架抽象类AbstractBankReceiptHandleImpl 需要重写match方法，参考demo即可

这一步主要是通过fetch这一步拿到的银行相关参数去下载回单文件，如果下载的是压缩包在这一步要将压缩包里面的回单文件一个一个放到固定目录下，并且返回，具体参考demo

api需要实现银企框架接口：IBankReceipt

继承业务框架抽象类AbstractBankReceiptImpl

info需要实现银企框架接口：IFileInfo

继承业务框架抽象类AbstractFileParser 并且根据需要重写下述方法：

getAccNo() 回单账号

getDate() 回单日期

getReceiptNo() 流水号

getAmount() 交易金额

getCdFlag() 借贷标记

getOppAccNo() 对方账号

通过这6个方法对应生成每条回单的匹配码的，用来跟交易明细的匹配码进行一一对应，其中getAccNo() getDate() getReceiptNo()必须要重写这三个方法是组装回单匹配码的必要素，其他三个方法要根据需求是否要实现，怎么判断是否需要，第一要确保回单这边有这些字段的值才能考虑来重写，第二要确保这几个字段交易明细也有对应的字段并且能保证一一匹配

getFileSplit()这个方法是用来解析回单文件名的分割符，也需要重写

回单信息的匹配码是通过info下面的解析类来组装的，交易明细里面的匹配码参考如下：

（1）重写查询与支付插件里面的元数据类里面的getDetailNoRule方法

@Override

public Map<String, Map<String, String>> getDetailNoRule() {

// accNo-oppAccNo-transDate-Amount-cdFlag-serialNo

Map<String, Map<String, String>> result = new HashMap<>(16);

Map<String, String> ruleMap = new HashMap<>(16);

ruleMap.put("accNo", "accNo");

ruleMap.put("oppAccNo", "oppAccNo");

ruleMap.put("transDate", "transDate");

ruleMap.put("Amount", "Amount");

ruleMap.put("cdFlag", "cdFlag");

ruleMap.put("serialNo", "HOST_SERIAL_NO");

result.put("default", ruleMap);

return result;

}

这个Map的key是匹配码固定六字段的值不需要改 value值是接口对应字段实际值比如说serialNo这个key对应的是银行接口里面的流水号字段以实际为准，如果回单这边六字段只满足账号，日期，流水号这三个字段那交易明细里面只需要设置serialNo对应字段名，账号，日期不需要设置这是固定的，其他三个字段根据需求设置