:feat: 按桂物合同集成v4接口说明补齐HCS字段与必填标注(合同更新顶层fdId、C103-4详情字段表VO、fdFieldJson.attachment附件挂载、xformFields必填字段赋值与fd_syn_time日期格式、C111合同引用fdContract、C108业务ID,新增HcsContractFieldConstant常量类)

This commit is contained in:
刘泉佳
2026-10-10 20:22:58 +08:00
parent 78dd523e2f
commit 242b203a68
20 changed files with 929 additions and 97 deletions
@@ -165,6 +165,10 @@ public class HcsProperties {
* TMS 结算方式 -> 付款|收款(fdSettlementType,§9-U3 字典映射待联调)
*/
private Map<String, String> settlementTypeMapping = new HashMap<>();
/**
* TMS 审核状态 -> HCS 合同状态(xformFields CONTRACT_STATUS 必填,draft/approving/approved 等,§9-U3 待联调后配置)
*/
private Map<String, String> statusMapping = new HashMap<>();
/**
* TMS 币种码 -> HCS 币种名称(照金蝶 RMB->CNY 映射惯例)
*/
@@ -56,7 +56,23 @@ public class HcsCategoryVO implements Serializable {
*/
private HcsRefVO fdParent;
/**
* 状态:enable / disable
* 状态:enable=启用 / disable=停用
*/
private String fdStatus;
/**
* 层级ID:由各级分类 fdId 以 x 包裹拼接(x+上级fdId+x+fdId+x,v4 新增)
*/
private String fdHierarchyId;
/**
* 创建人
*/
private HcsRefVO fdCreator;
/**
* 创建人部门
*/
private HcsRefVO fdCreatorDept;
/**
* 创建时间(毫秒时间戳)
*/
private Long fdCreateTime;
}
@@ -0,0 +1,519 @@
/**
* 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.hcs.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;
import java.io.Serial;
import java.io.Serializable;
import java.math.BigDecimal;
import java.util.List;
/**
* 合同合规系统(HCS)C103-4 合同详情出参(v4 字段表)
* <p>
* 级联/集合类字段(对象/数组)内部结构 v4 标注以实际返回为准,暂以 Object/List&lt;Object&gt; 承接,
* 联调确认后细化。fdSepcailContract 为接口文档原文拼写(Special 笔误,必须沿用)。
*
* @author Chill
*/
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)
public class HcsContractDetailVO implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
/**
* 合同ID
*/
private String fdId;
/**
* 租户ID
*/
private String fdTenantId;
/**
* 可阅读标示
*/
private String fdReaderFlag;
/**
* 不可阅读标记(可阅读者在文档发布前生效)
*/
private String fdNotReaderFlag;
/**
* 可阅读者(在文档发布前生效)
*/
private String fdRBPFlag;
/**
* 修改人
*/
private String fdAlter;
/**
* 修改时间(毫秒时间戳)
*/
private Long fdAlterTime;
/**
* 描述
*/
private String fdDesc;
/**
* 是否隐藏
*/
private Boolean fdIsHidden;
/**
* 最后修改时间(毫秒时间戳)
*/
private Long fdLastModifiedTime;
/**
* 合同名称
*/
private String fdSubject;
/**
* 合同分类(层级ID)
*/
private String fdCateHierarchyId;
/**
* 编号
*/
private String fdNumber;
/**
* 状态:draft=草稿; approving=审批中; approved=已审批; tosign=待签订; signing=签订中; signerror=签订异常; signed=已签订等
*/
private String fdStatus;
/**
* 合同发起ID
*/
private String fdDraftMainId;
/**
* 合同模板ID
*/
private String fdTemplateId;
/**
* 审批状态:approving=审批中; approved=已审批; approvalinvalid=审批作废
*/
private String fdApprovalStatus;
/**
* 签订状态:tosign=待签订; signing=签订中; signerror=签订异常; signed=已签订; signinvalid=签订作废
*/
private String fdSignStatus;
/**
* 签订异常信息
*/
private String fdSignErrorMsg;
/**
* 进入待签订时间(毫秒时间戳)
*/
private Long fdToSignTime;
/**
* 签订发起时间(毫秒时间戳)
*/
private Long fdSignCreateTime;
/**
* 完成签订时间(毫秒时间戳)
*/
private Long fdSignedTime;
/**
* 归档状态:toarchive=待归档; archiving=归档中; archived=已归档; archiveerror=归档异常
*/
private String fdArchiveStatus;
/**
* 变更状态:changing=变更中; changed=已变更; terminated=已终止
*/
private String fdChangeStatus;
/**
* 履约状态:toplan=待履约; planing=履约中; planerror=履约异常; planed=已履约; planterminate=履约终止
*/
private String fdPlanStatus;
/**
* 进入待履约时间(毫秒时间戳)
*/
private Long fdToPlanTime;
/**
* 完成履约时间(毫秒时间戳)
*/
private Long fdPlanedTime;
/**
* 关闭状态:toclose=待关闭; closing=关闭中; closed=已关闭
*/
private String fdCloseStatus;
/**
* 进入待关闭时间(毫秒时间戳)
*/
private Long fdToCloseTime;
/**
* 关闭时间(毫秒时间戳)
*/
private Long fdClosedTime;
/**
* 签署提供者:psign=物理签署; esign=电子签署; qjsign=智能用印签署
*/
private String fdSignProvider;
/**
* 签署实体ID
*/
private String fdSignEntityId;
/**
* 归档方式:auto=一键申请; review=流程申请
*/
private String fdFileWay;
/**
* 归档实体ID
*/
private String fdArchiveEntityId;
/**
* 进入待归档时间(毫秒时间戳)
*/
private Long fdToArchiveTime;
/**
* 完成归档时间(毫秒时间戳)
*/
private Long fdArchivedTime;
/**
* 履约计划创建时机:draft=起草环节创建; toplan=履约环节创建
*/
private String fdPlanCreateMoment;
/**
* 关闭方式:auto=一键关闭; review=流程关闭
*/
private String fdCloseWay;
/**
* 关闭实体ID
*/
private String fdCloseEntityId;
/**
* 是否锁定
*/
private Boolean fdIsLocked;
/**
* 锁定原因:invalid=合同作废; change=合同变更; termination=合同终止
*/
private String fdLockReason;
/**
* 合同作废实体ID
*/
private String fdInvalidEntityId;
/**
* 上次合同变动发起实体ID
*/
private String fdLastChangeEntityId;
/**
* 合同终止发起实体ID
*/
private String fdTerminationEntityId;
/**
* 批量发起任务ID
*/
private String fdBatchTaskId;
/**
* 是否关联交易
*/
private Boolean fdIsRelaDeal;
/**
* 是否补录
*/
private Boolean fdIsRecord;
/**
* 履约计划(级联字段,结构以实际返回为准)
*/
private Object fdPlan;
/**
* 验收计划(级联字段,结构以实际返回为准)
*/
private Object fdAcptPlan;
/**
* 外部合同数据(级联字段,结构以实际返回为准)
*/
private Object fdOuterAttr;
/**
* 订单明细配置ID
*/
private String fdOrderDetailConfigId;
/**
* 收付款进度(结构以实际返回为准)
*/
private Object fdPayColProgress;
/**
* 开票进度(结构以实际返回为准)
*/
private Object fdInvoiceProgress;
/**
* 履约状态(新):0=正常; 1=低风险; 2=中风险; 3=高风险
*/
private Integer fdPlanStatusNew;
/**
* 是否冻结
*/
private Boolean fdIsFreeze;
/**
* 解冻表单关联ID
*/
private String fdUnfreezeFormId;
/**
* 合同履约流程状态:00/01/02/10/11/12/20/21/29/30/39
*/
private String fdPlanFlowStatus;
/**
* 合同履约流程ID
*/
private String fdPlanFlowId;
/**
* 是否评分
*/
private Boolean fdRated;
/**
* 完成审批时间(毫秒时间戳)
*/
private Long fdApprovedTime;
/**
* 是否同步金蝶
*/
private Boolean fdIsSyncJd;
/**
* 同步金蝶状态:0/1/2
*/
private Integer fdSyncJdStatus;
/**
* 特批合同(字段名原文拼写笔误,必须沿用)
*/
private Boolean fdSepcailContract;
/**
* 合同结算模式:open=开口合同; close=闭口合同
*/
private String fdContractGwNature;
/**
* 合同类型:standard=标准合同; halfstandard=半标准合同; notstandard=非标准合同
*/
private String fdContractCharacter;
/**
* 合同性质:general=普通合同; framework=框架协议
*/
private String fdContractNature;
/**
* 引用范本ID
*/
private String fdModelId;
/**
* 合同属性:main=主合同; child=子合同; common=普通
*/
private String fdContractAttribute;
/**
* 承办人
*/
private HcsRefVO fdUnderTaker;
/**
* 承办人部门
*/
private HcsRefVO fdUnderTakerDept;
/**
* 预计开始时间(毫秒时间戳)
*/
private Long fdEstimateStartTime;
/**
* 预计结束时间(毫秒时间戳)
*/
private Long fdEstimateEndTime;
/**
* 实际开始时间(毫秒时间戳)
*/
private Long fdStartTime;
/**
* 实际结束时间(毫秒时间戳)
*/
private Long fdEndTime;
/**
* 合同发起来源:inner=内部发起; outer=外部发起
*/
private String fdContractSource;
/**
* 外部来源系统
*/
private String fdOuterSystem;
/**
* 合同结算类型:payment=付款; payment_collection=收支双向; collection=收款; none=不结算
*/
private String fdSettlementType;
/**
* 合同金额
*/
private BigDecimal fdAmount;
/**
* 币种
*/
private String fdCurrencyId;
/**
* 是否原始合同
*/
private Boolean fdIsOrigin;
/**
* 原始合同ID
*/
private String fdOriginContractId;
/**
* 合同变更类型:change=合同变更; termination=合同终止
*/
private String fdChangeType;
/**
* 是否含税
*/
private Boolean fdIncludeTax;
/**
* 是否引用范本
*/
private Boolean fdUseModel;
/**
* 引用范本名称
*/
private String fdModelName;
/**
* 引用范本版本
*/
private String fdModelVersion;
/**
* 是否固定期限
*/
private Boolean fdIsFixedTerm;
/**
* 合同开始期限
*/
private String fdStartTerm;
/**
* 合同结束期限
*/
private String fdEndTerm;
/**
* 有效期限
*/
private String fdValidTerm;
/**
* 项目立项ID
*/
private String fdProjectId;
/**
* 合同份数
*/
private Integer fdServings;
/**
* 合同说明
*/
private String fdContractDescription;
/**
* 合同的变更流程状态:changing=变更中; changed=已变更; noChangeProcess=无变更流程
*/
private String fdChangeLbpmStatus;
/**
* 紧急程度:1=普通; 2=急件; 3=特急
*/
private Integer fdUrgencyLevel;
/**
* 创建人
*/
private HcsRefVO fdCreator;
/**
* 创建时间(毫秒时间戳)
*/
private Long fdCreateTime;
/**
* 创建者部门
*/
private HcsRefVO fdCreatorDept;
/**
* 权限(级联字段,结构以实际返回为准)
*/
private Object fdPermissions;
/**
* 可阅读者(结构以实际返回为准)
*/
private List<Object> fdReaders;
/**
* 所有可阅读者(结构以实际返回为准)
*/
private List<Object> fdAllReaders;
/**
* 所有可阅读者ID(结构以实际返回为准)
*/
private List<Object> fdAllReaderIds;
/**
* 可维护者(结构以实际返回为准)
*/
private List<Object> fdEditors;
/**
* 所有可编辑者(结构以实际返回为准)
*/
private List<Object> fdAllEditors;
/**
* 协办人(结构以实际返回为准)
*/
private List<Object> fdCoTakers;
/**
* 合同时间线(结构以实际返回为准)
*/
private List<Object> fdTimeLines;
/**
* 合同关联(结构以实际返回为准)
*/
private List<Object> fdRelations;
/**
* 合同签约方及地位(结构以实际返回为准)
*/
private List<Object> fdStandingSigners;
/**
* 签印文件(结构以实际返回为准)
*/
private List<Object> fdSignFiles;
/**
* 业务明细(结构以实际返回为准)
*/
private List<Object> fdBusinessDetails;
/**
* 付款记录(结构以实际返回为准)
*/
private List<Object> fdPaymentRecords;
/**
* 收款记录(结构以实际返回为准)
*/
private List<Object> fdCollectionRecords;
/**
* 收票记录(结构以实际返回为准)
*/
private List<Object> fdInInvoices;
/**
* 开票记录(结构以实际返回为准)
*/
private List<Object> fdOutInvoices;
/**
* 预填写物理签印信息(结构以实际返回为准)
*/
private List<Object> fdPsignContents;
/**
* 审批人(结构以实际返回为准)
*/
private List<Object> fdApprovers;
/**
* 履约规则(结构以实际返回为准)
*/
private List<Object> fdExePlanRules;
}
@@ -43,6 +43,10 @@ import java.io.Serializable;
public class HcsContractDraftDTO implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
/**
* 合同ID(C103-11 合同更新顶层必填,传 C103-1 返回的 fdContractId;C103-1 新建不传)
*/
private String fdId;
/**
* 合同模板ID(C103-6 模板列表获取,配置 template-mapping,§9-U7)
*/
@@ -36,7 +36,7 @@ import java.util.List;
/**
* 合同合规系统(HCS)C103-1 合同发起 fdFieldJson 节点(C103-1 新建 / C103-11 更新共用)
* <p>
* §9-U8 待联调确认:v4 未定义合同附件传递字段,附件挂载方式待合规方确认后补充。
* v4 文档已定义 attachment 附件挂载(fdId/fdBindType 必填,fdEntityKey 仅给出特批附件枚举 eopCdraftSpecial)。
*
* @author Chill
*/
@@ -54,4 +54,8 @@ public class HcsContractFieldJsonDTO implements Serializable {
* 签署方(相对方)列表
*/
private List<HcsSignerDTO> signer;
/**
* 附件数据(C103-1 必填,C103-11 更新不传;fdEntityKey 普通附件枚举待合规方给出,暂不传)
*/
private List<HcsAttachmentRefDTO> attachment;
}
@@ -75,4 +75,12 @@ public class HcsCurrencyVO implements Serializable {
* 是否本位币
*/
private Boolean fdIsStandardCurrency;
/**
* 创建人
*/
private HcsRefVO fdCreator;
/**
* 创建时间(毫秒时间戳)
*/
private Long fdCreateTime;
}
@@ -60,6 +60,10 @@ public class HcsInvoiceRegAddDTO implements Serializable {
* 合同编号(必填,经应收结算链路回溯,§9-U10)
*/
private String fdContractNumber;
/**
* 合同 {fdId, fdName}(v4 新增,fdId 为合规合同ID,随编号一并回溯)
*/
private HcsRefVO fdContract;
/**
* 发票类型(字典映射 invoice-type-mapping,§9-U3)
*/
@@ -97,6 +97,16 @@ public class HcsPerfRecordPropsDTO implements Serializable {
*/
@JsonProperty("fd_contract_id")
private String fdContractId;
/**
* 创建时间(毫秒时间戳,v4 新增)
*/
@JsonProperty("fd_create_time")
private Long fdCreateTime;
/**
* 业务ID(方便溯源用,v4 新增,TMS 传付款申请单ID)
*/
@JsonProperty("fd_business_id")
private String fdBusinessId;
/**
* 附件不可下载
*/
@@ -59,6 +59,10 @@ public class HcsTemplateVO implements Serializable {
* 合同性质(如 standard)
*/
private String fdContractCharacter;
/**
* 分类层级ID(v4 新增)
*/
private String fdCateHierarchyId;
/**
* 创建时间(毫秒时间戳)
*/
@@ -71,6 +75,18 @@ public class HcsTemplateVO implements Serializable {
* 创建部门
*/
private HcsRefVO fdCreatorDept;
/**
* 是否禁止更新主数据权限
*/
private Boolean fdDisableUpdateMainAuth;
/**
* 主数据授权时间点(如 afterapproved)
*/
private String fdAuthToMainTime;
/**
* 是否强制自动编号
*/
private Boolean fdForceAutoNumber;
/**
* 模板扩展属性(含中文名)
*/
@@ -31,6 +31,7 @@ import org.springblade.hcs.dto.HcsAttachmentDownloadDTO;
import org.springblade.hcs.dto.HcsAttachmentVO;
import org.springblade.hcs.dto.HcsCategoryVO;
import org.springblade.hcs.dto.HcsContractDetailQueryDTO;
import org.springblade.hcs.dto.HcsContractDetailVO;
import org.springblade.hcs.dto.HcsContractDraftDTO;
import org.springblade.hcs.dto.HcsContractDraftVO;
import org.springblade.hcs.dto.HcsContractVO;
@@ -173,13 +174,13 @@ public interface IHcsClient {
/**
* C103-4 合同详情(fdId 与 fdNumber 二选一)
* <p>
* TODO 待联调确认:出参 data 结构 v4 未定义,暂以对象承接,联调后补充(设计文档 §5.9)
* v4 已定义详情响应字段表({@link HcsContractDetailVO});级联/集合字段内部结构以实际返回为准。
*
* @param param 请求参数
* @return 合同详情(结构待联调确认)
* @return 合同详情
*/
@PostMapping(CONTRACT_DETAIL_URL)
HcsResult<Object> contractDetail(@RequestBody HcsContractDetailQueryDTO param);
HcsResult<HcsContractDetailVO> contractDetail(@RequestBody HcsContractDetailQueryDTO param);
/**
* C103-9(新) 合同履约规则同步(行级增删改,与废弃旧接口同路径不同入参,务必用本新版结构)