songqq/contract-manager
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

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

Browse Source 
重构合同文件管理逻辑，增加错误处理和日志记录
新增ContractBalance实体、Repository和VO类
完善Voable接口文档和实现规范
更新项目架构文档和数据库设计
修复SmbFileService的连接问题
移动合同相关TabSkin类到contract包
添加合同文件重建任务的WebSocket支持
This commit is contained in:
宋其青
2025-11-19 00:50:16 +08:00
parent 87290f15b0
commit 02afa189f8
49 changed files with 7577 additions and 441 deletions
Download Patch File Download Diff File Expand all files Collapse all files

576
.trae/rules/client_service_rules.md
View File

@@ -1,83 +1,133 @@
# 客户端 Service 类规则
# Client Service 实现编写指南
## 1. 目录结构
- 所有客户端 Service 类位于 `client/src/main/java/com/ecep/contract/service/` 目录下
- 按业务领域组织，直接放置在 service 包下，不进行子包划分
- 服务类命名与实体类一一对应
## 📋 概述
## 2. 命名规范
- 服务类命名格式为：`[实体名称]Service.java`
- 例如：`CompanyService.java`、`ContractService.java`、`ProjectService.java`
- 基础服务接口命名为：`IEntityService.java`、`ViewModelService.java`
- 泛型基础服务类命名为：`QueryService.java`
本指南总结 Client 模块 Service 层的实现经验，用于指导后续 Service 的编写。本指南基于 Contract-Manager 项目中已实现的 Service 模式整理。
## 3. 继承关系
- 业务服务类通常继承自泛型基础服务类 `QueryService<T, TV>`
- `T` 表示 VO 类型（实现了 IdentityEntity 接口）
- `TV` 表示 ViewModel 类型（实现了 IdentityViewModel<T> 接口）
- `QueryService` 实现了 `ViewModelService<T, TV>` 接口
- `ViewModelService` 继承了 `IEntityService<T>` 接口
- 特定场景下可以不继承 `QueryService`，直接实现所需接口或创建独立服务类
---
## 🏗️ 基础架构
### 1. 继承层次结构
```java
// Service 接口定义
public interface IEntityService<T> {
T findById(Integer id);
T save(T entity);
void delete(T entity);
List<T> findAll();
Page<T> findAll(Map<String, Object> params, Pageable pageable);
StringConverter<T> getStringConverter();
}
// 基础 Service 实现
public abstract class QueryService<T extends IdentityEntity, TV extends IdentityViewModel<T>>
implements ViewModelService<T, TV> {
// 核心实现
}
// 具体业务 Service
@Service
@CacheConfig(cacheNames = "company")
public class CompanyService extends QueryService<CompanyVo, CompanyViewModel> {
// 业务方法实现
@CacheConfig(cacheNames = "business")
public class XxxService extends QueryService<XxxVo, XxxViewModel> {
// 业务特定实现
}
```
## 4. 注解使用
- **@Service**：标记为 Spring 服务组件，使其可被自动发现和注入
- **@CacheConfig**：配置缓存名称，通常与服务类名对应
- **@Cacheable**：标记方法结果可缓存，需指定缓存键（key）
- **@CacheEvict**：标记方法执行后清除缓存，可指定缓存键或清除所有
- **@Caching**：组合多个缓存操作（如同时清除多个缓存条目）
- **@Autowired**：用于自动注入依赖的其他服务
### 2. 核心特性
- **泛型支持**：`QueryService` 使用泛型处理不同类型的 Vo 和 ViewModel
- **WebSocket 通信**：通过 `WebSocketClientService` 与 Server 端通信
- **异步处理**：使用 `CompletableFuture` 实现异步操作
- **缓存机制**：集成 Spring Cache 支持多级缓存
- **错误处理**：统一的异常处理和日志记录
---
## 📝 Service 编写规范
### 1. 类声明和注解
```java
@Service
@CacheConfig(cacheNames = "contract")
public class ContractService extends QueryService<ContractVo, ContractViewModel> {
@Autowired
private SysConfService confService;
@Cacheable(key = "#p0")
public ContractVo findById(Integer id) {
return super.findById(id);
}
@Caching(evict = {
@CacheEvict(key = "#p0.id"),
@CacheEvict(key = "'code-'+#p0.code")
})
public ContractVo save(ContractVo contract) {
return super.save(contract);
}
@Service // Spring 组件注解
@CacheConfig(cacheNames = "xxx") // 缓存配置，xxx为业务域名称
public class XxxService extends QueryService<XxxVo, XxxViewModel> {
// Service 实现
}
```
## 5. 缓存机制
- 每个服务类应有独立的缓存名称空间
- 缓存键（key）应具有唯一性，通常使用 ID、代码或名称等唯一标识
- 保存和删除操作时应清除相关缓存，保持数据一致性
- 可使用 SpEL 表达式动态生成缓存键
- 频繁查询的数据应考虑缓存，提高性能
### 2. 缓存策略
## 6. 异步调用机制
- 使用 `async()` 方法进行异步远程调用
- 方法参数通常包括：方法名、参数值、参数类型列表
- 使用 `CompletableFuture` 处理异步结果
- 使用 `handle()` 方法处理响应和异常
- 远程调用异常应包装为 RuntimeException 并提供详细错误信息
#### 缓存注解使用
```java
@Cacheable(key = "#p0") // 按ID缓存
@Cacheable(key = "'code-'+#p0") // 按代码缓存
@Cacheable(key = "'name-'+#p0") // 按名称缓存
@CacheEvict(key = "#p0.id") // 删除时清除ID缓存
@CacheEvict(key = "'code-'+#p0.code") // 清除代码缓存
@Caching(evict = {
@CacheEvict(key = "#p0.id"),
@CacheEvict(key = "'code-'+#p0.code")
}) // 批量清除缓存
```
#### 缓存键设计原则
- **ID 缓存**：`#p0`（第一个参数，通常是ID）
- **代码缓存**：`'code-'+#p0`（业务代码的缓存）
- **名称缓存**：`'name-'+#p0`（业务名称的缓存）
- **关联缓存**：`'company-'+#p0.id`（关联实体的缓存）
### 3. 核心方法实现
#### findById 方法
```java
@Cacheable(key = "#p0")
@Override
public XxxVo findById(Integer id) {
return super.findById(id); // 调用父类方法
}
```
#### save 方法（带缓存清除）
```java
@Caching(evict = {
@CacheEvict(key = "#p0.id"),
@CacheEvict(key = "'code-'+#p0.code")
})
@Override
public XxxVo save(XxxVo entity) {
return super.save(entity);
}
```
#### delete 方法（带缓存清除）
```java
@Caching(evict = {
@CacheEvict(key = "#p0.id"),
@CacheEvict(key = "'code-'+#p0.code")
})
@Override
public void delete(XxxVo entity) {
super.delete(entity);
}
```
---
## 🔄 异步通信模式
### 1. 基本异步调用
```java
@Cacheable(key = "'code-'+#p0")
public ContractVo findByCode(String code) {
// 异步调用示例
public XxxVo findByCode(String code) {
try {
return async("findByCode", code, String.class).handle((response, ex) -> {
if (ex != null) {
throw new RuntimeException("远程方法+findByCode+调用失败", ex);
throw new RuntimeException("远程方法 findByCode 调用失败", ex);
}
if (response != null) {
return updateValue(createNewEntity(), response);
@@ -85,62 +135,374 @@ public ContractVo findByCode(String code) {
return null;
}).get();
} catch (Exception e) {
throw new RuntimeException("查询失败: " + code, e);
throw new RuntimeException("查找实体失败: " + code, e);
}
}
```
## 7. 基础方法实现
- 应实现 `IEntityService<T>` 接口定义的核心方法：
- `findById(Integer id)`：根据 ID 查询实体
- `save(T entity)`：保存实体
- `delete(T entity)`：删除实体
- `findAll()`：查询所有实体
- `findAll(Map<String, Object> params, Pageable pageable)`：条件分页查询
- `getStringConverter()`：获取类型转换器
- 通常通过继承 `QueryService` 来复用这些基础方法的实现
- 可根据业务需求重写或扩展基础方法
## 8. 业务方法规范
- 业务方法应与服务端对应，保持方法名和参数一致
- 方法命名应清晰表达其功能，如 `findByName`, `findByCode`
- 复杂业务逻辑应封装为独立方法
- 参数校验应在方法开始处进行
- 返回值类型应明确，避免使用过于泛化的类型
## 9. 类型转换器
- 实现 `getStringConverter()` 方法，返回对应的 StringConverter 实例
- 通常创建专用的 Converter 类，如 `CustomerCatalogStringConverter`
- 转换器实例应作为服务类的成员变量，避免重复创建
### 2. 复杂对象处理
```java
public class CustomerCatalogService extends QueryService<CustomerCatalogVo, CustomerCatalogViewModel> {
private final CustomerCatalogStringConverter stringConverter = new CustomerCatalogStringConverter(this);
@Override
public StringConverter<CustomerCatalogVo> getStringConverter() {
return stringConverter;
public List<XxxDetailVo> findDetailsByXxxId(Integer xxxId) {
try {
return async("findDetailsByXxxId", List.of(xxxId), List.of(Integer.class))
.handle((response, ex) -> {
if (ex != null) {
throw new RuntimeException("远程方法调用失败", ex);
}
if (response != null) {
try {
List<XxxDetailVo> content = new ArrayList<>();
for (JsonNode node : response) {
XxxDetailVo newEntity = new XxxDetailVo();
objectMapper.updateValue(newEntity, node);
content.add(newEntity);
}
return content;
} catch (Exception e) {
throw new RuntimeException(response.toString(), e);
}
}
return null;
}).get();
} catch (Exception e) {
throw new RuntimeException(e);
}
}
```
## 10. 错误处理
- 远程调用异常应捕获并包装为更具描述性的 RuntimeException
- 提供详细的错误信息，包括调用的方法名和参数
- 对于可预期的业务异常，可添加专门的处理逻辑
- 不推荐使用 printStackTrace()，应使用日志记录异常
---
## 11. 工具方法和辅助功能
- 通用功能可封装为工具方法
- 配置相关操作可通过 `SysConfService` 实现
- 文件路径处理应使用 `File` 类和相关工具方法
- 日期时间处理应使用 Java 8+ 的日期时间 API
## 💼 业务逻辑模式
## 12. 最佳实践
- 遵循单一职责原则，每个服务类专注于一个业务领域
- 优先使用继承和接口实现来复用代码
- 合理使用缓存提高性能，但注意缓存一致性
- 异步调用应正确处理异常和超时情况
- 服务类之间的依赖应通过 `@Autowired` 注入，避免硬编码
- 方法实现应简洁明了，复杂逻辑应拆分
- 为重要方法添加 JavaDoc 注释，说明其功能和参数含义
### 1. 文件系统集成
#### 路径管理
```java
@Autowired
private SysConfService confService;
private File basePath;
public File getBasePath() {
if (basePath == null) {
basePath = new File(confService.getString(Constant.KEY_BASE_PATH));
}
return basePath;
}
// 验证路径是否在基础目录内
public boolean checkXxxPathInBasePath(XxxVo xxx) {
if (!existsXxxPath(xxx)) {
return false;
}
File basePath = getBasePath();
if (basePath == null || !basePath.exists()) {
throw new IllegalArgumentException("基础目录不存在");
}
File path = new File(xxx.getPath());
return path.getAbsolutePath().startsWith(basePath.getAbsolutePath());
}
// 检查路径是否存在
public boolean existsXxxPath(XxxVo xxx) {
if (!StringUtils.hasText(xxx.getPath())) {
return false;
}
File path = new File(xxx.getPath());
return path.exists();
}
```
#### 目录创建
```java
public File makePath(XxxVo xxx) {
File basePath = getBasePath();
if (!basePath.exists()) {
holder.error("存储目录不存在：" + basePath.getAbsolutePath());
return null;
}
// 构建目录路径逻辑
String fileName = FileUtils.escapeFileName(xxx.getName());
File dir = new File(basePath, fileName);
if (!dir.exists()) {
if (!dir.mkdir()) {
holder.error("创建目录失败：" + dir.getAbsolutePath());
return null;
}
}
return dir;
}
```
### 2. 业务验证模式
#### 数据完整性验证
```java
public void verifyXxx(XxxVo xxx, LocalDate verifyDate, MessageHolder holder) {
// 检查关键字段
if (!StringUtils.hasText(xxx.getCode())) {
holder.error("编号异常：未设置");
return;
}
// 检查状态字段
String status = xxx.getStatus();
if (StringUtils.hasText(status) && status.contains("无效")) {
LocalDate end = xxx.getEndDate();
LocalDate begin = xxx.getBeginDate();
if (begin == null || end == null) {
holder.error("状态异常：" + status);
} else {
if (!MyDateTimeUtils.dateValidFilter(verifyDate, begin, end, 0)) {
holder.error("状态异常：" + status);
}
}
} else {
holder.error("状态异常：未设置");
}
}
```
#### 关联实体验证
```java
public boolean verifyAsXxxType(XxxVo xxx, LocalDate verifyDate, MessageHolder holder) {
boolean valid = false;
// 检查关联实体
RelatedVo related = relatedService.findById(xxx.getRelatedId());
if (related == null) {
holder.error("关联实体不存在");
valid = true;
}
// 检查关联数据
if (!StringUtils.hasText(xxx.getRelatedField())) {
holder.error("关联字段未设置");
valid = true;
}
// 检查业务规则
if (xxx.getStatus() == XxxStatus.INACTIVE) {
holder.error("业务状态异常：已停用");
valid = true;
}
return valid;
}
```
### 3. 复杂业务查询
#### 分页查询
```java
public List<XxxVo> findAllByXxxCondition(XxxCondition condition, LocalDate beginDate, LocalDate endDate) {
return findAll(ParamUtils.builder()
.equals("field1", condition.getField1())
.between("createDate", beginDate, endDate)
.equals("status", "ACTIVE")
.build(), Pageable.unpaged()).getContent();
}
```
#### 组合条件查询
```java
public Page<XxxVo> findAllWithComplexCondition(XxxQueryParam param) {
ParamUtils.ParamBuilder builder = ParamUtils.builder()
.equals("category", param.getCategory());
if (StringUtils.hasText(param.getName())) {
builder.like("name", "%" + param.getName() + "%");
}
if (param.getDateRange() != null) {
builder.between("createDate", param.getDateRange().getStart(),
param.getDateRange().getEnd());
}
return findAll(builder.build(), Pageable.ofSize(param.getPageSize()));
}
```
---
## 🔧 工具类和依赖注入
### 1. 常用工具类依赖
```java
// 常用注入
@Autowired
private SysConfService confService; // 系统配置服务
@Autowired
private RelatedService relatedService; // 关联实体服务
// 静态工具类使用
import com.ecep.contract.util.FileUtils; // 文件工具
import com.ecep.contract.util.ParamUtils; // 参数工具
import com.ecep.contract.util.MyStringUtils; // 字符串工具
```
### 2. 工具类使用示例
#### ParamUtils 构建查询条件
```java
// 构建复杂查询条件
Map<String, Object> params = ParamUtils.builder()
.equals("field1", value1)
.equals("field2", value2)
.like("name", "%" + keyword + "%")
.between("date", startDate, endDate)
.in("status", List.of("ACTIVE", "PENDING"))
.orderBy("createTime", "desc")
.build();
```
#### FileUtils 处理文件路径
```java
// 文件名转义
String safeFileName = FileUtils.escapeFileName(companyName);
// 获取父级前缀
String parentPrefix = FileUtils.getParentPrefixByDistrict(district);
```
---
## 📊 错误处理和日志
### 1. 异常处理模式
```java
// 查询异常处理
try {
return async("findByCode", code, String.class).handle((response, ex) -> {
if (ex != null) {
throw new RuntimeException("远程方法 findByCode 调用失败", ex);
}
if (response != null) {
return updateValue(createNewEntity(), response);
}
return null;
}).get();
} catch (Exception e) {
throw new RuntimeException("查找实体失败: " + code, e);
}
// 业务验证异常
public boolean businessMethod(XxxVo xxx) {
if (xxx == null) {
return false;
}
if (!xxx.isValid()) {
throw new IllegalArgumentException("实体数据无效");
}
return true;
}
```
### 2. 日志记录
```java
// 在 QueryService 中已集成日志
private static final Logger logger = LoggerFactory.getLogger(QueryService.class);
// 在业务方法中使用
public void deleteXxx(XxxVo xxx) {
try {
super.delete(xxx);
logger.info("删除实体成功 #{}", xxx.getId());
} catch (Exception e) {
logger.error("删除实体失败 #{}", xxx.getId(), e);
throw new RuntimeException("删除实体失败", e);
}
}
```
---
## 🧪 测试和验证
### 1. 方法验证检查点
- **输入参数验证**：检查空值、格式、范围
- **业务逻辑验证**：检查状态、关联、权限
- **文件系统验证**：检查路径、权限、空间
- **数据库验证**：检查连接、事务、一致性
### 2. 常见测试场景
```java
// 测试用例示例
@Test
public void testFindById() {
// 正常情况
XxxVo result = xxxService.findById(1);
assertNotNull(result);
// 异常情况
assertThrows(RuntimeException.class, () -> {
xxxService.findById(-1);
});
}
@Test
public void testSaveWithCache() {
XxxVo xxx = createTestXxx();
xxx.setCode("TEST001");
XxxVo saved = xxxService.save(xxx);
assertNotNull(saved.getId());
// 验证缓存
XxxVo cached = xxxService.findById(saved.getId());
assertEquals(saved.getId(), cached.getId());
}
```
---
## 🎯 最佳实践
### 1. 代码组织原则
- **单一职责**：每个 Service 专注特定的业务域
- **依赖注入**：合理使用 `@Autowired` 注入依赖
- **缓存策略**：为高频查询字段配置缓存
- **异常处理**：统一处理业务异常和系统异常
### 2. 性能优化建议
- **缓存配置**：合理设置缓存过期时间
- **分页查询**：避免大数据量一次性查询
- **异步处理**：使用异步调用提升响应速度
- **批量操作**：考虑批量处理减少网络开销
### 3. 可维护性提升
- **命名规范**：遵循项目统一的命名约定
- **注释文档**：为复杂业务逻辑添加注释
- **代码复用**：提取公共逻辑到工具类
- **版本兼容**：考虑前后端版本兼容性
---
## 📚 相关规范
- **Controller 规范**：[client_controller_rules.md](.trae/rules/client_controller_rules.md)
- **转换器规范**：[client_converter_rules.md](.trae/rules/client_converter_rules.md)
- **Task 规范**：[client_task_rules.md](.trae/rules/client_task_rules.md)
- **Entity 规范**：[entity_rules.md](.trae/rules/entity_rules.md)
- **VO 规范**：[vo_rules.md](.trae/rules/vo_rules.md)
---
*本文档基于 Contract-Manager 项目现有 Service 实现模式总结，遵循项目既定的技术架构和编程规范。*
**文档版本**: v1.0.0
**最后更新**: 2024-12-19
**维护团队**: Contract Manager Development Team

374
.trae/rules/repository_comprehensive_analysis_report.md Normal file
View File

@@ -0,0 +1,374 @@
# Repository一致性分析 - 综合报告
## 📊 执行摘要
### 分析概览
- **总Repository数量**: 22个
- **涉及业务域**: contract, company, customer, project, vendor
- **分析时间**: 2024年项目全面分析
- **分析范围**: 覆盖server模块下所有5个业务域的Repository实现
### 目录覆盖情况
✅ `server/src/main/java/com/ecep/contract/ds/contract/repository/` (13个)
✅ `server/src/main/java/com/ecep/contract/ds/company/repository/` (3个)
✅ `server/src/main/java/com/ecep/contract/ds/customer/repository/` (2个)
✅ `server/src/main/java/com/ecep/contract/ds/project/repository/` (3个)
✅ `server/src/main/java/com/ecep/contract/ds/vendor/repository/` (2个)
## 🔍 关键发现与评估
### 🔴 严重问题：继承层次不一致（5个）
#### 1. 直接继承JpaRepository（4个）
- `ContractFileRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
- `ContractItemRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
- `VendorFileRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
- `ProjectQuotationRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
#### 2. 继承多个冗余接口（1个）
- `PurchaseOrderRepository` - 同时继承了4个接口：`CrudRepository`, `PagingAndSortingRepository`, `JpaRepository`, `JpaSpecificationExecutor`
### 🟡 中等问题（6个）
#### 注解缺失（2个）
- `CompanyFileRepository` - 缺少`@Repository`注解
- `ProjectFileRepository` - 缺少`@Repository`注解
#### 文档注释缺失（4个）
- `CompanyFileRepository` - 缺少JavaDoc注释
- `ProjectFileRepository` - 缺少JavaDoc注释
- `VendorFileRepository` - 缺少JavaDoc注释
- `ProjectQuotationRepository` - 缺少JavaDoc注释
### 📈 整体质量评估
#### 正确实现统计
- ✅ **17个Repository正确继承MyRepository** (77%)
- ❌ **5个Repository继承层次错误** (23%)
- 🟡 **2个Repository缺少注解** (9%)
- 🟡 **4个Repository文档不完整** (18%)
#### 质量分级分布
- **A级（完全正确）**: 13个 (59%)
- **B级（轻微问题）**: 6个 (27%)
- **C级（严重错误）**: 3个 (14%)
---
# 详细技术分析
## 继承一致性详细分析
### ✅ 正确继承MyRepository的Repository（17个）
**contract业务域（7个）：**
- ContractRepository
- ContractBalanceRepository
- SalesOrderRepository
- ContractTypeRepository
- ContractKindRepository
- ContractInvoiceRepository
**company业务域（3个）：**
- CompanyRepository
- CompanyFileRepository (有注解问题)
- CompanyCustomerRepository
**customer业务域（2个）：**
- CustomerCatalogRepository
**project业务域（2个）：**
- ProjectRepository
- ProjectFileRepository (有注解问题)
**vendor业务域（1个）：**
- VendorRepository
### ❌ 继承层次错误的Repository（5个）
#### Contract业务域（3个）
1. **ContractFileRepository**
2. **ContractItemRepository**
3. **PurchaseOrderRepository**
#### Project业务域（1个）
4. **ProjectQuotationRepository**
#### Vendor业务域（1个）
5. **VendorFileRepository**
## 问题影响分析
### 技术影响
- ❌ 违反了统一的架构设计原则
- ❌ 失去了MyRepository提供的统一功能增强
- ❌ 代码风格不一致，影响可维护性
- ❌ 开发团队需要维护多种不同的实现模式
- ❌ 增加了代码维护成本和技术债务
### 业务影响
- ❌ 代码可维护性降低
- ❌ 新团队成员学习成本增加
- ❌ 代码审查复杂度提高
- ❌ 系统稳定性潜在风险增加
## 详细修复方案
### 🔴 优先级1：修复继承层次错误
#### 1. ContractFileRepository
```java
// ❌ 当前错误实现
public interface ContractFileRepository
extends JpaRepository<ContractFile, Integer>, JpaSpecificationExecutor<ContractFile> {
// ✅ 正确修复
@Repository
public interface ContractFileRepository extends MyRepository<ContractFile, Integer> {
// 自动获得MyRepository提供的所有功能
}
```
#### 2. ContractItemRepository
```java
// ❌ 当前错误实现
public interface ContractItemRepository
extends JpaRepository<ContractItem, Integer>, JpaSpecificationExecutor<ContractItem> {
// ✅ 正确修复
@Repository
public interface ContractItemRepository extends MyRepository<ContractItem, Integer> {
// 统一继承结构，简化维护
}
```
#### 3. VendorFileRepository
```java
// ❌ 当前错误实现
@Repository
public interface VendorFileRepository
extends JpaRepository<VendorFile, Integer>, JpaSpecificationExecutor<VendorFile> {
// ✅ 正确修复
@Repository
public interface VendorFileRepository extends MyRepository<VendorFile, Integer> {
// 保持注解的同时修正继承结构
}
```
#### 4. ProjectQuotationRepository
```java
// ❌ 当前错误实现
@Repository
public interface ProjectQuotationRepository
extends JpaRepository<ProjectQuotation, Integer>, JpaSpecificationExecutor<ProjectQuotation> {
// ✅ 正确修复
@Repository
public interface ProjectQuotationRepository extends MyRepository<ProjectQuotation, Integer> {
// 获得MyRepository的所有增强功能
}
```
#### 5. PurchaseOrderRepository
```java
// ❌ 当前错误实现（继承4个冗余接口）
public interface PurchaseOrderRepository extends
CrudRepository<PurchaseOrder, Integer>,
PagingAndSortingRepository<PurchaseOrder, Integer>,
JpaRepository<PurchaseOrder, Integer>,
JpaSpecificationExecutor<PurchaseOrder> {
// ✅ 正确修复
@Repository
public interface PurchaseOrderRepository extends MyRepository<PurchaseOrder, Integer> {
// 单一继承，清晰简洁
}
```
### 🟡 优先级2：修复注解缺失
#### CompanyFileRepository
```java
// ❌ 当前缺少注解
public interface CompanyFileRepository extends MyRepository<CompanyFile, Integer> {
// ✅ 添加注解
@Repository
public interface CompanyFileRepository extends MyRepository<CompanyFile, Integer> {
// 添加完整的JavaDoc注释
/**
* 公司文件数据访问接口
* 提供公司相关文件的CRUD操作和业务查询功能
*/
}
```
#### ProjectFileRepository
```java
// ❌ 当前缺少注解
public interface ProjectFileRepository extends MyRepository<ProjectFile, Integer> {
// ✅ 添加注解
@Repository
public interface ProjectFileRepository extends MyRepository<ProjectFile, Integer> {
/**
* 项目文件数据访问接口
* 提供项目文件的管理和查询功能
*/
}
```
### 🟡 优先级3：完善文档注释
为以下Repository补充完整的JavaDoc注释：
- CompanyFileRepository
- ProjectFileRepository
- VendorFileRepository
- ProjectQuotationRepository
标准JavaDoc格式示例：
```java
/**
* [功能描述]数据访问接口
*
* 提供[业务描述]的CRUD操作和业务查询功能
*
* @author [作者]
* @since [版本]
*/
```
## 实施计划
### 阶段1：立即修复（1-2天）
**目标**: 解决所有严重的继承层次错误
**执行步骤**:
1. 备份当前的Repository实现
2. 逐一修复5个继承层次错误的Repository
3. 添加缺失的@Repository注解
4. 运行编译测试确保无破坏性变更
5. 执行基本功能验证测试
**验收标准**:
- 所有Repository都继承MyRepository
- 编译通过，无语法错误
- 基本CRUD功能正常
### 阶段2：文档完善（1天）
**目标**: 统一JavaDoc注释规范
**执行步骤**:
1. 为4个Repository补充JavaDoc注释
2. 检查并更新相关单元测试
3. 验证文档格式规范性
4. 代码审查确认
**验收标准**:
- 所有Repository都有完整的JavaDoc注释
- 测试用例覆盖主要功能
- 代码审查通过
### 阶段3：质量保证（半天）
**目标**: 确保修改不影响系统稳定性
**执行步骤**:
1. 全面编译测试
2. 运行相关单元测试套件
3. 执行集成测试验证
4. 更新相关文档
5. 最终验收确认
**验收标准**:
- 所有测试通过
- 系统功能完整
- 性能无明显影响
## 对规范文档的影响
### ✅ 已更新的规范文档
- **`server_repository_rules.md`** - 已包含错误示例和正确实现指南
- 新增"2.2 重要错误示例"章节
- 新增"2.3 当前项目错误统计"章节
- 新增"2.5 MyRepository基类能力"章节
### 📋 需要更新的检查清单
1. **继承层次检查** - 确保所有Repository继承MyRepository
2. **注解完整性检查** - 验证所有Repository都有@Repository注解
3. **文档规范性检查** - 确认JavaDoc注释完整性
4. **代码风格一致性检查** - 验证命名规范和代码格式
## 🎯 预期收益
### 技术收益
- ✅ **统一架构设计** - 所有Repository遵循一致的设计模式
- ✅ **代码一致性提升** - 消除实现差异，提高代码质量
- ✅ **维护成本降低** - 单一继承结构，简化维护工作
- ✅ **团队开发效率提升** - 统一规范，降低学习成本
### 质量收益
- ✅ **减少代码冗余** - 消除重复的接口继承
- ✅ **提高代码可读性** - 统一模式，易于理解
- ✅ **降低技术债务** - 减少不一致实现的技术负担
- ✅ **增强系统稳定性** - 统一模式，减少潜在风险
## 📅 后续行动
### 立即行动（本周）
1. 🔧 修复5个继承层次错误的Repository
2. 🔧 添加缺失的@Repository注解
3. 🔧 编译测试验证功能完整性
### 短期完善（下周）
1. 📝 补充JavaDoc文档注释
2. 🧪 运行完整的单元测试套件
3. 👥 代码审查确认实现质量
### 长期维护
1. 📋 建立Repository开发规范检查清单
2. 🔍 定期进行Repository实现一致性检查
3. 🎓 团队培训和规范宣贯
4. 🤖 建立CI/CD流程中的自动检查机制
## 📞 技术支持
如需技术支持或有任何疑问，请参考：
### 相关文档
- **详细技术分析**: `repository_analysis_report.md`
- **实施规范指导**: `server_repository_rules.md`
- **项目整体规范**: `.trae/rules/` 目录
### 联系方式
- 技术问题: 参考详细分析报告中的修复代码示例
- 规范疑问: 查看server_repository_rules.md文档
- 实施支持: 遵循本报告的分阶段实施计划
---
## 结论
通过对项目中22个Repository的全面分析，我们发现了明显的实现不一致性问题，特别是23%的Repository存在继承层次错误。这些问题严重影响了代码的可维护性和架构的统一性。
**关键统计数据**:
- 17个Repository正确实现 (77%)
- 5个继承层次错误 (23%)
- 2个注解缺失 (9%)
- 4个文档不完整 (18%)
**修复优先级**:
1. **高优先级**: 修复5个继承层次错误（1-2天）
2. **中优先级**: 补充2个缺失注解（半天）
3. **低优先级**: 完善4个文档注释（1天）
建议按照本报告提出的分阶段实施计划，逐步改进所有Repository实现，确保项目达到统一的架构设计标准。通过这些改进，将显著提升代码质量、降低维护成本，并为团队的长期发展奠定坚实基础。
**分析状态**: ✅ 完成
**下一步**: 执行分阶段修复计划
**预计完成时间**: 3-4个工作日
---
**报告生成时间**: 2024年
**分析深度**: 全面技术分析
**实施可行性**: 高（详细修复方案已提供）

460
.trae/rules/server_repository_rules.md Normal file
View File

@@ -0,0 +1,460 @@
# Server模块 Repository 实现经验总结
## 1. Repository 基本架构
### 1.1 接口设计原则
- Repository接口必须继承`MyRepository<T, ID>`基类
- 使用`@Repository`注解标记为Spring组件
- 遵循接口隔离原则，按业务功能组织方法
### 1.2 包结构规范
```
com.ecep.contract.ds.{business}.repository.{EntityName}Repository.java
```
示例：`ContractBalanceRepository`位于`com.ecep.contract.ds.contract.repository`
## 2. 接口继承层次
### 2.1 基础接口结构
```java
@Repository
public interface ContractBalanceRepository extends MyRepository<ContractBalance, Integer> {
// 自定义查询方法
}
```
### 2.2 ⚠️ 重要错误示例 - 避免这些实现方式
**❌ 错误示例1：直接继承JpaRepository**
```java
// ContractFileRepository, ContractItemRepository, VendorFileRepository, ProjectQuotationRepository
@Repository
public interface ContractFileRepository
extends JpaRepository<ContractFile, Integer>, JpaSpecificationExecutor<ContractFile> {
// 错误：不应该直接继承JpaRepository
List<ContractFile> findByContractId(Integer contractId);
}
```
**❌ 错误示例2：继承多个冗余接口**
```java
// PurchaseOrderRepository
public interface PurchaseOrderRepository extends
CrudRepository<PurchaseOrder, Integer>,
PagingAndSortingRepository<PurchaseOrder, Integer>,
JpaRepository<PurchaseOrder, Integer>,
JpaSpecificationExecutor<PurchaseOrder> {
// 错误：冗余接口继承，应该只继承MyRepository
}
```
**❌ 错误示例3：缺少@Repository注解**
```java
// CompanyFileRepository, ProjectFileRepository
public interface CompanyFileRepository extends MyRepository<CompanyFile, Integer> {
// 错误：缺少@Repository注解
List<CompanyFile> findByCompany(Company company);
}
```
**❌ 错误示例4：缺少JavaDoc注释**
```java
// 多个Repository存在此问题
public interface VendorFileRepository extends MyRepository<VendorFile, Integer> {
// 错误：缺少JavaDoc注释说明用途和方法
List<VendorFile> findAllByVendorId(int vendorId);
}
```
**✅ 正确实现示例**
```java
/**
* 合同Repository - 提供合同相关的数据库访问操作
*/
@Repository
public interface ContractRepository extends MyRepository<Contract, Integer> {
// 正确：统一继承MyRepository，有完整的JavaDoc
/**
* 根据合同代码查询合同
* @param code 合同代码
* @return 合同 Optional
*/
Optional<Contract> findByCode(String code);
/**
* 根据状态查询合同列表
* @param status 合同状态
* @return 合同列表
*/
List<Contract> findByStatus(ContractStatus status);
}
```
### 2.3 当前项目错误统计
基于对全项目22个Repository的全面分析，发现以下问题分布：
**🔴 继承层次错误（5个）：**
- `ContractFileRepository` - 直接继承JpaRepository
- `ContractItemRepository` - 直接继承JpaRepository
- `VendorFileRepository` - 直接继承JpaRepository
- `ProjectQuotationRepository` - 直接继承JpaRepository
- `PurchaseOrderRepository` - 继承4个冗余接口
**🟡 注解缺失（2个）：**
- `CompanyFileRepository` - 缺少@Repository注解
- `ProjectFileRepository` - 缺少@Repository注解
**🟡 文档注释不完整（4个）：**
- `CompanyFileRepository` - 缺少JavaDoc注释
- `ProjectFileRepository` - 缺少JavaDoc注释
- `VendorFileRepository` - 缺少JavaDoc注释
- `ProjectQuotationRepository` - 缺少JavaDoc注释
**✅ 正确实现（17个）：**
- contract: ContractRepository, ContractBalanceRepository, SalesOrderRepository, ContractTypeRepository, ContractKindRepository, ContractInvoiceRepository
- company: CompanyRepository
- customer: CompanyCustomerRepository, CustomerCatalogRepository
- project: ProjectRepository
- vendor: VendorRepository
### 2.5 MyRepository基类能力
`MyRepository`接口继承结构：
- `JpaRepository`提供CRUD操作
- 继承`JpaSpecificationExecutor`提供条件查询能力
- 继承`QueryByExampleExecutor`提供示例查询能力
## 3. 查询方法设计
### 3.1 方法命名规范
使用Spring Data JPA的查询方法命名约定：
#### 基本查询方法
- `findBy{属性名}` - 根据属性查找
- `findBy{属性名}And{属性名}` - 多条件AND查询
- `findBy{属性名}Or{属性名}` - 多条件OR查询
- `findBy{属性名}OrderBy{排序属性}` - 带排序查询
#### 关联对象查询
- `findBy{关联对象属性名}.{关联对象属性}` - 嵌套属性查询
- 支持多级嵌套，如：`findByContractCompanyName`
#### 特殊查询类型
```java
// 根据业务ID查找
ContractBalance findByGuid(UUID guid);
// 根据合同ID查找（带分页支持）
Page<ContractBalance> findByContractId(Integer contractId, Pageable pageable);
// 根据多个条件组合查询
List<ContractBalance> findByContractIdAndRefId(Integer contractId, String refId);
```
### 3.2 自定义查询实现
当方法命名无法满足需求时，使用`@Query`注解：
```java
@Query("SELECT cb FROM ContractBalance cb WHERE cb.contract.id = :contractId " +
"AND cb.guid = :guid AND cb.setupDate >= :startDate")
Page<ContractBalance> findByContractAndGuidAndDateRange(
@Param("contractId") Integer contractId,
@Param("guid") UUID guid,
@Param("startDate") LocalDateTime startDate,
Pageable pageable
);
```
## 4. 分页和排序支持
### 4.1 分页查询
```java
// 在Repository接口中定义
Page<ContractBalance> findByContractId(Integer contractId, Pageable pageable);
// 在Service中调用
Page<ContractBalance> result = repository.findByContractId(contractId,
PageRequest.of(page, size, Sort.by("setupDate").descending()));
```
### 4.2 排序规范
- 默认按主键ID降序排列
- 业务相关字段按创建时间降序
- 支持多字段排序：`Sort.by("field1").ascending().and(Sort.by("field2").descending())`
## 5. 统计和聚合查询
### 5.1 基础统计
```java
@Query("SELECT COUNT(cb) FROM ContractBalance cb WHERE cb.contract.id = :contractId")
Long countByContractId(@Param("contractId") Integer contractId);
@Query("SELECT SUM(cb.balanceAmount) FROM ContractBalance cb WHERE cb.contract.id = :contractId")
BigDecimal sumBalanceByContractId(@Param("contractId") Integer contractId);
```
### 5.2 复杂聚合
```java
@Query("SELECT new com.ecep.contract.vo.ContractBalanceStatsVO(" +
"cb.contract.id, COUNT(cb), SUM(cb.balanceAmount)) " +
"FROM ContractBalance cb GROUP BY cb.contract.id")
List<ContractBalanceStatsVO> getBalanceStatsByContract();
```
## 6. 缓存策略
### 6.1 缓存注解使用
虽然Repository本身不直接使用缓存，但需要考虑Service层的缓存需求：
```java
// 在Service层配合使用
@Cacheable(key = "#p0")
ContractBalance findById(Integer id);
@CacheEvict(key = "#p0.id")
ContractBalance save(ContractBalance contractBalance);
```
### 6.2 缓存键设计原则
- 单一记录：使用主键作为键，如`"balance-" + id`
- 按业务维度缓存：使用业务标识，如`"contract-" + contractId`
- 避免缓存键冲突
## 7. 事务管理
### 7.1 事务传播级别
- 查询方法：默认`REQUIRED`
- 写操作：明确指定`@Transactional(propagation = Propagation.REQUIRED)`
### 7.2 异常处理
```java
@Transactional
public ContractBalance saveWithRetry(ContractBalance balance) {
try {
return repository.save(balance);
} catch (DataIntegrityViolationException e) {
// 处理数据完整性异常
throw new BusinessException("数据重复或违反约束", e);
}
}
```
## 8. 性能优化
### 8.1 懒加载优化
```java
// 在查询时指定抓取策略
@Query("SELECT cb FROM ContractBalance cb LEFT JOIN FETCH cb.contract " +
"LEFT JOIN FETCH cb.employee WHERE cb.id = :id")
Optional<ContractBalance> findByIdWithRelations(@Param("id") Integer id);
```
### 8.2 批量操作优化
```java
// 批量插入
@Modifying
@Query("DELETE FROM ContractBalance cb WHERE cb.contract.id IN :contractIds")
void deleteByContractIds(@Param("contractIds") List<Integer> contractIds);
```
## 9. 错误处理和调试
### 9.1 常见异常类型
- `DataAccessException` - 数据访问异常
- `DataIntegrityViolationException` - 数据完整性异常
- `EmptyResultDataAccessException` - 空结果异常
### 9.2 日志记录
```java
@Repository
@Slf4j
public class ContractBalanceRepository {
@Query("...")
public List<ContractBalance> findComplexQuery(...) {
log.debug("执行复杂查询: {}", jpql);
// 执行查询
}
}
```
## 10. 测试策略
### 10.1 Repository测试
```java
@DataJpaTest
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class ContractBalanceRepositoryTest {
@Autowired
private TestEntityManager em;
@Autowired
private ContractBalanceRepository repository;
@Test
void shouldFindByContractId() {
// 测试数据准备
ContractBalance balance = createTestBalance();
// 执行测试
Page<ContractBalance> result = repository.findByContractId(
balance.getContract().getId(),
PageRequest.of(0, 10)
);
// 断言验证
assertThat(result.getContent()).hasSize(1);
assertThat(result.getContent().get(0)).isEqualTo(balance);
}
}
```
### 10.2 性能测试
```java
@Test
@RepeatedTest(100)
@Timeout(value = 5, unit = TimeUnit.SECONDS)
void performanceTest() {
// 性能测试实现
}
```
## 11. 最佳实践总结
### 11.1 设计原则
1. **单一职责**：每个Repository只负责一个实体类型
2. **接口隔离**：根据客户端需求设计专用查询方法
3. **命名清晰**：方法名应能直观表达查询意图
4. **性能优先**：合理使用索引和查询优化
### 11.2 代码规范
1. **注解完整**：正确使用`@Repository`、`@Query`、`@Param`
2. **参数校验**：对传入参数进行null和有效性检查
3. **异常处理**：捕获并处理数据库访问异常
4. **日志记录**：记录关键查询操作和性能指标
### 11.3 维护性
1. **版本兼容**：考虑数据库模式变更的影响
2. **向后兼容**：新增方法不影响现有功能
3. **文档完整**：复杂查询添加JavaDoc说明
4. **测试覆盖**：确保关键查询逻辑有测试覆盖
## 12. 常见问题和解决方案
### 12.1 N+1查询问题
**问题**：查询列表时触发N+1次关联查询
**解决**：使用`JOIN FETCH`或`@EntityGraph`
### 12.2 性能瓶颈
**问题**：复杂查询导致响应慢
**解决**：
1. 添加数据库索引
2. 优化查询语句
3. 使用分页限制结果集
4. 考虑使用缓存
### 12.3 事务死锁
**问题**：并发操作导致事务死锁
**解决**：
1. 合理设计事务边界
2. 调整事务隔离级别
3. 实现重试机制
## 13. 扩展建议
### 13.1 动态查询支持
考虑使用`Querydsl`或`Specification`支持动态查询构建。
### 13.2 读写分离
实现主从数据库分离，提升查询性能。
### 13.3 分布式缓存
结合Redis等分布式缓存，提升查询性能。
---
## 14. 实施检查清单
### 14.1 Repository实现后验证步骤
在每个Repository实现完成后，请按以下清单进行验证：
#### ✅ 基础架构检查
- [ ] Repository接口继承了 `MyRepository<T, ID>`
- [ ] 使用了 `@Repository` 注解
- [ ] 包路径符合规范：`com.ecep.contract.ds.{business}.repository`
- [ ] 类名符合命名规范：`{EntityName}Repository`
#### ✅ 方法设计检查
- [ ] 遵循Spring Data JPA命名约定
- [ ] 包含必要的业务查询方法
- [ ] 复杂查询使用 `@Query` 注解
- [ ] 分页方法支持 `Pageable` 参数
#### ✅ 文档和注释检查
- [ ] 类级别JavaDoc注释完整
- [ ] 关键方法有JavaDoc说明
- [ ] 参数和返回值有明确说明
#### ✅ 性能和质量检查
- [ ] 避免N+1查询问题
- [ ] 适当使用索引提示
- [ ] 包含必要的单元测试
- [ ] 异常处理考虑周全
### 14.2 常见错误检查
在提交代码前，特别检查是否犯了以下常见错误：
#### ❌ 继承层次错误
```java
// 错误示例 - 不要这样做
public interface SomeRepository extends JpaRepository<Entity, Integer>
public interface AnotherRepository extends CrudRepository<Entity, Integer>
// 正确做法 - 统一使用MyRepository
public interface SomeRepository extends MyRepository<Entity, Integer>
```
#### ❌ 方法命名不规范
```java
// 错误示例
List<Entity> getDataByCondition(String condition) // 使用get前缀而非find
// 正确做法
List<Entity> findByCondition(String condition) // 使用find前缀
```
#### ❌ 缺少必要文档
```java
// 错误示例 - 无注释
List<Entity> findByStatus(String status);
// 正确做法 - 完整注释
/**
* 根据状态查询实体列表
*
* @param status 状态值
* @return 符合状态的实体列表
*/
List<Entity> findByStatus(String status);
```
### 14.3 架构一致性验证
确保新实现的Repository与项目中其他Repository保持一致：
1. **继承模式统一**：所有Repository都必须继承MyRepository
2. **注解使用统一**：统一使用@Repository注解
3. **命名约定统一**：遵循Spring Data JPA命名规范
4. **文档风格统一**：保持JavaDoc注释风格一致
### 14.4 后续维护注意事项
- 新增查询方法时遵循现有命名规范
- 修改现有方法时保持向后兼容性
- 定期审查Repository方法的性能和合理性
- 及时更新相关文档和测试用例
---
*本文档基于ContractBalanceRepository实现经验总结，结合项目实际情况分析，其他Repository实现应参考此文档规范。特别注意避免文档中提到的常见错误。*

633
.trae/rules/server_service_rules.md
View File

@@ -1,260 +1,435 @@
# 服务器端 Service 类规则文档
# 服务器端Service设计规范
## 1. 概述
## 目录结构
本规则文档定义了 Contract-Manager 项目服务器端（server模块）Service 类的设计规范、实现标准和最佳实践。所有服务器端 Service 类必须严格遵循本规则，以确保代码的一致性、可维护性和性能。
每个业务域下的service目录结构示例：
```
ds/
├── company/service/
│ ├── CompanyService.java # 主业务服务
│ ├── CompanyContactService.java # 联系人服务
│ ├── CompanyFileService.java # 文件管理服务
│ ├── CompanyOldNameService.java # 曾用名服务
│ └── ...
├── contract/service/
│ ├── ContractService.java # 主业务服务
│ ├── ContractCatalogService.java # 分类目录服务
│ └── ...
├── customer/service/
│ ├── CustomerService.java # 主业务服务（继承CompanyBasicService）
│ └── ...
├── project/service/
│ ├── ProjectService.java # 主业务服务
│ ├── ProjectFileService.java # 文件管理服务
│ └── ...
└── vendor/service/
├── VendorService.java # 主业务服务（继承CompanyBasicService）
└── ...
```
## 2. 目录结构
## 核心基类和接口体系
Service 类按业务领域组织，位于 `server/src/main/java/com/ecep/contract/ds/{业务领域}/service/` 目录下。其中 `{业务领域}` 对应具体的业务模块，如 `customer`、`contract`、`company`、`project`、`other` 等。
### 主要基类
- **EntityService<M, Vo, ID>**: 通用实体服务基类，提供CRUD操作的标准实现
- **CompanyBasicService**: 专门处理公司相关业务的基础服务类，支持公司关联查询
**示例：**
- 客户分类服务：`server/src/main/java/com/ecep/contract/ds/customer/service/CustomerCatalogService.java`
- 员工服务：`server/src/main/java/com/ecep/contract/ds/other/service/EmployeeService.java`
### 核心接口
- **IEntityService<T>**: 实体基本操作接口
- **QueryService<Vo>**: 查询服务接口
- **VoableService<M, Vo>**: 实体与视图对象转换服务接口
## 3. 命名规范
## 注解使用规范
- **类名**：采用驼峰命名法，首字母大写，以 `Service` 结尾，表示这是一个服务类。
**示例**：`CustomerCatalogService`、`EmployeeService`
### 类级别注解
```java
@Lazy // 延迟加载，避免循环依赖
@Service // Spring服务组件
@CacheConfig(cacheNames = "业务缓存名称") // 缓存配置
public class CompanyService extends EntityService<Company, CompanyVo, Integer>
implements IEntityService<Company>, QueryService<CompanyVo>, VoableService<Company, CompanyVo> {
// 实现代码
}
```
## 4. 接口实现
### 方法级别注解
```java
// 查询方法缓存 - 使用参数作为缓存键
@Cacheable(key = "#p0") // ID查询
public CompanyVo findById(Integer id) {
return repository.findById(id).map(Company::toVo).orElse(null);
}
所有业务领域的 Service 类必须实现以下三个核心接口：
@Cacheable(key = "'name-'+#p0") // 名称查询，带前缀
public CompanyVo findByName(String name) {
return repository.findFirstByName(name).map(Company::toVo).orElse(null);
}
### 4.1 IEntityService<T>
// 修改方法缓存清理 - 清理所有相关缓存
@Caching(evict = {
@CacheEvict(key = "#p0.id"),
@CacheEvict(key = "'name-'+#p0.name"),
@CacheEvict(key = "'code-'+#p0.code")
})
public Contract save(Contract contract) {
return contractRepository.save(contract);
}
```
提供实体类的基本 CRUD 操作。泛型 `T` 表示实体类类型。
## 依赖注入规范
**主要方法：**
- `T getById(Integer id)`：根据 ID 查询实体对象
- `Page<T> findAll(Specification<T> spec, Pageable pageable)`：根据条件和分页参数查询实体列表
- `Specification<T> getSpecification(String searchText)`：构建搜索条件
- `void delete(T entity)`：删除实体
- `T save(T entity)`：保存实体
### Repository注入
```java
@Lazy
@Autowired
private CompanyRepository repository;
```
### 4.2 QueryService<Vo>
### Service间依赖注入
```java
@Lazy
@Autowired
private ContractService contractService;
提供 VO 对象的查询能力。泛型 `Vo` 表示视图对象类型。
@Lazy
@Autowired
private VendorService vendorService;
**主要方法：**
- `Vo findById(Integer id)`：根据 ID 查询 VO 对象
- `Page<Vo> findAll(JsonNode paramsNode, Pageable pageable)`：根据 JSON 查询参数和分页条件查询 VO 列表
- `default long count(JsonNode paramsNode)`：根据查询参数统计数据总数
@Lazy
@Autowired
private CompanyContactService companyContactService;
```
### 4.3 VoableService<M, Vo>
### 外部服务依赖注入
```java
@Lazy
@Autowired
private CloudRkService cloudRkService;
提供从 VO 对象更新实体对象的能力。泛型 `M` 表示实体类类型，`Vo` 表示视图对象类型。
@Lazy
@Autowired
private CloudTycService cloudTycService;
**主要方法：**
- `void updateByVo(M model, Vo vo)`：根据 VO 对象更新实体对象
@Autowired(required = false) // 可选依赖
private YongYouU8Service yongYouU8Service;
```
**实现示例：**
## 查询实现模式
### 标准查询实现
```java
@Override
public Page<CompanyVo> findAll(JsonNode paramsNode, Pageable pageable) {
Specification<Company> spec = null;
// 搜索文本查询
if (paramsNode.has("searchText")) {
spec = getSpecification(paramsNode.get("searchText").asText());
}
// 字段等值查询
spec = SpecificationUtils.andFieldEqualParam(spec, paramsNode, "name", "uniscid", "abbName");
// 分页查询并转换为VO
return findAll(spec, pageable).map(Company::toVo);
}
```
### 复杂查询条件构建
```java
@Override
public Specification<Company> getSpecification(String searchText) {
if (!StringUtils.hasText(searchText)) {
return null;
}
return (root, query, builder) -> {
return builder.or(
builder.like(root.get("name"), "%" + searchText + "%"),
builder.like(root.get("code"), "%" + searchText + "%"),
builder.like(root.get("description"), "%" + searchText + "%"));
};
}
```
### CompanyBasicService继承模式
继承CompanyBasicService的Service（如CustomerService、VendorService）提供公司关联查询：
```java
@Override
public Specification<Vendor> getSpecification(String searchText) {
if (!StringUtils.hasText(searchText)) {
return null;
}
// 使用公司关联查询
Specification<Vendor> nameSpec = (root, query, builder) -> {
Path<Company> company = root.get("company");
return companyService.buildSearchPredicate(searchText, company, query, builder);
};
// 数字ID查询
if (MyStringUtils.isAllDigit(searchText)) {
try {
int id = Integer.parseInt(searchText);
nameSpec = SpecificationUtils.or(nameSpec, (root, query, builder) -> {
return builder.equal(root.get("id"), id);
});
} catch (Exception ignored) {
}
}
// 实体搜索
List<VendorEntity> searched = vendorEntityService.search(searchText);
if (!searched.isEmpty()) {
nameSpec = SpecificationUtils.or(nameSpec, (root, query, builder) -> {
return builder.in(root.get("id")).value(searched.stream()
.map(VendorEntity::getVendor)
.filter(Objects::nonNull)
.map(Vendor::getId)
.collect(Collectors.toSet()));
});
}
return nameSpec;
}
```
## 业务逻辑实现模式
### 1. 主业务Service（继承EntityService）
```java
@Lazy
@Service
@CacheConfig(cacheNames = "customer-catalog")
public class CustomerCatalogService implements IEntityService<CustomerCatalog>, QueryService<CustomerCatalogVo>,
VoableService<CustomerCatalog, CustomerCatalogVo> {
// 实现方法...
@CacheConfig(cacheNames = "contract")
public class ContractService extends EntityService<Contract, ContractVo, Integer>
implements IEntityService<Contract>, QueryService<ContractVo>, VoableService<Contract, ContractVo> {
@Override
protected ContractRepository getRepository() {
return contractRepository;
}
@Cacheable(key = "#p0")
public ContractVo findById(Integer id) {
return getRepository().findById(id).map(Contract::toVo).orElse(null);
}
// 业务特定方法
public List<Contract> findAllByCompany(Company company) {
return contractRepository.findAllByCompanyId(company.getId());
}
public File getContractCatalogPath(ContractCatalogVo catalog, ContractVo contract) {
// 文件路径处理逻辑
String parent = catalog.getParent();
File dir = getBasePath();
// ... 路径构建逻辑
return dir;
}
}
```
## 5. 注解规范
Service 类必须使用以下注解：
### 5.1 类级别注解
- `@Service`：标记这是一个 Spring 服务类，使其能够被自动扫描和管理
- `@Lazy`：延迟加载服务类，提高应用启动性能
- `@CacheConfig(cacheNames = "缓存名称")`：配置缓存名称，缓存名称通常与业务领域相关
**示例**：`@CacheConfig(cacheNames = "customer-catalog")`、`@CacheConfig(cacheNames = "employee")`
### 5.2 方法级别注解
#### 5.2.1 查询方法注解
- `@Cacheable(key = "缓存键")`：将查询结果缓存起来，下次相同查询可以直接从缓存获取
**示例**：`@Cacheable(key = "#p0")`（使用方法第一个参数作为缓存键）、`@Cacheable(key = "'code-'+#p0")`（使用前缀+参数值作为缓存键）
#### 5.2.2 数据修改方法注解
- `@Caching(evict = { ... })`：在保存或删除操作时清除相关缓存
**示例**：
```java
@Caching(evict = {
@CacheEvict(key = "#p0.id"),
@CacheEvict(key = "'code-'+#p0.code"),
@CacheEvict(key = "'name-'+#p0.name"),
@CacheEvict(key = "'all'")
})
```
- `@Transactional`：标记方法需要在事务中执行，确保数据一致性
**示例**：用于包含多个数据操作的复杂业务方法
## 6. 缓存策略
Service 类必须遵循以下缓存策略：
### 6.1 查询缓存
- 所有 `findById`、`findByCode`、`findByName` 等单条查询方法都应使用 `@Cacheable` 注解缓存结果
- 缓存键设计应具有唯一性和可读性，通常包含参数值和适当的前缀
- 列表查询（如 `findAll`）可以考虑使用 `@Cacheable`，但需谨慎管理缓存失效
### 6.2 缓存清理
- 所有 `save`、`delete` 等修改数据的方法都应使用 `@Caching` 和 `@CacheEvict` 注解清理相关缓存
- 清理缓存时应考虑所有可能影响的查询，确保缓存数据的一致性
## 7. 方法实现规范
### 7.1 IEntityService 方法实现
- `getById`：直接调用 Repository 的 `findById` 方法，返回实体对象
```java
@Override
public CustomerCatalog getById(Integer id) {
return repository.findById(id).orElse(null);
}
```
- `findAll(Specification<T>, Pageable)`：直接调用 Repository 的 `findAll` 方法，返回实体分页对象
```java
@Override
public Page<CustomerCatalog> findAll(Specification<CustomerCatalog> spec, Pageable pageable) {
return repository.findAll(spec, pageable);
}
```
- `save/delete`：调用 Repository 的相应方法，并添加缓存清理注解
```java
@Caching(evict = { ... })
@Override
public CustomerCatalog save(CustomerCatalog catalog) {
return repository.save(catalog);
}
```
### 7.2 QueryService 方法实现
- `findById`：调用 Repository 的 `findById` 方法，然后调用实体类的 `toVo` 方法转换为 VO 对象
```java
@Cacheable(key = "#p0")
@Override
public CustomerCatalogVo findById(Integer id) {
return repository.findById(id).map(CustomerCatalog::toVo).orElse(null);
}
```
- `findAll(JsonNode, Pageable)`：构建 Specification，调用 IEntityService 的 `findAll` 方法，然后使用 Stream API 的 `map` 方法将结果转换为 VO 对象
```java
@Override
public Page<CustomerCatalogVo> findAll(JsonNode paramsNode, Pageable pageable) {
Specification<CustomerCatalog> spec = null;
if (paramsNode.has(ServiceConstant.KEY_SEARCH_TEXT)) {
spec = getSpecification(paramsNode.get(ServiceConstant.KEY_SEARCH_TEXT).asText());
}
// 字段等值查询
spec = SpecificationUtils.andFieldEqualParam(spec, paramsNode, "code", "name", "description");
return repository.findAll(spec, pageable).map(CustomerCatalog::toVo);
}
```
### 7.3 VoableService 方法实现
- `updateByVo`：将 VO 对象的属性逐个复制到实体对象，实现 VO 到实体的转换
```java
@Override
public void updateByVo(CustomerCatalog model, CustomerCatalogVo vo) {
// 参数校验
if (model == null) {
throw new ServiceException("实体对象不能为空");
}
if (vo == null) {
throw new ServiceException("VO对象不能为空");
}
// 映射基本属性
model.setCode(vo.getCode());
model.setName(vo.getName());
model.setDescription(vo.getDescription());
}
```
## 8. 依赖注入规范
- Service 类应使用 `@Autowired` 注解注入所需的 Repository 和其他依赖
- 为了避免循环依赖，所有注入的依赖都应使用 `@Lazy` 注解标记为延迟加载
```java
@Lazy
@Autowired
private CustomerCatalogRepository repository;
```
## 9. 查询条件构建
- 使用 `SpecificationUtils` 工具类辅助构建查询条件
- 实现 `getSpecification(String searchText)` 方法，提供基于搜索文本的模糊查询能力
```java
@Override
public Specification<CustomerCatalog> getSpecification(String searchText) {
if (!StringUtils.hasText(searchText)) {
return null;
}
String likeText = "%" + searchText + "%";
return (root, query, builder) -> {
return builder.or(
builder.like(root.get("code"), likeText),
builder.like(root.get("name"), likeText),
builder.like(root.get("description"), likeText));
};
}
```
## 10. 异常处理
- Service 类应适当处理异常，特别是对输入参数的校验
- 对于业务逻辑异常，应抛出 `ServiceException`
```java
if (model == null) {
throw new ServiceException("实体对象不能为空");
}
```
## 11. 最佳实践
1. **VO优先原则**：QueryService 接口应使用 VO 类型作为泛型参数，返回 VO 对象而不是实体对象
2. **缓存粒度**：缓存键应设计得足够细粒度，避免缓存过大或频繁失效
3. **事务管理**：包含多个数据操作的方法应使用 `@Transactional` 注解确保事务一致性
4. **延迟加载**：所有依赖都应使用 `@Lazy` 注解，避免循环依赖问题
5. **参数校验**：方法开始时应进行参数校验，确保输入数据的合法性
6. **文档注释**：关键方法应有清晰的 JavaDoc 注释，说明其功能、参数和返回值
7. **代码复用**：尽量使用 SpecificationUtils 等工具类辅助构建查询条件，提高代码复用性
## 12. 不符合规范的Service类示例
以下是不符合规范的Service类实现，应避免：
### 2. 继承CompanyBasicService的Service
```java
// 错误：QueryService泛型参数使用实体类型而非VO类型
@Lazy
@Service
@CacheConfig(cacheNames = "company")
public class CompanyService extends EntityService<Company, Integer>
implements IEntityService<Company>, QueryService<Company>, VoableService<Company, CompanyVo> {
// 实现方法...
}
// 错误：未使用缓存注解
@Service
public class ExampleService implements IEntityService<Example>, QueryService<ExampleVo>,
VoableService<Example, ExampleVo> {
// 未使用@Cacheable、@CacheEvict等缓存注解
@CacheConfig(cacheNames = "company-customer")
public class CustomerService extends CompanyBasicService
implements IEntityService<CompanyCustomer>, QueryService<CustomerVo>,
VoableService<CompanyCustomer, CustomerVo> {
// 提供公司关联查询
public CompanyCustomer findByCompany(Company company) {
return repository.findByCompany(company).orElse(null);
}
public CustomerVo findByCompany(CompanyVo company) {
return repository.findByCompanyId(company.getId()).map(CompanyCustomer::toVo).orElse(null);
}
// 文件重建业务逻辑
public boolean reBuildingFiles(CompanyCustomer companyCustomer, MessageHolder holder) {
List<CompanyCustomerFile> dbFiles = companyCustomerFileService.findAllByCustomer(companyCustomer);
Map<String, CompanyCustomerFile> map = new HashMap<>();
boolean modified = fetchDbFiles(dbFiles, map, holder::info);
List<File> needMoveToCompanyPath = new ArrayList<>();
fetchFiles(companyCustomer.getPath(), needMoveToCompanyPath, retrieveFiles, map, holder::info);
moveFileToCompany(companyCustomer.getCompany(), needMoveToCompanyPath);
holder.info("导入 " + retrieveFiles.size() + " 个文件");
if (!retrieveFiles.isEmpty()) {
retrieveFiles.forEach(v -> v.setCustomer(companyCustomer));
companyCustomerFileService.saveAll(retrieveFiles);
modified = true;
}
return modified;
}
}
```
## 13. 总结
## 文件管理Service实现模式
本规则文档定义了服务器端 Service 类的完整规范，包括目录结构、命名规范、接口实现、注解规范、缓存策略、方法实现、依赖注入等方面。所有服务器端开发人员都必须严格遵循这些规则，以确保代码的一致性、可维护性和性能。
### 文件路径管理
```java
public File getBasePath() {
return new File(confService.getString(ContractConstant.KEY_BASE_PATH));
}
public File getContractCatalogPath(ContractCatalogVo catalog, ContractVo contract) {
String parent = catalog.getParent();
File dir = getBasePath();
if (StringUtils.hasText(parent)) {
dir = new File(dir, parent);
if (!dir.exists() && !dir.mkdir()) {
System.out.println("unable make directory = " + dir.getAbsolutePath());
return null;
}
}
dir = new File(dir, catalog.getPath());
if (!dir.exists() && !dir.mkdir()) {
System.out.println("unable make directory = " + dir.getAbsolutePath());
return null;
}
if (catalog.isUseYear()) {
String code = contract.getCode();
String catalogCode = catalog.getCode();
int length = catalogCode.length();
String yearCode = code.substring(length, length + 2);
dir = new File(dir, "20" + yearCode);
if (!dir.exists() && !dir.mkdir()) {
System.out.println("unable make directory = " + dir.getAbsolutePath());
return null;
}
}
return dir;
}
```
## 缓存策略最佳实践
### 缓存键设计原则
- **ID查询**: `@Cacheable(key = "#p0")`
- **字符串查询**: `@Cacheable(key = "'name-'+#p0")`
- **复合键查询**: `@Cacheable(key = "'code-year-'+#p0+'-'+#p1")`
### 缓存清理策略
```java
@Caching(evict = {
@CacheEvict(key = "#p0.id"), // 主键缓存
@CacheEvict(key = "'name-'+#p0.name"), // 名称缓存
@CacheEvict(key = "'code-'+#p0.code"), // 编码缓存
@CacheEvict(key = "'guid-'+#p0.guid") // GUID缓存
})
public Contract save(Contract contract) {
return contractRepository.save(contract);
}
```
## 性能优化建议
### 1. 延迟加载
所有Service依赖都应使用@Lazy注解，避免循环依赖和启动时的性能问题。
### 2. 缓存粒度
- 单条查询使用细粒度缓存键
- 避免缓存大量数据的列表查询
- 合理设置缓存过期策略
### 3. 分页查询
使用Page<T>进行分页查询，避免一次性加载大量数据：
```java
public Page<Project> findAll(Specification<Project> spec, Pageable pageable) {
return projectRepository.findAll(spec, pageable);
}
```
### 4. 批量操作
对于大量数据操作，考虑使用批量处理：
```java
public void saveAll(List<CompanyCustomerFile> files) {
companyCustomerFileService.saveAll(retrieveFiles);
}
```
## 异常处理规范
### 参数校验
```java
public void updateByVo(CustomerCatalog model, CustomerCatalogVo vo) {
if (model == null) {
throw new ServiceException("实体对象不能为空");
}
if (vo == null) {
throw new ServiceException("VO对象不能为空");
}
// ... 业务逻辑
}
```
### 业务异常处理
```java
public Company findAndRemoveDuplicateCompanyByUniscid(String uniscid) {
List<Company> companies = repository.findAllByUniscid(uniscid);
if (companies.isEmpty()) {
return null;
}
if (companies.size() == 1) {
return companies.getFirst();
} else {
List<Company> result = removeDuplicatesByUniscid(companies);
if (!result.isEmpty()) {
return result.getFirst();
}
}
return null;
}
```
## 工具类使用规范
### SpecificationUtils使用
```java
// 字段等值查询
spec = SpecificationUtils.andFieldEqualParam(spec, paramsNode, "name", "code", "status");
// 参数关联查询
spec = SpecificationUtils.andParam(spec, paramsNode, "company", "catalog", "type");
// 搜索文本组合
spec = SpecificationUtils.andWith(searchText, this::buildSearchSpecification);
```
### 字符串工具使用CompanyBasicService
```java
// 全数字判断
if (MyStringUtils.isAllDigit(searchText)) {
// 数字处理逻辑
}
// 空值检查
if (!StringUtils.hasText(searchText)) {
return null;
}
```
## 最佳实践总结
1. **接口实现完整性**: 所有Service应实现三个核心接口，确保功能一致性
2. **缓存策略一致性**: 遵循统一的缓存键设计和清理策略
3. **依赖注入规范**: 使用@Lazy避免循环依赖，清晰管理Service间依赖关系
4. **查询性能优化**: 合理使用SpecificationUtils构建查询条件，支持分页查询
5. **异常处理统一**: 统一的异常处理方式，提高代码健壮性
6. **代码复用**: 继承合适的基类，复用通用逻辑
7. **文档注释**: 关键方法和复杂业务逻辑应有清晰的JavaDoc注释
8. **性能监控**: 关注缓存命中率，适时调整缓存策略
这套规范确保了Service层的代码质量、性能和可维护性，为整个系统的稳定运行提供了坚实基础。

10
.trae/rules/server_task_rules.md
View File

@@ -118,7 +118,15 @@ WebSocketServerTaskManager类在启动时会读取`tasker_mapper.json`文件，
@Override
public void init(JsonNode argsNode) {
// 解析参数或初始化任务状态
// ContractRepairAllTasker 不需要参数，所以此方法为空实现
// 如果 Client 没有传递参数，就不做处理
// do nothing
// 如果有参数，正确做法：检查参数有效性并安全解析
if (argsNode != null && argsNode.size() > 0) {
ContractService contractService = getCachedBean(ContractService.class);
int contractId = argsNode.get(0).asInt();
this.contract = contractService.findById(contractId);
}
}
```