TBC/api_docs/dataset_api.md

1548 lines
69 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 视觉感知工作台 · 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`。*