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:///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:///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:///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:///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:///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:///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:///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:///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:///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:///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:///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:///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 ``` 
Your FST tree output here
``` --- ### 4. 获取单个 FST 详情 ``` GET /api/fst/{name} ``` #### 请求示例 ``` curl https:///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:///api/tags/bags/Data%20Quality ``` #### 成功响应 200 ```json {"bags": ["bag_2024_07"]} ``` --- ### 3. 根据 Creator 获取 Tags ``` GET /api/tags/creators/{creator} ``` #### 请求示例 ``` curl https:///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:///api/topics/bags/topic1 ``` #### 成功响应 200 ```json {"name": ["Bag Name"]} ``` ---