refactor: 将getSpecification重命名为getSearchSpecification以提高方法命名清晰度

server/src/main/java/com/ecep/contract/EntityService.java

@@ -41,56 +41,155 @@ public abstract class EntityService<T extends Voable<VO>, VO, ID> {
         return getRepository().findById(id).orElse(null);
     }
 
+    /**
+     * 创建新实体实例
+     * 设置默认值或必要的属性
+     * 实例是游离态的，未存储到数据库
+     * 
+     * @return 新实体实例
+     */
     public abstract T createNewEntity();
 
+    /**
+     * 统计所有实体数量
+     * 
+     * @return 实体数量
+     */
     public long count() {
         return getRepository().count();
     }
 
+    /**
+     * 根据查询规范统计实体数量
+     * 
+     * @param spec 查询规范
+     * @return 符合规范的实体数量
+     */
     public long count(Specification<T> spec) {
         return getRepository().count(spec);
     }
 
+    /**
+     * 根据JSON参数节点统计实体数量
+     * 
+     * @param paramsNode JSON参数节点
+     * @return 符合参数节点规范的实体数量
+     */
     public long count(JsonNode paramsNode) {
-        return getRepository().count(buildParameterSpecification(paramsNode));
+        return count(applyJsonParameter(paramsNode));
     }
 
+    /**
+     * 保存实体到数据库
+     * 
+     * @param entity 要保存的实体
+     * @return 保存后的实体
+     */
+    public T save(T entity) {
+        return getRepository().save(entity);
+    }
+
+    /**
+     * 删除实体
+     * 
+     * @param entity 要删除的实体
+     */
+    public void delete(T entity) {
+        getRepository().delete(entity);
+    }
+
+    @Deprecated
     protected abstract Specification<T> buildParameterSpecification(JsonNode paramsNode);
 
-    public Page<VO> findAll(JsonNode paramsNode, Pageable pageable) {
-        Specification<T> spec = SpecificationUtils.applySearchText(paramsNode, this::getSpecification);
-        JsonNode filterNode = paramsNode.get(ParamConstant.KEY_FILTER);
+    /**
+     * 应用JSON参数节点到查询规范
+     * 
+     * @param node JSON参数节点
+     * @return 应用参数节点后的查询规范
+     */
+    protected Specification<T> applyJsonParameter(JsonNode node) {
+        Specification<T> spec = SpecificationUtils.applySearchText(node, this::getSearchSpecification);
+        JsonNode filterNode = node.get(ParamConstant.KEY_FILTER);
         if (filterNode != null) {
             Specification<T> childSpec = buildFilterCondition(filterNode);
             if (childSpec != null) {
                 spec = SpecificationUtils.and(spec, childSpec);
             }
         }
-        return findAll(spec, pageable).map(T::toVo);
+        return spec;
     }
 
+    /**
+     * 根据JSON参数节点查询所有实体
+     * 
+     * @param paramsNode JSON参数节点
+     * @param pageable   分页信息
+     * @return 符合参数节点规范的实体分页结果
+     */
+    public Page<VO> findAll(JsonNode paramsNode, Pageable pageable) {
+        return findAll(applyJsonParameter(paramsNode), pageable).map(T::toVo);
+    }
+
+    /**
+     * 根据查询规范查询所有实体
+     * 
+     * @param spec     查询规范
+     * @param pageable 分页信息
+     * @return 符合规范的实体分页结果
+     */
     public Page<T> findAll(Specification<T> spec, Pageable pageable) {
         return getRepository().findAll(spec, pageable);
     }
 
+    /**
+     * 根据查询规范查询所有实体
+     * 
+     * @param spec 查询规范
+     * @param sort 排序信息
+     * @return 符合规范的实体列表
+     */
     public List<T> findAll(Specification<T> spec, Sort sort) {
         return getRepository().findAll(spec, sort);
     }
 
-    protected abstract Specification<T> buildSearchSpecification(String searchText);
+    /**
+     * 根据搜索文本查询所有实体
+     * 
+     * @param searchText 搜索文本
+     * @return 符合搜索文本规范的实体列表
+     */
+    public List<T> search(String searchText) {
+        Specification<T> spec = getSearchSpecification(searchText);
+        return getRepository().findAll(spec, Pageable.ofSize(10)).getContent();
+    }
 
-    public Specification<T> getSpecification(String searchText) {
+    /**
+     * 根据搜索文本构建查询规范
+     * 
+     * @param searchText 搜索文本
+     * @return 符合搜索文本规范的查询规范
+     */
+    public Specification<T> getSearchSpecification(String searchText) {
         if (!StringUtils.hasText(searchText)) {
             return null;
         }
         return SpecificationUtils.andWith(searchText, this::buildSearchSpecification);
     }
 
-    public List<T> search(String searchText) {
-        Specification<T> spec = getSpecification(searchText);
-        return getRepository().findAll(spec, Pageable.ofSize(10)).getContent();
-    }
+    /**
+     * 构建搜索规范
+     * 
+     * @param searchText 搜索文本,非空
+     * @return 符合搜索文本规范的查询规范
+     */
+    protected abstract Specification<T> buildSearchSpecification(String searchText);
 
+    /**
+     * 构建过滤条件规范
+     * 
+     * @param filterNode 过滤条件节点
+     * @return 过滤条件规范
+     */
     private Specification<T> buildFilterCondition(JsonNode filterNode) {
         String operatorStr = filterNode.get(ParamConstant.KEY_OPERATOR).asText();