♻️ 恢复HcsReconSupport对账查询组件

2026-10-11 16:29:54 +08:00
parent 9b130dfc74
commit bb22b52975
1 changed files with 142 additions and 0 deletions
@@ -0,0 +1,142 @@
+/**
+ * BladeX Commercial License Agreement
+ * Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
+ * <p>
+ * Use of this software is governed by the Commercial License Agreement
+ * obtained after purchasing a license from BladeX.
+ * <p>
+ * 1. This software is for development use only under a valid license
+ * from BladeX.
+ * <p>
+ * 2. Redistribution of this software's source code to any third party
+ * without a commercial license is strictly prohibited.
+ * <p>
+ * 3. Licensees may copyright their own code but cannot use segments
+ * from this software for such purposes. Copyright of this software
+ * remains with BladeX.
+ * <p>
+ * Using this software signifies agreement to this License, and the software
+ * must not be used for illegal purposes.
+ * <p>
+ * THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
+ * not liable for any claims arising from secondary or illegal development.
+ * <p>
+ * Author: Chill Zhuang (bladejava@qq.com)
+ */
+package org.springblade.transport.support.hcs;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springblade.core.tool.utils.StringUtil;
+import org.springblade.hcs.dto.HcsContractDetailQueryDTO;
+import org.springblade.hcs.dto.HcsPageQueryDTO;
+import org.springblade.hcs.dto.HcsResult;
+import org.springblade.hcs.exception.HcsException;
+import org.springblade.hcs.feign.IHcsClient;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * HCS 对账查询支撑组件（设计文档 §5.9/§8-P5，运维收尾）
+ * <p>
+ * 按来源单据编号回查 HCS 侧数据（项目立项/合同/合同详情/开票登记），
+ * 供对账查询页与人工排查使用；返回 HCS 原始数据结构。
+ *
+ * @author Chill
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class HcsReconSupport {
+
+	private final IHcsClient hcsClient;
+
+	/**
+	 * 按项目编号回查 HCS 项目立项（C102-3）
+	 *
+	 * @param projectCode 项目编号
+	 * @return HCS 项目立项列表
+	 */
+	public HcsResult<?> reconProject(String projectCode) {
+		HcsPageQueryDTO query = new HcsPageQueryDTO();
+		// C102-3 入参 columns 用下划线字段名
+		query.setColumns(List.of("fd_id", "fd_num", "fd_pro_name"));
+		// 项目编号精确匹配
+		query.setConditions(Map.of("fd_num", Objects.toString(projectCode, "")));
+		query.setOffset(0);
+		query.setPageSize(50);
+		HcsResult<?> result = hcsClient.projectList(query);
+		return requireSuccess("项目立项对账", result);
+	}
+
+	/**
+	 * 按合同编号回查 HCS 合同（C103-3）
+	 *
+	 * @param contractNo 合同编号
+	 * @return HCS 合同列表
+	 */
+	public HcsResult<?> reconContract(String contractNo) {
+		HcsPageQueryDTO query = new HcsPageQueryDTO();
+		query.setColumns(List.of("fdId", "fdSubject", "fdNumber", "fdCateHierarchyId"));
+		// 合同编号精确匹配（§9-U4 查询能力联调确认）
+		query.setConditions(Map.of("fdNumber", Objects.toString(contractNo, "")));
+		query.setOffset(0);
+		query.setPageSize(50);
+		HcsResult<?> result = hcsClient.contractList(query);
+		return requireSuccess("合同对账", result);
+	}
+
+	/**
+	 * 合同详情回查（C103-4，fdId 与 fdNumber 二选一）
+	 * <p>
+	 * v4 已定义详情响应字段表（HcsContractDetailVO），级联/集合字段内部结构以实际返回为准（设计文档 §5.9）
+	 *
+	 * @param fdId     合同ID（可空）
+	 * @param fdNumber 合同编号（可空）
+	 * @return HCS 合同详情
+	 */
+	public HcsResult<?> reconContractDetail(String fdId, String fdNumber) {
+		if (StringUtil.isBlank(fdId) && StringUtil.isBlank(fdNumber)) {
+			throw new HcsException("合同详情对账失败，fdId 与 fdNumber 至少传一项");
+		}
+		HcsContractDetailQueryDTO query = new HcsContractDetailQueryDTO();
+		// 合同ID（与编号二选一）
+		query.setFdId(fdId);
+		// 合同编号（与ID二选一）
+		query.setFdNumber(fdNumber);
+		HcsResult<?> result = hcsClient.contractDetail(query);
+		return requireSuccess("合同详情对账", result);
+	}
+
+	/**
+	 * 按申请单号回查 HCS 开票登记（C111-1）
+	 *
+	 * @param applicationNo 开票申请单号
+	 * @return HCS 开票登记列表
+	 */
+	public HcsResult<?> reconInvoiceRegistration(String applicationNo) {
+		HcsPageQueryDTO query = new HcsPageQueryDTO();
+		query.setColumns(List.of("fdId", "fdNumber", "fdBillDate", "fdContractNumber", "fdInvoiceAmount", "fdStatus"));
+		// 单据编号精确匹配（§9-U4 查询能力联调确认）
+		query.setConditions(Map.of("fdNumber", Objects.toString(applicationNo, "")));
+		query.setOffset(0);
+		query.setPageSize(50);
+		HcsResult<?> result = hcsClient.invoiceRegistrationList(query);
+		return requireSuccess("开票登记对账", result);
+	}
+
+	/**
+	 * 校验查询结果并返回
+	 */
+	private HcsResult<?> requireSuccess(String scene, HcsResult<?> result) {
+		if (result == null || !result.isSuccess()) {
+			log.error("HCS{}查询失败响应：{}", scene, result == null ? "无响应"
+				: String.format("msg=%s, traceId=%s", result.getMsg(), result.getTraceId()));
+			throw new HcsException("HCS" + scene + "失败：" + (result == null ? "响应为空" : result.getMsg()));
+		}
+		return result;
+	}
+}