cont/mjava-jinlun

mjava-jinlun

金伦项目的 Spring Boot 集成服务，用于在氚云/云枢、金蝶云星空和 Teambition 之间同步业务数据。项目主要承担表单回调接口、金蝶单据创建/更新、云枢表单回写、定时同步和客户对账查询。

技术栈

• Java 8
• Spring Boot 2.2.0.RELEASE
• Maven
• MyBatis / MyBatis-Plus
• MySQL Connector 8.0.32
• 金蝶云星空 WebAPI SDK
• 云枢 OpenAPI
• Teambition OpenAPI

项目结构

src/main/java/com/malk/jinlun
├── JinlunApplication.java        # 应用入口，启用定时任务
├── config                        # 金蝶、云枢配置映射
├── controller                    # 对外 HTTP 接口
├── entity                        # 金蝶请求模型与通用入参模型
├── mapper                        # MyBatis Mapper
├── schedule                      # 定时同步任务
└── service                       # 业务服务、云枢客户端与实现

src/main/resources
├── mapper/JinlunMapper.xml       # 客户对账 SQL
└── logback-spring.xml            # 日志配置

核心功能

表单触发接口

这些接口通常由云枢/氚云表单动作调用，请求体通过 objectId 定位表单实例，再按业务规则读取表单字段、组装金蝶单据、提交审核并回写结果。

方法	路径	说明
GET	/test	连通性测试
POST	/addCustomer	根据云枢客户流程 ZLKHLC 创建金蝶客户 BD_Customer
POST	/updateCustomer	根据云枢客户档案 KHDA 更新金蝶客户销售员
POST	/addCustomerContact	根据云枢联系人 JL002 创建金蝶联系人 BD_CommonContact，并回写联系人编码
POST	/addSaleOrder	根据云枢销售订单 XSDD 创建金蝶销售订单 SAL_SaleOrder，并回写订单编号
POST	/createTbProject	根据云枢重要样品打样申请 ZYYPDYSQ 创建 Teambition 项目，并回写项目 ID
POST	/queryFromData	按 schemaCode、propertyCode、propertyValue 查询单条云枢表单数据

示例请求：

{
  "objectId": "云枢表单实例ID"
}

/queryFromData 请求示例：

{
  "schemaCode": "KHDA",
  "propertyCode": "ShortText1758195840127",
  "propertyValue": "客户编码"
}

客户对账查询

方法	路径	参数	说明
GET	/getCustomerDzmx	startDate、endDate、customerName	查询客户回款对账明细
GET	/getCustomerWqqk	startDate、customerName	查询客户往期欠款

SQL 位于 src/main/resources/mapper/JinlunMapper.xml，当前查询涉及销售出库单、收款单和暂估应收等云枢业务表。

定时同步任务

JinlunTask 由配置项 enable.scheduling 控制是否启用。开启后每天 00:00 起按分钟顺序执行以下任务：

时间	方法	金蝶 FormId	云枢 schemaCode	说明
00:00	syncMaterial	BD_MATERIAL	WL	同步物料
00:01	syncSaleOut	SAL_OUTSTOCK	XSCKD	同步销售出库单
00:02	syncReceipt	AR_RECEIVEBILL	SKD	同步收款单
00:03	syncReceivable	AR_receivable	YSD	同步应收单
00:04	syncSaleReturn	SAL_RETURNSTOCK	XSTHD	同步销售退货单
00:05	syncXingneng	Sl_xingneng	XN	同步性能基础资料
00:06	syncSaleOrder	SAL_SaleOrder	XSDD_JDTB	同步销售订单进度
00:07	syncReceiptVerification	AR_MatchRecord	YSSKHXJL	同步应收收款核销记录

定时同步采用“先按关键字段查云枢，再更新或新增”的模式，避免重复创建。

配置项

项目通过 @ConfigurationProperties 读取配置。请在本地或部署环境中提供以下配置，不要把真实密钥、Token、Cookie 或生产连接串提交到仓库。

cloudpivot:
  grant-type: xxx
  client-id: xxx
  client-secret: xxx
  redirect-uri: xxx
  operator-user-id: xxx

kingdee:
  XKDApiAcctID: xxx
  XKDApiUserName: xxx
  XKDApiAppID: xxx
  XKDApiAppSec: xxx
  XKDApiServerUrl: xxx

enable:
  scheduling: true

项目还依赖公共包中的 Teambition 配置 TBConf，实际配置键以 com.malk.server.teambition 所在基础包为准。

构建与运行

在项目根目录执行：

mvn clean package

构建产物名由 pom.xml 指定为：

target/jinlun.jar

本地运行：

java -jar target/jinlun.jar

如需指定环境：

java -jar target/jinlun.jar --spring.profiles.active=dev

pom.xml 中当前配置了 <skipTests>true</skipTests>，默认 Maven 构建会跳过测试。若要执行测试，可临时覆盖：

mvn test -DskipTests=false

外部依赖

运行前需要确认以下依赖可用：

• com.malk:base:1.1-SNAPSHOT 已安装到本地 Maven 仓库或可从私服下载。
• com.example:k3cloud:8.0.6 已安装到本地 Maven 仓库或可从私服下载。
• com.example:gson:2.8.0 已安装到本地 Maven 仓库或可从私服下载。
• 应用可访问金蝶云星空 WebAPI、云枢 OpenAPI、Teambition OpenAPI 和业务数据库。

开发约束

• 表单字段编码、表单编码、金蝶 FormId 和云枢 schemaCode 必须以平台实际配置为准，不要臆造或随意替换。
• 涉及第三方凭证时，只通过配置注入，不在代码、README、测试数据或日志中硬编码。
• 新增云枢表单调用时，优先复用 CpClient 的 getCpBo、getCpBoList、createCpBo、updateCpBo。
• 新增金蝶单据调用时，沿用现有 Save、Submit、Audit、UnAudit、View 请求模型和 isTrue 校验方式。
• 对云枢子表字段保持行结构，避免把多行子表压平成不可追溯的字符串。
• 定时任务修改后，至少验证一次目标金蝶 FormId、云枢 schemaCode、关键查询字段和更新/新增分支。
• 接口失败时保留外部接口返回的错误信息，避免吞掉金蝶或云枢的诊断内容。

主要代码入口

• JinlunController：HTTP 接口入口。
• JinlunServiceImpl：表单触发业务、金蝶单据创建/更新、Teambition 项目创建。
• JinlunTaskServiceImpl：金蝶到云枢的定时同步逻辑。
• CpClientImpl：云枢 OpenAPI 封装。
• JinlunMapper.xml：客户对账 SQL。