添加 api.md

2025-09-26 02:59:05 +00:00 · 2025-09-26 02:59:05 +00:00 · 87e8bd1a12
commit 87e8bd1a12
parent 0a22540829
1 changed files with 80 additions and 0 deletions
--- a/api.md
+++ b/api.md
@ -0,0 +1,80 @@
+# 乐聚仿真机器人躯干控制能力接口
+
+## 接口列表
+- [躯干控制任务启动](#躯干控制任务启动)
+- [躯干控制任务取消](#躯干控制任务取消)
+### task_type
+| task_type         | 任务说明     |
+| ----------------- | ----------- |
+| 0                 |  躯干控制任务  |
+
+## 轮臂机器人躯干控制任务启动
+
+### 请求地址
+`POST /api/task/start_task`
+
+### 请求参数
+|      字段名        |     类型    | 必填 | 默认值 |    说明     |        示例值       |
+| ----------------- | ----------- | ---- | ----- |------------ | ------------------- |
+| task_type         | int64       |  是  |       |  任务类型id  |          0          |
+| payload           | object      |  是  |       | 任务输入参数 |                     |
+| ├─ angle1            | float       |  是  |       | 弧度，仿真不起作用 |         0.4          |
+| ├─ angle2          | float       |  是  |       | 弧度，仿真不起作用 |         0.4          |
+| ├─ angle3          | float       |  是  |       | 弧度 |         0.4          |
+| ├─ yaw          | float       |  是  |       | 角度 |         90          |
+### 响应参数
+| 字段名         | 类型   | 说明            | 示例值                                   |
+| -------------- | ------ | -------------- | --------------------------------------- |
+| task_id        | string | 任务id         | "e5672a6e-0bc2-4646-a019-dd914034e3ed"   |
+
+示例请求
+``` json
+{
+    "task_type": 0,
+    "payload": {
+        "angle1": 0.7,
+        "angle2": -1.4,
+        "angle3": -0.7,
+        "yaw": -1.57
+    }
+}
+```
+示例返回
+``` json
+{
+    "task_id": "e5672a6e-0bc2-4646-a019-dd914034e3ed"
+}
+```
+需要根据task_id向能力框架查询任务执行情况。
+如果执行成功或执行中，在向能力框架查询到的任务执行情况status字段为running或finished
+如果执行失败，在向能力框架查询到的任务执行情况status字段为error
+
+## 轮臂机器人头部控制任务取消
+
+### 请求地址
+`POST /api/task/cancel_task`
+
+### 请求参数
+|      字段名        |     类型    | 必填 | 默认值 |    说明     |        示例值       |
+| ----------------- | ----------- | ---- | ----- |------------ | ------------------- |
+| task_type         | int64       |  是  |       |  任务类型id  |          0          |
+### 响应参数
+| 字段名         | 类型   | 说明            | 示例值                                   |
+| -------------- | ------ | -------------- | --------------------------------------- |
+| task_id        | string | 任务id         | "e5672a6e-0bc2-4646-a019-dd914034e3ed"   |
+
+示例请求
+``` json
+{
+    "task_type": 0,
+}
+```
+示例返回
+``` json
+{
+    "task_id": "e5672a6e-0bc2-4646-a019-dd914034e3ed"
+}
+```
+需要根据task_id向能力框架查询任务执行情况。
+如果执行成功或执行中，在向能力框架查询到的任务执行情况status字段为running或finished
+如果执行失败，在向能力框架查询到的任务执行情况status字段为error