hik3d-python/config/接口说明

以下是您当前 Flask 应用中已实现的两个主要接口的 **API 接口文档**，采用标准 RESTful 风格描述。

---

## 🌐 接口文档

### 1. 更新配置 `/config/update`

#### ✅ 方法
- `GET`

#### 📦 描述
- 重新加载所有配置文件（相机、裁剪、模板等），用于刷新服务端配置。

#### 📤 响应示例

```json
{
  "message": "Hello, this service config update!",
  "status": "OK"
}
```


---

### 2. 添加/更新模板配置 `/api/addTemplate`

#### ✅ 方法
- `POST`

#### 📦 描述
- 接收一个 JSON 对象，以 `"type"` 字段作为文件名，保存为 `./config/template/{type}.json`。
- 支持覆盖写入已有模板。
- 写入成功后自动调用 [config.load_configs()](file://D:\git\test\hik3d-python\config.py#L82-L89) 刷新配置。

#### 📥 请求体（JSON）

| 字段名      | 类型   | 必填 | 示例值    | 描述               |
|-------------|--------|------|-----------|--------------------|
| type        | string | ✅   | "45"      | 模板名称             |
| width       | string | ❌   | "299"     | 模板宽度（暂无作用）  |
| length      | string | ❌   | "355"     | 模板长度（暂无作用）  |
| height      | number | ✅   | 314       | 最高高度（单位：毫米）|
| min_area    | number | ✅   | 20        | 空洞最小面积         |
| tolerance   | number | ✅   | 30        | 容差范围（单位：毫米）|

##### 示例请求体：

```json
{
  "type": "45",
  "width": "299",
  "length": "355",
  "height": 314,
  "min_area": 20,
  "tolerance": 30
}
```


#### 📤 成功响应

```json
{
  "status": "OK",
  "message": "Template '45' saved successfully."
}
```


#### 📤 错误响应

- 缺少数据：
  ```json
  {
    "status": "ERROR",
    "message": "No data provided"
  }
  ```


- 缺少 `type`：
  ```json
  {
    "status": "ERROR",
    "message": "Missing 'type' field"
  }
  ```


- 写入失败：
  ```json
  {
    "status": "ERROR",
    "message": "Failed to save template: [错误信息]"
  }
  ```


---

### 3. 图像处理与空洞检测 `/api/picCompute`

#### ✅ 方法
- `POST`

#### 📦 描述
- 根据设备编号和模板类型，获取点云并检测是否存在大空洞。
- 调用了 [SimpleView_SaveImage.pic()](file://D:\git\test\hik3d-python\SimpleView_SaveImage.py#L53-L137) 和 [image.detect_large_holes()](file://D:\git\test\hik3d-python\image.py#L187-L208)。

#### 📥 请求体（JSON）

| 字段名 | 类型   | 必填 | 示例值     | 描述           |
|--------|--------|------|------------|----------------|
| sn     | string | ✅   | "00DA6823936" | 设备序列号       |
| type   | string | ✅   | "45"       | 模板类型（对应模板配置） |

##### 示例请求体：

```json
{
  "sn": "00DA6823936",
  "type": "45"
}
```


#### 📤 成功响应

```json
{
  "message": true,
  "status": "OK"
}
```


> `message` 表示是否检测到空洞：
> - `true`：有空洞
> - `false`：无空洞

#### 📤 错误响应

- 缺少参数：
  ```json
  {
    "message": "",
    "status": "ERROR",
    "error": "Missing required parameter: 'sn'"
  }
  ```


- 模板不存在：
  ```json
  {
    "message": "",
    "status": "ERROR",
    "error": "Missing required parameter: 'type'"
  }
  ```


- 其他异常：
  ```json
  {
    "message": "",
    "status": "ERROR",
    "error": "Failed to get TIFF paths: [错误信息]"
  }
  ```


---

## ⚠️ 全局异常处理

所有未捕获的异常都会被全局异常处理器捕获，并返回如下格式：

```json
{
  "message": "",
  "status": "ERROR",
  "error": "[错误信息]"
}
```


---