1548 lines
69 KiB
Markdown
1548 lines
69 KiB
Markdown
# 视觉感知工作台 · CV 数据集 BFF API
|
||
|
||
> **代码对齐**:`internal/platform/cv/handler/cvdataset_handler.go`(15 业务路由 + 2 废弃路由)、`internal/platform/cv/dto/cvdataset/request.go`、`internal/platform/cv/dto/cvdataset/response.go`、`internal/platform/cv/service/dataset/`、`pkg/response/v1.go`
|
||
> **伴生 OpenAPI**:`docs/cvdataset/dataset_swagger.json`
|
||
> **前端接入指南**:`docs/cvdataset/dataset_frontend_integration_guide.md`
|
||
> **变更 diff**(自 merge dev #32 起):`docs/cvdataset/dataset_changelog_since_merge_dev_32.md`
|
||
> **联调参考**:`testui/dataset/app.js`
|
||
> **更新日期**:2026-06-29
|
||
> **受众**:前端工程师 / 联调 / AI 自动封装
|
||
|
||
**文档边界**:本文只描述 **BFF 对外 HTTP 契约**(路径、请求、响应、错误、状态机)。不展开 BFF 内部下游实现;运维配置见 `AGENTS.md`。
|
||
|
||
**Out of Scope**(同 Base URL 下另有路由,不在本文 15 业务接口内):`/annotation/*`、`/finetune/*`;旧版 LeRobot `/v1/datasets`(batch/episode/preview/RRD)。
|
||
|
||
---
|
||
|
||
## 1. 快速开始
|
||
|
||
### 1.1 服务地址
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| 默认 Host | `http://localhost:8080`(`SERVER_PORT`) |
|
||
| 业务前缀 | `{SERVER_CONTEXT_PATH}`,默认 `/roboticsBffApi` |
|
||
| CV 数据集前缀 | `{SERVER_CONTEXT_PATH}/cv/v1/dataset` |
|
||
| 完整示例 | `http://localhost:8080/roboticsBffApi/cv/v1/dataset` |
|
||
|
||
BFF 未启用 CV 数据集模块时,上述路径返回 404(通常因运行环境未配置下游数据集服务)。
|
||
|
||
### 1.2 鉴权 Headers
|
||
|
||
| Header | 必填 | 说明 |
|
||
|--------|------|------|
|
||
| `Authorization` | 是 | `Bearer <d-cloud token>` |
|
||
| `x-request-id` | 是 | 每次请求唯一 ID;缺失时中间件返回 `code: 40000` |
|
||
| `Content-Type` | POST 建议 | `application/json` |
|
||
|
||
**组织上下文**:collections 读写经 `requireCollectionAccess`;鉴权成功后 context 须含 `organizationId` 与 `orgSymbol`(`auth` 中间件注入)。缺失时返回 `40100` + `missing organization context`。
|
||
|
||
### 1.3 典型调用顺序
|
||
|
||
```text
|
||
1. 获取 d-cloud Bearer token
|
||
2. 每次请求生成唯一 x-request-id
|
||
3. POST /collections/list → 列表卡片(无 versions[])
|
||
4. GET /collections/get → 详情 / 轮询状态(含 versions[])
|
||
5. GET /collections/version-tree → 版本管理抽屉分支树
|
||
6. POST /samples/list → 样本宫格
|
||
7. 写操作见各接口前置条件(§3 状态机)
|
||
```
|
||
|
||
**异步任务**(create / import / export / save):响应含 `job_id` 与 `status: running`;BFF **无** job 轮询接口,请轮询 `GET /collections/get`,观察 `CollectionCard.status` 与 `status_text`(§3)。
|
||
|
||
### 1.4 最小 curl
|
||
|
||
```bash
|
||
export BASE='http://localhost:8080/roboticsBffApi/cv/v1/dataset'
|
||
export TOKEN='<d-cloud-bearer-token>'
|
||
export RID='quickstart-001'
|
||
|
||
curl -sS -X POST "$BASE/collections/list" \
|
||
-H "Content-Type: application/json" \
|
||
-H "x-request-id: $RID" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{"dataset_kind":"training","page":1,"page_size":20}'
|
||
```
|
||
|
||
### 1.5 术语
|
||
|
||
| 术语 | 含义 |
|
||
|------|------|
|
||
| **collection** | BFF 逻辑数据集卡片(`collection_id` 形如 `dc_*`),含训练/测试 Tab 与多版本 |
|
||
| **formal version** | 已封存正式版(`version_type=formal` 且 `saved_at` 非空),对用户展示为 V1/V2/… |
|
||
| **draft / editable** | 内部工作副本(`version_type=draft`,`version_index=0`),**不对用户展示 V 号**;所有写操作指向 `editable_version` |
|
||
| **baseline** | 当前编辑基准(`baseline_version` / `baseline_version_id`);切换基准会从该封存版 fork 新 draft |
|
||
| **highest version** | 已封存 formal 中 `version_index` 最大者(`highest_version`) |
|
||
| **current_version** | **兼容字段**,与 `baseline_version` 相同(不再表示「查看版本」) |
|
||
| **view version** | 详情只读视角:`GET /collections/get?version_id=`,**不落库** |
|
||
| **sample** | 样本行,BFF 映射为 `SampleItem` |
|
||
| **job_id** | 创建/导入/导出/封存/switch-baseline 时 BFF 返回的异步 clone 任务 ID |
|
||
|
||
### 1.6 版本模型(2026-06-23)
|
||
|
||
三条指针:
|
||
|
||
| 指针 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| 最高正式版 | `highest_version` | 只读展示;已封存 formal 中 `version_index` 最大者 |
|
||
| 当前基准 | `baseline_version` / `baseline_version_id` | 编辑语义来源;**保存快照后推进为新封存 formal**(与 `highest_version` 一致) |
|
||
| 工作副本 | `editable_version`(`version_type=draft`) | draft;**所有写操作** body `version_id`;**无** `CollectionCard` 顶层 `editable_version_id` 字段 |
|
||
|
||
**封存**:`POST /versions/save` 将当前 draft 克隆为新的 formal `Vn`;`based_on_version_id` 由 `resolveSaveParentVersionID` 记录血缘(优先 draft.`based_on_version_id`,否则保存前最高封存 formal,再否则 baseline);保存后 `baseline_version_id` = **新 formal id**;再 fork 新 draft(`based_on_version_id` = 新 formal id),可继续基于未保存工作副本编辑。
|
||
|
||
**版本树**:`GET /collections/version-tree` 返回已封存 formal 的父子树(`based_on_version_id`);版本管理抽屉数据源;**列表** `POST /collections/list` **不返回** `versions[]`。
|
||
|
||
**切换基准**:`POST /versions/switch-baseline` 仅能在版本管理操作;会丢弃当前 draft 未保存修改并从目标 formal fork 新 draft;响应含 `version_creator_id`。
|
||
|
||
**废弃**:`POST /versions/switch`(原切换查看)、`POST /versions/promote-snapshot` 均返回 `40000 deprecated`。
|
||
|
||
验收步骤见 `docs/cvdataset/dataset_version_verification.md`。
|
||
|
||
### 1.7 产品需求 ↔ 接口/字段(前端实现清单)
|
||
|
||
| # | 产品语义 | BFF 事实 | 前端必须 |
|
||
|---|----------|----------|----------|
|
||
| 1 | 用户只见 V1/V2/… | get 的 `versions[]` 仅已封存 `formal`;draft 无对外 V 号 | 训练选版 / 详情历史用 get 的 `versions[]`;版本管理抽屉用 `version-tree`;**勿**把 `editable_version` 当 V 号展示 |
|
||
| 2 | 卡片:最高 Vn + 基准 Vx | `highest_version`、`baseline_version` | 列表卡片版本条;▾ 按钮文案用 `highest_version.version_name`;list **无** `versions[]` |
|
||
| 3 | 保存快照仅在卡片 | `POST /versions/save` | **仅**卡片「最高版本 ▾ → 保存快照」;**无**底栏独立按钮;`version_id`=`editable_version_id`;**不要求**有未保存修改 |
|
||
| 4 | 版本管理右侧抽屉 | `GET /collections/version-tree` + `POST /versions/switch-baseline` | 递归渲染 `children`;展示 `version`、`created_at`、`version_creator_id`、`current_flag`、`is_latest`;「切换到此版本」调 switch-baseline |
|
||
| 5 | 编辑基于基准的 draft | 写操作 `version_id` = `editable_version_id` | 补数/删样本/编辑元数据均传 draft id;新 formal 的 `based_on_version_id` 记录血缘;保存后 `baseline_version_id` = 新 formal id |
|
||
| 6 | 详情历史只读 | `GET /collections/get?version_id=` 不落库 | 详情历史下拉 + `samples/list` 只读;**禁止** switch-baseline |
|
||
| 7 | 训练/微调仅 formal | `ensureTrainableVersion`;draft 返回 `400` | 选版列表用 `versions[]`;`POST /finetune/create` 等勿传 draft id |
|
||
|
||
### 1.8 训练 / 微调选版(`/finetune/*`,同 Base URL 子路由)
|
||
|
||
不在本文 15 个 collection 接口内,但 **R7** 与版本模型一致:
|
||
|
||
- 创建微调任务时 `version_id`(或等价字段)须为 **`versions[]` 中已封存 formal**。
|
||
- 传 draft `editable_version_id` → `40000` + `only sealed formal versions are trainable`。
|
||
- UI 下拉数据源:**仅** `GET /collections/get` 返回的 `versions[]`(list 不返回 `versions[]`),**勿**包含 `editable_version`。
|
||
|
||
---
|
||
|
||
## 2. 公共约定
|
||
|
||
### 2.1 成功响应 Envelope
|
||
|
||
15 个 CV 数据集业务接口统一 **`status` / `message` / `data`**:
|
||
|
||
```json
|
||
{ "status": 0, "message": "success", "data": {} }
|
||
```
|
||
|
||
分页接口 `data` 内嵌 `list`、`total`、`page`、`page_size`。
|
||
|
||
**分页默认值**(`dto.NormalizePage`):`page` 缺省或 `<1` → `1`;`page_size` 缺省或 `<1` → `20`;上限 `100`。
|
||
|
||
### 2.2 错误响应
|
||
|
||
#### 业务层(15 个 CV 业务接口 + 2 废弃)
|
||
|
||
HTTP 状态码与业务 `status` 对齐。错误响应通常省略 `data`:
|
||
|
||
```json
|
||
{ "status": 40000, "message": "invalid request body" }
|
||
```
|
||
|
||
#### 中间件层(鉴权 / 缺 `x-request-id`)
|
||
|
||
字段为 **`code` / `message`**(无 `status`):
|
||
|
||
```json
|
||
{ "code": 40100, "message": "unauthorized" }
|
||
```
|
||
|
||
判定:HTTP 2xx 且业务 `status === 0`;中间件错误看 `code`。
|
||
|
||
### 2.3 业务错误码
|
||
|
||
| status | HTTP | 典型场景 |
|
||
|--------|------|----------|
|
||
| `0` | 200 | 成功 |
|
||
| `40000` | 400 | 参数/业务校验失败 |
|
||
| `40100` | 401 | 无 token、d-cloud 拒绝、缺用户上下文、缺组织上下文(`missing organization context`) |
|
||
| `40400` | 404 | collection / version 不存在 |
|
||
| `40900` | 409 | 重名、task_types 冲突、版本绑定、fork 冲突 |
|
||
| `50000` | 500 | BFF DB/内部错误 |
|
||
| `50200` | 502 | 下游数据集服务不可达或异常 |
|
||
|
||
常见 `message`(与代码一致,便于前端分支):
|
||
|
||
| message | 触发接口 |
|
||
|---------|----------|
|
||
| `missing organization context` | collections 读写(`requireCollectionAccess`) |
|
||
| `no sealed versions found` | GET `/collections/version-tree` |
|
||
| `invalid dataset_kind` | collections/list、create |
|
||
| `name is required` | create |
|
||
| `collection name already exists` | create |
|
||
| `task_types is required` / `invalid task_type` | create / update / parser |
|
||
| `image_classification cannot combine with other types` / `stereo_depth cannot combine with other types` | create / update |
|
||
| `cannot remove existing task_type` / `cannot change task_types for …` | update |
|
||
| `sources is required` | create / import / parser |
|
||
| `path is required` / `invalid source_type` | sources 校验 |
|
||
| `collection_id is required` / `collection not found` | 多数接口 |
|
||
| `collection_id and version_id are required` | update / samples / export / save / switch |
|
||
| `version not found` / `dataset version not found` | 版本相关 |
|
||
| `version_id must match editable draft version` | collections/update、samples/import、samples/delete、versions/save;**原因**:body `version_id` ≠ 库内 `editable_version_id`;**处理**:用 list/get 最新 `editable_version.version_id`,勿用 baseline/highest;保存成功后须 refresh(见 §5.7.1) |
|
||
| `only draft working copy can be modified` | 对 formal id 执行写操作 |
|
||
| `only sealed formal versions can be baseline` | versions/switch-baseline 目标为 draft |
|
||
| `only sealed formal versions are trainable` | finetune/create 等传 draft `version_id` |
|
||
| `dataset is not ready` | import / delete / export(core `importing/appending/exporting/creating`) |
|
||
| `dataset is not ready for clone` | versions/save / promote-snapshot |
|
||
| `sample_ids is required` | samples/delete |
|
||
| `target_path, export_name and export_format are required` | export |
|
||
| `invalid export_format` | export(多任务检测类集,须 `coco` 或 `yolo`) |
|
||
| `uap storage config is required` | create / import / export |
|
||
| `cannot delete the only version` / `cannot delete editable head version` | versions/delete |
|
||
| `version has task binding` | versions/delete |
|
||
| `version is not snapshot` | versions/promote-snapshot |
|
||
| `snapshot_version_id` 缺失时 `collection_id and snapshot_version_id are required` | promote-snapshot |
|
||
|
||
---
|
||
|
||
## 3. 数据集状态(核心)
|
||
|
||
### 3.1 前端应读哪些字段
|
||
|
||
BFF **不在响应中返回** `creating`、`has_unsaved_changes` 等内部布尔字段。卡片对外状态由 **`CollectionCard.status` + `CollectionCard.status_text`** 表达:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `status` | string | 业务状态枚举;与旧版 `dataset` 服务 `dataset_version.status` **尽量同名对齐**,并新增 `exporting` / `published`(见 §3.2) |
|
||
| `status_text` | string | 中文展示文案;**UI 优先展示此字段**(`collectionStatusLabel()` 优先读 `status_text`,缺失时回退枚举映射) |
|
||
|
||
**状态如何计算**(`buildCollectionCard` → `resolveCollectionStatsVersion` + `resolveCollectionCardStatus` + `applyViewingVersionStatus`):
|
||
|
||
1. 默认列表/详情(无 `version_id`):stats/status 取自 **最高封存版**(`highest_version` 对应 core);`baseline_version_id` 低于最高版时(已 switch-baseline)改取 **可编辑 draft**(`editable_version_id`)。
|
||
2. `GET ?version_id=<formal>`:stats 取自该 formal 行;非当前主线且映射为 `tobepublished` 时对外改为 **`published`**(历史只读)。
|
||
3. 若 stats 版本 `clone_status=switching`(`switch-baseline` fork 新 draft)→ `switching`;`clone_status=running` 且 save 封存进行中 → `publishing`。
|
||
4. 否则将 core 快照映射为 legacy 状态(`succeeded`→`tobepublished` 等);未切基准时最高封存版就绪态仍展示 `tobepublished`(便于补数/编辑入口)。
|
||
|
||
**内部 dirty 标记**:`update` / `import` / `delete` 成功后 BFF 置 `has_unsaved_changes=true`,**不**映射到 `status_text`。**保存快照不校验 dirty**。
|
||
|
||
### 3.2 `CollectionCard.status` 全集
|
||
|
||
| status | status_text | 含义 | 是否处理中 |
|
||
|--------|-------------|------|------------|
|
||
| `creating` | 创建中 | 元数据已创建,core 尚未就绪 | 是 |
|
||
| `running` | 处理中 | core `importing` 等导入任务进行中 | 是 |
|
||
| `exporting` | 导出中 | core `exporting`,导出任务进行中 | 是 |
|
||
| `tobepublished` | 待发布 | draft 就绪且 core 空闲(卡片列表默认) | 否(可写) |
|
||
| `published` | 已保存 | `GET ?version_id=` 查看历史 formal 时 | 否(只读) |
|
||
| `switching` | 切换中 | `switch-baseline` fork 新 draft 后 clone 未完成 | 是 |
|
||
| `switchfailed` | 切换失败 | `switch-baseline` 后台 clone 失败 | 否(终态,可重试切换) |
|
||
| `publishing` | 发布中 | `versions/save` 封存后 clone 未完成 | 是 |
|
||
| `appending` | 追加中 | core `appending`,补数进行中 | 是 |
|
||
| `labeling` | 标注中 | core `in_annotation` | 是 |
|
||
| `gtgenerating` | 真值生成中 | core `training` | 是 |
|
||
| `labelfailed` | 标注失败 | core `annotation_failed` | 否(终态,可重试) |
|
||
| `appendfailed` | 追加失败 | core `appending_failed` | 否(终态,可重试补数) |
|
||
| `gtgeneratingfailed` | 真值生成失败 | core 训练失败类快照 | 否(终态) |
|
||
| `publishfailed` | 发布失败 | `versions/save` clone 失败(非导出) | 否(终态) |
|
||
| `exportfailed` | 导出失败 | core `export_failed` | 否(终态,可重试导出) |
|
||
| `failed` | 失败 | core `failed` | 否(终态) |
|
||
| `removed` | 已删除 | 已删除(列表接口通常查不到) | 否(终态) |
|
||
|
||
### 3.2.1 与旧版 `dataset` 状态快览(`/Users/d-robotics/Project/dataset`)
|
||
|
||
> 旧版事实源:`dataset_version.status`(见旧仓库 `docs/architecture_design.md` 状态机、`pkg/dataset/service/dataset_service.go`)。
|
||
> 新版 BFF **不读旧库**,但 `CollectionCard.status` 字符串尽量与旧版 `dataset_version.status` 同名,便于 trainer 迁移。
|
||
|
||
#### A. 完全一致(枚举相同,含义基本一致)
|
||
|
||
以下状态在旧版与新版的**字符串与业务语义**均对齐,前端可沿用原有分支逻辑:
|
||
|
||
| BFF `status` | 旧版 `dataset_version.status` | 说明 |
|
||
|--------------|-------------------------------|------|
|
||
| `creating` | `creating` | 数据集/版本创建初期 |
|
||
| `running` | `running` | 导入等工作流进行中 |
|
||
| `publishing` | `publishing` | save 封存后 clone 进行中 |
|
||
| `switching` | `switching` | switch-baseline fork 新 draft 后 clone 进行中 |
|
||
| `switchfailed` | `switchfailed` | switch-baseline clone 失败 |
|
||
| `appending` | `appending` | 补数进行中 |
|
||
| `labeling` | `labeling` | 标注任务进行中 |
|
||
| `gtgenerating` | `gtgenerating` | 真值生成进行中 |
|
||
| `labelfailed` | `labelfailed` | 标注失败 |
|
||
| `appendfailed` | `appendfailed` | 补数失败 |
|
||
| `gtgeneratingfailed` | `gtgeneratingfailed` | 真值生成失败 |
|
||
| `publishfailed` | `publishfailed` | **仅** save/发布 clone 失败 |
|
||
| `failed` | `failed` | 通用失败 |
|
||
|
||
#### B. 语义有变化(枚举相同或相关,**判定方式**不同)
|
||
|
||
| BFF `status` | 旧版对应 | 变化点 |
|
||
|--------------|----------|--------|
|
||
| `tobepublished` | `tobepublished` | 旧版:当前工作版本就绪。新版:**仅当「当前查看版本 = 可编辑头」且 core 空闲**;`status_text=待发布` |
|
||
| `published` | `published` | 旧版:发布成功后**写入 DB**。新版:**切换查看历史封存版**时展示;`status_text=已保存`;亦可看 `versions[].saved_at` |
|
||
|
||
#### C. BFF 新增(旧版 `dataset_version.status` 状态机中**无**此枚举)
|
||
|
||
| BFF `status` | 来源 | 说明 |
|
||
|--------------|------|------|
|
||
| `exporting` | dataset-core `exporting` | 旧版导出**不**在版本表持久化该状态;新版卡片展示 `status_text=导出中` |
|
||
| `exportfailed` | dataset-core `export_failed` | 旧版无独立枚举;新版与 `publishfailed`(发布失败)**分开**,`status_text=导出失败` |
|
||
|
||
#### D. `switch-baseline` 切换基准(与旧版 `switching` / `switchfailed` 对齐)
|
||
|
||
| BFF `status` | 旧版 `dataset_version.status` | 说明 |
|
||
|--------------|-------------------------------|------|
|
||
| `switching` | `switching` | `POST /versions/switch-baseline` fork 新 draft 后;`status_text=切换中`;HTTP **立即返回**,clone 后台执行 |
|
||
| `switchfailed` | `switchfailed` | 后台 clone 失败;`status_text=切换失败`;可再次 `switch-baseline` 重试 |
|
||
|
||
> **与 `publishing` 区分**:`publishing` / `publishfailed` 仅用于 `POST /versions/save`;切换基准不使用 `publishing`。
|
||
|
||
| 操作 | BFF 行为 | 前端应怎么做 |
|
||
|------|----------|--------------|
|
||
| 切换基准 | `POST /versions/switch-baseline` 立即返回;卡片 `status=switching` | 轮询 get/list 直至 `tobepublished` 或 `switchfailed` |
|
||
| 历史查看 | `GET /collections/get?version_id=` 只读 | 详情下拉;**禁止**调 switch-baseline |
|
||
| 旧 `versions/switch` | 返回 `400 deprecated` | 移除调用 |
|
||
|
||
**迁移建议**:旧代码若用 `current_version` 表示查看版本,新版查看走 query `version_id`;编辑/补数统一用 `editable_version_id`。旧 fork 补数逻辑已移除。
|
||
|
||
**前端辅助函数**(与 `testui/dataset/app.js` 一致):
|
||
|
||
```javascript
|
||
function baselineVersionId(c) {
|
||
return c?.baseline_version?.version_id || c?.current_version?.version_id || '';
|
||
}
|
||
function editableVersionId(c) {
|
||
return c?.editable_version?.version_id || '';
|
||
}
|
||
function canMutateCurrentVersion(c) {
|
||
return Boolean(editableVersionId(c));
|
||
}
|
||
function canSaveCollection(c) {
|
||
if (isCollectionBusy(collectionStatusOf(c))) return false;
|
||
const st = collectionStatusOf(c);
|
||
if (st === 'creating' || st === 'failed') return false;
|
||
return Boolean(editableVersionId(c)); // 不要求 has_unsaved_changes
|
||
}
|
||
function canSupplementCollection(c) {
|
||
return Boolean(editableVersionId(c))
|
||
&& (collectionStatusOf(c) === 'tobepublished' || collectionStatusOf(c) === 'appendfailed');
|
||
}
|
||
```
|
||
|
||
**按钮可用性**(testui 参考实现):
|
||
|
||
| 操作 | 条件 |
|
||
|------|------|
|
||
| 编辑 | `canMutateCurrentVersion(card)` 且 `status === 'tobepublished'`;`version_id` = `editable_version_id` |
|
||
| 补数 | `canSupplementCollection(card)` 且 `!isCollectionBusy(status)`;`version_id` = `editable_version_id` |
|
||
| 保存快照 | **仅卡片**「最高版本 ▾ → 保存快照」;`canSaveCollection(card)`;body 见 §5.7.1:`collection_id` + `editable_version.version_id` |
|
||
| 切换基准 | 版本管理抽屉;`POST /versions/switch-baseline`;目标为 version-tree 节点或 get `versions[]` 中已封存 formal |
|
||
| 导出 | `status === 'tobepublished'` 或详情只读 `published`;`version_id` 为当前查看版(列表默认 draft,历史查看为 formal) |
|
||
| 删除样本 | `status === 'tobepublished'` 且非详情历史只读;`version_id` = `editable_version_id` |
|
||
|
||
**轮询**:create / import / export / save 等异步任务提交后,每 3–5s `GET /collections/get?collection_id=...`,直至 `isCollectionTerminal(status)`。`samples/delete` 为**同步**操作,成功后刷新 get + list 即可,无需 job 轮询。
|
||
|
||
### 3.3 与旧版 `dataset` 服务状态对照
|
||
|
||
旧版视觉数据集走 `datasetApi/api/v1/datasets/*`(仓库 `/Users/d-robotics/Project/dataset`)。卡片状态对应旧版 **`dataset_version.status`**(版本级);下文不对旧版 `dataset.status`(数据集表级)展开。
|
||
|
||
#### 3.3.1 dataset-core 快照 → BFF `CollectionCard.status`
|
||
|
||
BFF 不直接读旧库,而是读 dataset-core 的 `status` 再映射(`mapCoreSnapshotStatus`):
|
||
|
||
| dataset-core `status` | BFF `status` | BFF `status_text` |
|
||
|----------------------|--------------|-------------------|
|
||
| `succeeded` | `tobepublished`(卡片列表默认可编辑 draft)或 `published`(`GET ?version_id=` 查看历史 formal 时) | 待发布 / 已保存 |
|
||
| `creating` | `creating` | 创建中 |
|
||
| `importing` | `running` | 处理中 |
|
||
| `exporting` | `exporting` | 导出中 |
|
||
| `appending` | `appending` | 追加中 |
|
||
| `in_annotation` | `labeling` | 标注中 |
|
||
| `annotation_failed` | `labelfailed` | 标注失败 |
|
||
| `appending_failed` | `appendfailed` | 追加失败 |
|
||
| `export_failed` | `exportfailed` | 导出失败 |
|
||
| `training` | `gtgenerating` | 真值生成中 |
|
||
| `failed` | `failed` | 失败 |
|
||
| `removed` | `removed` | 已删除 |
|
||
|
||
#### 3.3.2 旧版 `dataset_version.status` → BFF
|
||
|
||
| 旧版 `dataset_version.status` | BFF 等价 | 备注 |
|
||
|-------------------------------|----------|------|
|
||
| `creating` | `creating` 或 `running` | 创建后首次导入多为 `running` |
|
||
| `running` | `running` | 导入任务进行中 |
|
||
| **`tobepublished`** | **`tobepublished`** | 可编辑头就绪;`status_text=待发布` |
|
||
| `publishing` | `publishing` | save 后 clone 进行中 |
|
||
| **`published`** | **`published`** | 切换查看历史封存版时;或看 `versions[].saved_at` 非空 |
|
||
| `exporting` | `exporting` | 旧版导出中 → 新版同名 |
|
||
| `exportfailed` | — | 旧版无独立枚举 |
|
||
| `failed` | `failed` | |
|
||
| `publishfailed` | `publishfailed` | save / clone 失败(**不含**导出失败) |
|
||
| `labeling` | `labeling` | |
|
||
| `labelfailed` | `labelfailed` | |
|
||
| `gtgenerating` | `gtgenerating` | |
|
||
| `gtgeneratingfailed` | `gtgeneratingfailed` | |
|
||
| `appending` | `appending` | |
|
||
| `appendfailed` | `appendfailed` | |
|
||
| `switching` | `switching` | switch-baseline clone 进行中 |
|
||
| `switchfailed` | `switchfailed` | switch-baseline clone 失败 |
|
||
|
||
#### 3.3.3 旧版「发布」vs 新版「保存版本」
|
||
|
||
| 维度 | 旧版 `datasets/{id}/publish` | 新版 `POST /versions/save` |
|
||
|------|------------------------------|----------------------------|
|
||
| 触发 | 对当前版本发布 | `version_id` 须等于 `editable_version_id`;core 须 `succeeded` |
|
||
| 进行中 | `publishing` | `publishing` |
|
||
| 完成后 | 旧版 `published` 字符串 | 新可编辑头 `tobepublished`;旧版进 `versions[]` 且 `saved_at` 有值 |
|
||
|
||
#### 3.3.4 异步任务提交响应 `status`
|
||
|
||
create / import / export 首次响应(**不含** `samples/delete`,删除为同步):
|
||
|
||
| 字段 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| `status` | `running` | 任务已提交 |
|
||
| `status_text` | `运行中` | |
|
||
| `job_id` | string | 任务 ID(save 亦返回 `job_id`) |
|
||
|
||
### 3.4 样本行级状态
|
||
|
||
`SampleItem.is_labeled`:bool,行是否已标注。
|
||
|
||
`SampleItem.status` / `status_text`:可选;无 `status` 时 BFF 由 `is_labeled` 映射为 `已标注`/`未标注`。
|
||
|
||
---
|
||
|
||
## 4. 枚举与字段字典
|
||
|
||
### 4.1 `dataset_kind`
|
||
|
||
| 值 | 含义 |
|
||
|----|------|
|
||
| `training` | 训练集 Tab |
|
||
| `testing` | 测试集 Tab |
|
||
|
||
### 4.2 `task_type`(BFF 请求/响应均用 snake_case)
|
||
|
||
| 值 | 中文 | 组合规则 |
|
||
|----|------|----------|
|
||
| `object_detection` | 目标检测 | 可与 SS/KP 组合 |
|
||
| `semantic_segmentation` | 语义分割 | 可与 OD/KP 组合 |
|
||
| `keypoint` | 关键点检测 | 可与 OD/SS 组合 |
|
||
| `image_classification` | 图像分类 | **仅允许单任务** |
|
||
| `stereo_depth` | 双目深度 | **仅允许单任务** |
|
||
|
||
更新时仅允许**增量添加** task_type,不可删除已有类型。
|
||
|
||
### 4.3 `source_type` 与 `SourceItem`
|
||
|
||
`SourceItem`(`request.go`):
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `source_type` | string | 是 | `dataspace` \| `datageneration` |
|
||
| `path` | string | 条件必填 | `source_type` 为上述二者时必填;经 `NormalizeSourcePath` 后提交 dataset-core |
|
||
|
||
| `source_type` 值 | 含义 |
|
||
|------------------|------|
|
||
| `dataspace` | 数据空间目录 |
|
||
| `datageneration` | 数据生成产出目录 |
|
||
|
||
**路径规范化**(`NormalizeSourcePath`,与代码一致):
|
||
|
||
1. 若字符串**首字符**为 `/`,去掉**一个**前导 `/`;
|
||
2. 再 `TrimSpace` 首尾空白。
|
||
|
||
示例:`/dataSpace/a/train` → `dataSpace/a/train`;` /foo` → `/foo`(首字符为空格时不删 `/`)。
|
||
|
||
多个 `sources` 路径合并为**一次**导入/解析请求(`common_file_path` 数组)。
|
||
|
||
### 4.4 `export_format`(请求体)
|
||
|
||
BFF 校验后映射为 dataset-core 实际格式(`MapExportFormat`):
|
||
|
||
| 数据集 `task_types` | 请求体 `export_format` | 提交 core 的值 |
|
||
|---------------------|------------------------|----------------|
|
||
| 含 OD/SS/KP(非单任务 IC/深度) | 必填,须为 `coco` 或 `yolo` | 原样 |
|
||
| 仅 `image_classification` | 任意非空字符串 | 固定 `image_classification`(忽略前端具体值) |
|
||
| 仅 `stereo_depth` | 任意非空字符串 | 固定 `depth_estimation`(忽略前端具体值;前端可传 `tiff` 作语义占位) |
|
||
|
||
非法检测类格式返回 `invalid export_format`。
|
||
|
||
### 4.5 `version_type`
|
||
|
||
| 值 | 含义 |
|
||
|----|------|
|
||
| `formal` | 已封存正式版(对用户展示 V1/V2/…) |
|
||
| `draft` | 内部工作副本(无对外 V 号) |
|
||
| `snapshot` | **已废弃**;历史存量;`promote-snapshot` 已禁用 |
|
||
|
||
### 4.6 `annotations`(`SampleItem.annotations`)
|
||
|
||
类型:`map[string]json.RawMessage`。key 为 BFF **`task_type`**(snake_case);value 为按任务类型的标注 JSON。未标注时 key 缺失或 value 为 `[]` / `{}`。
|
||
|
||
#### 4.6.1 `object_detection`
|
||
|
||
value 类型:**`ObjectDetectionAnnotation[]`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `label` | string | 类别名,与 collection `labels` / 预解析标签一致 |
|
||
| `boxes` | `BoundingBox[]` | 检测框列表 |
|
||
|
||
**`BoundingBox`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `x` | number | 左上角 x(像素) |
|
||
| `y` | number | 左上角 y(像素) |
|
||
| `width` | number | 框宽(像素) |
|
||
| `height` | number | 框高(像素) |
|
||
|
||
```json
|
||
"object_detection": [
|
||
{ "label": "person", "boxes": [{ "x": 10, "y": 20, "width": 100, "height": 200 }] }
|
||
]
|
||
```
|
||
|
||
#### 4.6.2 `semantic_segmentation`
|
||
|
||
value 类型:**`SemanticSegmentationAnnotation[]`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `label` | string | 分割类别名 |
|
||
| `boxes` | `Point[]` | 多边形顶点序列(至少 3 点) |
|
||
|
||
**`Point`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `x` | number | 顶点 x |
|
||
| `y` | number | 顶点 y |
|
||
|
||
```json
|
||
"semantic_segmentation": [
|
||
{ "label": "road", "boxes": [{ "x": 10, "y": 20 }, { "x": 50, "y": 22 }, { "x": 48, "y": 60 }] }
|
||
]
|
||
```
|
||
|
||
#### 4.6.3 `keypoint`
|
||
|
||
value 类型:**`KeypointAnnotation[]`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `label` | string | 实例类别名,与 `keypoints_configs[].name` 对应 |
|
||
| `bbox` | `BoundingBox` | 可选,实例外接框 |
|
||
| `keypoints` | `Keypoint[]` | 关键点列表 |
|
||
|
||
**`Keypoint`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `x` | number | 关键点 x |
|
||
| `y` | number | 关键点 y |
|
||
| `visible` | integer | 可见性:`0`=未标注 / 不可见,`1`=遮挡,`2`=可见(COCO 语义) |
|
||
| `name` | string | 关键点名称,与 `keypoints_configs[].keypoints` 元素对应 |
|
||
|
||
```json
|
||
"keypoint": [
|
||
{
|
||
"label": "person",
|
||
"bbox": { "x": 0, "y": 0, "width": 200, "height": 400 },
|
||
"keypoints": [
|
||
{ "x": 95, "y": 40, "visible": 2, "name": "nose" },
|
||
{ "x": 80, "y": 38, "visible": 2, "name": "l_eye" }
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 4.6.4 `image_classification`
|
||
|
||
value 类型:**`string[]`**,每个元素为一个分类标签名。
|
||
|
||
```json
|
||
"image_classification": ["cat"]
|
||
```
|
||
|
||
#### 4.6.5 `stereo_depth`
|
||
|
||
value 类型:**`StereoDepthAnnotation`**(object)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `right` | string | 右目图对象存储路径 |
|
||
| `disparity` | string | 视差图对象存储路径 |
|
||
|
||
左目图路径在样本行 `storage_path`。
|
||
|
||
```json
|
||
"stereo_depth": {
|
||
"right": "/dataSpace/project/000001_right.png",
|
||
"disparity": "/dataSpace/project/000001_disparity.png"
|
||
}
|
||
```
|
||
|
||
### 4.7 列表筛选约定
|
||
|
||
以下与 `collection.go`(数据集列表)、`sample.go` + `sample_list_filter.go` + `sample_stats_resolve.go`(样本列表)行为一致。
|
||
|
||
#### 4.7.1 `POST /collections/list`
|
||
|
||
| 参数 | 传递方式 | 筛选效果 | 对 `total` / `list` 的影响 |
|
||
|------|----------|----------|---------------------------|
|
||
| `dataset_kind` | 必填 `training` \| `testing` | 仅返回该 Tab 下、当前组织(`organization_id` + `org_symbol`)可见的 collection | DB 条件;计入 `total` |
|
||
| `name` | 可选 string | 对 BFF 本地展示名 `name` **模糊匹配**(SQL `LIKE %name%`) | DB 条件;计入 `total` |
|
||
| `creator` | 可选 string | 对 `created_by_name` **模糊匹配**(SQL `LIKE %creator%`) | DB 条件;计入 `total` |
|
||
| `task_types` | 可选 string[] | collection 的 `task_types` 须**同时包含**请求中列出的**每一个**类型(AND / 超集匹配,非精确相等) | **DB 分页之后**在内存过滤;`list` 可能少于 `page_size`;**`total` 仍为 DB 计数,不随本筛选减少** |
|
||
| `page` / `page_size` | 可选 | 先对 DB 结果分页,再对当前页做 `task_types` 内存过滤 | 默认 1 / 20,上限 100 |
|
||
|
||
**前端注意**
|
||
|
||
- 任务类型 chips 筛选后,分页器 `total` 可能大于实际可见卡片数;若需精确 total,只能客户端二次统计或接受近似分页。
|
||
- `name` 与 `task_types` 可组合:`name` 在 DB 层生效,`task_types` 在当前页结果上生效。
|
||
|
||
**示例**
|
||
|
||
```json
|
||
{ "dataset_kind": "training", "name": "od", "task_types": ["object_detection", "keypoint"], "page": 1, "page_size": 20 }
|
||
```
|
||
|
||
含义:训练 Tab 下名称含 `od` 的数据集(DB),且任务类型同时含 OD 与 KP(当前页内存过滤)。
|
||
|
||
#### 4.7.2 `POST /samples/list`
|
||
|
||
公共参数:
|
||
|
||
| 参数 | 筛选效果 |
|
||
|------|----------|
|
||
| `collection_id` + `version_id` | 必填;定位 core dataset |
|
||
| `name` | 可选;文件名 **模糊搜索**,传入 dataset-core |
|
||
| `labels` | 可选 string[];样本 `labels` 列 **任意命中**(OR),传入 dataset-core;可与 `is_labeled` / `name` 组合 |
|
||
| `page` / `page_size` | 分页;默认 1 / 20,上限 100 |
|
||
|
||
**`is_labeled` 与 `annotation_task_types` 组合**
|
||
|
||
| `is_labeled` | `annotation_task_types` | 数据集类型 | BFF 列表策略 | 筛选语义 |
|
||
|:------------:|:------------------------:|------------|--------------|----------|
|
||
| 省略 | 省略 | 任意 | core 全量列表 | 不过滤标注状态 |
|
||
| 省略 | 非空(相对 collection `task_types` 的**真子集**) | 非 IC/深度单任务 | core 全量列表 | **列表不过滤**;BFF 仅裁剪 `list[].annotations` / `list[].task_annotation_statuses`(**不**转发 core) |
|
||
| `true` | 省略 | 多任务纯视觉 | core `is_labeled=true` | 与 Tab `status_stats.labeled`(≥1 分支已标)对齐 |
|
||
| `false` | 省略 | 多任务纯视觉 | core `is_labeled=false` | 与 Tab `status_stats.unlabeled`(**全部分支均未标**)对齐 |
|
||
| `true` / `false` | 任意 | **仅** `image_classification` 或 **仅** `stereo_depth` | BFF **本地扫页** | 按行级 `SampleItem.is_labeled` 匹配;**始终忽略** `annotation_task_types` |
|
||
| `true` | 非空 | OD / SS / KP **纯视觉**任务集 | BFF **本地扫页 AND** | 指定分支 **全部** 已标 |
|
||
| `false` | 非空 | OD / SS / KP **纯视觉**任务集 | BFF **本地扫页 AND** | 指定分支 **全部** 未标(**其他分支可已标**) |
|
||
| `true` / `false` | 非空 | 含 IC/深度等非纯视觉组合 | core + `annotation_task_match=and` | 指定分支 AND 匹配(以 core 行为为准;纯视觉子集优先走上一行本地扫页) |
|
||
|
||
**纯视觉任务集**(`IsVisualBranchTaskDataset`):collection 的 `task_types` **每一个**都属于 `object_detection` / `semantic_segmentation` / `keypoint`。
|
||
|
||
**本地扫页说明**:BFF 以 200 条/页向 core 拉取并在内存按 `task_annotation_statuses` 匹配,再组装目标页;大数据集下比 core 直筛慢,但保证 IC/深度行级筛选与「未标 + 任务子集」分支语义正确。
|
||
|
||
**testui 参考**(`testui/dataset/app.js`)
|
||
|
||
- Tab「全部」:**不传** `is_labeled`;任务真子集时仍传 `annotation_task_types`(仅响应裁剪)。
|
||
- Tab「已标注 / 未标注」:传 `is_labeled: true | false`。
|
||
- 任务 chips:相对 collection 全量 `task_types` 为**真子集**时传 `annotation_task_types`;全选时不传。
|
||
|
||
#### 4.7.3 响应统计字段与 `total` 对齐
|
||
|
||
**`status_stats`**(Tab 角标,与列表筛选语义对齐,`resolveSampleStatusStats`)
|
||
|
||
| 数据集类型 | `labeled` | `unlabeled` |
|
||
|------------|-----------|-------------|
|
||
| IC / 深度单任务 | core 行级 `labeled_count` | core 行级 `unlabeled_count` |
|
||
| 多任务纯视觉(OD/SS/KP 组合) | `multi_task_labeled_count`(至少一分支已标) | `all_tasks_unlabeled_count`(全部分支均未标) |
|
||
| 单任务纯视觉 | 该任务 `task_status_stats[task_type].labeled` | 同 bucket 的 `unlabeled` |
|
||
| 其他 / stats 降级 | core 全局 `labeled_count` | core 全局 `unlabeled_count` |
|
||
|
||
**`task_status_stats`**:key 为 BFF `task_type`;IC/深度单任务时该唯一 key 的计数与 `status_stats` 一致。
|
||
|
||
**`total`(分页总数,`resolveListTotal`)**
|
||
|
||
| 筛选条件 | `total` 来源 |
|
||
|----------|-------------|
|
||
| 未传 `is_labeled` | core 列表 `total`(含 `name` 搜索) |
|
||
| IC/深度 + `is_labeled` | `status_stats.labeled` 或 `status_stats.unlabeled`(与 Tab 一致) |
|
||
| `is_labeled=true` + `annotation_task_types`(纯视觉) | BFF 本地 AND 扫页后的 `total` |
|
||
| `is_labeled=true`(无任务子集) | `status_stats.labeled` |
|
||
| `is_labeled=false` + `annotation_task_types`(纯视觉) | BFF 本地 AND 扫页后的 `total`(应与对应 `task_status_stats[task].unlabeled` 一致,单选任务时) |
|
||
| `is_labeled=false`(无任务子集) | `status_stats.unlabeled` |
|
||
| 传了 `labels` | core / 本地扫页列表 `total`(stats 不按 label 过滤) |
|
||
|
||
### 4.8 其他枚举
|
||
|
||
#### `task_annotation_statuses`(`SampleItem.task_annotation_statuses`)
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `labeled` | 该 `task_type` 分支已有标注内容 |
|
||
| `unlabeled` | 该分支尚无标注 |
|
||
|
||
key 为 BFF `task_type`。多任务集上各 key 可独立取值;`image_classification` / `stereo_depth` 单任务时 BFF 按行级 `is_labeled` 覆盖对应单键。
|
||
|
||
#### `SampleItem.type`(样本 split 类型)
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `train` | 训练集 split |
|
||
| `val` | 验证集 split |
|
||
| `test` | 测试集 split |
|
||
| `error` | 导入异常样本 |
|
||
|
||
#### `SampleItem.status`(`SampleRowStatus`,可选透传)
|
||
|
||
dataset-core 行级状态;缺失时 `status_text` 由 `is_labeled` 映射为 `已标注` / `未标注`。
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `in_annotation` | 标注中 |
|
||
| `no_train` | 未参与训练 |
|
||
| `training` | 训练中 |
|
||
| `train_succeeded` | 训练成功 |
|
||
|
||
#### 异步任务响应 `status`(`JobStatus`)
|
||
|
||
create / import / export / save 提交后 `data.status` 固定为 `running`,`data.status_text` 为 `运行中`(与 `CollectionCard.status` 不同)。
|
||
|
||
---
|
||
|
||
## 5. 接口说明
|
||
|
||
路径均相对于 `{SERVER_CONTEXT_PATH}/cv/v1/dataset`。
|
||
|
||
### 5.1 POST `/collections/list`
|
||
|
||
**用途**:分页列出当前组织指定 Tab 下的数据集卡片(`requireCollectionAccess` + `repoScope()`)。
|
||
|
||
**请求**:`ListCollectionsRequest`(§6.1)。
|
||
|
||
| 字段 | 必填 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| `dataset_kind` | 是 | — | `training` / `testing` |
|
||
| `name` | 否 | — | 名称模糊搜索 |
|
||
| `creator` | 否 | — | 创建人展示名(`created_by_name`)模糊搜索 |
|
||
| `task_types` | 否 | — | 集合须**包含**所列全部类型 |
|
||
| `page` | 否 | `1` | |
|
||
| `page_size` | 否 | `20` | 上限 100 |
|
||
|
||
**筛选参数效果** — 详见 §4.7.1。
|
||
|
||
| 参数 | 筛选效果摘要 |
|
||
|------|--------------|
|
||
| `dataset_kind` | 训练 / 测试 Tab 隔离 |
|
||
| `name` | 展示名模糊搜索(DB 层,影响 `total`) |
|
||
| `creator` | 创建人 `created_by_name` 模糊搜索(DB 层,影响 `total`) |
|
||
| `task_types` | 任务类型超集 AND 匹配(**内存**过滤,**不影响** `total`) |
|
||
|
||
**`list[]` 元素**:`BuildCollectionListCard` + `enrichCardTaskStatusStats` 组装,**省略** `versions[]`;版本摘要字段(`highest_version`、`baseline_version`、`editable_version`、`version_count`)仍返回。
|
||
|
||
**`list[].task_status_stats`**:`map[string]TaskStats`,key 为 BFF `task_type`;每项 `labeled` / `unlabeled` / `total`。由 `loadSampleStatsForList` + `buildTaskStatusStats` 填充(sample/stats 无任务维度时回退 batch-get 嵌套 stats)。统计版本与 `stats` 一致(默认 `editable_version`,无 draft 时 `baseline_version`)。
|
||
|
||
**写操作 `version_id` 取自 list**:`list[].editable_version.version_id`(draft)。`CollectionCard` **无**顶层 `editable_version_id` 字段;`baseline_version` / `current_version` / `highest_version` 均为 formal,**不可**用于 save / import / delete / update。完整映射见 §5.7.1。
|
||
|
||
**`task_types` 注意**:筛选在 DB 分页后内存执行,当前页 `list` 可能变短,但 `total` 仍为 DB 分页总数。
|
||
|
||
**响应 `data`**:`ListCollectionsResponse`(§6.2),`list[]` 元素为 `CollectionCard`(§6.3)。
|
||
|
||
**示例片段**
|
||
|
||
```json
|
||
{
|
||
"status": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [{
|
||
"collection_id": "dc_abc123_20260608120000",
|
||
"name": "my-od-dataset",
|
||
"dataset_kind": "training",
|
||
"task_types": ["object_detection"],
|
||
"status": "tobepublished",
|
||
"status_text": "待发布",
|
||
"version_count": 1,
|
||
"highest_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
|
||
"baseline_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
|
||
"current_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
|
||
"editable_version": { "version_id": "dv_draft", "version_name": "", "version_type": "draft" },
|
||
"stats": { "total_count": 100, "labeled_count": 80, "unlabeled_count": 20 }
|
||
}],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 POST `/collections/create`
|
||
|
||
**用途**:创建 collection + 封存 **V1** formal,提交首次导入。V1-only 阶段 `editable_version` 指向 V1 formal;**draft 工作副本**仅由 `POST /versions/save` 或 `POST /versions/switch-baseline` 显式 fork,list/get 的 `reconcileVersionModel` **不**调用 dataset-core clone。
|
||
|
||
**请求**:`CreateCollectionRequest`(§6.1)。`sources[]` 元素为 `SourceItem`(§4.3 / §6.1)。
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `dataset_kind` | 是 | |
|
||
| `name` | 是 | 同组织(`organization_id` + `org_symbol`)同 kind 不可重名 |
|
||
| `description` | 否 | 数据集描述;写入 BFF 本地并透传 core `dataset_description` |
|
||
| `task_types` | 是 | §4.2 |
|
||
| `labels` | 否 | 类别标签名;双目深度创建通常省略 |
|
||
| `keypoints_configs` | 否 | **非空数组**时写入关键点骨架配置;仅含 `keypoint` 任务时有效,结构 §6.6。`skeleton` 前端传 0-based,BFF 写下游时转为 COCO 1-based |
|
||
| `sources` | 是 | ≥1 |
|
||
|
||
**响应 `data`**:`CreateCollectionResponse`(§6.2)。
|
||
|
||
成功后:`refreshList` + 轮询 get 直至 `status=tobepublished` 或失败终态。
|
||
|
||
---
|
||
|
||
### 5.3 GET `/collections/get`
|
||
|
||
**用途**:单张卡片详情;**所有异步任务轮询入口**。
|
||
|
||
**Query**:`GetCollectionQuery`(§6.1)。
|
||
|
||
**响应 `data`**:`CollectionCard`(§6.3,含 `versions[]`、`stats`、`task_status_stats`、`camera_intrinsics`、`keypoints_configs`)。由 `BuildCollectionCard` 组装,`includeVersionSummaries=true`。
|
||
|
||
**统计版本**:默认取 `editable_version` 的 core 数据集(无 draft 时回退 `baseline_version`);传 `version_id` 时取该查看版。`stats` 与 `task_status_stats` 均基于同一版本(`resolveCollectionStatsVersion`)。
|
||
|
||
**`task_status_stats`**:`map[string]TaskStats`,key 为 BFF `task_type`;由 `enrichCardTaskStatusStats` → `loadSampleStatsForList` + `buildTaskStatusStats` 填充(sample/stats 无任务维度时回退 batch-get 嵌套 stats)。**list / get 均返回**;list 不支持 `?version_id=` 指定历史版统计。
|
||
|
||
---
|
||
|
||
### 5.3.1 GET `/collections/version-tree`
|
||
|
||
**用途**:版本管理抽屉的分支树;仅含已封存 formal,按 `based_on_version_id` 建树。
|
||
|
||
**Query**:`GetVersionTreeQuery`(§6.1)
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `collection_id` | 是 | |
|
||
|
||
**响应 `data`**:单个 `VersionTreeNode` 根节点(§6.4.1),非数组。无封存版时 `40400` + `no sealed versions found`。
|
||
|
||
**节点字段摘要**:`version`(如 `V1`)、`related_version`(父版本名)、`current_flag`(是否基准)、`is_latest`、`version_creator_id`、`created_at`(优先 `saved_at`)、`children[]`(递归)。
|
||
|
||
---
|
||
|
||
### 5.4 POST `/collections/update`
|
||
|
||
**用途**:更新可编辑头元数据(name/description/labels/task_types 增量、关键点骨架配置)。
|
||
|
||
**请求**:`UpdateCollectionRequest`(§6.1)。
|
||
|
||
**前置**:`version_id` **必须**等于 `editable_version_id`(draft);`status=tobepublished`(或 core 非 busy)。
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `name` | 非空时仅更新 BFF 展示名 |
|
||
| `description` | 非空时同步下游 |
|
||
| `task_types` | 非空时仅增量 |
|
||
| `labels` | 非空数组时全量替换 |
|
||
| `keypoints_configs` | 非空数组时全量替换关键点骨架配置;仅含 `keypoint` 任务时有效,结构见 §6.6。前端统一传 **0-based** `skeleton`;BFF 写入下游时按 **COCO 格式**转换(`index_base=1`,skeleton 各下标 +1) |
|
||
|
||
**响应 `data`**:`UpdateCollectionResponse`(§6.2)。
|
||
|
||
---
|
||
|
||
### 5.5 DELETE `/collections/delete`
|
||
|
||
**Query**:`collection_id`。**响应 `data`**:`{}`。
|
||
|
||
---
|
||
|
||
### 5.6 POST `/versions/switch-baseline`
|
||
|
||
**用途**:切换**编辑基准**(版本管理抽屉);从目标已封存 formal fork 新 draft;**丢弃**当前 draft 未保存修改。
|
||
|
||
**Body**:`SwitchBaselineRequest`(§6.1)
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `collection_id` | 必填 |
|
||
| `version_id` | 必填;须为已封存 `formal`(`saved_at` 非空),**不能**为 draft |
|
||
|
||
**响应 `data`**:`SwitchBaselineResponse` — `baseline_version_id`、`editable_version_id`、`version_creator_id`、`job_id`(clone 任务)
|
||
|
||
成功后卡片 `status` 可能为 `switching`,轮询 get 直至新 draft 就绪(`tobepublished`)或 `switchfailed`。
|
||
|
||
---
|
||
|
||
### 5.6.1 POST `/versions/switch`(已废弃)
|
||
|
||
返回 `40000`:`versions/switch is deprecated; use versions/switch-baseline or GET collections/get?version_id= for view-only`。
|
||
|
||
---
|
||
|
||
### 5.7 POST `/versions/save`
|
||
|
||
**用途**:封存当前 **draft** 为新的 formal `Vn`,再 fork 新 draft;**更新** `baseline_version_id` 为新封存 formal id。
|
||
|
||
**Body**:`SaveVersionRequest`(§6.1)
|
||
|
||
**前置**:
|
||
|
||
- `version_id` 须等于库内 `editable_version_id`(即 list/get 的 `editable_version.version_id`)
|
||
- 对应 core 数据集 `status === succeeded`
|
||
|
||
**响应 `data`**:`SaveVersionResponse` — `saved_version`、`based_on_version`(封存血缘父版本)、`baseline_version`(**与 `saved_version` 相同**)、新 `editable_version`、`job_id`
|
||
|
||
**血缘**:新 formal 的 `based_on_version_id` = `resolveSaveParentVersionID` 结果;保存后 `col.BaselineVersionID` = 新 formal id。
|
||
|
||
#### 5.7.1 list → save 参数映射(前端必读)
|
||
|
||
| `SaveVersionRequest` 字段 | 取自 `POST /collections/list` 的 `list[]` | 说明 |
|
||
|---------------------------|-------------------------------------------|------|
|
||
| `collection_id` | `card.collection_id` | 必填 |
|
||
| `version_id` | `card.editable_version.version_id` | 须等于 BFF 当前 `editable_version_id`;JSON **可省略**(`omitempty`),省略时 BFF 默认用库内 editable |
|
||
|
||
**勿用**:`baseline_version.version_id`、`current_version.version_id`、`highest_version.version_id`(均为 formal,会触发 `version_id must match editable draft version`)。
|
||
|
||
**list 卡片示例**:
|
||
|
||
```json
|
||
{
|
||
"collection_id": "dc_abc123_20260608120000",
|
||
"highest_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
|
||
"baseline_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
|
||
"editable_version": { "version_id": "dv_draft", "version_name": "", "version_type": "draft" }
|
||
}
|
||
```
|
||
|
||
**对应 save 请求**:
|
||
|
||
```json
|
||
{
|
||
"collection_id": "dc_abc123_20260608120000",
|
||
"version_id": "dv_draft"
|
||
}
|
||
```
|
||
|
||
**保存成功后**:`editable_version` 变为新 fork 的 draft id;前端须 `refreshList()` 或用 `SaveVersionResponse.editable_version` 更新本地,**禁止**复用保存前的 `version_id`。
|
||
|
||
**实现差异**:list/get 在返回前执行 `reconcileVersionModel`(对齐 baseline 指针、legacy 行归一化,**不** fork draft);`SaveVersion` 直接 `GetCollection` 并按库内 `editable_version_id` 校验(`version_writable.go` → `resolveWritableVersion`)。故 save 必须以**最新** list/get 的 `editable_version` 为准。
|
||
|
||
**testui 参考**:`testui/dataset/app.js` — `editableVersionId()`、`canSaveCollection()`、卡片 `data-save` 处理器。
|
||
|
||
---
|
||
|
||
### 5.8 POST `/versions/promote-snapshot`(已废弃)
|
||
|
||
返回 `40000 deprecated`。快照模型已移除。
|
||
|
||
---
|
||
|
||
### 5.9 DELETE `/versions/delete`
|
||
|
||
**Query**:`collection_id`、`version_id`。
|
||
|
||
不可删可编辑头、不可删唯一版本、`has_task_binding=true` 时 `40900`。
|
||
|
||
---
|
||
|
||
### 5.10 POST `/samples/list`
|
||
|
||
**用途**:分页样本列表 + Tab 统计。
|
||
|
||
**必填**:`ListSamplesRequest` 中 `collection_id`、`version_id`(§6.1)。
|
||
|
||
**筛选参数** — 完整组合语义、列表策略、`status_stats` / `total` 对齐见 **§4.7.2–§4.7.3**。
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `name` | 文件名模糊搜索 |
|
||
| `labels` | 样本级标签任意命中(OR) |
|
||
| `is_labeled` | 省略=全部样本;`true`/`false`=已标/未标 Tab |
|
||
| `annotation_task_types` | 任务**真子集**时传;与 `is_labeled` 组合见 §4.7.2(纯视觉:已标/未标 Tab 均为 **AND**;「全部」Tab 仅裁剪响应) |
|
||
| `page` / `page_size` | 默认 1 / 20,上限 100 |
|
||
|
||
**列表策略摘要**(`sample.go` 分支):
|
||
|
||
1. **IC / 深度单任务** 且传了 `is_labeled` → BFF 本地按 `SampleItem.is_labeled` 扫页;忽略 `annotation_task_types`。
|
||
2. **纯视觉任务集** + `is_labeled` 已传 + `annotation_task_types` 非空 → BFF 本地按 `task_annotation_statuses` **AND** 扫页(已标=指定分支全部已标;未标=指定分支全部未标)。
|
||
3. **`is_labeled` 省略** + `annotation_task_types` 非空 → core 全量列表;BFF 仅裁剪 `list[]` 中任务字段。
|
||
4. **其他** → dataset-core 列表(仅 `is_labeled` 或全量);非纯视觉且带任务子集时 core 使用 `annotation_task_match=and`。
|
||
|
||
**响应 `data`**:`ListSamplesResponse`(§6.2);`list[]` 为 `SampleItem`(§6.8);标注 JSON §4.6。
|
||
|
||
`SampleItem.id` 即 `samples/delete` 的 `sample_ids` 元素。`thumbnail_url` 当前恒为空字符串。
|
||
|
||
---
|
||
|
||
### 5.11 POST `/samples/import`
|
||
|
||
**用途**:补数 / 追加导入。
|
||
|
||
**请求**:`ImportSamplesRequest`(§6.1)。`version_id` **必须**等于 `editable_version_id`(draft)。
|
||
|
||
历史 formal id 将返回 `40000`(不再 fork)。
|
||
|
||
**前置**:非处理中(`!isBusy(status)`)。
|
||
|
||
**响应 `data`**:`ImportSamplesResponse`(§6.2);**无** `forked` 字段。
|
||
|
||
---
|
||
|
||
### 5.12 POST `/samples/delete`
|
||
|
||
**用途**:批量删除样本(**同步**完成,无 `job_id`)。
|
||
|
||
**请求**:`DeleteSamplesRequest`(§6.1)。`version_id` **必须**等于 `editable_version_id`(draft)。
|
||
|
||
**前置**:core 非 busy;详情历史只读视角下前端应禁用删除。
|
||
|
||
**响应 `data`**:`DeleteSamplesResponse` — `deleted_count`(同步;**无** `forked`)
|
||
|
||
**示例**
|
||
|
||
```json
|
||
{
|
||
"status": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"deleted_count": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
成功后:`refreshSamples()` + `GET /collections/get`(`version_id` 仍为当前 draft)。
|
||
|
||
---
|
||
|
||
### 5.13 POST `/export`
|
||
|
||
**用途**:对**任意存在版本**提交导出任务(不要求可编辑头)。
|
||
|
||
**请求**:`ExportDatasetRequest`(§6.1)。`export_format` 规则见 §4.4。
|
||
|
||
**前置**:`status` 非处理中;须配置 UAP(否则 `uap storage config is required`)。
|
||
|
||
**响应 `data`**:`ExportDatasetResponse`(§6.2)。
|
||
|
||
轮询 get 观察 `status` 直至 `tobepublished` 或 `exportfailed`/`publishfailed`/`failed`。
|
||
|
||
---
|
||
|
||
### 5.14 POST `/labels/parser`
|
||
|
||
**用途**:从数据空间/数据生成目录**同步**预解析标签名与关键点骨架配置(无 `job_id`)。仅含 `keypoint` 任务时,响应可能含 `keypoints_configs`(§6.6)。
|
||
|
||
**请求**:`ParseLabelsRequest`(§6.1)。
|
||
|
||
**响应 `data`**:`ParseLabelsResponse`(§6.2)。
|
||
|
||
创建弹窗典型流:`parser` → 填入 `labels` 与(关键点任务)`keypoints_configs` → `create`(见 testui `runParseLabels()`)。
|
||
|
||
---
|
||
|
||
## 6. 数据模型参考(与 `dto/cvdataset` 对齐)
|
||
|
||
以下结构与 `internal/platform/cv/dto/cvdataset/request.go`、`response.go` **字段名、JSON tag 完全一致**。接口章节的「请求 / 响应」均引用本节类型名。
|
||
|
||
### 6.1 请求体 / Query
|
||
|
||
#### `ListCollectionsRequest` — POST `/collections/list`
|
||
|
||
| 字段 | 类型 | 必填 | 默认 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `dataset_kind` | string | 是 | — | `training` \| `testing` |
|
||
| `name` | string | 否 | — | 名称模糊搜索 |
|
||
| `creator` | string | 否 | — | `created_by_name` 模糊搜索 |
|
||
| `task_types` | string[] | 否 | — | 集合须**包含**所列全部类型 |
|
||
| `page` | int | 否 | `1` | ≥1 |
|
||
| `page_size` | int | 否 | `20` | 1–100 |
|
||
|
||
#### `CreateCollectionRequest` — POST `/collections/create`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `dataset_kind` | string | 是 | `training` \| `testing` |
|
||
| `name` | string | 是 | 同组织(`organization_id` + `org_symbol`)同 kind 不可重名 |
|
||
| `description` | string | 否 | 写入 BFF 本地并透传 core `dataset_description` |
|
||
| `task_types` | string[] | 是 | §4.2 |
|
||
| `labels` | string[] | 否 | 类别标签名;双目深度创建通常省略 |
|
||
| `keypoints_configs` | `KeypointCategoryConfig[]` | 否 | **非空数组**时写入关键点骨架配置;仅 `keypoint` 任务;结构 §6.6。`skeleton` 前端传 0-based,BFF 写下游时转为 COCO 1-based |
|
||
| `sources` | `SourceItem[]` | 是 | ≥1,§4.3 |
|
||
|
||
#### `GetCollectionQuery` — GET `/collections/get`
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | Query | 是 | |
|
||
| `version_id` | Query | 否 | 指定时用该版本展示 stats / status / camera / keypoints |
|
||
|
||
#### `GetVersionTreeQuery` — GET `/collections/version-tree`
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | Query | 是 | |
|
||
|
||
#### `UpdateCollectionRequest` — POST `/collections/update`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | string | 是 | |
|
||
| `version_id` | string | 是 | 须等于 `editable_version_id`(draft 工作副本) |
|
||
| `name` | string | 否 | 非空时仅更新 BFF 展示名 |
|
||
| `description` | string | 否 | 非空时同步下游 |
|
||
| `task_types` | string[] | 否 | 非空时仅**增量**添加 |
|
||
| `labels` | string[] | 否 | **非空数组**时全量替换;传 `[]` 或不传则不更新 labels |
|
||
| `keypoints_configs` | `KeypointCategoryConfig[]` | 否 | **非空数组**时全量替换;仅 `keypoint` 任务;结构 §6.6。`skeleton` 前端传 0-based,BFF 写下游时转为 COCO 1-based |
|
||
|
||
#### `SwitchBaselineRequest` — POST `/versions/switch-baseline`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | string | 是 | |
|
||
| `version_id` | string | 是 | 须为已封存 formal(`versions[]` 内项) |
|
||
|
||
#### `SwitchVersionRequest` — POST `/versions/switch`(已废弃)
|
||
|
||
| 字段 | 类型 | 必填 |
|
||
|------|------|------|
|
||
| `collection_id` | string | 是 |
|
||
| `version_id` | string | 是 |
|
||
|
||
#### `SaveVersionRequest` — POST `/versions/save`
|
||
|
||
| 字段 | 类型 | 必填 |
|
||
|------|------|------|
|
||
| `collection_id` | string | 是 |
|
||
| `version_id` | string | 是 | 须等于 `editable_version_id` |
|
||
|
||
#### `PromoteSnapshotRequest` — POST `/versions/promote-snapshot`
|
||
|
||
| 字段 | 类型 | 必填 |
|
||
|------|------|------|
|
||
| `collection_id` | string | 是 |
|
||
| `snapshot_version_id` | string | 是 |
|
||
|
||
#### `ListSamplesRequest` — POST `/samples/list`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | string | 是 | |
|
||
| `version_id` | string | 是 | 通常等于当前查看版 |
|
||
| `name` | string | 否 | 文件名模糊搜索 |
|
||
| `labels` | string[] | 否 | 样本 `labels` 列任意命中(OR) |
|
||
| `is_labeled` | bool | 否 | 省略=全部;指针字段,仅 JSON `true`/`false` 生效 |
|
||
| `annotation_task_types` | string[] | 否 | 任务**真子集**筛选/裁剪;与 `is_labeled` 组合语义 §4.7.2;「全部」Tab 可单独传(仅裁剪响应) |
|
||
| `page` | int | 否 | 默认 1 |
|
||
| `page_size` | int | 否 | 默认 20,上限 100 |
|
||
|
||
#### `ImportSamplesRequest` — POST `/samples/import`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | string | 是 | |
|
||
| `version_id` | string | 是 | 须等于 `editable_version_id`(draft) |
|
||
| `sources` | `SourceItem[]` | 是 | ≥1 |
|
||
| `labels` | string[] | 否 | 补数时可追加标签 |
|
||
|
||
#### `DeleteSamplesRequest` — POST `/samples/delete`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | string | 是 | |
|
||
| `version_id` | string | 是 | 须等于 `editable_version_id`(draft) |
|
||
| `sample_ids` | uint64[] | 是 | 非空;来自 `SampleItem.id` |
|
||
|
||
#### `ExportDatasetRequest` — POST `/export`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `collection_id` | string | 是 | |
|
||
| `version_id` | string | 是 | 任意存在版本均可 |
|
||
| `target_path` | string | 是 | 导出目标目录 |
|
||
| `export_name` | string | 是 | 导出任务名 |
|
||
| `export_format` | string | 是 | §4.4 |
|
||
|
||
#### `ParseLabelsRequest` — POST `/labels/parser`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `task_types` | string[] | 是 | ≥1 |
|
||
| `sources` | `SourceItem[]` | 是 | ≥1 |
|
||
| `collection_id` | string | 否 | 与 `version_id` **成对**非空时合并 DB 已有 `labels`;关键点任务时同时合并已有 `keypoints_configs` |
|
||
| `version_id` | string | 否 | 同上;只传其一时忽略 |
|
||
|
||
#### `SourceItem`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `source_type` | string | 是 | `dataspace` \| `datageneration` |
|
||
| `path` | string | 条件 | §4.3 |
|
||
|
||
---
|
||
|
||
### 6.2 响应体 `data`
|
||
|
||
#### `ListCollectionsResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `list` | `CollectionCard[]` | |
|
||
| `total` | int64 | DB 分页总数;**不**随 `task_types` 内存筛选减少 |
|
||
| `page` | int | |
|
||
| `page_size` | int | |
|
||
|
||
#### `CreateCollectionResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `collection_id` | string | `dc_*` |
|
||
| `version_id` | string | 首个封存 formal `dv_*`(创建响应;draft 由 save/switch 显式 fork) |
|
||
| `job_id` | string | 首次导入任务 ID |
|
||
| `status` | string | `running` |
|
||
| `status_text` | string | `运行中` |
|
||
|
||
#### `UpdateCollectionResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `collection_id` | string | 成功确认;不返回 dirty 标记 |
|
||
|
||
#### `SwitchBaselineResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `baseline_version_id` | string | 切换后的基准 formal id |
|
||
| `editable_version_id` | string | 新 fork 的 draft id |
|
||
| `version_name` | string | 目标 formal 名(如 `V2`) |
|
||
| `version_type` | string | `formal` |
|
||
| `version_creator_id` | string | 新 draft 操作人展示名(omitempty) |
|
||
| `job_id` | string | clone 任务 ID(omitempty) |
|
||
|
||
#### `SwitchVersionResponse`(已废弃)
|
||
|
||
接口返回 `40000`;下列字段仅作历史参考。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `current_version_id` | string | |
|
||
| `version_name` | string | |
|
||
| `version_type` | string | |
|
||
|
||
#### `SaveVersionResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `saved_version` | `VersionBrief` | 新封存的 formal `Vn` |
|
||
| `based_on_version` | `VersionBrief` | 封存血缘父版本(omitempty) |
|
||
| `baseline_version` | `VersionBrief` | 保存后基准,**与 `saved_version` 相同**(omitempty) |
|
||
| `editable_version` | `VersionBrief` | 新 fork 的 draft |
|
||
| `sealed_version` | `VersionBrief` | **兼容别名** = `saved_version` |
|
||
| `job_id` | string | clone 任务 ID |
|
||
|
||
#### `PromoteSnapshotResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `version_id` | string | 新 formal 版本 ID |
|
||
| `version_name` | string | |
|
||
| `version_type` | string | 固定 `formal` |
|
||
| `source_snapshot_id` | string | 源 snapshot 版本 ID |
|
||
| `job_id` | string | clone 任务 ID(可选 omitempty) |
|
||
|
||
#### `ListSamplesResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `list` | `SampleItem[]` | |
|
||
| `total` | int64 | 与当前 Tab/筛选一致 |
|
||
| `page` | int | |
|
||
| `page_size` | int | |
|
||
| `status_stats` | `SampleStatusStats` | Tab 计数 |
|
||
| `task_status_stats` | `map[string]TaskStats` | key 为 BFF `task_type` |
|
||
|
||
#### `ImportSamplesResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `job_id` | string | 导入任务 ID |
|
||
| `status` | string | `running` |
|
||
| `status_text` | string | `运行中` |
|
||
| `imported_count` | int | 当前固定 `0` |
|
||
|
||
> 响应结构体虽保留 `forked` 等 omitempty 字段,**当前实现不再 fork**;补数须传 `editable_version_id`。
|
||
|
||
#### `DeleteSamplesResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `deleted_count` | int64 | 实际删除条数 |
|
||
| `version_id` | string | 实际操作的 draft id(omitempty) |
|
||
|
||
> **无** `forked` / `clone_job_id` 业务语义。
|
||
|
||
#### `ExportDatasetResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `job_id` | string | 导出任务 ID |
|
||
| `status` | string | `running` |
|
||
| `status_text` | string | `运行中` |
|
||
|
||
#### `ParseLabelsResponse`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `labels` | string[] | 预解析标签名;可为空数组 |
|
||
| `keypoints_configs` | `KeypointCategoryConfig[]` | 仅含 `keypoint` 任务且解析/合并结果非空时出现;结构 §6.6;`skeleton` 为 **0-based**;含 `used` |
|
||
|
||
```json
|
||
{
|
||
"labels": ["person"],
|
||
"keypoints_configs": [
|
||
{
|
||
"name": "person",
|
||
"used": true,
|
||
"keypoints": ["nose", "l_eye", "r_eye"],
|
||
"skeleton": [[0, 1], [1, 2]]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
DELETE `/collections/delete`、`DELETE /versions/delete` 成功时 `data` 为 `{}`。
|
||
|
||
---
|
||
|
||
### 6.3 `CollectionCard`
|
||
|
||
列表 / 详情共用结构;**list 省略 `versions[]`**(`BuildCollectionListCard`),**get 含 `versions[]`**(`BuildCollectionCard`)。`stats` 与 `task_status_stats` **list / get 均有**。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `collection_id` | string | BFF 逻辑 ID,`dc_*` |
|
||
| `name` | string | 展示名 |
|
||
| `description` | string | 描述(omitempty) |
|
||
| `dataset_kind` | string | `training` \| `testing` |
|
||
| `task_types` | string[] | BFF snake_case 任务类型 |
|
||
| `labels` | string[] | 数据集级类别标签(omitempty) |
|
||
| `creator` | string | 当前查看版本对应 core 数据集创建者(omitempty) |
|
||
| `create_time` | string | BFF 本地创建时间,RFC3339(omitempty) |
|
||
| `status` | string | §3.2 `CollectionCard.status` 全集 |
|
||
| `status_text` | string | 中文展示文案 |
|
||
| `camera_intrinsics` | `CameraIntrinsics` | 仅 `stereo_depth` 任务;见 §6.5 |
|
||
| `keypoints_configs` | `KeypointCategoryConfig[]` | 仅含 `keypoint` 任务;见 §6.6;读响应含 `used` |
|
||
| `current_version` | `VersionBrief` | **兼容**:等同 `baseline_version` |
|
||
| `highest_version` | `VersionBrief` | 最高已封存 formal(omitempty) |
|
||
| `baseline_version` | `VersionBrief` | 当前编辑基准(omitempty) |
|
||
| `editable_version` | `VersionBrief` | draft 工作副本;`version_type=draft` 时 `version_name` 常为空 |
|
||
| `version_count` | int | 已封存 formal 数量 |
|
||
| `versions` | `VersionSummary[]` | **仅 get** 返回;已封存 formal;详情历史下拉 / 训练选版数据源(omitempty) |
|
||
| `stats` | `CollectionStats` | 当前查看版本样本统计(omitempty);list / get 均有 |
|
||
| `task_status_stats` | `map[string]TaskStats` | list / get 均返回;按任务类型 `labeled` / `unlabeled` / `total`(omitempty);见 §6.9 |
|
||
|
||
### 6.4 `VersionBrief` / `VersionSummary`
|
||
|
||
**`VersionBrief`**(`highest_version` / `baseline_version` / `current_version` / `editable_version` / save 响应内嵌)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `version_id` | string | `dv_*` |
|
||
| `version_name` | string | formal 如 `V1`;draft 通常为空 |
|
||
| `version_type` | string | `formal` \| `draft`(`snapshot` 已废弃,不再新建) |
|
||
| `version_creator_id` | string | d-cloud `userName`;draft 操作人或封存作者(omitempty) |
|
||
|
||
**`VersionSummary`**(get 的 `versions[]`)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `version_id` | string | |
|
||
| `version_name` | string | |
|
||
| `version_type` | string | `formal`(`snapshot` 仅历史存量) |
|
||
| `saved_at` | string | 封存时间 RFC3339;非空表示已 save(omitempty) |
|
||
| `saved_by` | string | 封存操作者 user ID(omitempty) |
|
||
| `version_creator_id` | string | 操作人展示名;存量行 fallback `saved_by`(omitempty) |
|
||
| `description` | string | 版本描述(omitempty) |
|
||
| `is_latest` | bool | 是否为最新封存的 formal |
|
||
| `is_baseline` | bool | 是否为当前基准 |
|
||
| `based_on_version_id` | string | 封存时记录的基准版本 id(omitempty) |
|
||
| `based_on_version_name` | string | 血缘展示,如「基于 V1」(omitempty) |
|
||
| `has_task_binding` | bool | 是否被训练/评测任务绑定;`true` 时不可 delete |
|
||
|
||
### 6.4.1 `VersionTreeNode` — GET `/collections/version-tree` 响应
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `version_id` | string | BFF 版本 id(omitempty) |
|
||
| `dataset_id` | string | 兼容字段,值为 `collection_id` |
|
||
| `collection_id` | string | |
|
||
| `version` | string | 版本名,如 `V1` |
|
||
| `status` | string | 固定 `published` |
|
||
| `description` | string | omitempty |
|
||
| `related_version` | string | 父版本名;根节点为空字符串 |
|
||
| `current_flag` | bool | 是否为当前基准(`baseline_version_id`) |
|
||
| `is_latest` | bool | 是否为最高封存 formal(omitempty) |
|
||
| `version_creator_id` | string | 操作人展示名(omitempty) |
|
||
| `created_at` | string | RFC3339;优先 `saved_at` |
|
||
| `updated_at` | string | RFC3339 |
|
||
| `children` | `VersionTreeNode[]` | 子节点,递归同结构 |
|
||
|
||
### 6.5 `CameraIntrinsics`
|
||
|
||
深度任务相机内参,来自 dataset-core `extra_info`,只读展示。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `fx` | float64 | 焦距 x |
|
||
| `fy` | float64 | 焦距 y |
|
||
| `cx` | float64 | 主点 x |
|
||
| `cy` | float64 | 主点 y |
|
||
| `baseline` | float64 | 双目基线(与深度单位一致) |
|
||
|
||
```json
|
||
"camera_intrinsics": {
|
||
"fx": 718.856,
|
||
"fy": 718.856,
|
||
"cx": 607.1928,
|
||
"cy": 185.2157,
|
||
"baseline": 0.5327
|
||
}
|
||
```
|
||
|
||
### 6.6 `KeypointCategoryConfig`
|
||
|
||
关键点骨架配置;**读**(get/list/`labels/parser`)时 BFF 将 core `skeleton` 下标归一化为 **0-based**(减去 core `index_base`,该字段不对外暴露);**写**(create/update)时前端同样按 0-based 传 `skeleton`,BFF 固定按 **COCO 格式**写入下游(`index_base=1`,skeleton 各下标 +1)。`keypoints` 各元素 name 非空时即按此约定处理。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | string | 类别名,与标注 `label`、collection `labels` 一致 |
|
||
| `used` | bool | 该类别配置是否已被样本标注使用;**仅读响应**(get/list/`labels/parser`)由下游透传;create/update 写入时 BFF 不发送该字段 |
|
||
| `keypoints` | string[] | 关键点名称列表;数组下标即 skeleton 引用索引(0 起) |
|
||
| `virtual_initial_points` | float[][] | 虚拟初始点 `[x, y]` 列表, 坐标为**归一化值** (相对图像宽高, 通常 0~1), 数组长度与 `keypoints` 对齐 (omitempty) |
|
||
| `skeleton` | int[][] | 骨架连线 `[i, j]` 对;`i`/`j` 为 `keypoints` 数组下标,**0 起**(omitempty) |
|
||
|
||
读响应示例(`CollectionCard` / `ParseLabelsResponse` 中的 `keypoints_configs`):
|
||
|
||
```json
|
||
"keypoints_configs": [
|
||
{
|
||
"name": "person",
|
||
"used": true,
|
||
"keypoints": ["nose", "l_eye", "r_eye", "l_shoulder", "r_shoulder"],
|
||
"virtual_initial_points": [[0.5, 0.375], [0.47, 0.34], [0.53, 0.34], [0.44, 0.56], [0.56, 0.56]],
|
||
"skeleton": [[0, 1], [0, 2], [3, 4]]
|
||
}
|
||
]
|
||
```
|
||
|
||
create / update 请求示例(BFF 会将 `skeleton` 转为 `[[1,2],[1,3],[4,5]]` 写入下游, `virtual_initial_points` 原样透传;无需传 `used`):
|
||
|
||
```json
|
||
{
|
||
"dataset_kind": "training",
|
||
"name": "pose-v1",
|
||
"task_types": ["keypoint"],
|
||
"labels": ["person"],
|
||
"sources": [{ "source_type": "dataspace", "path": "/data/pose" }],
|
||
"keypoints_configs": [
|
||
{
|
||
"name": "person",
|
||
"keypoints": ["nose", "l_eye", "r_eye", "l_shoulder", "r_shoulder"],
|
||
"virtual_initial_points": [[0.5, 0.375], [0.47, 0.34], [0.53, 0.34], [0.44, 0.56], [0.56, 0.56]],
|
||
"skeleton": [[0, 1], [0, 2], [3, 4]]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"collection_id": "dc_xxx",
|
||
"version_id": "dv_xxx",
|
||
"keypoints_configs": [
|
||
{
|
||
"name": "person",
|
||
"keypoints": ["nose", "l_eye", "r_eye", "l_shoulder", "r_shoulder"],
|
||
"virtual_initial_points": [[0.5, 0.375], [0.47, 0.34], [0.53, 0.34], [0.44, 0.56], [0.56, 0.56]],
|
||
"skeleton": [[0, 1], [0, 2], [3, 4]]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.7 `CollectionStats`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `total_count` | int64 | 样本总数 |
|
||
| `labeled_count` | int64 | 已标注数 |
|
||
| `unlabeled_count` | int64 | 未标注数 |
|
||
|
||
### 6.8 `SampleItem`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | uint64 | 样本 ID;`samples/delete` 的 `sample_ids` 元素 |
|
||
| `type` | string | `train` / `val` / `test` / `error`,§4.8 |
|
||
| `name` | string | 展示名(basename) |
|
||
| `storage_path` | string | 对象存储路径(omitempty) |
|
||
| `width` | int | 图片宽度(像素) |
|
||
| `height` | int | 图片高度(像素) |
|
||
| `annotations` | object | 按 `task_type` 分 key;各 value 结构 §4.6 |
|
||
| `task_annotation_statuses` | object | key=`task_type`,value=`labeled`\|`unlabeled` |
|
||
| `labels` | string[] | 样本级标签(omitempty) |
|
||
| `is_labeled` | bool | 行级是否已标注 |
|
||
| `status` | string | core 行级状态透传(omitempty),§4.8 |
|
||
| `status_text` | string | 展示文案(omitempty) |
|
||
| `last_update_time` | int64 | 更新时间 Unix 秒(omitempty) |
|
||
| `thumbnail_url` | string | BFF 预留;当前恒为空字符串 |
|
||
|
||
### 6.9 `SampleStatusStats` / `TaskStats`
|
||
|
||
**`SampleStatusStats`**(`ListSamplesResponse.status_stats`)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `labeled` | int64 | 已标注 Tab 计数 |
|
||
| `unlabeled` | int64 | 未标注 Tab 计数 |
|
||
|
||
**`TaskStats`**(`CollectionCard.task_status_stats[task_type]`(list / get)/ `ListSamplesResponse.task_status_stats`(samples/list))
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `labeled` | int64 | 该任务已标注数 |
|
||
| `unlabeled` | int64 | 该任务未标注数 |
|
||
| `total` | int64 | 该任务样本总数 |
|
||
|
||
### 6.10 前端辅助:`canMutate` / 版本条显示
|
||
|
||
```typescript
|
||
function editableVersionId(c: CollectionCard) {
|
||
return c.editable_version?.version_id || '';
|
||
}
|
||
function baselineVersionId(c: CollectionCard) {
|
||
return c.baseline_version?.version_id || c.current_version?.version_id || '';
|
||
}
|
||
const canMutate = Boolean(editableVersionId(card));
|
||
// 版本条:有 highest/baseline/versions 或非 creating 且有 draft 即展示(见 testui showCollectionVersionBar)
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 接口索引
|
||
|
||
| # | Method | Path |
|
||
|---|--------|------|
|
||
| 1 | POST | `/collections/list` |
|
||
| 2 | POST | `/collections/create` |
|
||
| 3 | GET | `/collections/get` |
|
||
| 4 | GET | `/collections/version-tree` |
|
||
| 5 | POST | `/collections/update` |
|
||
| 6 | DELETE | `/collections/delete` |
|
||
| 7 | POST | `/versions/switch-baseline` |
|
||
| 7.1 | POST | `/versions/switch`(deprecated) |
|
||
| 8 | POST | `/versions/save` |
|
||
| 9 | POST | `/versions/promote-snapshot`(deprecated) |
|
||
| 10 | DELETE | `/versions/delete` |
|
||
| 11 | POST | `/samples/list` |
|
||
| 12 | POST | `/samples/import` |
|
||
| 13 | POST | `/samples/delete` |
|
||
| 14 | POST | `/export` |
|
||
| 15 | POST | `/labels/parser` |
|
||
|
||
---
|
||
|
||
*修改 DTO / 状态映射时请同步更新本文、`dataset_swagger.json`、`dataset_frontend_integration_guide.md` 与 `dataset_changelog_since_merge_dev_32.md`。*
|