core_wing_web/docs/backend-api.md

# Corewing QC 后端接口文档

> 基础路径: `/api/qc`

## 通用响应结构

所有接口统一返回 `Result<T>`:

```json
{
  "code": 200,
  "message": "操作成功",
  "data": T,
  "success": true
}
```

| 字段    | 类型    | 说明                       |
|---------|---------|---------------------------|
| code    | Integer | 状态码                     |
| message | String  | 消息内容                   |
| data    | T       | 业务数据                   |
| success | Boolean | 是否成功                   |

---

## 1. 验证无线板

验证 BLE MAC 地址对应的无线板是否已在系统中注册。

- **URL**: `POST /api/qc/wireless/validate-wireless`
- **Content-Type**: `application/json`

### 请求体

```json
{
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

| 字段 | 类型   | 必填 | 说明                             |
|------|--------|------|----------------------------------|
| mac  | String | 是   | BLE MAC 地址，即设备 SN          |

### 响应

```json
{
  "code": 200,
  "message": "验证通过",
  "data": true,
  "success": true
}
```

- `data = true` — 设备已注册，允许进行 QC 测试
- `data = false` / `success = false` — 设备未注册或验证失败，APP 端将**作废本次测试**

---

## 2. 上传测试记录

上传完整的 QC 测试结果（含所有步骤数据和照片 URL）。

- **URL**: `POST /api/qc/test/upload`
- **Content-Type**: `application/json`

### 请求体

```json
{
  "testNo": "WL-20260227-001",
  "productType": "WIRELESS_BOARD",
  "sn": "AA:BB:CC:DD:EE:FF",
  "operatorId": "OP001",
  "operatorName": "张三",
  "phoneModel": "Pixel 7",
  "appVersion": "1.0.0",
  "status": "PASS",
  "createTime": "1740000000000",
  "updatedAt": "1740001000000",
  "uploadTime": "1740002000000",
  "steps": [
    {
      "stepIndex": 1,
      "stepName": "BLE连接与特征订阅",
      "result": "PASS",
      "dataJson": "{\"deviceName\":\"CoreWing-001\",\"deviceMac\":\"AA:BB:CC:DD:EE:FF\",\"validated\":true}",
      "duration": 5200,
      "completedAt": "1740000500000"
    }
  ],
  "photoUrls": [
    "https://qc.corewing.com/photos/xxx.jpg"
  ]
}
```

| 字段         | 类型             | 必填 | 说明                                           |
|--------------|------------------|------|------------------------------------------------|
| testNo       | String           | 是   | 测试单号，格式: `WL-yyyyMMdd-NNN` 或 `FC-yyyyMMdd-NNN` |
| productType  | String           | 是   | `WIRELESS_BOARD` / `FLIGHT_CONTROLLER`         |
| sn           | String           | 是   | 产品序列号（无线板为 BLE MAC 地址）            |
| operatorId   | String           | 是   | 测试员 ID                                      |
| operatorName | String           | 是   | 测试员姓名                                     |
| phoneModel   | String           | 否   | 测试手机型号                                   |
| appVersion   | String           | 否   | APP 版本号                                     |
| status       | String           | 是   | `PASS` / `FAIL`                                |
| createTime   | String           | 是   | 创建时间（毫秒时间戳字符串）                   |
| updatedAt    | String           | 否   | 最后更新时间（毫秒时间戳字符串）               |
| uploadTime   | String           | 否   | 上传时间（毫秒时间戳字符串）                   |
| steps        | StepResultData[] | 是   | 步骤结果数组                                   |
| photoUrls    | String[]         | 否   | 已上传照片的远程 URL 列表                      |

**StepResultData:**

| 字段        | 类型   | 必填 | 说明                                 |
|-------------|--------|------|--------------------------------------|
| stepIndex   | int    | 是   | 步骤序号（从 1 开始）                |
| stepName    | String | 是   | 步骤名称                             |
| result      | String | 否   | `PASS` / `FAIL` / null（未完成）     |
| dataJson    | String | 否   | 步骤详细数据 JSON 字符串             |
| duration    | long   | 否   | 步骤耗时（毫秒）                     |
| completedAt | String | 否   | 完成时间（毫秒时间戳字符串）         |

### 响应

```json
{
  "code": 200,
  "message": "上传成功",
  "data": "https://qc.corewing.com/report/WL-20260227-001",
  "success": true
}
```

- `data` — 测试报告 URL（可为 null）

---

## 3. 上传照片

上传测试步骤关联的照片。

- **URL**: `POST /api/qc/test/upload-photo`
- **Content-Type**: `multipart/form-data`

### 请求参数

| 字段   | 类型          | 必填 | 说明             |
|--------|---------------|------|------------------|
| testNo | String (text) | 是   | 测试单号         |
| photo  | File          | 是   | 照片文件 (JPEG等)|

### 响应

```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "https://qc.corewing.com/photos/xxx.jpg"
  },
  "success": true
}
```

---

## 4. 验证 SN

验证序列号是否有效（飞控板扫码流程使用）。

- **URL**: `POST /api/qc/test/validate-sn`
- **Content-Type**: `application/json`

### 请求体

```json
{
  "sn": "FC-SN-20260001"
}
```

### 响应

```json
{
  "code": 200,
  "message": "SN 有效",
  "data": true,
  "success": true
}
```

---

## 5. 获取测试配置

获取指定产品类型的测试参数/阈值。

- **URL**: `GET /api/qc/config/test-params?productType=WIRELESS_BOARD`

### 响应

```json
{
  "code": 200,
  "success": true,
  "data": { }
}
```

> `data` 结构由后端自定义，APP 当前未使用。

---

## 6. 查询 SN 历史记录

- **URL**: `GET /api/qc/test/history?sn=AA:BB:CC:DD:EE:FF`

### 响应

```json
{
  "code": 200,
  "success": true,
  "data": { }
}
```

---

## 7. 获取测试报告

- **URL**: `GET /api/qc/test/report?testNo=WL-20260227-001`

### 响应

```json
{
  "code": 200,
  "success": true,
  "data": "https://qc.corewing.com/report/WL-20260227-001"
}
```

---

## 枚举值参考

### productType（产品类型）

| 值                  | 说明   |
|---------------------|--------|
| WIRELESS_BOARD      | 无线板 |
| FLIGHT_CONTROLLER   | 飞控板 |

### status（测试状态）

| 值          | 说明     |
|-------------|----------|
| IN_PROGRESS | 进行中   |
| PASS        | 通过     |
| FAIL        | 失败     |
| UPLOADED    | 已上传   |

### result（步骤结果）

| 值   | 说明 |
|------|------|
| PASS | 通过 |
| FAIL | 失败 |

### 无线板测试步骤（7 步）

| stepIndex | stepName               |
|-----------|------------------------|
| 1         | BLE连接与特征订阅       |
| 2         | 安装无线板/外观检查     |
| 3         | 供电测试(4.5V)          |
| 4         | Type-C USB测试          |
| 5         | BLE信号质量测试         |
| 6         | MAVLink心跳通信测试     |
| 7         | 激活/入库               |

### 飞控板测试步骤（12 步）

| stepIndex | stepName        |
|-----------|-----------------|
| 1         | USB串口连接      |
| 2         | 安装SD卡与装夹   |
| 3         | 心跳检测         |
| 4         | IMU测试          |
| 5         | 气压计测试       |
| 6         | GPS模块检测      |
| 7         | RC输入测试       |
| 8         | ADC接口测试      |
| 9         | PWM输出测试      |
| 10        | 图传与OSD检查    |
| 11        | 参数重置         |
| 12        | 数据上传/结束    |