304 lines
7.4 KiB
Markdown
304 lines
7.4 KiB
Markdown
# 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 | 数据上传/结束 |
|