feat(face): 增加人脸识别详情与人工调整功能

- 新增人脸识别详情接口，返回系统采纳与被过滤的样本信息
- 新增人工调整识别结果接口，支持用户手动选择或排除样本
- 引入样本过滤原因枚举，用于记录和展示过滤原因
- 重构样本过滤逻辑，增加过滤轨迹追踪功能
- 优化时间范围与设备照片数量限制的过滤实现
- 在搜索结果中增加过滤轨迹信息，便于前端展示
- 添加人脸识别详情VO和样本VO，丰富返回数据结构
- 完善人脸识别相关的请求与响应模型定义

src/main/java/com/ycwl/basic/controller/pc/FaceController.java

@@ -3,6 +3,8 @@ package com.ycwl.basic.controller.pc;
 import com.github.pagehelper.PageInfo;
 import com.ycwl.basic.model.pc.face.entity.FaceEntity;
 import com.ycwl.basic.model.pc.face.req.FaceReqQuery;
+import com.ycwl.basic.model.pc.face.req.FaceRecognitionUpdateReq;
+import com.ycwl.basic.model.pc.face.resp.FaceRecognitionDetailVO;
 import com.ycwl.basic.model.pc.face.resp.FaceRespVO;
 import com.ycwl.basic.service.pc.FaceService;
 import com.ycwl.basic.utils.ApiResponse;
@@ -53,5 +55,17 @@ public class FaceController {
         return faceService.deleteByIds(ids);
     }
 
+    @PutMapping("/{faceId}/recognition")
+    public ApiResponse<FaceRecognitionDetailVO> updateRecognition(@PathVariable Long faceId,
+                                                                  @RequestBody FaceRecognitionUpdateReq req) {
+        req.setFaceId(faceId);
+        return ApiResponse.success(faceService.updateRecognition(req));
+    }
+
+    @GetMapping("/{faceId}/recognition/detail")
+    public ApiResponse<FaceRecognitionDetailVO> recognitionDetail(@PathVariable Long faceId) {
+        return ApiResponse.success(faceService.getRecognitionDetail(faceId));
+    }
+
 
 }

src/main/java/com/ycwl/basic/model/pc/face/enums/FaceRecognitionFilterReason.java

@@ -0,0 +1,22 @@
+package com.ycwl.basic.model.pc.face.enums;
+
+import lombok.Getter;
+
+/**
+ * 标识系统在过滤识别样本时的原因，便于前端渲染提示。
+ */
+@Getter
+public enum FaceRecognitionFilterReason {
+    SCORE_BELOW_THRESHOLD("score_below_threshold", "置信度低于阈值"),
+    OUT_OF_TIME_RANGE("out_of_time_range", "超出景区时间范围限制"),
+    DEVICE_PHOTO_LIMIT("device_photo_limit", "超过设备照片数量限制"),
+    MANUAL_REJECTED("manual_rejected", "已被手动排除");
+
+    private final String code;
+    private final String description;
+
+    FaceRecognitionFilterReason(String code, String description) {
+        this.code = code;
+        this.description = description;
+    }
+}

src/main/java/com/ycwl/basic/model/pc/face/req/FaceRecognitionUpdateReq.java

@@ -0,0 +1,36 @@
+package com.ycwl.basic.model.pc.face.req;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 人工调整人脸识别结果的请求体。
+ */
+@Data
+public class FaceRecognitionUpdateReq {
+    /**
+     * 指定需要操作的人脸ID。
+     */
+    private Long faceId;
+
+    /**
+     * 用户人工选中希望保留的样本ID列表。
+     */
+    private List<Long> manualAcceptedSampleIds;
+
+    /**
+     * 用户主动排除的样本ID列表。
+     */
+    private List<Long> manualRejectedSampleIds;
+
+    /**
+     * 是否强制重新走一次识别流程。
+     */
+    private Boolean forceRematch;
+
+    /**
+     * 前端传回的备注信息。
+     */
+    private String remark;
+}

src/main/java/com/ycwl/basic/model/pc/face/resp/FaceRecognitionDetailVO.java

@@ -0,0 +1,35 @@
+package com.ycwl.basic.model.pc.face.resp;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * 人脸识别详情，包含系统采纳及被过滤的样本。
+ */
+@Data
+public class FaceRecognitionDetailVO {
+    private Long faceId;
+    private Long memberId;
+    private Long scenicId;
+    private String faceUrl;
+
+    private Float score;
+    private Float firstMatchRate;
+    private Boolean lowThreshold;
+
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private Date lastMatchedAt;
+
+    /**
+     * 系统采纳的样本信息。
+     */
+    private List<FaceRecognitionSampleVO> acceptedSamples;
+
+    /**
+     * 被系统过滤的样本信息。
+     */
+    private List<FaceRecognitionSampleVO> filteredSamples;
+}

src/main/java/com/ycwl/basic/model/pc/face/resp/FaceRecognitionSampleVO.java

@@ -0,0 +1,42 @@
+package com.ycwl.basic.model.pc.face.resp;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.ycwl.basic.model.pc.face.enums.FaceRecognitionFilterReason;
+import lombok.Data;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * 单个人脸样本识别结果的信息描述。
+ */
+@Data
+public class FaceRecognitionSampleVO {
+    private Long sampleId;
+    private Float score;
+    private Boolean accepted;
+
+    private Long sourceId;
+    private Integer sourceType;
+    private String sourceUrl;
+    private String faceUrl;
+
+    private Long deviceId;
+    private String deviceName;
+
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private Date shotAt;
+
+    private Integer isFree;
+    private Integer isBuy;
+
+    /**
+     * 过滤原因列表，用于提示用户样本被过滤的原因。
+     */
+    private List<FaceRecognitionFilterReason> filterReasons;
+
+    /**
+     * 过滤原因的描述集合，方便前端直接展示。
+     */
+    private List<String> filterReasonTexts;
+}

src/main/java/com/ycwl/basic/model/task/resp/SampleFilterTrace.java

@@ -0,0 +1,34 @@
+package com.ycwl.basic.model.task.resp;
+
+import com.ycwl.basic.model.pc.face.enums.FaceRecognitionFilterReason;
+import lombok.Data;
+
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 样本筛选的轨迹信息，记录最终样本集合及各过滤原因。
+ */
+@Data
+public class SampleFilterTrace {
+    private List<Long> acceptedSampleIds;
+    private Map<Long, EnumSet<FaceRecognitionFilterReason>> filteredReasonMap = new HashMap<>();
+
+    public void addReason(Long sampleId, FaceRecognitionFilterReason reason) {
+        if (sampleId == null || reason == null) {
+            return;
+        }
+        filteredReasonMap.computeIfAbsent(sampleId, key -> EnumSet.noneOf(FaceRecognitionFilterReason.class))
+                .add(reason);
+    }
+
+    public Map<Long, EnumSet<FaceRecognitionFilterReason>> getFilteredReasonMap() {
+        if (filteredReasonMap == null) {
+            return Collections.emptyMap();
+        }
+        return filteredReasonMap;
+    }
+}

src/main/java/com/ycwl/basic/model/task/resp/SearchFaceRespVo.java

@@ -11,4 +11,5 @@ public class SearchFaceRespVo {
     private String searchResultJson;
     private Float firstMatchRate;
     private boolean lowThreshold;
+    private SampleFilterTrace filterTrace;
 }

src/main/java/com/ycwl/basic/service/pc/FaceService.java

@@ -5,8 +5,10 @@ import com.ycwl.basic.model.mobile.face.FaceRecognizeResp;
 import com.ycwl.basic.model.mobile.face.FaceStatusResp;
 import com.ycwl.basic.model.mobile.scenic.content.ContentPageVO;
 import com.ycwl.basic.model.pc.face.entity.FaceEntity;
+import com.ycwl.basic.model.pc.face.req.FaceRecognitionUpdateReq;
 import com.ycwl.basic.model.pc.face.req.FaceReqQuery;
 import com.ycwl.basic.model.pc.face.resp.FaceRespVO;
+import com.ycwl.basic.model.pc.face.resp.FaceRecognitionDetailVO;
 import com.ycwl.basic.model.pc.faceSample.entity.FaceSampleEntity;
 import com.ycwl.basic.model.pc.faceSample.resp.FaceSampleRespVO;
 import com.ycwl.basic.model.task.resp.SearchFaceRespVo;
@@ -51,4 +53,8 @@ public interface FaceService {
     List<FaceSampleEntity> getLowMatchedFaceSamples(Long faceId);
 
     void matchCustomFaceId(Long faceId, List<Long> faceSampleIds);
+
+    FaceRecognitionDetailVO updateRecognition(FaceRecognitionUpdateReq req);
+
+    FaceRecognitionDetailVO getRecognitionDetail(Long faceId);
 }

src/main/java/com/ycwl/basic/service/pc/impl/FaceServiceImpl.java

@@ -25,8 +25,13 @@ import com.ycwl.basic.model.mobile.goods.VideoTaskStatusVO;
 import com.ycwl.basic.model.mobile.order.IsBuyRespVO;
 import com.ycwl.basic.model.mobile.scenic.content.ContentPageVO;
 import com.ycwl.basic.model.mobile.statistic.req.StatisticsRecordAddReq;
+import com.ycwl.basic.model.pc.device.entity.DeviceEntity;
 import com.ycwl.basic.model.pc.face.entity.FaceEntity;
+import com.ycwl.basic.model.pc.face.enums.FaceRecognitionFilterReason;
+import com.ycwl.basic.model.pc.face.req.FaceRecognitionUpdateReq;
 import com.ycwl.basic.model.pc.face.req.FaceReqQuery;
+import com.ycwl.basic.model.pc.face.resp.FaceRecognitionDetailVO;
+import com.ycwl.basic.model.pc.face.resp.FaceRecognitionSampleVO;
 import com.ycwl.basic.model.pc.face.resp.FaceRespVO;
 import com.ycwl.basic.model.pc.faceSample.entity.FaceSampleEntity;
 import com.ycwl.basic.model.pc.mp.MpConfigEntity;
@@ -42,6 +47,7 @@ import com.ycwl.basic.model.pc.template.resp.TemplateRespVO;
 import com.ycwl.basic.model.pc.video.entity.MemberVideoEntity;
 import com.ycwl.basic.model.pc.video.entity.VideoEntity;
 import com.ycwl.basic.model.repository.TaskUpdateResult;
+import com.ycwl.basic.model.task.resp.SampleFilterTrace;
 import com.ycwl.basic.model.task.resp.SearchFaceRespVo;
 import com.ycwl.basic.repository.DeviceRepository;
 import com.ycwl.basic.repository.FaceRepository;
@@ -74,12 +80,19 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.Date;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -1077,7 +1090,10 @@ public class FaceServiceImpl implements FaceService {
 
     @Override
     public void matchCustomFaceId(Long faceId, List<Long> faceSampleIds) {
-        // 参数验证
+        handleCustomFaceMatching(faceId, faceSampleIds);
+    }
+
+    private SearchFaceRespVo handleCustomFaceMatching(Long faceId, List<Long> faceSampleIds) {
         if (faceId == null) {
             throw new IllegalArgumentException("faceId 不能为空");
         }
@@ -1088,7 +1104,6 @@ public class FaceServiceImpl implements FaceService {
         log.debug("开始自定义人脸匹配：faceId={}, faceSampleIds={}", faceId, faceSampleIds);
 
         try {
-            // 1. 获取基础数据
             FaceEntity face = faceRepository.getFace(faceId);
             if (face == null) {
                 log.warn("人脸不存在，faceId: {}", faceId);
@@ -1109,21 +1124,19 @@ public class FaceServiceImpl implements FaceService {
                 throw new BaseException("人脸识别服务不可用，请稍后再试");
             }
 
-            // 2. 对每个faceSample进行人脸搜索
             List<SearchFaceRespVo> searchResults = new ArrayList<>();
             for (FaceSampleEntity faceSample : faceSamples) {
                 try {
                     SearchFaceRespVo result = faceService.searchFace(faceBodyAdapter,
-                                                                   String.valueOf(face.getScenicId()), 
-                                                                   faceSample.getFaceUrl(), 
-                                                                   "自定义人脸匹配");
+                            String.valueOf(face.getScenicId()),
+                            faceSample.getFaceUrl(),
+                            "自定义人脸匹配");
                     if (result != null) {
                         searchResults.add(result);
                     }
                 } catch (Exception e) {
                     log.warn("人脸样本搜索失败，faceSampleId={}, faceUrl={}",
                             faceSample.getId(), faceSample.getFaceUrl(), e);
-                    // 继续处理其他样本，不中断整个流程
                 }
             }
 
@@ -1132,21 +1145,23 @@ public class FaceServiceImpl implements FaceService {
                 throw new BaseException("人脸识别失败，请重试");
             }
 
-            // 3. 整合多个搜索结果
             SearchFaceRespVo mergedResult = mergeSearchResults(searchResults);
 
-            // 4. 应用后置筛选逻辑
             if (mergedResult.getSampleListIds() != null && !mergedResult.getSampleListIds().isEmpty()) {
                 List<FaceSampleEntity> allFaceSampleList = faceSampleMapper.listByIds(mergedResult.getSampleListIds());
-                List<Long> filteredSampleIds = faceService.applySampleFilters(mergedResult.getSampleListIds(), allFaceSampleList, scenicConfig);
+                SampleFilterTrace filterTrace = faceService.applySampleFiltersWithTrace(
+                        mergedResult.getSampleListIds(), allFaceSampleList, scenicConfig);
+                List<Long> filteredSampleIds = filterTrace.getAcceptedSampleIds() == null
+                        ? Collections.emptyList()
+                        : filterTrace.getAcceptedSampleIds();
                 mergedResult.setSampleListIds(filteredSampleIds);
-                log.debug("应用后置筛选：原始样本数={}, 筛选后样本数={}", allFaceSampleList.size(), filteredSampleIds.size());
+                mergedResult.setFilterTrace(filterTrace);
+                log.debug("应用后置筛选：原始样本数={}, 筛选后样本数={}",
+                        allFaceSampleList.size(), filteredSampleIds.size());
             }
 
-            // 5. 更新人脸实体结果
             updateFaceEntityResult(face, mergedResult, faceId);
 
-            // 6. 执行后续业务逻辑
             List<Long> sampleListIds = mergedResult.getSampleListIds();
             if (sampleListIds != null && !sampleListIds.isEmpty()) {
                 try {
@@ -1155,18 +1170,17 @@ public class FaceServiceImpl implements FaceService {
                     if (!memberSourceEntityList.isEmpty()) {
                         List<Long> freeSourceIds = processFreeSourceLogic(memberSourceEntityList, scenicConfig, false);
                         processBuyStatus(memberSourceEntityList, freeSourceIds, face.getMemberId(),
-                                       face.getScenicId(), faceId);
+                                face.getScenicId(), faceId);
 
                         handleVideoRecreation(scenicConfig, memberSourceEntityList, faceId,
-                                             face.getMemberId(), sampleListIds, false);
+                                face.getMemberId(), sampleListIds, false);
 
-                        // 过滤已存在的关联关系和无效的source引用，防止数据不一致
                         List<MemberSourceEntity> existingFiltered = sourceMapper.filterExistingRelations(memberSourceEntityList);
                         List<MemberSourceEntity> validFiltered = sourceMapper.filterValidSourceRelations(existingFiltered);
                         if (!validFiltered.isEmpty()) {
                             sourceMapper.addRelations(validFiltered);
                             log.debug("创建关联关系: faceId={}, 原始数量={}, 过滤后数量={}",
-                                      faceId, memberSourceEntityList.size(), validFiltered.size());
+                                    faceId, memberSourceEntityList.size(), validFiltered.size());
                         } else {
                             log.warn("没有有效的关联关系可创建: faceId={}, 原始数量={}", faceId, memberSourceEntityList.size());
                         }
@@ -1174,16 +1188,17 @@ public class FaceServiceImpl implements FaceService {
                         taskTaskService.autoCreateTaskByFaceId(faceId);
 
                         log.info("自定义人脸匹配完成：faceId={}, 匹配样本数={}, 关联源文件数={}, 免费数={}",
-                                 faceId, sampleListIds.size(), memberSourceEntityList.size(), freeSourceIds.size());
+                                faceId, sampleListIds.size(), memberSourceEntityList.size(), freeSourceIds.size());
                     }
                 } catch (Exception e) {
                     log.error("处理源文件关联失败，faceId={}", faceId, e);
-                    // 源文件关联失败不影响主流程
                 }
             } else {
                 log.warn("自定义人脸匹配无结果：faceId={}, faceSampleIds={}", faceId, faceSampleIds);
             }
 
+            return mergedResult;
+
         } catch (BaseException e) {
             throw e;
         } catch (Exception e) {
@@ -1192,6 +1207,320 @@ public class FaceServiceImpl implements FaceService {
         }
     }
 
+    @Override
+    public FaceRecognitionDetailVO updateRecognition(FaceRecognitionUpdateReq req) {
+        if (req == null || req.getFaceId() == null) {
+            throw new IllegalArgumentException("faceId 不能为空");
+        }
+        Long faceId = req.getFaceId();
+        FaceEntity face = faceRepository.getFace(faceId);
+        if (face == null) {
+            throw new BaseException("人脸不存在");
+        }
+
+        boolean forceRematch = Boolean.TRUE.equals(req.getForceRematch());
+        if (forceRematch) {
+            matchFaceId(faceId, false);
+            face = faceRepository.getFace(faceId);
+        }
+
+        List<Long> currentAccepted = parseMatchSampleIds(face.getMatchSampleIds());
+        List<Long> manualAccepted = Optional.ofNullable(req.getManualAcceptedSampleIds()).orElse(Collections.emptyList());
+        List<Long> manualRejected = Optional.ofNullable(req.getManualRejectedSampleIds()).orElse(Collections.emptyList());
+        Set<Long> manualRejectedSet = new HashSet<>(manualRejected);
+
+        LinkedHashSet<Long> finalSampleSet = new LinkedHashSet<>();
+        manualAccepted.stream()
+                .filter(Objects::nonNull)
+                .forEach(finalSampleSet::add);
+        currentAccepted.stream()
+                .filter(Objects::nonNull)
+                .filter(id -> !manualRejectedSet.contains(id))
+                .forEach(finalSampleSet::add);
+
+        boolean hasManualChange = !manualAccepted.isEmpty() || !manualRejectedSet.isEmpty();
+        List<Long> finalSampleList = new ArrayList<>(finalSampleSet);
+        boolean needsUpdate = hasManualChange && !finalSampleList.equals(currentAccepted);
+
+        if (needsUpdate) {
+            if (finalSampleList.isEmpty()) {
+                throw new BaseException("至少需要保留一个样本");
+            }
+            handleCustomFaceMatching(faceId, finalSampleList);
+        }
+
+        if (Strings.isNotBlank(req.getRemark())) {
+            log.info("人脸识别人工调整备注：faceId={}, remark={}", faceId, req.getRemark());
+        }
+
+        return getRecognitionDetail(faceId);
+    }
+
+    @Override
+    public FaceRecognitionDetailVO getRecognitionDetail(Long faceId) {
+        if (faceId == null) {
+            throw new IllegalArgumentException("faceId 不能为空");
+        }
+        FaceEntity face = faceRepository.getFace(faceId);
+        if (face == null) {
+            throw new BaseException("人脸不存在");
+        }
+
+        FaceRecognitionDetailVO detail = new FaceRecognitionDetailVO();
+        detail.setFaceId(faceId);
+        detail.setMemberId(face.getMemberId());
+        detail.setScenicId(face.getScenicId());
+        detail.setFaceUrl(face.getFaceUrl());
+        detail.setScore(face.getScore());
+        detail.setFirstMatchRate(face.getFirstMatchRate() != null ? face.getFirstMatchRate().floatValue() : null);
+        detail.setLowThreshold(redisTemplate.hasKey(FACE_LOW_THRESHOLD_PFX + faceId));
+        detail.setLastMatchedAt(face.getUpdateAt() != null ? face.getUpdateAt() : face.getCreateAt());
+
+        String matchResultJson = face.getMatchResult();
+        if (Strings.isBlank(matchResultJson)) {
+            detail.setAcceptedSamples(Collections.emptyList());
+            detail.setFilteredSamples(Collections.emptyList());
+            return detail;
+        }
+
+        List<SearchFaceResultItem> resultItems = JacksonUtil.fromJsonToList(matchResultJson, SearchFaceResultItem.class);
+        if (resultItems == null) {
+            resultItems = Collections.emptyList();
+        }
+
+        List<Long> persistedAcceptedIds = parseMatchSampleIds(face.getMatchSampleIds());
+        LinkedHashSet<Long> sampleUniverse = new LinkedHashSet<>();
+        Map<Long, SearchFaceResultItem> itemBySampleId = new LinkedHashMap<>();
+        for (SearchFaceResultItem item : resultItems) {
+            Long sampleId = parseLongSilently(item.getExtData());
+            if (sampleId != null) {
+                sampleUniverse.add(sampleId);
+                itemBySampleId.putIfAbsent(sampleId, item);
+            }
+        }
+        sampleUniverse.addAll(persistedAcceptedIds);
+
+        List<Long> allSampleIds = new ArrayList<>(sampleUniverse);
+        if (allSampleIds.isEmpty()) {
+            detail.setAcceptedSamples(Collections.emptyList());
+            detail.setFilteredSamples(Collections.emptyList());
+            return detail;
+        }
+
+        List<FaceSampleEntity> allSamples = faceSampleMapper.listByIds(allSampleIds);
+        Map<Long, FaceSampleEntity> sampleEntityMap = allSamples.stream()
+                .collect(Collectors.toMap(FaceSampleEntity::getId, Function.identity(), (a, b) -> a, LinkedHashMap::new));
+
+        List<SourceEntity> sourceEntities = sourceMapper.listBySampleIds(allSampleIds);
+        Map<Long, SourceEntity> sourceBySampleId = sourceEntities.stream()
+                .collect(Collectors.toMap(SourceEntity::getFaceSampleId, Function.identity(), (a, b) -> a, LinkedHashMap::new));
+        Map<Long, SourceEntity> sourceById = sourceEntities.stream()
+                .collect(Collectors.toMap(SourceEntity::getId, Function.identity(), (a, b) -> a));
+
+        ScenicConfigManager scenicConfig = scenicRepository.getScenicConfigManager(face.getScenicId());
+        Float thresholdConfig = scenicConfig != null ? scenicConfig.getFloat("face_score_threshold") : null;
+        float threshold = thresholdConfig != null ? thresholdConfig / 100F : 0F;
+
+        List<Long> initialAcceptedIds = allSampleIds.stream()
+                .filter(id -> {
+                    SearchFaceResultItem item = itemBySampleId.get(id);
+                    return item != null && item.getScore() != null && item.getScore() > threshold;
+                })
+                .collect(Collectors.toList());
+
+        List<FaceSampleEntity> orderedSampleList = allSampleIds.stream()
+                .map(sampleEntityMap::get)
+                .filter(Objects::nonNull)
+                .collect(Collectors.toList());
+
+        SampleFilterTrace filterTrace = faceService.applySampleFiltersWithTrace(initialAcceptedIds, orderedSampleList, scenicConfig);
+        List<Long> systemAcceptedIds = filterTrace.getAcceptedSampleIds() == null
+                ? Collections.emptyList()
+                : filterTrace.getAcceptedSampleIds();
+
+        Set<Long> initialAcceptedSet = new HashSet<>(initialAcceptedIds);
+        for (Long sampleId : allSampleIds) {
+            if (!initialAcceptedSet.contains(sampleId) && !systemAcceptedIds.contains(sampleId)) {
+                filterTrace.addReason(sampleId, FaceRecognitionFilterReason.SCORE_BELOW_THRESHOLD);
+            }
+        }
+
+        Set<Long> systemAcceptedSet = new HashSet<>(systemAcceptedIds);
+        Set<Long> persistedAcceptedSet = new HashSet<>(persistedAcceptedIds);
+        for (Long sampleId : systemAcceptedSet) {
+            if (!persistedAcceptedSet.contains(sampleId)) {
+                filterTrace.addReason(sampleId, FaceRecognitionFilterReason.MANUAL_REJECTED);
+            }
+        }
+
+        List<MemberSourceEntity> relations = new ArrayList<>();
+        List<MemberSourceEntity> videoRelations = memberRelationRepository.listSourceByFaceRelation(faceId, 1);
+        if (videoRelations != null) {
+            relations.addAll(videoRelations);
+        }
+        List<MemberSourceEntity> imageRelations = memberRelationRepository.listSourceByFaceRelation(faceId, 2);
+        if (imageRelations != null) {
+            relations.addAll(imageRelations);
+        }
+        Map<Long, MemberSourceEntity> relationBySampleId = new HashMap<>();
+        for (MemberSourceEntity relation : relations) {
+            SourceEntity source = sourceById.get(relation.getSourceId());
+            if (source != null && source.getFaceSampleId() != null) {
+                relationBySampleId.putIfAbsent(source.getFaceSampleId(), relation);
+            }
+        }
+
+        Map<Long, EnumSet<FaceRecognitionFilterReason>> reasonMap = filterTrace.getFilteredReasonMap();
+        Map<Long, DeviceEntity> deviceCache = new HashMap<>();
+
+        List<Long> acceptedOrdered = new ArrayList<>();
+        for (Long sampleId : allSampleIds) {
+            if (persistedAcceptedSet.contains(sampleId)) {
+                acceptedOrdered.add(sampleId);
+            }
+        }
+        for (Long sampleId : persistedAcceptedIds) {
+            if (!acceptedOrdered.contains(sampleId)) {
+                acceptedOrdered.add(sampleId);
+            }
+        }
+
+        List<FaceRecognitionSampleVO> acceptedSamples = acceptedOrdered.stream()
+                .map(sampleId -> buildSampleVO(
+                        sampleId,
+                        true,
+                        itemBySampleId.get(sampleId),
+                        sampleEntityMap.get(sampleId),
+                        sourceBySampleId.get(sampleId),
+                        relationBySampleId.get(sampleId),
+                        deviceCache,
+                        Collections.emptyList()))
+                .collect(Collectors.toList());
+
+        Set<Long> acceptedSet = new HashSet<>(acceptedOrdered);
+        List<FaceRecognitionSampleVO> filteredSamples = new ArrayList<>();
+        for (Long sampleId : allSampleIds) {
+            if (acceptedSet.contains(sampleId)) {
+                continue;
+            }
+            EnumSet<FaceRecognitionFilterReason> reasons = reasonMap.get(sampleId);
+            List<FaceRecognitionFilterReason> reasonList = reasons == null
+                    ? Collections.emptyList()
+                    : new ArrayList<>(reasons);
+            filteredSamples.add(buildSampleVO(
+                    sampleId,
+                    false,
+                    itemBySampleId.get(sampleId),
+                    sampleEntityMap.get(sampleId),
+                    sourceBySampleId.get(sampleId),
+                    relationBySampleId.get(sampleId),
+                    deviceCache,
+                    reasonList));
+        }
+
+        detail.setAcceptedSamples(acceptedSamples);
+        detail.setFilteredSamples(filteredSamples);
+        return detail;
+    }
+
+    private List<Long> parseMatchSampleIds(String matchSampleIds) {
+        if (Strings.isBlank(matchSampleIds)) {
+            return Collections.emptyList();
+        }
+        String[] segments = matchSampleIds.split(",");
+        List<Long> result = new ArrayList<>(segments.length);
+        for (String segment : segments) {
+            Long id = parseLongSilently(segment);
+            if (id != null) {
+                result.add(id);
+            }
+        }
+        return result;
+    }
+
+    private Long parseLongSilently(String value) {
+        if (Strings.isBlank(value)) {
+            return null;
+        }
+        try {
+            return Long.valueOf(value.trim());
+        } catch (NumberFormatException e) {
+            return null;
+        }
+    }
+
+    private FaceRecognitionSampleVO buildSampleVO(Long sampleId,
+                                                  boolean accepted,
+                                                  SearchFaceResultItem resultItem,
+                                                  FaceSampleEntity sampleEntity,
+                                                  SourceEntity sourceEntity,
+                                                  MemberSourceEntity relation,
+                                                  Map<Long, DeviceEntity> deviceCache,
+                                                  List<FaceRecognitionFilterReason> reasons) {
+        FaceRecognitionSampleVO vo = new FaceRecognitionSampleVO();
+        vo.setSampleId(sampleId);
+        vo.setAccepted(accepted);
+        if (resultItem != null) {
+            vo.setScore(resultItem.getScore());
+        }
+        if (sampleEntity != null) {
+            vo.setFaceUrl(sampleEntity.getFaceUrl());
+            vo.setDeviceId(sampleEntity.getDeviceId());
+            vo.setShotAt(sampleEntity.getCreateAt());
+            DeviceEntity device = getDeviceCached(sampleEntity.getDeviceId(), deviceCache);
+            if (device != null) {
+                vo.setDeviceName(device.getName());
+            }
+        }
+        if (sourceEntity != null) {
+            vo.setSourceId(sourceEntity.getId());
+            vo.setSourceType(sourceEntity.getType());
+            vo.setSourceUrl(resolveSourceUrl(sourceEntity));
+        }
+        if (relation != null) {
+            vo.setIsFree(relation.getIsFree());
+            vo.setIsBuy(relation.getIsBuy());
+        }
+        if (reasons != null && !reasons.isEmpty()) {
+            vo.setFilterReasons(new ArrayList<>(reasons));
+            vo.setFilterReasonTexts(reasons.stream()
+                    .map(FaceRecognitionFilterReason::getDescription)
+                    .collect(Collectors.toList()));
+        } else {
+            vo.setFilterReasons(Collections.emptyList());
+            vo.setFilterReasonTexts(Collections.emptyList());
+        }
+        return vo;
+    }
+
+    private DeviceEntity getDeviceCached(Long deviceId, Map<Long, DeviceEntity> cache) {
+        if (deviceId == null) {
+            return null;
+        }
+        if (cache.containsKey(deviceId)) {
+            return cache.get(deviceId);
+        }
+        DeviceEntity device = deviceRepository.getDevice(deviceId);
+        cache.put(deviceId, device);
+        return device;
+    }
+
+    private String resolveSourceUrl(SourceEntity sourceEntity) {
+        if (sourceEntity == null) {
+            return null;
+        }
+        if (!Strings.isBlank(sourceEntity.getUrl())) {
+            return sourceEntity.getUrl();
+        }
+        if (!Strings.isBlank(sourceEntity.getVideoUrl())) {
+            return sourceEntity.getVideoUrl();
+        }
+        if (!Strings.isBlank(sourceEntity.getThumbUrl())) {
+            return sourceEntity.getThumbUrl();
+        }
+        return null;
+    }
+
     /**
      * 合并多个搜索结果
      */

src/main/java/com/ycwl/basic/service/task/TaskFaceService.java

@@ -3,6 +3,7 @@ package com.ycwl.basic.service.task;
 import com.ycwl.basic.facebody.adapter.IFaceBodyAdapter;
 import com.ycwl.basic.integration.common.manager.ScenicConfigManager;
 import com.ycwl.basic.model.pc.faceSample.entity.FaceSampleEntity;
+import com.ycwl.basic.model.task.resp.SampleFilterTrace;
 import com.ycwl.basic.model.task.resp.SearchFaceRespVo;
 import org.springframework.web.multipart.MultipartFile;
 
@@ -28,4 +29,16 @@ public interface TaskFaceService {
     List<Long> applySampleFilters(List<Long> acceptedSampleIds,
                                  List<FaceSampleEntity> allFaceSampleList,
                                  ScenicConfigManager scenicConfig);
+
+    /**
+     * 带过滤轨迹的样本筛选逻辑。
+     *
+     * @param acceptedSampleIds 已接受的样本ID列表
+     * @param allFaceSampleList 所有人脸样本实体列表
+     * @param scenicConfig 景区配置
+     * @return 包含最终样本及过滤原因的轨迹对象
+     */
+    SampleFilterTrace applySampleFiltersWithTrace(List<Long> acceptedSampleIds,
+                                                 List<FaceSampleEntity> allFaceSampleList,
+                                                 ScenicConfigManager scenicConfig);
 }

src/main/java/com/ycwl/basic/service/task/impl/TaskFaceServiceImpl.java

@@ -23,6 +23,7 @@ import com.ycwl.basic.model.pc.device.entity.DeviceConfigEntity;
 import com.ycwl.basic.model.pc.device.entity.DeviceEntity;
 import com.ycwl.basic.model.pc.face.entity.FaceEntity;
 import com.ycwl.basic.model.pc.face.resp.FaceRespVO;
+import com.ycwl.basic.model.pc.face.enums.FaceRecognitionFilterReason;
 import com.ycwl.basic.model.pc.faceDetectLog.entity.FaceDetectLog;
 import com.ycwl.basic.model.pc.faceDetectLog.resp.MatchLocalRecord;
 import com.ycwl.basic.model.pc.faceSample.entity.FaceSampleEntity;
@@ -30,6 +31,7 @@ import com.ycwl.basic.model.pc.scenic.entity.ScenicConfigEntity;
 import com.ycwl.basic.model.pc.source.entity.MemberSourceEntity;
 import com.ycwl.basic.model.pc.source.entity.SourceEntity;
 import com.ycwl.basic.model.task.resp.SearchFaceRespVo;
+import com.ycwl.basic.model.task.resp.SampleFilterTrace;
 import com.ycwl.basic.repository.DeviceRepository;
 import com.ycwl.basic.repository.FaceRepository;
 import com.ycwl.basic.repository.ScenicRepository;
@@ -52,7 +54,10 @@ import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.HashSet;
+import java.util.Objects;
 import java.util.Optional;
+import java.util.Set;
 import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 
@@ -264,7 +269,18 @@ public class TaskFaceServiceImpl implements TaskFaceService {
                 idIndexMap.put(allFaceSampleIds.get(i), i);
             }
             allFaceSampleList.sort(Comparator.comparing(sample -> idIndexMap.get(sample.getId())));
-            acceptFaceSampleIds = applySampleFilters(acceptFaceSampleIds, allFaceSampleList, scenicConfig);
+            SampleFilterTrace filterTrace = applySampleFiltersWithTrace(acceptFaceSampleIds, allFaceSampleList, scenicConfig);
+            List<Long> finalAcceptedSampleIds = filterTrace.getAcceptedSampleIds() == null
+                    ? Collections.emptyList()
+                    : filterTrace.getAcceptedSampleIds();
+            Set<Long> initialAcceptedSet = acceptFaceSampleIds == null
+                    ? Collections.emptySet()
+                    : new HashSet<>(acceptFaceSampleIds);
+            for (Long sampleId : allFaceSampleIds) {
+                if (!finalAcceptedSampleIds.contains(sampleId) && !initialAcceptedSet.contains(sampleId)) {
+                    filterTrace.addReason(sampleId, FaceRecognitionFilterReason.SCORE_BELOW_THRESHOLD);
+                }
+            }
             List<MatchLocalRecord> collect = new ArrayList<>();
             for (SearchFaceResultItem item : records) {
                 MatchLocalRecord record = new MatchLocalRecord();
@@ -277,7 +293,7 @@ public class TaskFaceServiceImpl implements TaskFaceService {
                         if (device != null) {
                             record.setDeviceName(device.getName());
                         }
-                        record.setAccept(acceptFaceSampleIds.contains(optionalFse.get().getId()));
+                        record.setAccept(finalAcceptedSampleIds.contains(optionalFse.get().getId()));
                         record.setFaceUrl(optionalFse.get().getFaceUrl());
                         record.setShotDate(optionalFse.get().getCreateAt());
                     }
@@ -289,13 +305,14 @@ public class TaskFaceServiceImpl implements TaskFaceService {
                 collect.add(record);
             }
             logEntity.setMatchLocalRecord(JacksonUtil.toJSONString(collect));
-            if (acceptFaceSampleIds.isEmpty()) {
+            if (finalAcceptedSampleIds.isEmpty()) {
                 respVo.setFirstMatchRate(0f);
                 respVo.setSampleListIds(Collections.emptyList());
                 return respVo;
             }
             respVo.setFirstMatchRate(response.getFirstMatchRate());
-            respVo.setSampleListIds(acceptFaceSampleIds);
+            respVo.setSampleListIds(finalAcceptedSampleIds);
+            respVo.setFilterTrace(filterTrace);
             return respVo;
         } catch (Exception e) {
             logEntity.setMatchRawResult("识别错误，错误为：["+e.getLocalizedMessage()+"]");
@@ -389,158 +406,136 @@ public class TaskFaceServiceImpl implements TaskFaceService {
      */
     @Override
     public List<Long> applySampleFilters(List<Long> acceptedSampleIds,
-                                        List<FaceSampleEntity> allFaceSampleList, 
-                                        ScenicConfigManager scenicConfig) {
+                                         List<FaceSampleEntity> allFaceSampleList,
+                                         ScenicConfigManager scenicConfig) {
+        SampleFilterTrace trace = applySampleFiltersWithTrace(acceptedSampleIds, allFaceSampleList, scenicConfig);
+        List<Long> result = trace.getAcceptedSampleIds();
+        return result == null ? Collections.emptyList() : result;
+    }
+
+    @Override
+    public SampleFilterTrace applySampleFiltersWithTrace(List<Long> acceptedSampleIds,
+                                                         List<FaceSampleEntity> allFaceSampleList,
+                                                         ScenicConfigManager scenicConfig) {
+        SampleFilterTrace trace = new SampleFilterTrace();
         if (acceptedSampleIds == null || acceptedSampleIds.isEmpty()) {
-            return acceptedSampleIds;
+            trace.setAcceptedSampleIds(acceptedSampleIds == null ? Collections.emptyList() : new ArrayList<>(acceptedSampleIds));
+            return trace;
         }
-        if (scenicConfig == null) {
-            // 没有配置，不管
-            return acceptedSampleIds;
+        if (allFaceSampleList == null || allFaceSampleList.isEmpty()) {
+            trace.setAcceptedSampleIds(new ArrayList<>(acceptedSampleIds));
+            return trace;
         }
 
-        // 1. 找到最高匹配的样本（按创建时间倒序排列的第一个）
-        Optional<FaceSampleEntity> firstFaceSample = allFaceSampleList.stream()
-                .filter(faceSample -> acceptedSampleIds.contains(faceSample.getId())).max(Comparator.comparing(FaceSampleEntity::getCreateAt));
+        Map<Long, FaceSampleEntity> sampleMap = allFaceSampleList.stream()
+                .collect(Collectors.toMap(FaceSampleEntity::getId, sample -> sample, (a, b) -> a));
 
-        if (firstFaceSample.isEmpty()) {
-            log.warn("样本筛选逻辑：未找到匹配的人脸样本，acceptedIds: {}", acceptedSampleIds);
-            return acceptedSampleIds;
+        List<Long> workingList = acceptedSampleIds.stream()
+                .filter(sampleMap::containsKey)
+                .collect(Collectors.toCollection(ArrayList::new));
+
+        if (workingList.isEmpty()) {
+            trace.setAcceptedSampleIds(Collections.emptyList());
+            return trace;
         }
 
-        FaceSampleEntity topMatchSample = firstFaceSample.get();
-        log.debug("样本筛选逻辑：找到最高匹配样本 ID={}, 创建时间={}", 
-                 topMatchSample.getId(), topMatchSample.getCreateAt());
-
-        List<Long> filteredIds = acceptedSampleIds;
-
-        // 2. 应用时间范围筛选（基于景区配置）
-        if (scenicConfig.getInteger("tour_time", 0) > 0) {
-            filteredIds = filterSampleIdsByTimeRange(filteredIds, topMatchSample, scenicConfig.getInteger("tour_time"));
-            log.debug("应用时间范围筛选：游览时间限制={}分钟", scenicConfig.getInteger("tour_time"));
+        Integer tourMinutes = scenicConfig != null ? scenicConfig.getInteger("tour_time") : null;
+        if (tourMinutes != null && tourMinutes > 0) {
+            workingList = filterSampleIdsByTimeRangeWithTrace(workingList, sampleMap, tourMinutes, trace);
+            log.debug("应用时间范围筛选：游览时间限制={}分钟，过滤后数量={}", tourMinutes, workingList.size());
         } else {
             log.debug("时间范围逻辑：景区未设置游览时间限制");
         }
 
+        workingList = applyDevicePhotoLimitWithTrace(workingList, sampleMap, trace);
+        trace.setAcceptedSampleIds(new ArrayList<>(workingList));
 
-
-        // 3. 应用设备照片数量限制筛选
-        filteredIds = applyDevicePhotoLimit(filteredIds, allFaceSampleList);
-        log.debug("应用设备照片数量限制筛选完成");
-
-        // 4. TODO: 基于景区配置的其他筛选策略
-        // 可以根据 scenicConfig 中的配置来决定是否启用特定筛选
-        // 示例：未来可能的筛选策略
-        // if (scenicConfig.getEnableLocationFilter() != null && scenicConfig.getEnableLocationFilter()) {
-        //     filteredIds = applyLocationFilter(filteredIds, allFaceSampleList, scenicConfig);
-        // }
-        // if (scenicConfig.getEnableQualityFilter() != null && scenicConfig.getEnableQualityFilter()) {
-        //     filteredIds = applyQualityFilter(filteredIds, allFaceSampleList, scenicConfig);
-        // }
-        // if (scenicConfig.getMaxSampleCount() != null) {
-        //     filteredIds = applySampleCountLimit(filteredIds, scenicConfig.getMaxSampleCount());
-        // }
-
-        log.debug("样本筛选完成：原始数量={}, 最终数量={}",
-                 acceptedSampleIds.size(), filteredIds.size());
-        return filteredIds;
+        log.debug("样本筛选完成：原始数量={}, 最终数量={}", acceptedSampleIds.size(), workingList.size());
+        return trace;
     }
 
-    /**
-     * 根据时间范围过滤人脸样本ID
-     * 基于最高匹配样本的时间，过滤出指定时间范围内的样本ID
-     */
-    private List<Long> filterSampleIdsByTimeRange(List<Long> acceptedSampleIds, 
-                                                  FaceSampleEntity firstMatch, 
-                                                  int tourMinutes) {
-        if (acceptedSampleIds == null || acceptedSampleIds.isEmpty() || 
-            firstMatch == null || tourMinutes <= 0) {
+    private List<Long> filterSampleIdsByTimeRangeWithTrace(List<Long> acceptedSampleIds,
+                                                           Map<Long, FaceSampleEntity> sampleMap,
+                                                           int tourMinutes,
+                                                           SampleFilterTrace trace) {
+        if (acceptedSampleIds == null || acceptedSampleIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        FaceSampleEntity topMatchSample = acceptedSampleIds.stream()
+                .map(sampleMap::get)
+                .filter(Objects::nonNull)
+                .max(Comparator.comparing(FaceSampleEntity::getCreateAt))
+                .orElse(null);
+        if (topMatchSample == null || topMatchSample.getCreateAt() == null) {
+            log.warn("样本筛选逻辑：未找到匹配的人脸样本，acceptedIds: {}", acceptedSampleIds);
             return acceptedSampleIds;
         }
 
-        List<FaceSampleEntity> acceptFaceSampleList = faceSampleMapper.listByIds(acceptedSampleIds);
-        if (acceptFaceSampleList.isEmpty()) {
-            return acceptedSampleIds;
+        Date startDate = DateUtil.offsetMinute(topMatchSample.getCreateAt(), -tourMinutes);
+        Date endDate = DateUtil.offsetMinute(topMatchSample.getCreateAt(), 1);
+
+        List<Long> result = new ArrayList<>();
+        for (Long sampleId : acceptedSampleIds) {
+            FaceSampleEntity sample = sampleMap.get(sampleId);
+            if (sample == null || sample.getCreateAt() == null) {
+                result.add(sampleId);
+                continue;
+            }
+            Date createAt = sample.getCreateAt();
+            if (createAt.after(startDate) && createAt.before(endDate)) {
+                result.add(sampleId);
+            } else {
+                trace.addReason(sampleId, FaceRecognitionFilterReason.OUT_OF_TIME_RANGE);
+            }
         }
 
-        Date startDate = DateUtil.offsetMinute(firstMatch.getCreateAt(), -tourMinutes);
-        Date endDate = DateUtil.offsetMinute(firstMatch.getCreateAt(), 1);
-
-        List<Long> filteredIds = acceptFaceSampleList.stream()
-                .filter(faceSample -> faceSample.getCreateAt().after(startDate) && 
-                                     faceSample.getCreateAt().before(endDate))
-                .map(FaceSampleEntity::getId)
-                .collect(Collectors.toList());
-
         log.info("时间范围逻辑：最高匹配：{}，时间范围：{}~{}，原样本数：{}，过滤后样本数：{}",
-                firstMatch.getId(), startDate, endDate, acceptedSampleIds.size(), filteredIds.size());
-
-        return filteredIds;
+                topMatchSample.getId(), startDate, endDate, acceptedSampleIds.size(), result.size());
+        return result;
     }
 
-    /**
-     * 根据设备配置的limit_photo值限制每个设备的照片数量
-     * 
-     * @param acceptedSampleIds 已接受的样本ID列表
-     * @param allFaceSampleList 所有人脸样本实体列表
-     * @return 应用设备照片数量限制后的样本ID列表
-     */
-    private List<Long> applyDevicePhotoLimit(List<Long> acceptedSampleIds, 
-                                           List<FaceSampleEntity> allFaceSampleList) {
+    private List<Long> applyDevicePhotoLimitWithTrace(List<Long> acceptedSampleIds,
+                                                      Map<Long, FaceSampleEntity> sampleMap,
+                                                      SampleFilterTrace trace) {
         if (acceptedSampleIds == null || acceptedSampleIds.isEmpty()) {
-            return acceptedSampleIds;
+            return Collections.emptyList();
         }
 
-        // 获取过滤后的样本列表
-        List<FaceSampleEntity> filteredSamples = allFaceSampleList.stream()
-                .filter(sample -> acceptedSampleIds.contains(sample.getId()))
-                .collect(Collectors.toList());
+        Map<Long, Integer> usedCount = new HashMap<>();
+        Map<Long, Integer> limitCache = new HashMap<>();
+        List<Long> result = new ArrayList<>();
 
-        // 按设备ID分组
-        Map<Long, List<FaceSampleEntity>> samplesByDevice = filteredSamples.stream()
-                .collect(Collectors.groupingBy(FaceSampleEntity::getDeviceId));
-
-        List<Long> resultIds = new ArrayList<>();
-
-        // 处理每个设备的样本
-        for (Map.Entry<Long, List<FaceSampleEntity>> entry : samplesByDevice.entrySet()) {
-            Long deviceId = entry.getKey();
-            List<FaceSampleEntity> deviceSamples = entry.getValue();
-
-            // 获取设备配置
-            DeviceConfigManager deviceConfig = deviceRepository.getDeviceConfigManager(deviceId);
-            Integer limitPhoto = null;
-            if (deviceConfig != null) {
-                limitPhoto = deviceConfig.getInteger("limit_photo");
+        for (Long sampleId : acceptedSampleIds) {
+            FaceSampleEntity sample = sampleMap.get(sampleId);
+            if (sample == null) {
+                result.add(sampleId);
+                continue;
             }
-
-            // 如果没有配置或配置为0，不限制
+            Long deviceId = sample.getDeviceId();
+            if (deviceId == null) {
+                result.add(sampleId);
+                continue;
+            }
+            Integer limitPhoto = limitCache.computeIfAbsent(deviceId, id -> {
+                DeviceConfigManager deviceConfig = deviceRepository.getDeviceConfigManager(id);
+                return deviceConfig != null ? deviceConfig.getInteger("limit_photo") : null;
+            });
             if (limitPhoto == null || limitPhoto <= 0) {
-                List<Long> deviceSampleIds = deviceSamples.stream()
-                        .map(FaceSampleEntity::getId)
-                        .collect(Collectors.toList());
-                resultIds.addAll(deviceSampleIds);
-                log.debug("设备照片限制：设备ID={}, 无限制，保留{}张照片", 
-                         deviceId, deviceSampleIds.size());
+                result.add(sampleId);
+                continue;
+            }
+            int used = usedCount.getOrDefault(deviceId, 0);
+            if (used < limitPhoto) {
+                result.add(sampleId);
+                usedCount.put(deviceId, used + 1);
             } else {
-                // 取前N张
-                List<FaceSampleEntity> limitedSamples = deviceSamples.stream()
-                        .limit(limitPhoto)
-                        .collect(Collectors.toList());
-                
-                List<Long> limitedIds = limitedSamples.stream()
-                        .map(FaceSampleEntity::getId)
-                        .collect(Collectors.toList());
-                
-                resultIds.addAll(limitedIds);
-                log.debug("设备照片限制：设备ID={}, 限制={}张, 原始{}张，最终{}张", 
-                         deviceId, limitPhoto, deviceSamples.size(), limitedIds.size());
+                trace.addReason(sampleId, FaceRecognitionFilterReason.DEVICE_PHOTO_LIMIT);
             }
         }
 
         log.info("设备照片数量限制筛选：原始样本数量={}, 筛选后数量={}",
-                acceptedSampleIds.size(), resultIds.size());
-        
-        return resultIds;
+                acceptedSampleIds.size(), result.size());
+        return result;
     }
+
 }