From f2d25f20a0f4385932abe9233d478c01d1f0c1d2 Mon Sep 17 00:00:00 2001 From: Weasley J <1432689025@qq.com> Date: Fri, 28 Jul 2023 16:51:35 +0800 Subject: [PATCH] =?UTF-8?q?[feature]=20=E4=BC=98=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E4=BB=8B=E7=BB=8D=E6=8F=8F=E8=BF=B0=EF=BC=8C=E5=A2=9E?= =?UTF-8?q?=E5=8A=A0=EF=BC=9A=E6=8A=A5=E6=96=87=E5=8A=A0=E7=AD=BE=E6=8E=A8?= =?UTF-8?q?=E9=80=81=E6=B5=81=E7=A8=8B=E5=9B=BE=EF=BC=8C=E5=B8=AE=E5=8A=A9?= =?UTF-8?q?=E6=8E=A5=E5=85=A5=E4=BC=81=E4=B8=9A=E4=BA=86=E8=A7=A3=E5=AF=B9?= =?UTF-8?q?=E6=8E=A5=E6=B5=81=E7=A8=8B=20[feature]=20=E4=BC=98=E5=8C=96?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E6=A8=A1=E5=9E=8B=E7=9A=84=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=E6=8B=93=E5=B1=95=E7=B1=BB=E5=9B=BE=E5=8F=8A=E6=94=AF=E6=8C=81?= =?UTF-8?q?=E7=9A=84=E6=8A=A5=E6=96=87=E6=A0=B7=E4=BE=8B=E7=A4=BA=E6=84=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 69 ++++++++-------- .../src/main/resources/static/index.html | 4 +- chinaport-data-signature-data-model/README.md | 78 ++++++++++++++++++- 3 files changed, 113 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index c7d6dbe..4db5d47 100644 --- a/README.md +++ b/README.md @@ -5,42 +5,44 @@ ![Docker Pulls](https://img.shields.io/docker/pulls/weasleyj/chinaport-data-signature) ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/weasleyj/chinaport-data-signature/latest) ![Docker Image Version (latest semver)](https://img.shields.io/docker/v/weasleyj/chinaport-data-signature) +[![Maven Central](https://img.shields.io/maven-central/v/io.github.weasley-j/chinaport-data-signature-data-model)](https://search.maven.org/artifact/io.github.weasley-j/chinaport-data-signature-data-model) ## 前言 -After nearly two years of open-source code maintenance and exploration, we have successfully developed an all-in-one solution that offers free access and usage for a wide range of businesses. This solution aims to digitally sign and forward XML messages to the General Administration of Customs at the Chinese Electronic Port (HaiKou Customs), facilitating cross-border e-commerce operations and import-export trade for enterprises. - -经过长达近两年的开源代码维护和探索，我们终于成功开发出一站式解决方案，为更多企业提供免费接入和使用。该解决方案的目标是对中国电子口岸海关（海口海关）总署的XML报文进行加签推送，以促进企业的跨境电商业务和进出口贸易。 - -Weasley J（2023-07） - - - -中国电子口岸海关（海口海关）总署`XML`报文&海关179数据上报加签服务，一站式的免费解决方案，开箱即用，无中间件；本项目遵守`GNU 3.0` -协议，本项目测试用例中用到的企业信息已经过企业的批准，企业使用`ukey`加签进行业务申报时, 请下载`release` -文件根据自己的实际情况适当修改运行参数既可。 - - - -> 业务场景: +> After nearly two years of open-source code maintenance and exploration, we have successfully developed an all-in-one solution that offers free access and usage for a wide range of businesses. This solution aims to digitally sign and forward XML messages to the General Administration of Customs at the Chinese Electronic Port (HaiKou Customs), facilitating cross-border e-commerce operations and import-export trade for enterprises. > -> - 中国境内的跨进电商业务, 进出口贸易 +> 经过长达近两年的开源代码维护和探索，我们终于成功开发出一站式解决方案，为更多企业提供免费接入和使用。该解决方案的目标是对中国电子口岸海关（海口海关）总署的XML报文进行加签推送，以促进企业的跨境电商业务和进出口贸易。 > -> 提示: -> -> - 单体应用直接下载[release](https://github.com/Weasley-J/chinaport-data-signature/releases)的二进制文件使用即可（使用较多） -> - 分布式微服务请切换到[feature_microservice](https://github.com/Weasley-J/chinaport-data-signature/tree/feature_microservice)分支构建（较少使用） -> - [通过Docker镜像快速搭建报文加签推送的环境](https://hub.docker.com/repository/docker/weasleyj/chinaport-data-signature) +> Weasley J（2023-07） +该项目为中国电子口岸海关（海口海关）总署XML报文和海关179数据上报加签服务，提供一站式的免费解决方案，开箱即用，无需使用中间件。本项目遵守`GNU 3.0`协议。请注意，本项目测试用例中用到的企业信息已经经过企业批准。 +### 业务场景 + +- 中国境内的跨境电商业务，进出口贸易 + +### 使用提示 + +- 对于单体应用，您可以直接下载[release](https://github.com/Weasley-J/chinaport-data-signature/releases)中的二进制文件使用（使用较多），根据您的实际情况适当修改运行参数。 +- 对于分布式微服务，建议切换到[feature_microservice](https://github.com/Weasley-J/chinaport-data-signature/tree/feature_microservice)分支进行构建（较少使用）。 +- 您还可以通过[Docker镜像快速搭建报文加签推送的环境](https://hub.docker.com/repository/docker/weasleyj/chinaport-data-signature)。 +- 如果您的电商后台系统也是使用`Java`语言开发，我们在[Maven仓库中上传了项目中用到的数据模型](https://central.sonatype.com/artifact/io.github.weasley-j/chinaport-data-signature-data-model/1.0.4)，可帮助您的系统与本项目快速集成。您只需要使用这些数据模型填充数据，然后使用`JSON`进行数据交互，从而降低对接成本。 + +### 功能概述 ![image-20230718223758675](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230718223758675.png) +### 系统架构 + ![image-20230715002603102](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230715002603102.png) +### 报文加签推送流程 + +![image-20230728164622813](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230728164622813.png) -决定将此项目开源项目的时候，地球上的搜索引擎在**2022-02-14**之前还搜索不到任何有价值的信息，ChatGPT在面对这种付费的解决方案时，它能解决吗..... + +当我们决定将此项目开源的时候，地球上的搜索引擎在2022年2月14日之前还无法搜索到任何有价值的信息。当面对付费解决方案时，ChatGPT是否能提供帮助呢…… @@ -50,15 +52,16 @@ Weasley J（2023-07）
-- **Previews of China e-port data signature** -项目开始前我们先了解下海关总署XML报文的加签都在什么价位？百度、CSDN里你能搜索到的仅一个海关179号文件对接，**但唯独没有XML的加签**，细品下图: +- **Previews of China E-Port Sata Signature** + +在项目开始之前，让我们先了解一下海关总署`XML`报文的加签服务在市场上的定价。虽然在百度和`CSDN`上，您可以找到海关179数据上报的接口对接方式，**但是唯独没有关于XML报文加签的信息**，请参考下图： IMG_0373-side -你没看错：你去找乙方对接，乙方不告诉你加签用到的算法，需要接入方自己开发。好，那就开发吧！ +没错，您没有看错：当您尝试寻求乙方（服务提供方）的对接时，乙方可能不会提供加签所使用的算法，因此需要接入方（您）自己进行开发。好吧，那就让我们开始开发吧！ -- [x] 电子口岸的操作员`u-key`长啥样: +- [x] 电子口岸的操作员`u-key`图片资料: ![IMG_0401](https://alphahub-test-bucket.oss-cn-shanghai.aliyuncs.com/image/IMG_0401.jpg) @@ -78,7 +81,7 @@ Weasley J（2023-07） ## 1 项目代码质量 -![image-20230713234327922](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230713234327922.png) +![image-20230728152146033](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230728152146033.png) ## 2 软件运行概况 @@ -104,14 +107,14 @@ Weasley J（2023-07） | eport.signature.ukey.ws-url | Y | u-key做插`Windows`电脑的`socket`链接`url`,如: `ws://127.0.0.1:61232`,下载`release`直接运行的修改全局配置的`UKEY_HOST`即可 | | eport.signature.ukey.password | N | u-key密码的密码，默认: `88888888`, 如果密码改过，需要指定下，下载`release`直接运行的修改全局配置的`UKEY_PASSWORD`即可 | | eport.signature.ukey.health.endpoint.client-name | N | Windows上重启的ukey可执行文件全限定文件名称，不指定将自动查找 | -| eport.signature.auth.enable | N | [是否启用token鉴权](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/AuthenticationProperties.java#L17)，取值：on/off | -| eport.signature.auth.token | N | 客户端请求鉴权token, 默认值: DefaultAuthToken, [请求头](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/AuthenticationProperties.java#L24) | +| eport.signature.auth.enable | N | [是否启用token鉴权](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/AuthenticationProperties.java#L17)，取值：on/off，生产环境建议开启 | +| eport.signature.auth.token | N | 客户端请求鉴权token, 默认值: DefaultAuthToken, [请求头](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/AuthenticationProperties.java#L24)，生产环境不建议使用默认值 | | eport.signature.report.ceb-message.cop-code | Y | [电子口岸XML报文](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/ChinaEportProperties.java#L20)传输企业代码 | | eport.signature.report.ceb-message.cop-name | Y | 传输企业名称，报文传输的企业名称 | | eport.signature.report.ceb-message.dxp-id | Y | 文传输编号，向中国电子口岸数据中心申请数据交换平台的用户编号 | -| eport.signature.report.ceb-message.server | N | [海关服务器地址](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/ChinaEportProperties.java#L43)，缺省则采用Client中的密文作文默认Server URL | +| eport.signature.report.ceb-message.server | N | [海关服务器地址](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/ChinaEportProperties.java#L43)，缺省则采用Client中的密文作文默认Server URL | | eport.signature.report.customs179.ebp-code | Y | [海关 179 数据上报](https://github.com/Weasley-J/chinaport-data-signature/blob/main/chinaport-data-signature-app/src/main/java/cn/alphahub/eport/signature/config/Customs179Properties.java#L24)的电商平台代码 | -| eport.signature.report.customs179.server | N | 数据上报服务器URL地址，链接格式: https://域名联系海关/ceb2grab/grab/realTimeDataUpload，没有配置的话采用项目内置的URL密文地址 | +| eport.signature.report.customs179.server | N | 数据上报服务器URL地址，链接格式: https://域名联系海关/ceb2grab/grab/realTimeDataUpload，没有配置的话采用项目内置的URL密文地址 | ## 4 项目启动脚本 @@ -167,9 +170,9 @@ java -Dfile.encoding=utf-8 ${JVM_ARGS} -jar ${APP}.jar \ ## 6 开发文档 -> 本项目支持直接使用`JSON`数据加签上报，告别XML数据、179特殊数据组装那样三拜九叩的繁琐！ +> 本项目已支持直接使用`JSON`数据加签上报，告别XML数据、179特殊数据组装那样三拜九叩的繁琐！ -启动项目，浏览器访问: http://127.0.0.1:8080 ,会打开[接口文档](https://github.com/Weasley-J/chinaport-data-signature/blob/main/中国电子口岸报文加签接口文档.md)的H5页面，可直接在页面给ukey发送请求进行调试，注意请求参数的**字符串转义**。 +启动项目，浏览器访问: http://127.0.0.1:8080 ,会打开[接口文档](https://github.com/Weasley-J/chinaport-data-signature/blob/main/中国电子口岸报文加签接口文档.md)的H5页面，可直接在页面给ukey发送请求进行调试，注意请求参数的**字符串转义问题**。 ![image-20230713233904520](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230713233904520.png) diff --git a/chinaport-data-signature-app/src/main/resources/static/index.html b/chinaport-data-signature-app/src/main/resources/static/index.html index d975da0..9e15d8b 100644 --- a/chinaport-data-signature-app/src/main/resources/static/index.html +++ b/chinaport-data-signature-app/src/main/resources/static/index.html @@ -1,4 +1,4 @@ -中国电子口岸（海口海关）报文加签API文档
VersionUpdate TimeStatusAuthorDescription

1.0.0

2022-02-16 10:30

创建

Weasley J

创建API文档

1.0.9

2023-06-11 15:36

编辑

Weasley J

更新API文档

1.1.0

2023-07-15 15:36

编辑

Weasley J

补充API文档

1. 电子口岸报文加签测试

1.1. 海关总署XML数据加签

Type: GET

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: 非正式调用API，只为了让你看到海关总署XML加密的数据返回格式

Request-headers:

HeaderValueTypeRequiredDescription

x-auth-token-eport-sign

string

true

客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Response-fields:

FieldTypeDescriptionSince

message

string

返回消息

-

success

boolean

是否成功

-

timestamp

string

响应时间戳

-

code

int32

状态码

-

data

object

响应数据

-

└─success

boolean

本次加签是否成功

-

└─certNo

string

签名的ukey的卡序列号

-

└─x509Certificate

string

签名的ukey证书

-

└─digestValue

string

XML报文的数字摘要

-

└─signatureValue

string

调用ukey获取的签名值

-

└─signatureNode

string

XML报文的签名节点 +中国电子口岸（海口海关）报文加签API文档

VersionUpdate TimeStatusAuthorDescription

1.0.0

2022-02-16 10:30

创建

Weasley J

创建API文档

1.0.9

2023-06-11 15:36

编辑

Weasley J

更新API文档

1.1.0

2023-07-15 15:36

编辑

Weasley J

补充API文档

1. 电子口岸报文加签测试

1.1. 海关总署XML数据加签

Type: GET

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: 非正式调用API，只为了让你看到海关总署XML加密的数据返回格式

Request-headers:

HeaderValueTypeRequiredDescription

x-auth-token-eport-sign

string

true

客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Response-fields:

FieldTypeDescriptionSince

message

string

返回消息

-

success

boolean

是否成功

-

timestamp

string

响应时间戳

-

code

int32

状态码

-

data

object

响应数据

-

└─success

boolean

本次加签是否成功

-

└─certNo

string

签名的ukey的卡序列号

-

└─x509Certificate

string

签名的ukey证书

-

└─digestValue

string

XML报文的数字摘要

-

└─signatureValue

string

调用ukey获取的签名值

-

└─signatureNode

string

XML报文的签名节点

  • 用来组装 ds:SignedInfo 节点

    • -

    Response-example:

    {
   "message": "",
   "success": true,
@@ -199,4 +199,4 @@
 }

    Curl-example:

    curl -X POST -H 'Content-Type: application/json' -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/signature --data '{
   "id": 0,
   "data": ""
-}'
    Generated by smart-doc at 2023-07-27 20:17:57Suggestions,contact,support and error reporting on Gitee or Github
    Top
    \ No newline at end of file +}'
    Generated by smart-doc at 2023-07-28 15:11:34Suggestions,contact,support and error reporting on Gitee or Github
    Top
    \ No newline at end of file diff --git a/chinaport-data-signature-data-model/README.md b/chinaport-data-signature-data-model/README.md index b537e24..8d585fb 100644 --- a/chinaport-data-signature-data-model/README.md +++ b/chinaport-data-signature-data-model/README.md @@ -1,8 +1,80 @@ -# 中国电子口岸加签服务数据模型 +# 中国电子口岸加签服务的数据模型 [![Maven Central](https://img.shields.io/maven-central/v/io.github.weasley-j/chinaport-data-signature-data-model)](https://search.maven.org/artifact/io.github.weasley-j/chinaport-data-signature-data-model) > 海关报文加签的数据模型，方便各方引入依赖。 -1. 海关 179 数据抓取报文 -2. 海关总署`xml`报文, 进口单：CEB311Message, CEB621Message +## 1 目前已实现的数据模型 + +### 1.1 海关 179 数据抓取报文 + +### 1.2 海关总署`xml`报文, 进口单：CEB311Message, CEB621Message + + + +## 2 数据模型的设计拓展 + +### 2.1 `AbstractCebMessage`拓展 + +> 用来接收各类进口单、出口单的底层数据模型对象 + +![image-20230728135612365](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230728135612365.png) + +### 2.2 `IMessageType`拓展 + +> 获取各类进口单、出口单消息类型 + +![image-20230728135844727](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230728135844727.png) + +### 2.3 数据上报客户端设计 + +![image-20230728140512291](https://weasley.oss-cn-shanghai.aliyuncs.com/Photos/image-20230728140512291.png) + +### 2.4 基于`AbstractCebMessage`和`ChinaEportReportClient#report`设计所支持的报文类型 + +> 此种设计理论上支持海关的所有进出口单的数据模型 + +**样例报文**: + +```tex +├── 出口样例 +│ ├── CEB303Message.xml +│ ├── CEB304Message.xml +│ ├── CEB403Message.xml +│ ├── CEB404Message.xml +│ ├── CEB505Message.xml +│ ├── CEB506Message.xml +│ ├── CEB507Message.xml +│ ├── CEB508Message.xml +│ ├── CEB509Message.xml +│ ├── CEB510Message.xml +│ ├── CEB603Message.xml +│ ├── CEB604Message.xml +│ ├── CEB605Message.xml +│ ├── CEB606Message.xml +│ ├── CEB607Message.xml +│ ├── CEB608Message.xml +│ ├── CEB701Message.xml +│ ├── CEB702Message.xml +│ └── CEB792Message.xml +└── 进口样例 + ├── CEB311Message.xml + ├── CEB312Message.xml + ├── CEB411Message.xml + ├── CEB412Message.xml + ├── CEB511Message.xml + ├── CEB512Message.xml + ├── CEB513Message.xml + ├── CEB514Message.xml + ├── CEB621Message.xml + ├── CEB622Message.xml + ├── CEB623Message.xml + ├── CEB624Message.xml + ├── CEB625Message.xml + ├── CEB626Message.xml + ├── CEB711Message.xml + └── CEB712Message.xml +``` + + +