Design Document: 任务分配与模板管理

Overview

本设计文档描述了标注平台的任务分配与模板管理功能的技术实现方案。该功能将完善现有平台的工作流程，实现从管理员（数据源）→ 任务派发 → 人员标注任务分配 → 数据收集 → 数据导出的完整闭环。

主要包含两大模块：

任务分配系统：支持管理员将任务分配给特定标注人员，标注人员只能看到分配给自己的任务
模板管理系统：提供类似 LabelStudio 的模板选择界面和自定义 XML 配置编辑器

技术栈：

前端: React + TypeScript + Jotai + @humansignal/ui + Monaco Editor
后端: Python FastAPI + SQLite/MySQL
编辑器: Monaco Editor (XML 语法高亮) + @humansignal/editor (预览)

Architecture

System Architecture

graph TB
    subgraph "Frontend (web/apps/lq_label)"
        A[React App] --> B[Layout Component]
        B --> C[User Management View]
        B --> D[Task Assignment View]
        B --> E[Template Manager View]
        B --> F[Config Editor View]
        B --> G[Export View]
        
        E --> H[Template Gallery]
        E --> I[Template Preview]
        
        F --> J[Monaco Editor]
        F --> K[Visual Builder]
        F --> L[Live Preview]
        
        A --> M[Jotai State Management]
    end
    
    subgraph "Backend (backend/)"
        N[FastAPI Server] --> O[User API]
        N --> P[Task Assignment API]
        N --> Q[Template API]
        N --> R[Export API]
        N --> S[Statistics API]
        
        O --> T[Database]
        P --> T
        Q --> T
        R --> T
        S --> T
    end
    
    A -->|HTTP/REST| N

Task Assignment Flow

sequenceDiagram
    participant Admin as 管理员
    participant Frontend as 前端
    participant Backend as 后端
    participant DB as 数据库
    
    Admin->>Frontend: 选择任务
    Admin->>Frontend: 点击分配按钮
    Frontend->>Backend: GET /api/users?role=annotator
    Backend->>DB: 查询标注人员列表
    DB-->>Backend: 返回用户列表
    Backend-->>Frontend: 返回用户列表
    Frontend->>Admin: 显示用户选择对话框
    Admin->>Frontend: 选择用户并确认
    Frontend->>Backend: PUT /api/tasks/{id}/assign
    Backend->>DB: 更新任务分配
    DB-->>Backend: 确认更新
    Backend-->>Frontend: 返回更新后的任务
    Frontend->>Admin: 显示分配成功

Template Selection Flow

sequenceDiagram
    participant Admin as 管理员
    participant Frontend as 前端
    participant Editor as 编辑器
    
    Admin->>Frontend: 创建项目
    Frontend->>Admin: 显示模板选择界面
    Admin->>Frontend: 选择模板类别
    Frontend->>Admin: 显示模板列表
    Admin->>Frontend: 选择具体模板
    Frontend->>Editor: 加载模板配置
    Editor->>Admin: 显示预览效果
    Admin->>Frontend: 确认使用模板
    Frontend->>Frontend: 填充配置到项目表单

Components and Interfaces

Frontend Components

1. UserManagementView

Location: web/apps/lq_label/src/views/user-management-view/

Responsibility: 用户管理界面，显示用户列表和任务统计

Interface:

interface UserManagementViewProps {}

interface UserWithStats {
  id: string;
  username: string;
  email: string;
  role: 'admin' | 'annotator' | 'viewer';
  created_at: string;
  task_stats: {
    assigned_count: number;
    completed_count: number;
    annotation_count: number;
    completion_rate: number;
  };
}

Features:

用户列表展示（使用 DataTable）
角色筛选
用户搜索
任务统计显示

2. TaskAssignmentDialog

Location: web/apps/lq_label/src/components/task-assignment-dialog/

Responsibility: 任务分配对话框

Interface:

interface TaskAssignmentDialogProps {
  open: boolean;
  taskIds: string[];
  onClose: () => void;
  onAssign: (userId: string) => Promise<void>;
}

interface AssignableUser {
  id: string;
  username: string;
  email: string;
  current_task_count: number;
}

Features:

用户选择列表
当前工作量显示
批量分配支持
平均分配选项

3. TemplateGallery

Location: web/apps/lq_label/src/components/template-gallery/

Responsibility: 模板选择画廊

Interface:

interface TemplateGalleryProps {
  onSelect: (template: Template) => void;
  selectedId?: string;
}

interface Template {
  id: string;
  name: string;
  category: TemplateCategory;
  description: string;
  config: string;
  preview_image?: string;
  tags: string[];
}

type TemplateCategory = 
  | 'image_classification'
  | 'object_detection'
  | 'image_segmentation'
  | 'text_classification'
  | 'ner'
  | 'text_labeling'
  | 'audio_transcription'
  | 'video_annotation';

Features:

分类筛选
模板搜索
模板预览卡片
选中状态显示

4. ConfigEditor

Location: web/apps/lq_label/src/components/config-editor/

Responsibility: 标注配置编辑器（代码模式 + 可视化模式）

Interface:

interface ConfigEditorProps {
  value: string;
  onChange: (value: string) => void;
  mode: 'code' | 'visual';
  onModeChange: (mode: 'code' | 'visual') => void;
  previewData?: Record<string, any>;
}

interface ValidationResult {
  valid: boolean;
  errors: Array<{
    line: number;
    column: number;
    message: string;
  }>;
}

Features:

Monaco Editor 集成（XML 语法高亮）
实时语法验证
错误提示
模式切换

5. VisualConfigBuilder

Location: web/apps/lq_label/src/components/visual-config-builder/

Responsibility: 可视化配置构建器

Interface:

interface VisualConfigBuilderProps {
  value: string;
  onChange: (value: string) => void;
}

interface ConfigComponent {
  type: string;
  name: string;
  icon: React.ReactNode;
  category: 'data' | 'annotation' | 'layout';
  defaultProps: Record<string, any>;
}

Features:

组件面板
拖拽构建
属性编辑面板
组件树视图

6. ConfigPreview

Location: web/apps/lq_label/src/components/config-preview/

Responsibility: 配置预览面板

Interface:

interface ConfigPreviewProps {
  config: string;
  data?: Record<string, any>;
  onError?: (error: string) => void;
}

Features:

LabelStudio 编辑器集成
示例数据支持
错误显示
全屏模式

7. DataExportDialog

Location: web/apps/lq_label/src/components/data-export-dialog/

Responsibility: 数据导出对话框

Interface:

interface DataExportDialogProps {
  open: boolean;
  projectId: string;
  onClose: () => void;
}

type ExportFormat = 'json' | 'csv' | 'coco' | 'yolo';

interface ExportOptions {
  format: ExportFormat;
  status_filter?: 'all' | 'completed' | 'pending' | 'in_progress';
  include_metadata: boolean;
}

Features:

格式选择
状态筛选
进度显示
下载触发

8. ProjectStatisticsPanel

Location: web/apps/lq_label/src/components/project-statistics-panel/

Responsibility: 项目统计面板

Interface:

interface ProjectStatisticsPanelProps {
  projectId: string;
}

interface ProjectStatistics {
  total_tasks: number;
  completed_tasks: number;
  in_progress_tasks: number;
  pending_tasks: number;
  total_items: number;
  annotated_items: number;
  completion_rate: number;
  user_stats: UserTaskStats[];
}

interface UserTaskStats {
  user_id: string;
  username: string;
  assigned_tasks: number;
  completed_tasks: number;
  annotation_count: number;
  completion_rate: number;
}

Features:

项目级统计
人员级统计
进度条可视化
实时更新

Backend API Endpoints

User API Extensions

Router: backend/routers/user.py

New Endpoints:

GET    /api/users                    # List all users (admin only)
GET    /api/users/{id}               # Get user by ID
GET    /api/users/{id}/stats         # Get user task statistics
GET    /api/users/annotators         # List annotators for assignment

Models:

class UserResponse(BaseModel):
    id: str
    username: str
    email: str
    role: str
    created_at: datetime

class UserWithStatsResponse(UserResponse):
    task_stats: TaskStats

class TaskStats(BaseModel):
    assigned_count: int
    completed_count: int
    annotation_count: int
    completion_rate: float

Task Assignment API

Router: backend/routers/task.py (扩展)

New Endpoints:

PUT    /api/tasks/{id}/assign        # Assign task to user
POST   /api/tasks/batch-assign       # Batch assign tasks
GET    /api/tasks/my-tasks           # Get current user's tasks

Models:

class TaskAssignRequest(BaseModel):
    user_id: str

class BatchAssignRequest(BaseModel):
    task_ids: List[str]
    user_ids: List[str]
    mode: str = 'round_robin'  # 'round_robin' | 'equal'

Template API

Router: backend/routers/template.py

Endpoints:

GET    /api/templates                # List all templates
GET    /api/templates/{id}           # Get template by ID
GET    /api/templates/categories     # List template categories
POST   /api/templates/validate       # Validate XML config

Models:

class TemplateResponse(BaseModel):
    id: str
    name: str
    category: str
    description: str
    config: str
    preview_image: Optional[str]
    tags: List[str]

class ConfigValidationRequest(BaseModel):
    config: str

class ConfigValidationResponse(BaseModel):
    valid: bool
    errors: List[ValidationError]

Export API

Router: backend/routers/export.py

Endpoints:

POST   /api/projects/{id}/export     # Export project annotations
GET    /api/exports/{id}/status      # Get export job status
GET    /api/exports/{id}/download    # Download export file

Models:

class ExportRequest(BaseModel):
    format: str  # 'json' | 'csv' | 'coco' | 'yolo'
    status_filter: Optional[str]
    include_metadata: bool = True

class ExportResponse(BaseModel):
    export_id: str
    status: str
    download_url: Optional[str]

Statistics API

Router: backend/routers/statistics.py

Endpoints:

GET    /api/projects/{id}/statistics # Get project statistics
GET    /api/statistics/overview      # Get overall platform statistics

Models:

class ProjectStatisticsResponse(BaseModel):
    total_tasks: int
    completed_tasks: int
    in_progress_tasks: int
    pending_tasks: int
    total_items: int
    annotated_items: int
    completion_rate: float
    user_stats: List[UserTaskStats]

Data Models

Database Schema Extensions

-- 预设模板表 (可选，也可以使用静态配置)
CREATE TABLE templates (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    description TEXT,
    config TEXT NOT NULL,
    preview_image TEXT,
    tags TEXT,  -- JSON array
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 导出任务表
CREATE TABLE export_jobs (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    format TEXT NOT NULL,
    status TEXT DEFAULT 'pending',  -- pending, processing, completed, failed
    file_path TEXT,
    error_message TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP,
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);

-- 任务分配历史表 (可选，用于追踪分配记录)
CREATE TABLE task_assignments (
    id TEXT PRIMARY KEY,
    task_id TEXT NOT NULL,
    assigned_to TEXT NOT NULL,
    assigned_by TEXT NOT NULL,
    assigned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    FOREIGN KEY (assigned_to) REFERENCES users(id),
    FOREIGN KEY (assigned_by) REFERENCES users(id)
);

State Management (Jotai Atoms)

Location: web/apps/lq_label/src/atoms/

// userAtoms.ts
export const usersAtom = atom<UserWithStats[]>([]);
export const annotatorsAtom = atom<AssignableUser[]>([]);
export const userLoadingAtom = atom<boolean>(false);

// templateAtoms.ts
export const templatesAtom = atom<Template[]>([]);
export const selectedTemplateAtom = atom<Template | null>(null);
export const templateCategoriesAtom = atom<TemplateCategory[]>([]);

// configEditorAtoms.ts
export const configValueAtom = atom<string>('');
export const configValidationAtom = atom<ValidationResult | null>(null);
export const editorModeAtom = atom<'code' | 'visual'>('code');

// statisticsAtoms.ts
export const projectStatisticsAtom = atom<ProjectStatistics | null>(null);
export const statisticsLoadingAtom = atom<boolean>(false);

// exportAtoms.ts
export const exportJobAtom = atom<ExportJob | null>(null);
export const exportProgressAtom = atom<number>(0);

Predefined Templates

模板将以静态配置的形式存储在前端：

// templates/index.ts
export const PREDEFINED_TEMPLATES: Template[] = [
  {
    id: 'image_classification_basic',
    name: '图像分类 - 基础',
    category: 'image_classification',
    description: '简单的图像分类任务，支持单选分类',
    config: `<View>
  <Image name="image" value="$image"/>
  <Choices name="choice" toName="image">
    <Choice value="类别1"/>
    <Choice value="类别2"/>
    <Choice value="类别3"/>
  </Choices>
</View>`,
    tags: ['图像', '分类', '单选'],
  },
  {
    id: 'object_detection_bbox',
    name: '目标检测 - 边界框',
    category: 'object_detection',
    description: '使用矩形框标注图像中的目标',
    config: `<View>
  <Image name="image" value="$image"/>
  <RectangleLabels name="label" toName="image">
    <Label value="目标1"/>
    <Label value="目标2"/>
  </RectangleLabels>
</View>`,
    tags: ['图像', '检测', '边界框'],
  },
  // ... 更多模板
];

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: 用户列表筛选正确性

For any 角色筛选值或搜索关键词，返回的用户列表中的所有用户都应该满足筛选条件：

如果按角色筛选，所有用户的 role 字段都应该等于筛选值
如果按关键词搜索，所有用户的 username 或 email 都应该包含该关键词

Validates: Requirements 1.2, 1.3

Property 2: 任务分配正确性

For any 任务和用户的分配操作：

分配后任务的 assigned_to 字段应该等于选择的用户 ID
分配记录应该包含正确的分配时间和分配人信息

Validates: Requirements 2.3, 2.4

Property 3: 批量分配平均性

For any 任务列表和用户列表的批量分配操作（平均分配模式），分配后每个用户分配的任务数量差异不应超过 1。

Validates: Requirements 2.6

Property 4: 标注人员任务可见性

For any 标注人员用户，其任务列表中的所有任务的 assigned_to 字段都应该等于该用户的 ID。任何状态筛选都应该在此基础上进行。

Validates: Requirements 3.1, 3.2

Property 5: 任务状态自动更新

For any 任务，当其所有数据项都被标注后，任务状态应该自动更新为 'completed'。

Validates: Requirements 3.6

Property 6: 模板选择填充

For any 选择的模板，确认选择后项目配置字段的值应该等于模板的 config 值。模板搜索结果中的每个模板的名称或描述都应该包含搜索关键词。

Validates: Requirements 4.4, 4.5

Property 7: XML 配置验证

For any XML 配置字符串，验证结果应该正确反映其语法有效性：

有效的 XML 应该返回 valid: true
无效的 XML 应该返回 valid: false 并包含错误位置信息

Validates: Requirements 5.3, 5.4

Property 8: 配置编辑器同步 (Round-trip)

For any 有效的标注配置：

在代码模式和可视化模式之间切换后，配置内容应该保持语义等价
导出配置后再导入应该得到语义等价的配置

Validates: Requirements 5.6, 5.8

Property 9: 可视化编辑器 XML 生成

For any 组件拖拽或属性修改操作，生成的 XML 代码应该正确反映该操作：

拖拽组件后，XML 应该包含该组件的标签
修改属性后，XML 中对应的属性值应该更新

Validates: Requirements 6.3, 6.6

Property 10: 配置预览错误处理

For any 无效的标注配置，预览面板应该显示错误信息而不是崩溃或显示空白。

Validates: Requirements 7.5

Property 11: 数据导出完整性

For any 导出请求：

导出的数据应该只包含匹配状态筛选条件的任务
导出文件应该包含完整的任务元数据和标注结果
导出格式应该符合所选格式的规范（JSON/CSV/COCO/YOLO）

Validates: Requirements 8.3, 8.4, 8.5

Property 12: 统计数据准确性

For any 项目或用户：

项目统计应该准确反映实际的任务数量和状态分布
用户统计应该准确反映该用户的任务分配和完成情况
进度百分比应该等于 (已标注数 / 总数) * 100
标注操作后统计数据应该立即更新

Validates: Requirements 9.2, 9.3, 9.6, 9.7

Error Handling

Frontend Error Handling

API 请求错误
- 使用 try-catch 包装所有 API 调用
- 显示用户友好的错误消息
- 记录错误到控制台
配置验证错误
- 实时显示 XML 语法错误
- 高亮错误位置
- 提供修复建议
导出错误
- 显示导出失败原因
- 支持重试
- 提供错误日志下载
编辑器错误
- Monaco Editor 加载失败时显示降级方案
- LabelStudio 预览失败时显示错误信息

Backend Error Handling

权限错误
- 非管理员访问用户管理返回 403
- 标注人员访问非分配任务返回 403
数据验证错误
- 无效的 XML 配置返回 400
- 无效的导出格式返回 400
资源不存在
- 用户/任务/项目不存在返回 404
导出错误
- 导出失败记录错误日志
- 返回失败状态和错误信息

Testing Strategy

Unit Testing

Frontend:

测试组件渲染和交互
测试状态管理逻辑
测试 XML 验证函数
测试统计计算函数

Backend:

测试 API 端点
测试数据库操作
测试导出格式转换
测试权限检查

Property-Based Testing

配置:

前端使用 fast-check
后端使用 Hypothesis
每个属性测试至少运行 100 次迭代
使用 Feature: task-assignment-template, Property N: {property_text} 格式标记测试

重点属性测试:

Property 1: 用户列表筛选
Property 3: 批量分配平均性
Property 4: 标注人员任务可见性
Property 7: XML 配置验证
Property 8: 配置编辑器同步
Property 11: 数据导出完整性
Property 12: 统计数据准确性

Integration Testing

测试完整的任务分配流程
测试模板选择到项目创建流程
测试配置编辑到预览流程
测试数据导出流程

Implementation Notes

Monaco Editor Integration

// 安装依赖
// npm install @monaco-editor/react

import Editor from '@monaco-editor/react';

const ConfigCodeEditor: React.FC<Props> = ({ value, onChange }) => {
  return (
    <Editor
      height="400px"
      language="xml"
      value={value}
      onChange={(value) => onChange(value || '')}
      options={{
        minimap: { enabled: false },
        lineNumbers: 'on',
        wordWrap: 'on',
        automaticLayout: true,
      }}
    />
  );
};

XML Validation

// 使用 DOMParser 进行 XML 验证
function validateXML(xml: string): ValidationResult {
  const parser = new DOMParser();
  const doc = parser.parseFromString(xml, 'application/xml');
  const parseError = doc.querySelector('parsererror');
  
  if (parseError) {
    return {
      valid: false,
      errors: [{
        line: 1,
        column: 1,
        message: parseError.textContent || 'XML 解析错误',
      }],
    };
  }
  
  return { valid: true, errors: [] };
}

Export Format Converters

# backend/services/export_service.py

def export_to_json(annotations: List[Annotation]) -> str:
    return json.dumps([a.to_dict() for a in annotations], indent=2)

def export_to_csv(annotations: List[Annotation]) -> str:
    # 使用 pandas 或 csv 模块
    pass

def export_to_coco(annotations: List[Annotation]) -> str:
    # COCO 格式转换
    pass

def export_to_yolo(annotations: List[Annotation]) -> str:
    # YOLO 格式转换
    pass

Statistics Calculation

# backend/services/statistics_service.py

def calculate_project_statistics(project_id: str) -> ProjectStatistics:
    with get_db_connection() as conn:
        cursor = conn.cursor()
        
        # 任务统计
        cursor.execute("""
            SELECT 
                COUNT(*) as total,
                SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed,
                SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END) as in_progress,
                SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pending
            FROM tasks WHERE project_id = ?
        """, (project_id,))
        
        # 标注统计
        cursor.execute("""
            SELECT COUNT(*) as total_annotations
            FROM annotations a
            JOIN tasks t ON a.task_id = t.id
            WHERE t.project_id = ?
        """, (project_id,))
        
        # 用户统计
        cursor.execute("""
            SELECT 
                u.id, u.username,
                COUNT(DISTINCT t.id) as assigned_tasks,
                SUM(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END) as completed_tasks,
                COUNT(a.id) as annotation_count
            FROM users u
            LEFT JOIN tasks t ON t.assigned_to = u.id AND t.project_id = ?
            LEFT JOIN annotations a ON a.task_id = t.id AND a.user_id = u.id
            WHERE u.role = 'annotator'
            GROUP BY u.id, u.username
        """, (project_id,))
        
        # 返回统计结果
        pass

Deployment Considerations

Frontend

Monaco Editor 需要额外的 webpack 配置
确保 @humansignal/editor 正确集成
配置 CSS 前缀处理

Backend

导出大文件时考虑使用异步任务队列
统计查询可能需要缓存优化
考虑添加导出文件的定期清理

Database

添加必要的索引优化查询性能
考虑统计数据的物化视图

design.md 22 KB Istoric Crud

Design Document: 任务分配与模板管理

Overview

Architecture

System Architecture

Task Assignment Flow

Template Selection Flow

Components and Interfaces

Frontend Components

1. UserManagementView

2. TaskAssignmentDialog

3. TemplateGallery

4. ConfigEditor

5. VisualConfigBuilder

6. ConfigPreview

7. DataExportDialog

8. ProjectStatisticsPanel

Backend API Endpoints

User API Extensions

Task Assignment API

Template API

Export API

Statistics API

Data Models

Database Schema Extensions

State Management (Jotai Atoms)

Predefined Templates

Correctness Properties

Property 1: 用户列表筛选正确性

Property 2: 任务分配正确性

Property 3: 批量分配平均性

Property 4: 标注人员任务可见性

Property 5: 任务状态自动更新

Property 6: 模板选择填充

Property 7: XML 配置验证

Property 8: 配置编辑器同步 (Round-trip)

Property 9: 可视化编辑器 XML 生成

Property 10: 配置预览错误处理

Property 11: 数据导出完整性

Property 12: 统计数据准确性

Error Handling

Frontend Error Handling

Backend Error Handling

Testing Strategy

Unit Testing

Property-Based Testing

Integration Testing

Implementation Notes

Monaco Editor Integration

XML Validation

Export Format Converters

Statistics Calculation

Deployment Considerations

Frontend

Backend

Database

design.md 22 KB

Istoric Crud