core_wing_web/docs/backend-api.md

Corewing QC 后端接口文档

基础路径: /api/qc

通用响应结构

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

{
  "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

请求体

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

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

响应

{
  "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

请求体

{
  "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	否	完成时间（毫秒时间戳字符串）

响应

{
  "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等)

响应

{
  "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

请求体

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

响应

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

---

5. 获取测试配置

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

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

响应

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

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

---

6. 查询 SN 历史记录

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

响应

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

---

7. 获取测试报告

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

响应

{
  "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	数据上传/结束