fst_data_pipeline-feature-editor-api/fst_data_pipeline/apps/API.md

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"]}
```

---