@glodon-aiot/dataset-annotation 3.25.1-alpha.2 → 3.25.1-alpha.4

package/dist/src/components/OCRImageViewer/index.d.ts

@@ -25,6 +25,7 @@ interface OCRImageViewerProps {
     children?: ReactNode;
     labels?: TInfer[];
     onImageLoad?: (img: HTMLImageElement) => void;
+    onImageError?: () => void;
 }
 export interface OCRImageViewerRefProps {
     onImageLoad?: (img: HTMLImageElement) => void;

package/dist/src/components/VersionCompare/VersionCompareSelectModal/index.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+import { CVForceDatahubApi, IVersion } from '@glodon-aiot/apis';
+export interface VersionCompareSelectModalProps {
+    open: boolean;
+    datasetId?: string;
+    datasetName?: string;
+    initialBaseVersionId?: string;
+    initialTargetVersionId?: string;
+    versions?: IVersion[];
+    cvforceDatahub?: CVForceDatahubApi;
+    useMock?: boolean;
+    onCancel: () => void;
+    onConfirm: (baseVersionId: string, targetVersionId: string, baseVersion?: IVersion, targetVersion?: IVersion) => void;
+}
+declare const VersionCompareSelectModal: React.FC<VersionCompareSelectModalProps>;
+export default VersionCompareSelectModal;

package/dist/src/components/VersionCompare/adapter.d.ts

@@ -0,0 +1,50 @@
+import { CVForceDatahubApi, IVersionCompareSampleItem, IVersionCompareSamplesParams, IVersionCompareSummary, IVersionCompareSummaryParams, Paged } from '@glodon-aiot/apis';
+import { MockCompareScene } from './mock';
+import { VersionCompareAsyncTaskProgress, VersionCompareSampleItemVM, VersionCompareSamplesPageVM, VersionCompareSummaryVM } from './types';
+/**
+ * 格式化对比时间戳为 YYYY-MM-DD HH:mm:ss。
+ * 兼容毫秒级与秒级时间戳；空值或 0 显示为 -
+ */
+export declare const formatCompareTimestamp: (ts?: number | string) => string;
+/**
+ * 将后端对比概览 DTO 转换为前端内部 ViewModel
+ */
+export declare const adaptVersionCompareSummary: (raw: IVersionCompareSummary, extraLabelNames?: string[]) => VersionCompareSummaryVM;
+/**
+ * 将单条对比样本 DTO 转换为前端内部 ViewModel，并注入一致的标签颜色
+ */
+export declare const adaptVersionCompareSampleItem: (item: IVersionCompareSampleItem, colorMap?: Map<string, string>) => VersionCompareSampleItemVM;
+/**
+ * 将后端对比样本分页列表 DTO 转换为前端内部 ViewModel
+ */
+export declare const adaptVersionCompareSamples: (paged: Paged<IVersionCompareSampleItem> & {
+    items?: IVersionCompareSampleItem[];
+    total?: number;
+}, colorMap?: Map<string, string>) => VersionCompareSamplesPageVM;
+export interface VersionCompareAdapterOptions {
+    cvforceDatahub?: CVForceDatahubApi;
+    /** 强制使用本地结构化 Mock 数据 */
+    useMock?: boolean;
+    /** 接口失败时是否降级到 Mock。默认关闭，失败直接抛出。 */
+    fallbackToMockOnError?: boolean;
+    /** Mock 数据场景（默认根据 datasetId 或传入 markType 自动推断） */
+    mockScene?: MockCompareScene;
+    /** 覆盖 Mock 数据集名称 */
+    mockDatasetName?: string;
+    /** 预留异步对比任务轮询间隔（毫秒，默认 2000ms） */
+    asyncPollIntervalMs?: number;
+    /** 预留异步对比任务最大轮询次数（默认 60 次） */
+    maxAsyncPollAttempts?: number;
+    /** 预留异步对比任务进度回调（若后续后端切换为异步任务，可通过该回调驱动进度条） */
+    onAsyncTaskProgress?: (progress: VersionCompareAsyncTaskProgress) => void;
+    /** 取消信号（组件卸载或切换版本时中止异步轮询） */
+    signal?: AbortSignal;
+}
+/**
+ * 获取版本对比概览。接口为同步返回，失败时仅在显式开启 fallbackToMockOnError 时降级到 Mock。
+ */
+export declare const fetchVersionCompareSummaryWithAdapter: (datasetId: string, params: IVersionCompareSummaryParams, options?: VersionCompareAdapterOptions) => Promise<VersionCompareSummaryVM>;
+/**
+ * 获取版本对比分页样本列表（支持标签颜色注入与本地 Mock 降级）
+ */
+export declare const fetchVersionCompareSamplesWithAdapter: (datasetId: string, params: IVersionCompareSamplesParams, colorMap?: Map<string, string>, options?: VersionCompareAdapterOptions) => Promise<VersionCompareSamplesPageVM>;

package/dist/src/components/VersionCompare/components/DataChangeStatsCard.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { IVersionCompareChangeStats } from '../types';
+export interface DataChangeStatsCardProps {
+    baseVersionNo: string;
+    targetVersionNo: string;
+    changeStats: IVersionCompareChangeStats;
+}
+declare const DataChangeStatsCard: React.FC<DataChangeStatsCardProps>;
+export default DataChangeStatsCard;

package/dist/src/components/VersionCompare/components/DiffValue.d.ts

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+export interface DiffValueProps {
+    /** 目标版本当前数值（若传入则与差值并排展示） */
+    value?: number;
+    /** 已计算的差值（目标版本值 - 基准版本值） */
+    diff?: number;
+    /** 基准版本数值（当未直接传 diff 时用于自动计算） */
+    baseValue?: number;
+    /** 目标版本数值（当未直接传 diff 时用于自动计算） */
+    targetValue?: number;
+    /** 主数值与差值之间的间距（px），默认 8px */
+    gap?: number;
+    className?: string;
+}
+/**
+ * 版本对比通用差值展示组件
+ * 规则：差值 = 目标版本值 - 基准版本值
+ * - > 0：展示 +N（#FF4D4F）
+ * - < 0：展示 -|N|（#52C41A）
+ * - = 0：不展示差值标识
+ */
+declare const DiffValue: React.FC<DiffValueProps>;
+export default DiffValue;

package/dist/src/components/VersionCompare/components/LabelComparisonCard.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { VersionCompareLabelRowVM } from '../types';
+export interface LabelComparisonCardProps {
+    markType: 'detection' | 'ocr' | string;
+    ocrMarkTmpl?: string;
+    isOcrDetection?: boolean;
+    baseVersionNo: string;
+    targetVersionNo: string;
+    labelComparisons: VersionCompareLabelRowVM[];
+}
+declare const LabelComparisonCard: React.FC<LabelComparisonCardProps>;
+export default LabelComparisonCard;

package/dist/src/components/VersionCompare/components/ModifiedSampleCompareModal.d.ts

@@ -0,0 +1,48 @@
+import { default as React } from 'react';
+import { VersionCompareSampleItemVM } from '../types';
+export interface ModifiedSampleCompareModalProps {
+    /** 弹窗是否打开 */
+    open: boolean;
+    /** 关闭弹窗回调 */
+    onCancel: () => void;
+    /** 当前选中的修改对比样本项 */
+    item?: VersionCompareSampleItemVM;
+    /** 是否为 OCR 检测数据集 */
+    isOcrDetection: boolean;
+    /** 数据集 ID */
+    datasetId: string;
+    /** 基准版本 ID */
+    baseVersionId: string;
+    /** 基准版本号展示文本（如 V1） */
+    baseVersionNo: string;
+    /** 目标版本 ID */
+    targetVersionId: string;
+    /** 目标版本号展示文本（如 V3） */
+    targetVersionNo: string;
+    /** 统一标签颜色映射表 */
+    labelColorMap?: Map<string, string>;
+    /** 是否存在上一张（在第 1 张时为 false） */
+    canPrev: boolean;
+    /** 是否存在下一张（在最后 1 张时为 false） */
+    canNext: boolean;
+    /** 外部列表是否正在跨页加载 */
+    switching?: boolean;
+    /** 点击上一张 */
+    onPrev: () => void;
+    /** 点击下一张 */
+    onNext: () => void;
+    /** 当前样本两侧主图均加载就绪状态回调（用于驱动后台相邻图片预加载） */
+    onImageReadyChange?: (ready: boolean) => void;
+    /** 注入的 cvforceDatahub 服务实例（真实接口兜底补全单样本详情） */
+    cvforceDatahub?: any;
+    /** 是否启用本地 Mock */
+    useMock?: boolean;
+}
+/**
+ * 修改样本的左右双图并排只读对比弹窗（用于「修改」Tab 下的样本对比查看）
+ * - 左侧展示基准版本（baseSample），右侧展示目标版本（sample）
+ * - 两侧均处于只读模式，各自支持独立的画布缩放与拖拽平移
+ * - OCR 检测模式下在两侧浅蓝版本栏右侧分别展示各自的「标注框数量」
+ */
+declare const ModifiedSampleCompareModal: React.FC<ModifiedSampleCompareModalProps>;
+export default ModifiedSampleCompareModal;

package/dist/src/components/VersionCompare/components/SampleChangeDetailsCard.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+import { IProxy } from '@glodon-aiot/apis';
+import { IVersionCompareChangeStats, VersionCompareChangeType, VersionCompareSampleItemVM } from '../types';
+export interface SampleChangeDetailsCardProps {
+    baseVersionNo: string;
+    targetVersionNo: string;
+    isOcrDetection: boolean;
+    changeStats: IVersionCompareChangeStats;
+    activeTab: VersionCompareChangeType;
+    items: VersionCompareSampleItemVM[];
+    total: number;
+    pageNo: number;
+    pageSize: number;
+    loading?: boolean;
+    imgProxy?: IProxy;
+    onTabChange: (tab: VersionCompareChangeType) => void;
+    onPageChange: (page: number, pageSize: number) => void;
+    onSampleClick?: (item: VersionCompareSampleItemVM, index: number) => void;
+}
+declare const SampleChangeDetailsCard: React.FC<SampleChangeDetailsCardProps>;
+export default SampleChangeDetailsCard;

package/dist/src/components/VersionCompare/components/SingleSampleDetailModal.d.ts

@@ -0,0 +1,46 @@
+import { default as React } from 'react';
+import { VersionCompareChangeType } from '@glodon-aiot/apis';
+import { VersionCompareSampleItemVM } from '../types';
+export interface SingleSampleDetailModalProps {
+    /** 弹窗是否打开 */
+    open: boolean;
+    /** 关闭弹窗回调 */
+    onCancel: () => void;
+    /** 当前选中的对比样本项 */
+    item?: VersionCompareSampleItemVM;
+    /** 当前所属变更类型 Tab */
+    changeType: VersionCompareChangeType;
+    /** 是否为 OCR 检测数据集 */
+    isOcrDetection: boolean;
+    /** 数据集 ID */
+    datasetId: string;
+    /** 基准版本 ID */
+    baseVersionId: string;
+    /** 目标版本 ID */
+    targetVersionId: string;
+    /** 统一标签颜色映射表 */
+    labelColorMap?: Map<string, string>;
+    /** 是否存在上一张（在第 1 张时为 false） */
+    canPrev: boolean;
+    /** 是否存在下一张（在最后 1 张时为 false） */
+    canNext: boolean;
+    /** 外部列表是否正在跨页加载 */
+    switching?: boolean;
+    /** 点击上一张 */
+    onPrev: () => void;
+    /** 点击下一张 */
+    onNext: () => void;
+    /** 当前样本主图加载就绪状态回调（用于驱动后台相邻图片预加载） */
+    onImageReadyChange?: (ready: boolean) => void;
+    /** 注入的 cvforceDatahub 服务实例（真实接口兜底补全单样本详情） */
+    cvforceDatahub?: any;
+    /** 是否启用本地 Mock */
+    useMock?: boolean;
+}
+/**
+ * 单图只读详情弹窗（用于「新增」、「删除」、「无变动」Tab 下的样本查看）
+ * - 物体检测：复用只读态 LabelMaker（支持画布缩放与拖拽平移，禁止框编辑/删除/新建）
+ * - OCR 检测：复用 OCRImageViewer，并在画布右上方额外展示「标注框数量」
+ */
+declare const SingleSampleDetailModal: React.FC<SingleSampleDetailModalProps>;
+export default SingleSampleDetailModal;

package/dist/src/components/VersionCompare/components/VersionCompareHeader.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+export interface VersionCompareHeaderProps {
+    datasetName: string;
+    baseVersionNo: string;
+    targetVersionNo: string;
+    formattedCompareTime: string;
+    /** 是否展示顶部「← 数据集管理 / 版本对比」面包屑导航栏，默认 true */
+    showBreadcrumb?: boolean;
+    onBack?: () => void;
+    onReselect?: () => void;
+}
+declare const VersionCompareHeader: React.FC<VersionCompareHeaderProps>;
+export default VersionCompareHeader;

package/dist/src/components/VersionCompare/components/VersionOverviewCard.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { VersionCompareOverviewRowVM } from '../types';
+export interface VersionOverviewCardProps {
+    baseVersionNo: string;
+    targetVersionNo: string;
+    rows: VersionCompareOverviewRowVM[];
+}
+declare const VersionOverviewCard: React.FC<VersionOverviewCardProps>;
+export default VersionOverviewCard;

package/dist/src/components/VersionCompare/index.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+import { CVForceDatahubApi, IProxy, IVersion } from '@glodon-aiot/apis';
+import { MockCompareScene } from './mock';
+import { VersionCompareChangeType, VersionCompareSampleItemVM } from './types';
+export interface DatasetVersionCompareProps {
+    datasetId: string;
+    baseVersionId: string;
+    targetVersionId: string;
+    datasetName?: string;
+    markType?: 'detection' | 'ocr' | string;
+    ocrMarkTmpl?: string;
+    cvforceDatahub?: CVForceDatahubApi;
+    imgProxy?: IProxy;
+    versions?: IVersion[];
+    /** 是否显示顶部「← 数据集管理 / 版本对比」面包屑栏，默认 true */
+    showBreadcrumb?: boolean;
+    /** 是否强制使用本地 Mock 数据 */
+    useMock?: boolean;
+    /** 当后端接口报错时是否降级到本地 Mock 数据，默认 true */
+    fallbackToMockOnError?: boolean;
+    /** Mock 数据场景（detection | ocr） */
+    mockScene?: MockCompareScene;
+    /** 点击返回按钮回调 */
+    onBack?: () => void;
+    /** 在重新选择对比版本弹窗点击「开始对比」后的回调 */
+    onVersionsChange?: (baseVersionId: string, targetVersionId: string, baseVersion?: IVersion, targetVersion?: IVersion) => void;
+    /** 点击某张样本卡片的回调（阶段 5.2 / 5.3 接入单/双图弹窗） */
+    onSampleClick?: (item: VersionCompareSampleItemVM, index: number, changeType: VersionCompareChangeType) => void;
+}
+declare const DatasetVersionCompare: React.FC<DatasetVersionCompareProps>;
+export default DatasetVersionCompare;
+export * from './types';
+export * from './adapter';
+export * from './mock';

package/dist/src/components/VersionCompare/mock.d.ts

@@ -0,0 +1,25 @@
+import { IVersion, IVersionCompareSampleItem, IVersionCompareSummary, Paged, VersionCompareChangeType } from '@glodon-aiot/apis';
+export type MockCompareScene = 'detection' | 'ocr';
+export declare const MOCK_DATASET_VERSIONS: IVersion[];
+/**
+ * 获取本地结构化 Mock 版本对比概览
+ */
+export declare const getMockVersionCompareSummary: (params: {
+    datasetId: string;
+    baseVersionId: string;
+    targetVersionId: string;
+    scene?: MockCompareScene;
+    datasetName?: string;
+}) => IVersionCompareSummary;
+/**
+ * 获取本地结构化 Mock 版本对比样本分页列表
+ */
+export declare const getMockVersionCompareSamples: (params: {
+    datasetId: string;
+    baseVersionId: string;
+    targetVersionId: string;
+    changeType: VersionCompareChangeType;
+    pageNo?: number;
+    pageSize?: number;
+    scene?: MockCompareScene;
+}) => Paged<IVersionCompareSampleItem>;

package/dist/src/components/VersionCompare/types.d.ts

@@ -0,0 +1,75 @@
+import { ISample, IVersionCompareChangeStats, IVersionCompareLabelItem, IVersionCompareSampleItem, IVersionCompareSummary, IVersionOverviewMetrics, VersionCompareChangeType, VersionCompareTaskStatus } from '@glodon-aiot/apis';
+import { LabelBox } from '../DetectionAnnotation/components/LabelMaker';
+export type { VersionCompareChangeType, VersionCompareTaskStatus, IVersionOverviewMetrics, IVersionCompareChangeStats, IVersionCompareLabelItem, IVersionCompareSummary, IVersionCompareSampleItem, };
+export type VersionCompareOverviewMetricKey = 'totalSampleCount' | 'labeledSampleCount' | 'totalBoxCount';
+export interface VersionCompareOverviewRowVM {
+    key: VersionCompareOverviewMetricKey;
+    metricLabel: string;
+    baseValue: number;
+    targetValue: number;
+    /** 目标版本值 - 基准版本值 */
+    diff: number;
+}
+export interface VersionCompareLabelRowVM extends IVersionCompareLabelItem {
+    color: string;
+    /** 目标版本标注框数 - 基准版本标注框数 */
+    boxDiff: number;
+    /** 目标版本图片数 - 基准版本图片数 */
+    sampleDiff: number;
+}
+export interface VersionCompareSummaryVM {
+    datasetId: string;
+    datasetName: string;
+    markType: 'detection' | 'ocr' | string;
+    ocrMarkTmpl?: string;
+    /** 是否为 OCR 检测类型（隐藏标签明细对比、画布使用 OCRImageViewer） */
+    isOcrDetection: boolean;
+    baseVersionId: string;
+    baseVersionNo: string;
+    targetVersionId: string;
+    targetVersionNo: string;
+    compareTime: number;
+    formattedCompareTime: string;
+    overview: {
+        baseVersion: IVersionOverviewMetrics;
+        targetVersion: IVersionOverviewMetrics;
+    };
+    overviewRows: VersionCompareOverviewRowVM[];
+    changeStats: IVersionCompareChangeStats;
+    labelComparisons: VersionCompareLabelRowVM[];
+    /** 全量标签稳定颜色映射表 */
+    labelColorMap: Map<string, string>;
+    /** 预留异步任务扩展字段 */
+    taskId?: string;
+    taskStatus?: VersionCompareTaskStatus;
+    progress?: number;
+}
+export interface VersionCompareSampleItemVM {
+    fileKey: string;
+    changeType: VersionCompareChangeType;
+    /**
+     * 卡片主样本：
+     * - added / modified / unchanged 为目标版本样本
+     * - deleted 为基准版本样本
+     */
+    sample: ISample;
+    /** 仅当 changeType === 'modified' 时返回基准版本样本 */
+    baseSample?: ISample | null;
+    /** 归一化后的展示文件名 */
+    displayFileName: string;
+    /** 注入稳定颜色后的目标版本（或单图主样本）标注框 */
+    targetColorLabels: LabelBox[];
+    /** 注入稳定颜色后的基准版本标注框（modified 场景左侧画布使用） */
+    baseColorLabels: LabelBox[];
+}
+export interface VersionCompareSamplesPageVM {
+    items: VersionCompareSampleItemVM[];
+    total: number;
+    pageNo: number;
+    pageSize: number;
+}
+export interface VersionCompareAsyncTaskProgress {
+    taskId?: string;
+    taskStatus: VersionCompareTaskStatus;
+    progress?: number;
+}

package/dist/src/components/VersionCompare/utils/labelColors.d.ts

@@ -0,0 +1,13 @@
+import { ISample } from '@glodon-aiot/apis';
+import { LabelBox } from '../../DetectionAnnotation/components/LabelMaker';
+/**
+ * 为版本对比构建稳定的标签颜色映射表（Map<labelKey, color>）
+ * 优先按对比概览中的标签列表顺序分配颜色，再为样本中可能出现的历史标签兜底分配颜色，
+ * 保证基准版本与目标版本中同一标签的标注框颜色完全一致。
+ */
+export declare const buildCompareLabelColorMap: (labelNames?: string[], samples?: Array<Pick<ISample, "labels"> | undefined | null>) => Map<string, string>;
+/**
+ * 为单个样本的 labels 注入稳定颜色，转换为 LabelMaker 所需的 LabelBox[]
+ * 确保所有有效标注框均包含非空 color 字段，不会被 LabelMaker 的 .filter(i => i.color) 过滤
+ */
+export declare const injectSampleLabelColors: (sample?: Pick<ISample, "labels"> | null, colorMap?: Map<string, string>) => LabelBox[];

package/dist/src/createDatasetVersionCompare/index.d.ts

@@ -0,0 +1,26 @@
+import { IVersion } from '@glodon-aiot/apis';
+import { TokenGetter } from '../utils';
+import { MockCompareScene } from '../components/VersionCompare/mock';
+export interface DatasetVersionCompareConfig {
+    getContainer: () => HTMLElement;
+    token: string;
+    getToken?: TokenGetter;
+    datasetId: string;
+    baseVersionId: string;
+    targetVersionId: string;
+    datasetName?: string;
+    markType?: 'detection' | 'ocr' | string;
+    ocrMarkTmpl?: string;
+    apiUrl?: string;
+    showBreadcrumb?: boolean;
+    useMock?: boolean;
+    fallbackToMockOnError?: boolean;
+    mockScene?: MockCompareScene;
+    errorHandlers?: {
+        aiotToken?: (error: Error) => void;
+    };
+    onBack?: () => void;
+    onVersionsChange?: (baseVersionId: string, targetVersionId: string, baseVersion?: IVersion, targetVersion?: IVersion) => void;
+}
+declare const _default: (config: DatasetVersionCompareConfig) => void;
+export default _default;

package/dist/src/index.d.ts

@@ -11,3 +11,9 @@ export { default as VLMAnnotation } from './components/VLMAnnotation';
 export type { VLMAnnotationProps, VLMLabel, VLMSample } from './components/VLMAnnotation';
 export { default as VQAAnnotation } from './components/VQAAnnotation';
 export type { VQAAnnotationRef, VQASample, VQAConversation } from './components/VQAAnnotation';
+export { default as VersionCompareSelectModal } from './components/VersionCompare/VersionCompareSelectModal';
+export type { VersionCompareSelectModalProps } from './components/VersionCompare/VersionCompareSelectModal';
+export { default as DatasetVersionCompare } from './components/VersionCompare';
+export type { DatasetVersionCompareProps } from './components/VersionCompare';
+export { default as createDatasetVersionCompare } from './createDatasetVersionCompare';
+export type { DatasetVersionCompareConfig } from './createDatasetVersionCompare';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glodon-aiot/dataset-annotation",
-  "version": "3.25.1-alpha.2",
+  "version": "3.25.1-alpha.4",
   "module": "./dist/es/index.mjs",
   "main": "./dist/lib/index.js",
   "types": "./dist/src/index.d.ts",
@@ -37,7 +37,7 @@
   "dependencies": {
     "@ant-design/icons": "^5.3.4",
     "@aws-crypto/sha256-js": "^3.0.0",
-    "@glodon-aiot/apis": "^3.25.1-alpha.2",
+    "@glodon-aiot/apis": "^3.25.1-alpha.4",
     "@glodon-aiot/minio": "^0.1.6",
     "@reduxjs/toolkit": "^1.9.5",
     "@types/fabric": "^5.3.2",