FST/fst_data_pipeline-feature-editor-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

第一次

Browse Source
This commit is contained in:
ZhuJW
2026-04-16 15:44:32 +08:00
commit 5a98242f2f
171 changed files with 42954 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

676
fst_data_pipeline/apps/API.md Normal file
View File

@@ -0,0 +1,676 @@
ROOT DB API 使用文档
========================
> 版本：1.0.0
---
目录
----
* [Bags](#bags)
* [FST](#fst)
* [Geometry](#geometry)
* [Projects](#projects)
* [Tags](#tags)
* [Topics](#topics)
---
Bags
----
### 1. 获取全部 Bags（按项目分组）
```
GET /api/bags/all
```
#### 请求示例
```
curl https://<host>/api/bags/all
```
#### 成功响应 200
```json
{
"Project A": ["Bag 1", "Bag 2"],
"Uncategorized": ["Bag 3"]
}
```
#### 错误响应 500
```json
{"error": "An error occurred"}
```
---
### 2. 批量查询 FST 节点
```
POST /api/bags/fst/nodes
```
#### 请求体
```json
["a.bag", "b.bag"]
```
#### 请求示例
```
curl -X POST https://<host>/api/bags/fst/nodes \
-H "Content-Type: application/json" \
-d '["a.bag", "b.bag"]'
```
#### 成功响应 200
```json
{
"a.bag": [
{"name": "node1", "start": 0, "end": 10},
{"name": "node2", "start": 11, "end": 20}
],
"b.bag": [
{"name": "node3", "start": 21, "end": 30}
]
}
```
#### 错误响应
- `400`：Body must be a list of bag names
- `500`：An error occurred
---
### 3. 获取生命周期信息
```
POST /api/bags/life_cycle
```
#### 请求体
```json
{"bag_names": ["a.bag", "b.bag"]}
```
#### 请求示例
```
curl -X POST https://<host>/api/bags/life_cycle \
-H "Content-Type: application/json" \
-d '{"bag_names": ["a.bag", "b.bag"]}'
```
#### 成功响应 200
```json
{
"a.bag": {
"collect_time": "2025-07-16T00:00:00Z",
"decode_time": "2025-07-16T01:00:00Z",
"fst_index_time": "2025-07-16T02:00:00Z",
"mining_time": "2025-07-16T03:00:00Z",
"auto_annotate_time": "2025-07-16T04:00:00Z",
"manual_annotate_time": "2025-07-16T05:00:00Z",
"clone2dev_time": "2025-07-16T06:00:00Z"
},
"b.bag": { }
}
```
---
### 4. 批量查询 Minerva 主记录（按 session_id）
```
POST /api/bags/minerva
```
#### 请求体
```json
{"session_ids": ["p1.bag", "p2.bag"]}
```
#### 请求示例
```
curl -X POST https://<host>/api/bags/minerva \
-H "Content-Type: application/json" \
-d '{"session_ids": ["p1.bag", "p2.bag"]}'
```
#### 成功响应 200
```json
{
"p1.bag": [{
"session_id": "p1.bag",
"vin": "L123456789",
"platform": "Platform A",
"start_ts": 1626307200,
"end_ts": 1626314400,
"length": 7200,
"datetime": "2025-07-16T00:00:00Z",
"path": "/path/to/bag",
"converted_path": "/path/to/converted",
"gt_path": "/path/to/gt",
"reserved_json": {}
}],
"p2.bag": []
}
```
---
### 5. 批量查询 Minerva 详情（按 bag name）
```
POST /api/bags/minerva/detail
```
#### 请求体
```json
["p1.bag", "p2.bag"]
```
#### 请求示例
```
curl -X POST https://<host>/api/bags/minerva/detail \
-H "Content-Type: application/json" \
-d '["p1.bag", "p2.bag"]'
```
#### 响应格式同 `/api/bags/minerva`
---
### 6. 批量查询 Pangu 主记录
```
POST /api/bags/pangu
```
#### 请求体
```json
{"names": ["name1", "name2"]}
```
#### 请求示例
```
curl -X POST https://<host>/api/bags/pangu \
-H "Content-Type: application/json" \
-d '{"names": ["name1", "name2"]}'
```
#### 成功响应 200
```json
{
"name1": [{
"name": "Pangu 1",
"datetime": "2025-07-16T00:00:00Z",
"vehicle": "Vehicle A",
"raw_bag_path": "/path/to/bag",
"decoded_path": "/path/to/decoded",
"reserved_str": "Some reserved string",
"reserved_json": {}
}],
"name2": []
}
```
---
### 7. 批量查询 Pangu 详情（按 bag name）
```
POST /api/bags/pangu/detail
```
#### 请求体
```json
["bag1.bag", "bag2.bag"]
```
#### 请求示例
```
curl -X POST https://<host>/api/bags/pangu/detail \
-H "Content-Type: application/json" \
-d '["bag1.bag", "bag2.bag"]'
```
#### 成功响应 200
```json
{
"bag1.bag": {"detail": "...", "other_property": "..."},
"bag2.bag": {"detail": "...", "other_property": "..."}
}
```
---
### 8. 搜索 Main Pangu
```
POST /api/bags/search/pangu
```
#### 请求体
```json
{
"name": "Pangu 1",
"vehicle": "Vehicle A",
"datetime_from": "2025-07-16 00:00:00",
"datetime_to": "2025-07-16 23:59:59"
}
```
字段均可选。
#### 请求示例
```
curl -X POST https://<host>/api/bags/search/pangu \
-H "Content-Type: application/json" \
-d '{"name": "Pangu 1"}'
```
#### 成功响应 200
```json
[
{
"name": "Pangu 1",
"datetime": "2025-07-16T00:00:00Z",
"vehicle": "Vehicle A"
}
]
```
---
### 9. 聚合查询列表
```
POST /api/bags/search/aggregate?page=1&per_page=20
```
#### 请求参数
参数来源说明：
- collect_start / collect_end：前端日期选择
- vehicles：GET /api/bags/vehicles
- sw_version / hw_version：GET /api/bags/versions
- topics：GET /api/topics/all
- tags：GET /api/tags/all
- gt_names：GET /api/gt/types
- fst_level1：GET /api/fst/print_tree（取 level=1 的节点名；或用 /api/fst/all_nodes 过滤根节点子节点）
Query 参数：
- page: 页码，默认 1
- per_page: 每页数量，默认 20，最大 100
- debug_sql: 是否打印 SQL（仅日志输出），默认 false
Body 字段（均可选）：
- collect_start: 起始日期，基于 MainPangu.datetime，格式 YYYYMMDD，例如 "20250101"
- collect_end: 结束日期，基于 MainPangu.datetime，格式 YYYYMMDD，例如 "20250131"
- bag_name: bag 名称模糊匹配（支持 * 通配），例如 "xxx*2025*"
- gt_names: GT 名称列表（OR 语义）
- fst_level1: FST 一级节点名称（包含其子孙节点）
- vehicles: 车号列表（OR 语义，精确匹配）
- sw_version: 软件版本，支持 * 通配，例如 "v1.*" 或 "*2024*"
- hw_version: 硬件版本，支持 * 通配
- topics: Topic 名称列表（OR 语义）
- tags: Tag 名称列表（OR 语义）
#### 请求体示例
```json
{
"collect_start": "20250101",
"collect_end": "20250131",
"bag_name": "xxx*2025*",
"gt_names": ["gt_a", "gt_b"],
"fst_level1": "root_fst",
"vehicles": ["PL061763"],
"sw_version": "v1.*",
"hw_version": "h1.*",
"topics": ["topic_a", "topic_b"],
"tags": ["tag_a", "tag_b"]
}
```
#### 请求示例
```
curl -X POST "https://<host>/api/bags/search/aggregate?page=1&per_page=20&debug_sql=true" \
-H "Content-Type: application/json" \
-d '{"collect_start":"20250101","collect_end":"20250131","bag_name":"xxx*2025*","gt_names":["gt_a"],"fst_level1":"root_fst","vehicles":["PL061763"],"sw_version":"v1.*","hw_version":"h1.*","topics":["topic_a"],"tags":["tag_a"]}'
```
#### 响应字段
- items: 列表
- bag_id: bag_list.id
- bag_name: bag 名称
- bag_path: 原始 bag 路径（空则返回 ""）
- data_path: 解析后数据路径（空则返回 ""）
- datetime: MainPangu.datetime（YYYY-MM-DD HH:MM:SS，空则返回 ""）
- collect_time: BagLifecycle.collect_time（YYYY-MM-DD HH:MM:SS，空则返回 ""）
- vehicle: 车号（空则返回 ""）
- sw_version: 软件版本（空则返回 ""）
- hw_version: 硬件版本（空则返回 ""）
- mviz_link: 可视化链接（预留，当前为空字符串）
- mbviz_link: 可视化链接（预留，当前为空字符串）
- fst: FST 路径数组（可能多条，level1 对应业务一级节点，level0(root) 不返回）
- level1/level2/level3/level4: 对应层级节点对象，缺失则为 {}
- gt: 关联 GT 列表（包含 id/name/type/path/comment）
- topics: 关联 Topic 列表（包含 id/name/type）
- tags: 关联 Tag 列表（包含 id/name/type/creator）
- page: 当前页
- per_page: 每页数量
- total: 总数
#### 成功响应 200
```json
{
"items": [
{
"bag_id": 123,
"bag_name": "xxx.bag",
"bag_path": "/path/to/bag",
"data_path": "/path/to/data",
"datetime": "2025-07-16 00:00:00",
"collect_time": "2025-07-16 00:00:00",
"vehicle": "PL061763",
"sw_version": "v1.2.3",
"hw_version": "h1.0",
"mviz_link": "",
"mbviz_link": "",
"fst": [
{
"level1": {"id": 1, "name": "L1"},
"level2": {"id": 2, "name": "L2"},
"level3": {"id": 3, "name": "L3"},
"level4": {"id": 4, "name": "L4"}
}
],
"gt": [
{"id": 10, "name": "gt_a", "type": "3DBox", "path": "/path/to/gt", "comment": "备注"}
],
"topics": [
{"id": 20, "name": "topic_a", "type": "sensor_msgs/PointCloud2"}
],
"tags": [
{"id": 30, "name": "tag_a", "type": "user", "creator": "alice"}
]
}
],
"page": 1,
"per_page": 20,
"total": 123
}
```
---
### 10. 获取可用版本列表
```
GET /api/bags/versions
```
#### 请求示例
```
curl https://<host>/api/bags/versions
```
#### 成功响应 200
```json
{
"sw_versions": ["v1.0", "v1.1", "v2.0"],
"hw_versions": ["h1.0", "h2.0"]
}
```
---
### 11. 获取可用车号列表
```
GET /api/bags/vehicles
```
#### 请求示例
```
curl https://<host>/api/bags/vehicles
```
#### 成功响应 200
```json
{
"vehicles": ["PL061763", "PL061764"]
}
```
---
### 12. 批量查询 Tags
```
POST /api/bags/tags
```
#### 请求体
```json
["a.bag", "b.bag"]
```
#### 成功响应 200
```json
{
"a.bag": [
{"name": "tag1", "type": "type1"},
{"name": "tag2", "type": "type2"}
],
"b.bag": [
{"name": "tag3", "type": "type3"}
]
}
```
---
### 13. 批量查询 Topics
```
POST /api/bags/topics
```
#### 请求体
```json
["a.bag", "b.bag"]
```
#### 成功响应 200
```json
{
"a.bag": [
{"name": "topic1", "type": "type1"},
{"name": "topic2", "type": "type2"}
],
"b.bag": [
{"name": "topic3", "type": "type3"}
]
}
```
---
FST
---
### 1. 批量获取 FST → Bags 映射
```
POST /api/fst/bags/nodes
```
#### 请求体
```json
["fst1", "fst2"]
```
#### 成功响应 200
```json
{
"fst1": ["Bag1", "Bag2"],
"fst2": ["Bag3"]
}
```
---
### 2. 获取指定 FST 及其子节点的 Bags
```
GET /api/fst/bags/path/{name}
```
#### 请求示例
```
curl https://<host>/api/fst/bags/path/fst1
```
#### 成功响应 200
```json
{
"fst1": {"bags": ["Bag1", "Bag2"]},
"fst1_child": {"bags": ["Bag3"]}
}
```
#### 错误响应 404：Specified FST not found
---
### 3. 获取 FST 树形结构（纯文本）
```
GET /api/fst/print_tree
```
#### 成功响应 200
```
<pre>
Your FST tree output here
</pre>
```
---
### 4. 获取单个 FST 详情
```
GET /api/fst/{name}
```
#### 请求示例
```
curl https://<host>/api/fst/fst1
```
#### 成功响应 200
```json
{
"name": "fst1",
"parent_node": "Parent FST Name",
"linked_bags_sum": 5
}
```
#### 错误响应 404：Specified FST not found
---
Geometry
--------
### 批量获取 Rosbag 的 Geometry 信息
```
POST /api/geometry/
```
#### 请求体
```json
{"rosbag_names": ["rosbag1", "rosbag2"]}
```
#### 成功响应 200
```json
{
"rosbag1": [[12.345678, 12.345678, 0.0]],
"rosbag2": [[98.765432, 98.765432, 0.0]]
}
```
---
Projects
--------
### 获取所有项目
```
GET /api/projects/all
```
#### 成功响应 200
```json
[
{"id": 1, "name": "Project Name"}
]
```
---
Tags
----
### 1. 获取全部 Tags
```
GET /api/tags/all
```
#### 成功响应 200
```json
[
{
"name": "Data Quality",
"type": "quality",
"creator": "alice@example.com"
}
]
```
---
### 2. 根据 Tag 名称获取关联 Bags
```
GET /api/tags/bags/{tag_name}
```
#### 请求示例
```
curl https://<host>/api/tags/bags/Data%20Quality
```
#### 成功响应 200
```json
{"bags": ["bag_2024_07"]}
```
---
### 3. 根据 Creator 获取 Tags
```
GET /api/tags/creators/{creator}
```
#### 请求示例
```
curl https://<host>/api/tags/creators/alice@example.com
```
#### 成功响应 200
```json
{"tags": ["Sales", "Data Quality"]}
```
---
Topics
------
### 1. 获取全部 Topics
```
GET /api/topics/all
```
#### 成功响应 200
```json
[
{"name": "Topic Name", "type": "Topic Type"}
]
```
---
### 2. 根据 Topic 名称获取关联 Bags
```
GET /api/topics/bags/{topic_name}
```
#### 请求示例
```
curl https://<host>/api/topics/bags/topic1
```
#### 成功响应 200
```json
{"name": ["Bag Name"]}
```
---