feat: 新增人脸检测API和人脸检测测试脚本，并更新 API 文档。

API_DOCUMENTATION.md

@@ -0,0 +1,260 @@
+# 人脸识别系统 API 接口文档
+
+本文档详细说明了人脸识别系统的后端业务接口与算法服务接口，供开发人员集成使用。
+
+## 1. 系统业务接口 (Java Backend)
+
+后端服务主要提供分组管理和人员信息管理功能。所有接口统一通过 HTTP 协议调用，返回 JSON 格式数据。
+
+**基础路径**: `/api` (例如: `http://<server_ip>:<port>/api`)
+
+### 1.1 分组管理
+
+#### 1.1.1 创建/添加分组
+*   **接口地址**: `/groups/add`
+*   **请求方式**: `POST`
+*   **请求类型**: `application/json`
+*   **请求参数**:
+    
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | name | String | 是 | 分组名称 |
+    | description | String | 否 | 分组描述 (如果有) |
+
+    **请求示例**:
+    ```json
+    {
+        "name": "VIP人员",
+        "description": "重要客户分组"
+    }
+    ```
+
+*   **返回结果**:
+    ```json
+    {
+        "code": 200,
+        "msg": "success",
+        "data": {
+            "id": 1,
+            "name": "VIP人员",
+            "createTime": "2023-12-30T10:00:00"
+        }
+    }
+    ```
+
+#### 1.1.2 获取分组列表
+*   **接口地址**: `/groups/list`
+*   **请求方式**: `GET`
+*   **返回结果**:
+    ```json
+    {
+        "code": 200,
+        "msg": "success",
+        "data": [
+            {
+                "id": 1,
+                "name": "默认分组"
+            },
+            {
+                "id": 2,
+                "name": "员工分组"
+            }
+        ]
+    }
+    ```
+
+---
+
+### 1.2 人员管理
+
+#### 1.2.1 新增人员 (带照片)
+该接口用于注册新用户，同时上传人脸照片用于提取特征。
+
+*   **接口地址**: `/users/add`
+*   **请求方式**: `POST`
+*   **请求类型**: `multipart/form-data` (表单上传)
+*   **请求参数**:
+
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | name | String | 是 | 人员姓名 |
+    | groupId | Long | 否 | 所属分组ID |
+    | photo | File | 是 | 人脸照片文件 (jpg/png) |
+
+*   **返回结果**:
+    ```json
+    {
+        "code": 200,
+        "msg": "success",
+        "data": {
+            "id": 101,
+            "name": "张三",
+            "groupId": 2,
+            "feature": "..." // (内部可能不直接返回长特征，视具体实现而定)
+        }
+    }
+    ```
+
+#### 1.2.2 编辑人员信息
+用于更新人员姓名、分组或重新上传人脸照片。
+
+*   **接口地址**: `/users/update/{id}`
+*   **请求方式**: `POST`
+*   **请求类型**: `multipart/form-data`
+*   **路径参数**:
+    *   `id`: 人员ID (Long)
+
+*   **请求参数**:
+
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | name | String | 是 | 人员姓名 |
+    | groupId | Long | 否 | 所属分组ID (不传则不修改) |
+    | photo | File | 否 | 新的人脸照片 (不传则不修改) |
+
+*   **返回结果**:
+    ```json
+    {
+        "code": 200,
+        "msg": "success",
+        "data": { ... }
+    }
+    ```
+
+#### 1.2.3 获取人员列表 (查询)
+*   **接口地址**: `/users/list`
+*   **请求方式**: `GET`
+*   **请求参数**:
+
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | name | String | 否 | 按姓名模糊查询 |
+    | groupId | Long | 否 | 按分组ID筛选 |
+
+*   **返回结果**:
+    ```json
+    {
+        "code": 200,
+        "msg": "success",
+        "data": [ ...User Objects... ]
+    }
+    ```
+    
+#### 1.2.4 人脸搜索 (1:N 检索)
+用于上传一张人脸照片，并在指定分组内检索最相似的人员。
+
+*   **接口地址**: `/users/search`
+*   **请求方式**: `POST`
+*   **请求类型**: `multipart/form-data`
+*   **请求参数**:
+
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | photo | File | 是 | 待检索的人脸照片 |
+    | groupId | Long | 是 | 目标分组ID |
+
+*   **返回结果**:
+    
+    **成功找到匹配**:
+    ```json
+    {
+        "code": 200,
+        "msg": "success",
+        "data": {
+            "id": 101,
+            "name": "张三",
+            "groupId": 2,
+            ...
+        }
+    }
+    ```
+
+    **未找到匹配 (相似度低于阈值 0.6)**:
+    ```json
+    {
+        "code": 404,
+        "msg": "未找到匹配用户"
+    }
+    ```
+
+---
+
+## 2. 算法服务接口 (Python - FaceFeatureExtractor)
+
+该接口通常由 Java 后端内部调用，但如果开发人员需要独立调试算法或进行集成，可直接调用该微服务。
+
+**功能**: 接收图片，进行质量检测（人脸检测、模糊度、亮度、姿态等），合格后提取 1024 维人脸特征向量。
+
+**默认端口**: `8000` (具体取决于 docker-compose 配置)
+
+### 2.1 提取人脸特征
+*   **接口地址**: `/api/extract_feature`
+*   **请求方式**: `POST`
+*   **请求类型**: `multipart/form-data`
+*   **请求参数**:
+
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | image | File | 是 | 图片文件 (支持 jpg, png 等常见格式) |
+
+*   **返回结果 (JSON)**:
+
+    **成功响应**:
+    ```json
+    {
+        "success": true,
+        "message": "Success",
+        "feature": [0.123, -0.456, ...],  // 1024维浮点数组
+        "feature_dim": 1024,
+        "processing_time": 0.045
+    }
+    ```
+
+    **失败/质量不合格响应**:
+    ```json
+    {
+        "success": false,
+        "message": "No face detected" // 或 "Face quality check failed...", "Server error..."
+    }
+    ```
+
+### 2.2 健康检查
+*   **接口地址**: `/health`
+*   **请求方式**: `GET`
+*   **返回结果**: `{"status": "healthy", "service": "Face Feature Extractor"}`
+
+### 2.3 人脸检测 (获取坐标)
+*   **接口地址**: `/api/detect_face`
+*   **请求方式**: `POST`
+*   **请求类型**: `multipart/form-data`
+*   **请求参数**:
+
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | image | File | 是 | 图片文件 |
+    | expand_scale | Float | 否 | 扩充比例，默认 0.0。例如 0.3 表示长宽各扩充 30% |
+
+*   **返回结果**:
+
+    > **坐标说明**:
+    > *   `x1`, `y1`: 人脸检测框 **左上角** 的像素坐标。
+    > *   `x2`, `y2`: 人脸检测框 **右下角** 的像素坐标。
+    > *   `score`: 检测置信度 (0-1之间)。
+    > *   **注意**: 即使设置了 `expand_scale`，返回的坐标也会被限制在图片边界内 (Clip to bounds)。
+
+    ```json
+    {
+        "success": true,
+        "message": "Success",
+        "faces": [
+            {
+                "x1": 100.0,
+                "y1": 50.0,
+                "x2": 200.0,
+                "y2": 150.0,
+                "score": 0.98
+            }
+        ],
+        "processing_time": 0.02
+    }
+    ```

FaceFeatureExtractorAPI/feature_server.py

@@ -5,7 +5,7 @@
 """
 
 import uvicorn
-from fastapi import FastAPI, File, UploadFile, HTTPException
+from fastapi import FastAPI, File, UploadFile, HTTPException, Form
 from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 from typing import List, Optional
@@ -118,6 +118,94 @@ async def extract_feature(image: UploadFile = File(...)):
             message=f"Server error: {str(e)}"
         )
 
+# 新增人脸检测响应模型
+class FaceRect(BaseModel):
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    score: float
+
+class DetectFaceResponse(BaseModel):
+    success: bool
+    message: str
+    faces: List[FaceRect] = []
+    processing_time: Optional[float] = None
+
+@app.post("/api/detect_face", response_model=DetectFaceResponse)
+async def detect_face(image: UploadFile = File(...), expand_scale: float = Form(0.0)):
+    """
+    人脸检测接口
+    输入: 图片文件, 扩充比例(expand_scale)
+    输出: 人脸坐标列表 (x1, y1, x2, y2)
+    """
+    import time
+    start_time = time.time()
+    try:
+        img = decode_image(image)
+        if img is None:
+            raise HTTPException(status_code=400, detail="Invalid image file")
+
+        # 获取图片尺寸用于坐标截断
+        h_img, w_img = img.shape[:2]
+
+        ext = get_extractor()
+        # 直接调用检测器，不进行旋转校正，保证坐标对应原图
+        boxes = ext.detect_faces(img)
+
+        face_rects = []
+        if boxes:
+            for box in boxes:
+                # 原始坐标
+                x1 = float(box.x1)
+                y1 = float(box.y1)
+                x2 = float(box.x2)
+                y2 = float(box.y2)
+
+                # 应用扩充逻辑 (如果 expand_scale > 0)
+                if expand_scale > 0:
+                    w = x2 - x1
+                    h = y2 - y1
+                    cx = x1 + w / 2
+                    cy = y1 + h / 2
+
+                    new_w = w * (1 + expand_scale)
+                    new_h = h * (1 + expand_scale)
+
+                    x1 = cx - new_w / 2
+                    y1 = cy - new_h / 2
+                    x2 = cx + new_w / 2
+                    y2 = cy + new_h / 2
+
+                # 强制限制坐标在图片范围内，防止出现负数或越界
+                x1 = max(0.0, min(x1, float(w_img)))
+                y1 = max(0.0, min(y1, float(h_img)))
+                x2 = max(0.0, min(x2, float(w_img)))
+                y2 = max(0.0, min(y2, float(h_img)))
+
+                face_rects.append(FaceRect(
+                    x1=x1,
+                    y1=y1,
+                    x2=x2,
+                    y2=y2,
+                    score=float(box.score)
+                ))
+
+        return DetectFaceResponse(
+            success=True if face_rects else False,
+            message="Success" if face_rects else "No face detected",
+            faces=face_rects,
+            processing_time=time.time() - start_time
+        )
+
+    except Exception as e:
+        logger.error(f"Detection failed: {e}", exc_info=True)
+        return DetectFaceResponse(
+            success=False,
+            message=f"Server error: {str(e)}",
+            processing_time=time.time() - start_time
+        )
+
 if __name__ == "__main__":
     import argparse
     parser = argparse.ArgumentParser(description='Face Feature Extraction Microservice')

backend-java/src/main/java/com/bonuos/face/controller/UserController.java

@@ -106,4 +106,23 @@ public class UserController {
         result.put("data", count);
         return result;
     }
+
+    @PostMapping("/search")
+    public Map<String, Object> searchUser(
+            @RequestParam("photo") MultipartFile photo,
+            @RequestParam("groupId") Long groupId) {
+
+        User user = userService.searchUser(photo, groupId);
+
+        Map<String, Object> result = new HashMap<>();
+        if (user != null) {
+            result.put("code", 200);
+            result.put("msg", "success");
+            result.put("data", user);
+        } else {
+            result.put("code", 404);
+            result.put("msg", "未找到匹配用户");
+        }
+        return result;
+    }
 }

backend-java/src/main/java/com/bonuos/face/service/UserService.java

@@ -58,5 +58,14 @@ public interface UserService {
      * 
      * @param id 用户ID
      */
+    /**
+     * 人脸搜索
+     * 
+     * @param photo   人脸照片
+     * @param groupId 分组ID
+     * @return 匹配的用户（如果匹配度过低返回null）
+     */
+    User searchUser(MultipartFile photo, Long groupId);
+
     void deleteUser(Long id);
 }

backend-java/src/main/java/com/bonuos/face/service/impl/UserServiceImpl.java

@@ -41,6 +41,8 @@ public class UserServiceImpl implements UserService {
             if (userGroupMapper.selectById(groupId) == null) {
                 throw new RuntimeException("指定的用户分组不存在");
             }
+            // 检查重名
+            checkDuplicateName(name, groupId, null);
         }
 
         // 确保上传目录存在
@@ -142,6 +144,12 @@ public class UserServiceImpl implements UserService {
                 throw new RuntimeException("指定的用户分组不存在");
             }
         }
+
+        // 如果修改了名字或分组，检查重名
+        if (!user.getName().equals(name) || (groupId != null && !groupId.equals(user.getGroupId()))) {
+            checkDuplicateName(name, groupId != null ? groupId : user.getGroupId(), id);
+        }
+
         user.setName(name);
         user.setGroupId(groupId);
         user.setUpdateTime(LocalDateTime.now());
@@ -220,4 +228,90 @@ public class UserServiceImpl implements UserService {
             }
         }
     }
+
+    @Override
+    public User searchUser(MultipartFile photo, Long groupId) {
+        if (groupId == null) {
+            throw new RuntimeException("必须指定分组ID");
+        }
+
+        // 1. 保存上传的照片 (临时)
+        String fileName = IdUtil.fastSimpleUUID() + "_" + photo.getOriginalFilename();
+        File uploadDir = new File(uploadPath);
+        if (!uploadDir.exists()) {
+            uploadDir.mkdirs();
+        }
+        File dest = new File(uploadDir, fileName);
+
+        try {
+            photo.transferTo(dest);
+        } catch (IOException e) {
+            throw new RuntimeException("照片处理失败", e);
+        }
+
+        try {
+            // 2. 提取特征
+            List<Float> targetFeature = faceFeatureExtractorClient.extractFeature(dest);
+            if (targetFeature == null || targetFeature.isEmpty()) {
+                throw new RuntimeException("未能从上传图片中提取到人脸特征");
+            }
+
+            // 3. 获取分组下所有用户
+            List<User> users = getUsers(null, groupId);
+            if (users == null || users.isEmpty()) {
+                return null;
+            }
+
+            // 4. 比对特征
+            User bestMatch = null;
+            float maxSimilarity = 0f;
+            float threshold = 0.6f; // 相似度阈值
+
+            for (User user : users) {
+                if (user.getFeatureData() == null)
+                    continue;
+
+                List<Float> dbFeature = com.bonuos.face.util.FaceUtils.parseFeatureData(user.getFeatureData());
+                if (dbFeature != null) {
+                    float similarity = com.bonuos.face.util.FaceUtils.cosineSimilarity(targetFeature, dbFeature);
+                    if (similarity > maxSimilarity) {
+                        maxSimilarity = similarity;
+                        bestMatch = user;
+                    }
+                }
+            }
+
+            // 5. 返回结果
+            if (maxSimilarity >= threshold) {
+                return bestMatch;
+            }
+            return null; // 未找到匹配
+
+        } catch (Exception e) {
+            throw new RuntimeException("人脸搜索失败: " + e.getMessage(), e);
+        } finally {
+            // 清理临时文件
+            if (dest.exists()) {
+                dest.delete();
+            }
+        }
+    }
+
+    /**
+     * 检查分组下是否存在同名用户
+     */
+    private void checkDuplicateName(String name, Long groupId, Long excludeId) {
+        com.baomidou.mybatisplus.core.conditions.query.QueryWrapper<User> wrapper = new com.baomidou.mybatisplus.core.conditions.query.QueryWrapper<>();
+        wrapper.eq("group_id", groupId)
+                .eq("name", name)
+                .eq("status", 1); // 只检查有效用户
+
+        if (excludeId != null) {
+            wrapper.ne("id", excludeId);
+        }
+
+        if (userMapper.selectCount(wrapper) > 0) {
+            throw new RuntimeException("该分组下已存在名为 [" + name + "] 的用户");
+        }
+    }
 }

backend-java/src/main/java/com/bonuos/face/util/FaceUtils.java

@@ -0,0 +1,58 @@
+package com.bonuos.face.util;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import java.util.List;
+
+public class FaceUtils {
+
+    private static final ObjectMapper objectMapper = new ObjectMapper();
+
+    /**
+     * 计算两个特征向量的余弦相似度
+     *
+     * @param feature1 特征向量1
+     * @param feature2 特征向量2
+     * @return 相似度 [-1, 1]
+     */
+    public static float cosineSimilarity(List<Float> feature1, List<Float> feature2) {
+        if (feature1 == null || feature2 == null || feature1.size() != feature2.size() || feature1.isEmpty()) {
+            return -1f;
+        }
+
+        float dotProduct = 0.0f;
+        float normA = 0.0f;
+        float normB = 0.0f;
+
+        for (int i = 0; i < feature1.size(); i++) {
+            dotProduct += feature1.get(i) * feature2.get(i);
+            normA += Math.pow(feature1.get(i), 2);
+            normB += Math.pow(feature2.get(i), 2);
+        }
+
+        if (normA == 0 || normB == 0) {
+            return 0.0f;
+        }
+
+        return (float) (dotProduct / (Math.sqrt(normA) * Math.sqrt(normB)));
+    }
+
+    /**
+     * 解析特征数据字符串
+     *
+     * @param featureDataJson JSON字符串 [0.1, 0.2, ...]
+     * @return 特征列表
+     */
+    public static List<Float> parseFeatureData(String featureDataJson) {
+        if (featureDataJson == null || featureDataJson.isEmpty()) {
+            return null;
+        }
+        try {
+            return objectMapper.readValue(featureDataJson, new TypeReference<List<Float>>() {
+            });
+        } catch (Exception e) {
+            return null;
+        }
+    }
+}

quick_test_api.py

@@ -0,0 +1,103 @@
+
+import requests
+import json
+import cv2
+import numpy as np
+import os
+
+# 配置服务地址
+JAVA_BACKEND_URL = "http://localhost:18080"
+PYTHON_ALGO_URL = "http://localhost:18000"
+
+def create_test_image(filename="test_face.jpg"):
+    """创建一张简单的测试图片（如果不存在）"""
+    if not os.path.exists(filename):
+        print(f"Creating test image: {filename}...")
+        # 创建一个 640x480 的黑色图像
+        img = np.zeros((480, 640, 3), np.uint8)
+        # 画一个简单的圆代表"脸" (虽然检测不到，但可以测试文件上传流程)
+        cv2.circle(img, (320, 240), 100, (255, 255, 255), -1)
+        cv2.imwrite(filename, img)
+    return filename
+
+def test_python_health():
+    """测试 Python 算法服务健康检查"""
+    url = f"{PYTHON_ALGO_URL}/health"
+    print(f"\n[Testing] Python Algorithm Service Health ({url})...")
+    try:
+        response = requests.get(url, timeout=5)
+        if response.status_code == 200:
+            print(f"✅ Success: {response.json()}")
+        else:
+            print(f"❌ Failed: Status {response.status_code}, Response: {response.text}")
+    except requests.exceptions.ConnectionError:
+        print("❌ Failed: Connection refused. Is the service running on port 18000?")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+def test_extract_feature(image_path):
+    """测试人脸特征提取接口"""
+    url = f"{PYTHON_ALGO_URL}/api/extract_feature"
+    print(f"\n[Testing] Face Feature Extraction ({url})...")
+    
+    if not os.path.exists(image_path):
+        print("❌ Error: Test image not found.")
+        return
+
+    try:
+        with open(image_path, 'rb') as f:
+            files = {'image': f}
+            response = requests.post(url, files=files, timeout=10)
+        
+        if response.status_code == 200:
+            result = response.json()
+            if result.get('success'):
+                dim = result.get('feature_dim')
+                print(f"✅ Success: Feature extracted. Dimension: {dim}")
+            else:
+                # 预期内失败，因为我们的假脸可能过不了检测，但这证明接口通了
+                print(f"⚠️ Service Reachable (Logic Result): {result.get('message')}") 
+        else:
+            print(f"❌ Failed: Status {response.status_code}, Response: {response.text}")
+    except requests.exceptions.ConnectionError:
+        print("❌ Failed: Connection refused.")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+def test_java_group_list():
+    """测试 Java 后端分组列表接口"""
+    url = f"{JAVA_BACKEND_URL}/api/groups/list"
+    print(f"\n[Testing] Java Backend Group List ({url})...")
+    try:
+        response = requests.get(url, timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            if data.get('code') == 200:
+                print(f"✅ Success: Retrieved {len(data.get('data', []))} groups.")
+                print(f"   Response: {json.dumps(data, ensure_ascii=False)}")
+            else:
+                print(f"❌ Functional Error: {data}")
+        else:
+            print(f"❌ Failed: Status {response.status_code}, Response: {response.text}")
+    except requests.exceptions.ConnectionError:
+        print("❌ Failed: Connection refused. Is the service running on port 18080?")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+if __name__ == "__main__":
+    print("=== Face Recognition System Quick Test ===")
+    
+    # 1. 准备测试图片
+    test_img = create_test_image()
+    
+    # 2. 测试算法服务
+    test_python_health()
+    test_extract_feature(test_img)
+    
+    # 3. 测试Java后端
+    test_java_group_list()
+    
+    print("\n=== Test Finished ===")
+    # 清理生成的测试图 (可选，这里保留以便用户查看)
+    # if os.path.exists(test_img):
+    #    os.remove(test_img)

test_detect_face.py

@@ -0,0 +1,126 @@
+import requests
+import cv2
+import numpy as np
+import os
+import json
+import argparse
+import sys
+
+# 配置服务地址
+PYTHON_ALGO_URL = "http://192.168.0.37:18000"
+
+def get_default_image_path():
+    """获取一个默认存在的测试图片路径"""
+    # 尝试找一个存在的真实图片
+    potential_paths = [
+        r"C:\Users\24830\Desktop\人脸.jpg",
+    ]
+    for path in potential_paths:
+        if os.path.exists(path):
+            return path
+    return None
+
+def detect_and_draw(image_path, expand_scale=0.0):
+    url = f"{PYTHON_ALGO_URL}/api/detect_face"
+    print(f"\n[Processing] Image: {image_path}")
+    print(f"[API URL] {url}")
+    print(f"[Expand Scale] {expand_scale}")
+    
+    if not os.path.exists(image_path):
+        print(f"❌ Error: Image file not found: {image_path}")
+        return
+
+    try:
+        # 1. 准备发送请求
+        # 读取图片用于显示/画框
+        img_array = np.fromfile(image_path, dtype=np.uint8)
+        original_img = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
+        
+        if original_img is None:
+             print(f"❌ Error: Failed to read image using opencv: {image_path}")
+             return
+
+        # 2. 调用API
+        data = {'expand_scale': expand_scale}
+        with open(image_path, 'rb') as f:
+            files = {'image': f}
+            # 注意: 使用 data=data 发送表单数据，而不是 params=params (查询参数)
+            response = requests.post(url, files=files, data=data, timeout=10)
+        
+        if response.status_code != 200:
+            print(f"❌ Failed: Status {response.status_code}, Response: {response.text}")
+            return
+
+        result = response.json()
+        print("\n=== API Response ===")
+        print(json.dumps(result, indent=2))
+
+        # 3. 处理结果并画图
+        if result.get('success'):
+            faces = result.get('faces', [])
+            count = len(faces)
+            print(f"\n✅ Success: Detected {count} faces.")
+            
+            # 创建副本用于画图
+            draw_img = original_img.copy()
+
+            for i, face in enumerate(faces):
+                x1 = int(face['x1'])
+                y1 = int(face['y1'])
+                x2 = int(face['x2'])
+                y2 = int(face['y2'])
+                score = face['score']
+                
+                # 画矩形框
+                # 颜色 (B, G, R) - 绿色
+                color = (0, 255, 0)
+                thickness = 2
+                cv2.rectangle(draw_img, (x1, y1), (x2, y2), color, thickness)
+                
+                # 写文字
+                label = f"Face {i+1}: {score:.2f}"
+                cv2.putText(draw_img, label, (x1, y1 - 10), 
+                           cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 2)
+                
+                print(f"  - Face {i+1}: Box({x1}, {y1}, {x2}, {y2}), Score: {score:.4f}")
+
+                # 保存裁剪的人脸图观察效果
+                face_crop = original_img[y1:y2, x1:x2]
+                if face_crop.size > 0:
+                    crop_filename = f"face_crop_{i+1}_scale_{expand_scale}.jpg"
+                    cv2.imencode('.jpg', face_crop)[1].tofile(crop_filename)
+                    print(f"    Saved crop: {crop_filename}")
+
+            # 4. 保存结果图
+            output_filename = f"result_detected_scale_{expand_scale}.jpg"
+            cv2.imencode('.jpg', draw_img)[1].tofile(output_filename)
+            print(f"\n✅ Result image saved to: {os.path.abspath(output_filename)}")
+            
+        else:
+            print(f"⚠️ API logic returned failure: {result.get('message')}") 
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Face Detection API Test Script')
+    parser.add_argument('image_path', nargs='?', help='Path to the image file')
+    parser.add_argument('--scale', type=float, default=0.6, help='Expand scale (default: 0.0)')
+    
+    args = parser.parse_args()
+    
+    target_path = args.image_path
+    
+    if not target_path:
+        default_path = get_default_image_path()
+        if default_path:
+            print(f"No image path provided, using default found: {default_path}")
+            target_path = default_path
+        else:
+            print("Usage: python test_detect_face.py <path_to_image> [--scale 0.3]")
+            print("Error: No image path provided and no default test image found.")
+            sys.exit(1)
+            
+    detect_and_draw(target_path, args.scale)

verify_changes.py

@@ -0,0 +1,78 @@
+
+import requests
+import json
+import os
+
+# 配置
+BASE_URL = "http://localhost:18080/api"
+GROUP_NAME = "TestGroup_Verify"
+USER_NAME = "DuplicateTestUser"
+TEST_IMG = "verify_face.jpg"
+
+def create_test_image():
+    if not os.path.exists(TEST_IMG):
+        # 创建一个简单的dummy文件
+        with open(TEST_IMG, 'wb') as f:
+            f.write(b'\xFF\xD8\xFF\xE0' + b'\x00' * 1000) # Fake JPG header
+    return TEST_IMG
+
+def run_verification():
+    print("=== 开始验证 ===")
+    
+    # 1. 创建测试分组
+    print("\n1. 创建分组...")
+    resp = requests.post(f"{BASE_URL}/groups/add", json={"name": GROUP_NAME})
+    if resp.status_code == 200 and resp.json()['code'] == 200:
+        group_id = resp.json()['data']['id']
+        print(f"✅ 分组创建成功 ID: {group_id}")
+    else:
+        print(f"❌ 分组创建失败: {resp.text}")
+        return
+
+    # 准备图片
+    create_test_image()
+    files = {'photo': open(TEST_IMG, 'rb')}
+    
+    # 2. 添加用户 (第一次)
+    print("\n2. 添加用户 (预期成功)...")
+    data = {"name": USER_NAME, "groupId": group_id}
+    # Re-open file for each request
+    resp = requests.post(f"{BASE_URL}/users/add", data=data, files={'photo': open(TEST_IMG, 'rb')})
+    
+    if resp.status_code == 200 and resp.json()['code'] == 200:
+        print(f"✅ 用户创建成功")
+    else:
+        # 如果是因为测试图片无法提取特征而失败，也是预期的(说明代码跑到了特征提取那一步)
+        # 但我们主要验证重名逻辑，所以这里假设如果失败是因为重名则是有问题，如果是因为特征提取则是环境问题
+        print(f"⚠️ 用户创建返回: {resp.json().get('msg')}")
+
+    # 3. 添加同名用户 (预期失败)
+    print("\n3. 再次添加同名用户 (预期被拦截)...")
+    resp = requests.post(f"{BASE_URL}/users/add", data=data, files={'photo': open(TEST_IMG, 'rb')})
+    
+    res_json = resp.json()
+    if res_json.get('code') != 200 and "已存在" in str(res_json.get('msg')):
+        print(f"✅ 成功拦截重名用户: {res_json.get('msg')}")
+    else:
+        print(f"❌ 拦截失败或错误信息不匹配: {resp.text}")
+
+    # 4. 测试搜索接口
+    print("\n4. 测试人脸搜索接口...")
+    try:
+        resp = requests.post(f"{BASE_URL}/users/search", data={"groupId": group_id}, files={'photo': open(TEST_IMG, 'rb')})
+        if resp.status_code == 200:
+            print(f"✅ 接口调用成功: {resp.json()}")
+        elif resp.status_code == 404:
+             print(f"✅ 接口调用成功 (未找到匹配 - 符合预期): {resp.json()}")
+        else:
+            print(f"❌ 接口调用异常: {resp.status_code} - {resp.text}")
+    except Exception as e:
+        print(f"❌ 请求异常: {e}")
+
+    print("\n=== 验证结束 ===")
+
+if __name__ == "__main__":
+    try:
+        run_verification()
+    except Exception as e:
+        print(f"Fatal Error: {e}")