+ * Use of this software is governed by the Commercial License Agreement + * obtained after purchasing a license from BladeX. + *
+ * 1. This software is for development use only under a valid license + * from BladeX. + *
+ * 2. Redistribution of this software's source code to any third party + * without a commercial license is strictly prohibited. + *
+ * 3. Licensees may copyright their own code but cannot use segments + * from this software for such purposes. Copyright of this software + * remains with BladeX. + *
+ * Using this software signifies agreement to this License, and the software + * must not be used for illegal purposes. + *
+ * THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is + * not liable for any claims arising from secondary or illegal development. + *
+ * 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，运维收尾） + *
+ * 按来源单据编号回查 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 二选一） + *
+ * 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; + } +}