feat(contract): 新增合同余额功能及重构文件管理

重构合同文件管理逻辑，增加错误处理和日志记录新增ContractBalance实体、Repository和VO类完善Voable接口文档和实现规范更新项目架构文档和数据库设计修复SmbFileService的连接问题移动合同相关TabSkin类到contract包添加合同文件重建任务的WebSocket支持
2025-11-19 00:50:16 +08:00
parent 87290f15b0
commit 02afa189f8
49 changed files with 7577 additions and 441 deletions
--- a/common/src/main/java/com/ecep/contract/model/Voable.java
+++ b/common/src/main/java/com/ecep/contract/model/Voable.java
@@ -1,12 +1,106 @@
 package com.ecep.contract.model;

+import java.io.Serializable;
+
+/**
+ * 可转换为Vo的实体类接口
+ * 
+ * 该接口用于实体对象与视图对象(View Object)之间的转换，
+ * 是实现MVC架构中数据传输层的重要接口。
+ * 
+ * <p>
+ * <strong>使用场景：</strong>
+ * </p>
+ * <ul>
+ * <li>服务端将实体对象转换为轻量级的VO对象传输给前端</li>
+ * <li>避免直接暴露实体对象中的敏感信息和内部实现细节</li>
+ * <li>减少网络传输数据量，提高性能</li>
+ * <li>统一实体-VO转换的标准接口</li>
+ * </ul>
+ * 
+ * <p>
+ * <strong>实现要求：</strong>
+ * </p>
+ * <ul>
+ * <li>实现类必须重写toVo()方法，提供完整的字段映射逻辑</li>
+ * <li>对于关联实体对象，只映射其ID到VO中，避免加载整个关联对象</li>
+ * <li>对可能为null的关联对象进行空值检查和防护</li>
+ * <li>VO对象必须实现Serializable接口以支持序列化</li>
+ * <li>转换过程应包含所有需要在前端显示的字段</li>
+ * </ul>
+ * 
+ * <p>
+ * <strong>典型实现模式：</strong>
+ * </p>
+ * 
+ * <pre>
+ * {@literal @}Override
+ * public ContractBalanceVo toVo() {
+ *     ContractBalanceVo vo = new ContractBalanceVo();
+ *     vo.setId(id);
+ *     vo.setRefId(refId);
+ *     vo.setGuid(guid);
+ *     
+ *     // 关联对象只映射ID
+ *     if (contract != null) {
+ *         vo.setContractId(contract.getId());
+ *     }
+ *     
+ *     // 其他字段映射...
+ *     return vo;
+ * }
+ * </pre>
+ * 
+ * @param <T> 目标VO类类型，必须实现Serializable接口
+ * @since 1.0
+ */
 public interface Voable<T> {
+
    /**
-     * 转换为Vo 
+     * 转换为对应的视图对象(View Object)
     * 
-     * @return
+     * <p>
+     * 该方法负责将当前实体对象转换为轻量级的VO对象，用于：
+     * <ul>
+     * <li>前端数据展示：提供前端需要显示的所有字段</li>
+     * <li>数据传输：减少网络传输的数据量和敏感信息暴露</li>
+     * <li>界面渲染：支持UI组件的数据绑定和显示</li>
+     * </ul>
+     * </p>
+     * 
+     * <p>
+     * <strong>转换规则：</strong>
+     * </p>
+     * <ul>
+     * <li>基本类型字段直接映射：id, code, name, createDate等</li>
+     * <li>关联实体字段只映射ID：如 contract.getId(), employee.getId()等</li>
+     * <li>日期字段保持原有类型：LocalDate, LocalDateTime等</li>
+     * <li>枚举字段转换为字符串或保持原类型</li>
+     * <li>数值类型根据需要进行类型转换或格式化</li>
+     * </ul>
+     * 
+     * <p>
+     * <strong>空值处理：</strong>
+     * </p>
+     * <ul>
+     * <li>所有关联对象访问前必须进行null检查</li>
+     * <li>如关联对象为null，则VO中对应字段设为null或默认值</li>
+     * <li>使用条件判断：{@code if (关联对象 != null) vo.set关联Id(关联对象.getId());}</li>
+     * </ul>
+     * 
+     * <p>
+     * <strong>性能考虑：</strong>
+     * </p>
+     * <ul>
+     * <li>避免在转换过程中执行复杂业务逻辑</li>
+     * <li>不加载不必要的关联对象数据</li>
+     * <li>使用懒加载机制，减少数据库查询</li>
+     * </ul>
+     * 
+     * @return 转换后的VO对象实例，不能为null
+     * @throws IllegalStateException 如果转换过程中发生不可恢复的状态错误
+     * @see Serializable
+     * @see IdentityEntity
     */
    T toVo();
-
-
 }
--- a/common/src/main/java/com/ecep/contract/vo/ContractBalanceVo.java
+++ b/common/src/main/java/com/ecep/contract/vo/ContractBalanceVo.java
@@ -0,0 +1,120 @@
+package com.ecep.contract.vo;
+
+import com.ecep.contract.model.IdentityEntity;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Data
+public class ContractBalanceVo implements IdentityEntity, ContractBasedVo, Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private Integer id;
+    /**
+     * 余额ID (对应cBalanceID)
+     */
+    private String refId;
+
+    /**
+     * GUID，余额在系统中的唯一标识 (对应GUID字段)
+     */
+    private UUID guid;
+
+    /**
+     * 关联合同ID (对应cContractID)
+     */
+    private Integer contractId;
+
+    /**
+     * 业务员ID (对应cFunctionaryID)
+     */
+    private Integer employeeId;
+
+    /**
+     * 余额类型ID (对应cBalancelTypeID)
+     */
+    private String balanceTypeId;
+
+    /**
+     * 汇率 (对应decExchangeRate)
+     */
+    private Double exchangeRate;
+
+    /**
+     * 发票号码 (对应cBalanceDetails)
+     */
+    private String invoiceNumber;
+
+    /**
+     * 创建人 (对应cProducer)
+     */
+    private Integer setupPersonId;
+
+    /**
+     * 创建日期 (对应dtProduceDate)
+     */
+    private LocalDate setupDate;
+
+    /**
+     * 审核人 (对应cAuditer)
+     */
+    private Integer auditerId;
+
+    /**
+     * 审核日期 (对应dtAuditeDate)
+     */
+    private LocalDate auditeDate;
+
+    /**
+     * 管理员 (对应cAdmin)
+     */
+    private Integer adminId;
+
+    /**
+     * 管理员日期 (对应dtAdminDate)
+     */
+    private LocalDate adminDate;
+
+    /**
+     * 凭证ID (对应cPZID)
+     */
+    private String pzId;
+
+    /**
+     * 凭证编号 (对应cPZNum)
+     */
+    private String pzNum;
+
+    /**
+     * JSD类型 (对应cJsdType)
+     */
+    private String jsdType;
+
+    /**
+     * 源余额ID (对应cSrcBalanceID)
+     */
+    private String srcBalanceId;
+
+    /**
+     * 创建时间 (对应dtCreateTime)
+     */
+    private LocalDateTime createTime;
+
+    /**
+     * 修改时间 (对应dtModifyTime)
+     */
+    private LocalDateTime modifyTime;
+
+    /**
+     * 修改人 (对应cModifer)
+     */
+    private Integer modiferId;
+
+    /**
+     * 生效时间 (对应dtEffectTime)
+     */
+    private LocalDateTime effectTime;
+}