Web_PMSApi_Server_V1_Prod/BLWWS/图片校验工具使用文档.md

# **宝来威 人脸提交接口优化说明文档**

**处理流程说明图例：**



```mermaid
flowchart TD
    A[入驻流程开始]:::startEnd --> B[开房信息录入]
    B --> C[调用PMS接口 获取CheckInID]
    C --> D[照片截取]
    D --> E[调用图片质量检测模块]:::critical
    E --> F{图片质量分值合格}
    F -- 否 --> D
    F -- 是 --> G[调用UploadPhoto接口上传图片]
    G --> H{返回成功}
    H -- 否 --> I[提示人脸机不可用 向前台索取门卡开门]:::warning
    H -- 是 --> J[入驻流程完成]:::startEnd
    I --> J
    
    classDef startEnd fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef critical fill:#FFC0CB,stroke:#333,stroke-width:1px;
    classDef warning fill:#FFA500,stroke:#333,stroke-width:1px;
    class E critical
```

# 一、UploadPhoto 修改说明

这部分将说明如何调用`faceidtest.exe`可执行文件进行人脸验证，并提人脸验证工具调用说明

**修改返回值 `Msg` 规则：**

- 有问题时返回对应错误信息
- 同时确认图片分辨率和人脸机在线状态
- 二者都满足时直接返回 `OK (200)`

新增返回值代码表：

| Code | Msg                |
| ---- | ------------------ |
| 200  | 图片上传成功       |
| 301  | 图片分辨率过高     |
| 302  | 图片分辨率过低     |
| 403  | 人脸机离线或不可用 |

# 二、图片质量检测模块调用说明

这部分将说明如何调用`faceidtest.exe`可执行文件进行人脸验证，并提供C#调用示例代码。

**说明**：本应用生成的quality值，是一个相对参考值，推荐值：*** > 0.5**

## 📍 准备工作

1. **放置可执行文件**
    确保`faceidtest.exe`位于项目的 `ValRel` 子目录中：

   ```cmake
   Project_Root/
   ├── ValRel/
   │   └── faceidtest.exe
   ├── Controllers/
   └── ...
   ```

2. **NuGet 包依赖（C#环境）**
    安装以下依赖包：

   ```json
   Install-Package CliWrap
   ```

## ⚙️ 执行流程概述

```mermaid
flowchart TD
    A[接收图片路径] --> B{参数校验}
    B -- 路径为空 --> C[返回400错误]
    B -- 文件不存在 --> D[返回400错误]
    B -- 参数有效 --> E[准备执行环境]
    E --> F{exe文件校验}
    F -- 不存在 --> G[返回500错误]
    F -- 存在 --> H[执行外部进程]
    H --> I[解析输出]
    I --> J{验证结果}
    J -- 成功 --> K[返回质量分数]
    J -- 失败 --> L[返回错误]
```

## 📝 调用参数说明

| 参数           | 类型   | 必需 | 说明                              |
| -------------- | ------ | ---- | --------------------------------- |
| localImagePath | string | 是   | 本地图片文件的**绝对路径**        |
| exeArguments   | string | 是   | 固定参数格式：`{图片路径} 80x v3` |

## 🧩 C# 完整调用示例

```c#
[HttpPost]
public async Task<IActionResult> FaceValidator(string localImagePath)
{
    // 1. 参数基础校验
    if (string.IsNullOrWhiteSpace(localImagePath))
    {
        return BadRequest("图片路径不能为空");
    }
    if (!File.Exists(localImagePath))
    {
        return BadRequest($"图片文件不存在: {localImagePath}");
    }

    // 2. 确定exe执行路径
    var exePath = Path.Combine(_hostingEnvironment.ContentRootPath, "ValRel", "faceidtest.exe");
    var exeDirectory = Path.GetDirectoryName(exePath);
    
    if (!File.Exists(exePath))
    {
        _logger.LogError($"可执行文件缺失: {exePath}");
        return StatusCode(500, "人脸验证程序未找到");
    }

    try
    {
        // 3. 配置输出捕获
        var stdOutBuffer = new StringBuilder();
        var stdErrBuffer = new StringBuilder();
        var arguments = $"{localImagePath} 80x v3";  // 固定参数格式

        // 4. 执行外部进程（20秒超时）
        using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(20));
        
        // 核心执行方法
        var result = await Cli.Wrap(exePath)
            .WithArguments(arguments)
            .WithWorkingDirectory(exeDirectory)
            .WithValidation(CommandResultValidation.None)
            .WithStandardOutputPipe(PipeTarget.ToStringBuilder(stdOutBuffer))
            .WithStandardErrorPipe(PipeTarget.ToStringBuilder(stdErrBuffer))
            .ExecuteAsync(cts.Token);

        // 5. 处理输出结果
        var fullOutput = $"{stdErrBuffer}{stdOutBuffer}";
        string[] lines = fullOutput.Split(["\r\n", "\r", "\n"], StringSplitOptions.None);
        
        var validationResult = "";
        foreach (var line in lines)
        {
            if (line.Contains("quality:"))
            {
                validationResult = line.Split(':')[2].Trim();
                break;
            }
        }

        // 6. 构造返回数据
        var baseUrl = "http://your-domain.com/upload/";  // 替换为实际地址
        var imageUrl = baseUrl + Path.GetFileName(localImagePath);
        
        if (double.TryParse(validationResult, out double qualityScore))
        {
            return Ok(new
            {
                Success = true,
                Quality = qualityScore,
                ImageUrl = imageUrl
            });
        }
        return Ok(new
        {
            Success = false,
            Message = "验证结果解析失败",
            ImageUrl = imageUrl
        });
    }
    catch (OperationCanceledException)
    {
        _logger.LogError("验证超时");
        return StatusCode(504, "验证超时");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "验证异常");
        return StatusCode(500, $"系统错误: {ex.Message}");
    }
}
```

## 🔍 关键功能说明

### 参数校验

- 空路径检查：确保传入有效的文件路径
- 文件存在性检查：验证图片实际存在于磁盘

### 安全执行

- **绝对路径构造**：使用`ContentRootPath`确保路径可靠性
- **工作目录设置**：在exe所在目录执行避免路径问题
- **超时控制**：20秒执行超时机制（可根据需要调整）

### 结果解析

1. 合并标准输出和错误流
2. 识别关键行：查找包含`quality:`的输出行
3. 提取质量分数：从`quality:value`格式的第三部分获取数值

## ⚠️ 重要注意事项

1. **输出格式依赖**
    结果解析基于特定输出格式：

   ```c#
   [输出行示例] <文件名>.jpg quality: 0.66
   ```

2. **权限要求**
    应用需要以下权限：

   - 读取`ValRel`目录的执行权限
   - 访问图片文件的读权限
   - 写入日志文件的权限

3. **URL构造**
    替换示例中的`baseUrl`为实际图片服务地址：

   ```c#
   var baseUrl = "http://your-actual-service.com/uploads/";
   ```

4. **超时调整**
    根据实际硬件性能调整超时时间：

   ```c#
   // 调整超时为30秒
   new CancellationTokenSource(TimeSpan.FromSeconds(30))
   ```

5. **日志监控**
    建议添加详细日志记录：

   ```c#
   _logger.LogInformation($"启动人脸验证: {localImagePath}");
   _logger.LogDebug($"完整输出: {fullOutput}");
   ```