face_reg_docker/API_DOCUMENTATION.md

# 人脸识别系统 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"}`