Merge branch 'feature/luojunhui/20260527-material-match' of Server/video-vector-server into master

core/src/main/java/com/tzld/videoVector/dao/mapper/pgVector/ext/MaterialVectorMapperExt.java

@@ -49,4 +49,11 @@ public interface MaterialVectorMapperExt {
     int deleteAbovePointIndex(@Param("materialId") String materialId,
                               @Param("configCode") String configCode,
                               @Param("minPointIndex") int minPointIndex);
+
+    /** 查询指定素材已向量化的所有 configCode */
+    List<String> selectDistinctConfigCodesByMaterialId(@Param("materialId") String materialId);
+
+    /** 查询指定素材在指定 configCode 下的所有向量（按 pointIndex 升序） */
+    List<MaterialVector> selectVectorsByMaterialIdAndConfigCode(@Param("materialId") String materialId,
+                                                                @Param("configCode") String configCode);
 }

core/src/main/java/com/tzld/videoVector/model/param/recall/MatchByMaterialIdParam.java

@@ -0,0 +1,19 @@
+package com.tzld.videoVector.model.param.recall;
+
+import lombok.Data;
+
+/**
+ * 素材ID召回参数 (matchByMaterialId)
+ */
+@Data
+public class MatchByMaterialIdParam {
+
+    /** 素材 ID（必填） */
+    private String materialId;
+
+    /** 召回维度，不传则使用该素材已向量化的所有维度 */
+    private String configCode;
+
+    /** 返回 Top-N，默认 50 */
+    private Integer topN = 50;
+}

core/src/main/java/com/tzld/videoVector/model/vo/recall/MaterialBasicVO.java

@@ -0,0 +1,19 @@
+package com.tzld.videoVector.model.vo.recall;
+
+import lombok.Data;
+
+/**
+ * 素材基础信息 VO（materialDetail 接口用）
+ */
+@Data
+public class MaterialBasicVO {
+
+    /** 素材 ID */
+    private String materialId;
+
+    /** 素材图片 CDN 地址 */
+    private String imageUrl;
+
+    /** 素材标题 */
+    private String title;
+}

core/src/main/java/com/tzld/videoVector/service/MaterialVectorStoreService.java

@@ -1,6 +1,7 @@
 package com.tzld.videoVector.service;
 
 import com.tzld.videoVector.model.entity.MaterialMatch;
+import com.tzld.videoVector.model.po.pgVector.MaterialVector;
 
 import java.util.Collection;
 import java.util.List;
@@ -58,4 +59,10 @@ public interface MaterialVectorStoreService {
     List<MaterialMatch> searchTopNByRawVector(String configCode, String rawVector, int topN);
 
     List<MaterialMatch> searchTopNBySource(String configCode, List<Float> queryVector, int topN, Short sourceType);
+
+    /** 查询指定素材已向量化的所有 configCode */
+    List<String> getDistinctConfigCodes(String materialId);
+
+    /** 查询指定素材在指定 configCode 下的所有向量行（raw embedding），用于获取素材自身向量进行跨模态召回 */
+    List<MaterialVector> getVectorsByMaterialId(String materialId, String configCode);
 }

core/src/main/java/com/tzld/videoVector/service/VectorStoreService.java

@@ -178,4 +178,9 @@ public interface VectorStoreService {
      */
     List<VideoMatch> searchTopN(String configCode, List<Float> queryVector, int topN);
 
+    /**
+     * 用原始 embedding 字符串搜索（绕过 Java Float 回环精度损失）
+     */
+    List<VideoMatch> searchTopNByRawVector(String configCode, String rawVector, int topN);
+
 }

core/src/main/java/com/tzld/videoVector/service/impl/PgMaterialVectorStoreServiceImpl.java

@@ -252,6 +252,24 @@ public class PgMaterialVectorStoreServiceImpl implements MaterialVectorStoreServ
         return convertToMatch(results, configCode);
     }
 
+    @Override
+    public List<String> getDistinctConfigCodes(String materialId) {
+        if (!StringUtils.hasText(materialId)) {
+            return Collections.emptyList();
+        }
+        List<String> codes = materialVectorMapperExt.selectDistinctConfigCodesByMaterialId(materialId);
+        return codes != null ? codes : Collections.emptyList();
+    }
+
+    @Override
+    public List<MaterialVector> getVectorsByMaterialId(String materialId, String configCode) {
+        if (!StringUtils.hasText(materialId) || !StringUtils.hasText(configCode)) {
+            return Collections.emptyList();
+        }
+        List<MaterialVector> vectors = materialVectorMapperExt.selectVectorsByMaterialIdAndConfigCode(materialId, configCode);
+        return vectors != null ? vectors : Collections.emptyList();
+    }
+
     private List<MaterialMatch> convertToMatch(List<MaterialVector> results, String configCode) {
         return results.stream()
                 .map(mv -> {

core/src/main/java/com/tzld/videoVector/service/impl/PgVectorStoreServiceImpl.java

@@ -264,7 +264,29 @@ public class PgVectorStoreServiceImpl implements VectorStoreService {
             return Collections.emptyList();
         }
 
-        List<VideoMatch> matches = results.stream()
+        return convertSearchResults(results);
+    }
+
+    @Override
+    public List<VideoMatch> searchTopNByRawVector(String configCode, String rawVector, int topN) {
+        if (rawVector == null || rawVector.isEmpty() || topN <= 0) {
+            return Collections.emptyList();
+        }
+        if (configCode == null || configCode.isEmpty()) {
+            configCode = DEFAULT_CONFIG_CODE;
+        }
+        log.info("searchTopNByRawVector raw前100字符: {}, topN={}, configCode={}",
+                rawVector.substring(0, Math.min(100, rawVector.length())), topN, configCode);
+        List<VideoVectorSearchResult> results = videoVectorMapperExt.searchTopNByCosine(configCode, rawVector, topN);
+        if (results == null || results.isEmpty()) {
+            log.info("searchTopNByRawVector 无匹配结果，configCode={}", configCode);
+            return Collections.emptyList();
+        }
+        return convertSearchResults(results);
+    }
+
+    private List<VideoMatch> convertSearchResults(List<VideoVectorSearchResult> results) {
+        return results.stream()
                 .map(vv -> {
                     VideoMatch m = new VideoMatch(vv.getVideoId(), vv.getScore() != null ? vv.getScore() : 0.0);
                     m.setPointIndex(vv.getPointIndex());
@@ -272,9 +294,6 @@ public class PgVectorStoreServiceImpl implements VectorStoreService {
                     return m;
                 })
                 .collect(Collectors.toList());
-
-//        log.info("pgvector搜索完成，configCode={}，返回 {} 条结果", configCode, matches.size());
-        return matches;
     }
 
     // ---------------------------------------------------------------- 工具方法

core/src/main/java/com/tzld/videoVector/service/impl/RedisVectorStoreServiceImpl.java

@@ -9,6 +9,7 @@ import com.tzld.videoVector.model.entity.VideoMatch;
 import com.tzld.videoVector.model.po.pgVector.DeconstructVectorConfig;
 import com.tzld.videoVector.model.po.pgVector.DeconstructVectorConfigExample;
 import com.tzld.videoVector.service.VectorStoreService;
+import com.tzld.videoVector.util.VectorUtils;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.redis.core.RedisCallback;
@@ -367,6 +368,18 @@ public class RedisVectorStoreServiceImpl implements VectorStoreService {
         return topMatches;
     }
 
+    @Override
+    public List<VideoMatch> searchTopNByRawVector(String configCode, String rawVector, int topN) {
+        if (rawVector == null || rawVector.isEmpty() || topN <= 0) {
+            return Collections.emptyList();
+        }
+        List<Float> queryVector = VectorUtils.parseVectorString(rawVector);
+        if (queryVector == null || queryVector.isEmpty()) {
+            return Collections.emptyList();
+        }
+        return searchTopN(configCode, queryVector, topN);
+    }
+
     /**
      * 并行搜索 TopN（使用堆排序优化）
      */

core/src/main/java/com/tzld/videoVector/service/recall/VectorRecallTestService.java

@@ -1,9 +1,11 @@
 package com.tzld.videoVector.service.recall;
 
+import com.tzld.videoVector.model.param.recall.MatchByMaterialIdParam;
 import com.tzld.videoVector.model.param.recall.MatchByTextParam;
 import com.tzld.videoVector.model.param.recall.MatchByVideoIdParam;
 import com.tzld.videoVector.model.vo.recall.AIUnderstandingVO;
 import com.tzld.videoVector.model.vo.recall.DeconstructPointsVO;
+import com.tzld.videoVector.model.vo.recall.MaterialBasicVO;
 import com.tzld.videoVector.model.vo.recall.RecallResultVO;
 import com.tzld.videoVector.model.vo.recall.VideoBasicVO;
 
@@ -58,4 +60,20 @@ public interface VectorRecallTestService {
      * @return AI理解结果,无数据返回 null (严禁mock)
      */
     AIUnderstandingVO getAiUnderstanding(Long videoId);
+
+    /**
+     * 素材ID召回 — 用素材自身的向量做跨模态相似搜索
+     *
+     * @param param 素材ID召回参数
+     * @return 召回结果（视频 + 素材 + 文章混合）
+     */
+    RecallResultVO matchByMaterialId(MatchByMaterialIdParam param);
+
+    /**
+     * 素材详情预览 — 返回素材图片URL和标题
+     *
+     * @param materialId 素材ID
+     * @return 素材基础信息，不存在返回 null
+     */
+    MaterialBasicVO getMaterialDetail(String materialId);
 }

core/src/main/java/com/tzld/videoVector/service/recall/impl/VectorRecallTestServiceImpl.java

@@ -12,7 +12,9 @@ import com.tzld.videoVector.dao.mapper.pgVector.ext.MaterialDeconstructResultMap
 import com.tzld.videoVector.model.entity.ArticleMatch;
 import com.tzld.videoVector.model.entity.MaterialMatch;
 import com.tzld.videoVector.model.entity.VideoDetail;
+import com.tzld.videoVector.model.entity.VideoMatch;
 import com.tzld.videoVector.model.param.MatchTopNVideoParam;
+import com.tzld.videoVector.model.param.recall.MatchByMaterialIdParam;
 import com.tzld.videoVector.model.param.recall.MatchByTextParam;
 import com.tzld.videoVector.model.param.recall.MatchByVideoIdParam;
 import com.tzld.videoVector.model.po.pgVector.ArticleDeconstructResult;
@@ -23,6 +25,7 @@ import com.tzld.videoVector.model.vo.VideoMatchResult;
 import com.tzld.videoVector.model.vo.recall.AIUnderstandingVO;
 import com.tzld.videoVector.model.vo.recall.DeconstructPointsVO;
 import com.tzld.videoVector.model.vo.recall.ArticleDetailVO;
+import com.tzld.videoVector.model.vo.recall.MaterialBasicVO;
 import com.tzld.videoVector.model.vo.recall.MaterialDetailVO;
 import com.tzld.videoVector.model.vo.recall.RecallResultVO;
 import com.tzld.videoVector.model.vo.recall.VideoBasicVO;
@@ -30,11 +33,16 @@ import com.tzld.videoVector.model.vo.recall.VideoMatchEnrichedVO;
 import com.tzld.videoVector.service.ArticleVectorStoreService;
 import com.tzld.videoVector.service.EmbeddingService;
 import com.tzld.videoVector.service.MaterialVectorStoreService;
+import com.tzld.videoVector.service.VectorStoreService;
 import com.tzld.videoVector.service.VideoSearchService;
 import com.tzld.videoVector.service.recall.VectorRecallTestService;
 import com.tzld.videoVector.util.Md5Util;
+import com.tzld.videoVector.util.RedisUtils;
+import com.tzld.videoVector.util.VectorUtils;
+import com.tzld.videoVector.model.po.pgVector.MaterialVector;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.stereotype.Service;
 import org.springframework.util.CollectionUtils;
@@ -93,6 +101,15 @@ public class VectorRecallTestServiceImpl implements VectorRecallTestService {
     @Autowired
     private EmbeddingService embeddingService;
 
+    @Autowired
+    private VectorStoreService vectorStoreService;
+
+    @Autowired
+    private RedisUtils redisUtils;
+
+    @Value("${video.detail.metrics.days:7}")
+    private int metricsDays;
+
     private static final String SOURCE_AIGC = "aigc_deconstruct";
 
     /** source_type → 中文来源标签 */
@@ -466,18 +483,8 @@ public class VectorRecallTestServiceImpl implements VectorRecallTestService {
             }
 
             MaterialDetailVO detail = new MaterialDetailVO();
-            if (basic != null) {
-                detail.setTitle(basic.title);
-            }
-            if (vo.getImageList() != null) {
-                detail.setImageCount(vo.getImageList().size());
-            }
-            Short sourceType = m.getSourceType();
-            if (sourceType == null && row != null) {
-                sourceType = row.getSourceType();
-            }
-            detail.setSource(mapSourceTypeToLabel(sourceType));
-            detail.setDeconstruct(deconstructFlat);
+            fillMaterialDetailVO(detail, basic, row, deconstructFlat, m.getSourceType());
+            fillMaterialDetailImageCount(detail, vo.getImageList());
             vo.setMaterialDetail(detail);
 
             applyCompatibilityFields(vo);
@@ -829,12 +836,82 @@ public class VectorRecallTestServiceImpl implements VectorRecallTestService {
         if (images != null && !images.isEmpty()) {
             meta.imagesJson = images.toJSONString();
         }
+        meta.uploadTime = firstNonBlankString(
+                nestedString(raw, "target_post", "uploadTime"),
+                nestedString(raw, "target_post", "createTime"),
+                raw.getString("uploadTime"),
+                raw.getString("createTime"),
+                raw.getString("采集时间")
+        );
+        meta.usageCount = firstNonBlankString(
+                nestedString(raw, "target_post", "usageCount"),
+                raw.getString("usageCount"),
+                raw.getString("使用次数")
+        );
+        meta.tags = extractStringList(raw, "target_post", "tags");
+        if (meta.tags == null) {
+            meta.tags = extractStringList(raw, null, "tags");
+        }
+        if (meta.tags == null) {
+            String tagsStr = firstNonBlankString(raw.getString("标签"), nestedString(raw, "target_post", "label"));
+            if (StringUtils.hasText(tagsStr)) {
+                meta.tags = java.util.Arrays.stream(tagsStr.split("[,，]"))
+                        .map(String::trim)
+                        .filter(StringUtils::hasText)
+                        .collect(Collectors.toList());
+            }
+        }
         if (!StringUtils.hasText(meta.title) && !StringUtils.hasText(meta.imagesJson)) {
             return null;
         }
         return meta;
     }
 
+    private List<String> extractStringList(JSONObject raw, String objKey, String fieldKey) {
+        JSONArray arr = objKey != null ? nestedArray(raw, objKey, fieldKey) : raw.getJSONArray(fieldKey);
+        if (arr == null || arr.isEmpty()) {
+            return null;
+        }
+        List<String> list = new ArrayList<>(arr.size());
+        for (int i = 0; i < arr.size(); i++) {
+            Object item = arr.get(i);
+            if (item == null) {
+                continue;
+            }
+            String s = String.valueOf(item).trim();
+            if (StringUtils.hasText(s)) {
+                list.add(s);
+            }
+        }
+        return list.isEmpty() ? null : list;
+    }
+
+    private void fillMaterialDetailVO(MaterialDetailVO detail, MaterialBasicMeta basic,
+                                      MaterialDeconstructResult row, Map<String, Object> deconstructFlat,
+                                      Short sourceTypeOverride) {
+        if (detail == null) {
+            return;
+        }
+        if (basic != null) {
+            detail.setTitle(basic.title);
+            detail.setUploadTime(basic.uploadTime);
+            detail.setUsageCount(basic.usageCount);
+            detail.setTags(basic.tags);
+        }
+        Short sourceType = sourceTypeOverride;
+        if (sourceType == null && row != null) {
+            sourceType = row.getSourceType();
+        }
+        detail.setSource(mapSourceTypeToLabel(sourceType));
+        detail.setDeconstruct(deconstructFlat);
+    }
+
+    private void fillMaterialDetailImageCount(MaterialDetailVO detail, List<String> imageList) {
+        if (detail != null && imageList != null) {
+            detail.setImageCount(imageList.size());
+        }
+    }
+
     /**
      * cover 取自 imagesJson  JSON 数组的第一张图
      */
@@ -1021,6 +1098,349 @@ public class VectorRecallTestServiceImpl implements VectorRecallTestService {
         return buildResult(videoItems, Collections.emptyList(), Collections.emptyList());
     }
 
+    // ====================================================================
+    // matchByMaterialId — 素材ID跨模态召回
+    // ====================================================================
+
+    @Override
+    public RecallResultVO matchByMaterialId(MatchByMaterialIdParam param) {
+        RecallResultVO empty = emptyResult();
+        if (param == null || !StringUtils.hasText(param.getMaterialId())) {
+            log.info("matchByMaterialId: materialId 为空");
+            return empty;
+        }
+
+        String materialId = param.getMaterialId().trim();
+        int topN = param.getTopN() != null && param.getTopN() > 0 ? param.getTopN() : 50;
+
+        List<String> configCodes;
+        if (StringUtils.hasText(param.getConfigCode())) {
+            configCodes = Collections.singletonList(param.getConfigCode().trim());
+        } else {
+            configCodes = materialVectorStoreService.getDistinctConfigCodes(materialId);
+            if (configCodes.isEmpty()) {
+                log.info("matchByMaterialId: materialId={} 无向量数据", materialId);
+                return empty;
+            }
+        }
+        log.info("matchByMaterialId: materialId={}, topN={}, configCodes={}", materialId, topN, configCodes);
+
+        // 收集所有有效向量点（支持多点模式）
+        List<MaterialVectorQuery> vectorQueries = new ArrayList<>();
+        for (String configCode : configCodes) {
+            List<MaterialVector> vectors = materialVectorStoreService.getVectorsByMaterialId(materialId, configCode);
+            for (MaterialVector vector : vectors) {
+                if (vector != null && StringUtils.hasText(vector.getEmbedding())) {
+                    vectorQueries.add(new MaterialVectorQuery(configCode, vector.getEmbedding()));
+                }
+            }
+        }
+        if (vectorQueries.isEmpty()) {
+            log.info("matchByMaterialId: materialId={} 无有效向量 embedding", materialId);
+            return empty;
+        }
+
+        int candidateTopN = Math.max(topN * VectorConstants.MULTI_POINT_RECALL_CANDIDATE_FACTOR,
+                VectorConstants.MULTI_POINT_RECALL_MIN_CANDIDATES);
+
+        List<VideoMatchEnrichedVO> allResults = Collections.synchronizedList(new ArrayList<>());
+        List<CompletableFuture<Void>> allFutures = new ArrayList<>();
+
+        for (MaterialVectorQuery query : vectorQueries) {
+            final String cc = query.configCode;
+            final String rawEmbedding = query.rawEmbedding;
+            final int ctn = candidateTopN;
+            final int tn = topN;
+
+            allFutures.add(CompletableFuture.runAsync(() -> {
+                try {
+                    List<VideoMatch> matches = vectorStoreService.searchTopNByRawVector(cc, rawEmbedding, ctn);
+                    List<VideoMatch> deduped = deduplicateVideoMatches(matches, tn);
+                    log.info("matchByMaterialId 视频搜索 cc={}: {} 条, 去重后 {} 条",
+                            cc, matches != null ? matches.size() : 0, deduped.size());
+                    if (!deduped.isEmpty()) {
+                        List<VideoMatchResult> videoResults = toVideoMatchResults(deduped, cc);
+                        populateVideoMatchResultDetails(videoResults);
+                        allResults.addAll(enrichVideoMatches(videoResults, cc));
+                    }
+                } catch (Exception e) {
+                    log.error("matchByMaterialId 视频搜索失败 configCode={}: {}", cc, e.getMessage(), e);
+                }
+            }, RECALL_EXECUTOR));
+
+            allFutures.add(CompletableFuture.runAsync(() -> {
+                try {
+                    List<MaterialMatch> matches = materialVectorStoreService.searchTopNByRawVector(cc, rawEmbedding, ctn);
+                    matches = matches.stream()
+                            .filter(m -> !materialId.equals(m.getMaterialId()))
+                            .collect(Collectors.toList());
+                    List<MaterialMatch> deduped = deduplicateMaterialMatches(matches, tn);
+                    if (!deduped.isEmpty()) {
+                        allResults.addAll(enrichMaterialMatches(deduped, cc));
+                    }
+                } catch (Exception e) {
+                    log.error("matchByMaterialId 素材搜索失败 configCode={}: {}", cc, e.getMessage(), e);
+                }
+            }, RECALL_EXECUTOR));
+
+            allFutures.add(CompletableFuture.runAsync(() -> {
+                try {
+                    List<ArticleMatch> matches = articleVectorStoreService.searchTopNByRawVector(cc, rawEmbedding, ctn);
+                    List<ArticleMatch> deduped = deduplicateArticleMatches(matches, tn);
+                    if (!deduped.isEmpty()) {
+                        allResults.addAll(enrichArticleMatches(deduped, cc));
+                    }
+                } catch (Exception e) {
+                    log.error("matchByMaterialId 文章搜索失败 configCode={}: {}", cc, e.getMessage(), e);
+                }
+            }, RECALL_EXECUTOR));
+        }
+
+        for (CompletableFuture<Void> future : allFutures) {
+            try {
+                future.get(30, TimeUnit.SECONDS);
+            } catch (Exception e) {
+                log.error("matchByMaterialId 并行搜索等待异常: {}", e.getMessage(), e);
+            }
+        }
+
+        List<VideoMatchEnrichedVO> merged = deduplicateCrossConfigCode(allResults);
+
+        List<VideoMatchEnrichedVO> videoItems = merged.stream()
+                .filter(it -> it.getModality() == Modality.VIDEO)
+                .sorted(Comparator.comparing(VideoMatchEnrichedVO::getScore,
+                        Comparator.nullsLast(Comparator.reverseOrder())))
+                .limit(topN)
+                .collect(Collectors.toList());
+        List<VideoMatchEnrichedVO> materialItems = merged.stream()
+                .filter(it -> it.getModality() == Modality.MATERIAL)
+                .sorted(Comparator.comparing(VideoMatchEnrichedVO::getScore,
+                        Comparator.nullsLast(Comparator.reverseOrder())))
+                .limit(topN)
+                .collect(Collectors.toList());
+        List<VideoMatchEnrichedVO> articleItems = merged.stream()
+                .filter(it -> it.getModality() == Modality.ARTICLE)
+                .sorted(Comparator.comparing(VideoMatchEnrichedVO::getScore,
+                        Comparator.nullsLast(Comparator.reverseOrder())))
+                .limit(topN)
+                .collect(Collectors.toList());
+
+        log.info("matchByMaterialId 按模态截断后: video={}, material={}, article={}",
+                videoItems.size(), materialItems.size(), articleItems.size());
+
+        String selfConfigCode = StringUtils.hasText(param.getConfigCode())
+                ? param.getConfigCode().trim()
+                : vectorQueries.get(0).configCode;
+        ensureSelfMaterialInResults(materialItems, materialId, selfConfigCode, topN);
+
+        RecallResultVO result = buildResult(videoItems, materialItems, articleItems);
+        log.info("matchByMaterialId 完成: total={}, video={}, material={}, article={}",
+                result.getTotal(), result.getVideoCount(), result.getMaterialCount(), result.getArticleCount());
+        return result;
+    }
+
+    /**
+     * 视频向量搜索结果去重：同一 videoId 保留最高分
+     */
+    private List<VideoMatch> deduplicateVideoMatches(List<VideoMatch> matches, int topN) {
+        if (CollectionUtils.isEmpty(matches)) return Collections.emptyList();
+        Map<Long, VideoMatch> deduped = new LinkedHashMap<>();
+        for (VideoMatch m : matches) {
+            if (m == null || m.getVideoId() == null) continue;
+            VideoMatch existing = deduped.get(m.getVideoId());
+            if (existing == null || m.getScore() > existing.getScore()) {
+                deduped.put(m.getVideoId(), m);
+            }
+        }
+        return deduped.values().stream().limit(topN).collect(Collectors.toList());
+    }
+
+    /**
+     * 跨 configCode 去重：同一 (id, modality) 保留最高分
+     */
+    private List<VideoMatchEnrichedVO> deduplicateCrossConfigCode(List<VideoMatchEnrichedVO> items) {
+        if (CollectionUtils.isEmpty(items)) return Collections.emptyList();
+        Map<String, VideoMatchEnrichedVO> deduped = new LinkedHashMap<>();
+        for (VideoMatchEnrichedVO item : items) {
+            if (item == null || item.getModality() == null) continue;
+            String key = keyOf(item);
+            VideoMatchEnrichedVO existing = deduped.get(key);
+            if (existing == null || (item.getScore() != null &&
+                    (existing.getScore() == null || item.getScore() > existing.getScore()))) {
+                deduped.put(key, item);
+            }
+        }
+        return new ArrayList<>(deduped.values());
+    }
+
+    private String keyOf(VideoMatchEnrichedVO item) {
+        String idPart = item.getMaterialId() != null ? "mat:" + item.getMaterialId()
+                : item.getArticleId() != null ? "art:" + item.getArticleId()
+                : "vid:" + item.getId();
+        return item.getModality() + ":" + idPart;
+    }
+
+    private List<VideoMatchResult> toVideoMatchResults(List<VideoMatch> matches, String configCode) {
+        if (CollectionUtils.isEmpty(matches)) {
+            return Collections.emptyList();
+        }
+        List<VideoMatchResult> results = new ArrayList<>(matches.size());
+        for (VideoMatch match : matches) {
+            if (match == null || match.getVideoId() == null) {
+                continue;
+            }
+            results.add(new VideoMatchResult(configCode, match.getVideoId(), match.getScore(), match.getText()));
+        }
+        return results;
+    }
+
+    /**
+     * 填充 VideoMatchResult.videoDetail（运营指标 + 解构），对齐 VideoSearchServiceImpl。
+     */
+    private void populateVideoMatchResultDetails(List<VideoMatchResult> results) {
+        if (CollectionUtils.isEmpty(results)) {
+            return;
+        }
+
+        try {
+            List<String> metricsKeys = results.stream()
+                    .map(r -> VectorConstants.VIDEO_DETAIL_DAYS_KEY_PREFIX + metricsDays + "d:" + r.getVideoId())
+                    .collect(Collectors.toList());
+            List<String> metricsValues = redisUtils.mGet(metricsKeys);
+            if (metricsValues != null) {
+                for (int i = 0; i < results.size() && i < metricsValues.size(); i++) {
+                    String json = metricsValues.get(i);
+                    if (!StringUtils.hasText(json)) {
+                        continue;
+                    }
+                    try {
+                        Map<String, Object> detail = JSONObject.parseObject(json, Map.class);
+                        if (detail != null && !detail.isEmpty()) {
+                            results.get(i).setVideoDetail(detail);
+                        }
+                    } catch (Exception e) {
+                        log.debug("解析视频指标失败 videoId={}", results.get(i).getVideoId());
+                    }
+                }
+            }
+        } catch (Exception e) {
+            log.error("批量读取视频指标失败: {}", e.getMessage(), e);
+        }
+
+        try {
+            List<String> decodeKeys = results.stream()
+                    .map(r -> VectorConstants.VID_DECODE_KEY_PREFIX + r.getVideoId())
+                    .collect(Collectors.toList());
+            List<String> decodeValues = redisUtils.mGet(decodeKeys);
+            if (decodeValues == null) {
+                return;
+            }
+            for (int i = 0; i < results.size(); i++) {
+                String json = i < decodeValues.size() ? decodeValues.get(i) : null;
+                if (!StringUtils.hasText(json)) {
+                    continue;
+                }
+                try {
+                    Map<String, Object> deconstructFlat = buildFlatDeconstruct(JSON.parseObject(json));
+                    if (deconstructFlat == null || deconstructFlat.isEmpty()) {
+                        continue;
+                    }
+                    VideoMatchResult result = results.get(i);
+                    Map<String, Object> detailMap = result.getVideoDetail();
+                    if (detailMap == null) {
+                        detailMap = new LinkedHashMap<>();
+                        result.setVideoDetail(detailMap);
+                    }
+                    detailMap.put("deconstruct", deconstructFlat);
+                } catch (Exception e) {
+                    log.debug("解析视频解构失败 videoId={}: {}", results.get(i).getVideoId(), e.getMessage());
+                }
+            }
+        } catch (Exception e) {
+            log.error("批量读取解构缓存失败: {}", e.getMessage(), e);
+        }
+    }
+
+    /**
+     * 保证输入素材自身出现在 material 结果中（score=1.0），且 material 列表不超过 topN。
+     */
+    private void ensureSelfMaterialInResults(List<VideoMatchEnrichedVO> materialItems,
+                                             String materialId, String configCode, int topN) {
+        materialItems.removeIf(it -> materialId.equals(it.getMaterialId()));
+        materialItems.add(0, enrichSelfMaterial(materialId, configCode));
+        while (materialItems.size() > topN) {
+            materialItems.remove(materialItems.size() - 1);
+        }
+    }
+
+    /**
+     * 构建输入素材自身的 enriched 条目（score=1.0）
+     */
+    private VideoMatchEnrichedVO enrichSelfMaterial(String materialId, String configCode) {
+        Map<String, MaterialDeconstructResult> rows = loadMaterialDeconstructRows(Collections.singletonList(materialId));
+        MaterialDeconstructResult row = rows.get(materialId);
+
+        JSONObject raw = row != null ? parseResultJson(row) : null;
+        MaterialBasicMeta basic = raw != null ? extractMaterialBasicMeta(raw) : null;
+        Map<String, Object> deconstructFlat = raw != null ? buildDeconstructFromRaw(raw) : null;
+
+        VideoMatchEnrichedVO vo = new VideoMatchEnrichedVO();
+        vo.setMaterialId(materialId);
+        try {
+            vo.setId(Long.parseLong(materialId));
+        } catch (NumberFormatException ignored) {
+        }
+        vo.setModality(Modality.MATERIAL);
+        vo.setConfigCode(StringUtils.hasText(configCode) ? configCode : null);
+        vo.setScore(1.0);
+
+        if (basic != null) {
+            vo.setTitle(basic.title);
+            applyMaterialImagesAndCover(vo, basic.imagesJson);
+        }
+
+        MaterialDetailVO detail = new MaterialDetailVO();
+        fillMaterialDetailVO(detail, basic, row, deconstructFlat, row != null ? row.getSourceType() : null);
+        fillMaterialDetailImageCount(detail, vo.getImageList());
+        vo.setMaterialDetail(detail);
+
+        applyCompatibilityFields(vo);
+        return vo;
+    }
+
+    // ====================================================================
+    // materialDetail — 素材详情预览
+    // ====================================================================
+
+    @Override
+    public MaterialBasicVO getMaterialDetail(String materialId) {
+        if (!StringUtils.hasText(materialId)) {
+            return null;
+        }
+        String trimmed = materialId.trim();
+        Map<String, MaterialDeconstructResult> rows = loadMaterialDeconstructRows(Collections.singletonList(trimmed));
+        MaterialDeconstructResult row = rows.get(trimmed);
+        if (row == null) {
+            log.info("getMaterialDetail: materialId={} 不存在", trimmed);
+            return null;
+        }
+
+        JSONObject raw = parseResultJson(row);
+        MaterialBasicMeta basic = raw != null ? extractMaterialBasicMeta(raw) : null;
+
+        MaterialBasicVO vo = new MaterialBasicVO();
+        vo.setMaterialId(trimmed);
+        if (basic != null) {
+            vo.setTitle(basic.title);
+        }
+        // 取第一张图片作为预览
+        List<String> images = basic != null && basic.imagesJson != null
+                ? parseImages(basic.imagesJson) : Collections.emptyList();
+        vo.setImageUrl(!images.isEmpty() ? images.get(0) : null);
+
+        return vo;
+    }
+
     @Override
     public DeconstructPointsVO getDeconstructPoints(Long videoId) {
         if (videoId == null || videoId <= 0L) {
@@ -1156,6 +1576,19 @@ public class VectorRecallTestServiceImpl implements VectorRecallTestService {
     private static class MaterialBasicMeta {
         String title;
         String imagesJson;
+        String uploadTime;
+        String usageCount;
+        List<String> tags;
+    }
+
+    private static class MaterialVectorQuery {
+        final String configCode;
+        final String rawEmbedding;
+
+        MaterialVectorQuery(String configCode, String rawEmbedding) {
+            this.configCode = configCode;
+            this.rawEmbedding = rawEmbedding;
+        }
     }
 
     private static class ArticleBasicMeta {
@@ -1168,3 +1601,4 @@ public class VectorRecallTestServiceImpl implements VectorRecallTestService {
         List<String> images;
     }
 }
+

core/src/main/resources/mapper/pgVector/ext/MaterialVectorMapperExt.xml

@@ -150,4 +150,30 @@
           AND point_index >= #{minPointIndex}
     </delete>
 
+    <!-- 查询指定素材已向量化的所有 configCode -->
+    <select id="selectDistinctConfigCodesByMaterialId" resultType="java.lang.String">
+        SELECT DISTINCT config_code
+        FROM material_vectors
+        WHERE material_id = #{materialId}
+    </select>
+
+    <!-- 查询指定素材在指定 configCode 下的所有向量（embedding::text 保证精度） -->
+    <select id="selectVectorsByMaterialIdAndConfigCode" resultMap="MaterialVectorResultMap">
+        SELECT
+            id,
+            material_id,
+            config_code,
+            embedding::text AS embedding,
+            created_at,
+            updated_at,
+            point_index,
+            text,
+            text_hash,
+            source_type
+        FROM material_vectors
+        WHERE material_id = #{materialId}
+          AND config_code = #{configCode}
+        ORDER BY point_index ASC
+    </select>
+
 </mapper>

server/src/main/java/com/tzld/videoVector/controller/VectorRecallTestController.java

@@ -1,10 +1,12 @@
 package com.tzld.videoVector.controller;
 
 import com.tzld.videoVector.common.base.CommonResponse;
+import com.tzld.videoVector.model.param.recall.MatchByMaterialIdParam;
 import com.tzld.videoVector.model.param.recall.MatchByTextParam;
 import com.tzld.videoVector.model.param.recall.MatchByVideoIdParam;
 import com.tzld.videoVector.model.vo.recall.AIUnderstandingVO;
 import com.tzld.videoVector.model.vo.recall.DeconstructPointsVO;
+import com.tzld.videoVector.model.vo.recall.MaterialBasicVO;
 import com.tzld.videoVector.model.vo.recall.RecallResultVO;
 import com.tzld.videoVector.model.vo.recall.VideoBasicVO;
 import com.tzld.videoVector.service.recall.VectorRecallTestService;
@@ -78,4 +80,22 @@ public class VectorRecallTestController {
     public CommonResponse<AIUnderstandingVO> aiUnderstanding(@RequestParam("videoId") Long videoId) {
         return CommonResponse.success(vectorRecallTestService.getAiUnderstanding(videoId));
     }
+
+    /**
+     * 素材ID召回 (素材相似度召回 Tab)
+     * POST /videoVector/recallTest/matchByMaterialId
+     */
+    @PostMapping("/matchByMaterialId")
+    public CommonResponse<RecallResultVO> matchByMaterialId(@RequestBody MatchByMaterialIdParam param) {
+        return CommonResponse.success(vectorRecallTestService.matchByMaterialId(param));
+    }
+
+    /**
+     * 素材详情预览 (素材相似度召回 Tab — 输入防抖预览)
+     * GET /videoVector/recallTest/materialDetail?materialId=xxx
+     */
+    @GetMapping("/materialDetail")
+    public CommonResponse<MaterialBasicVO> materialDetail(@RequestParam("materialId") String materialId) {
+        return CommonResponse.success(vectorRecallTestService.getMaterialDetail(materialId));
+    }
 }