Design Document: External API Enhancement

Overview

本设计文档描述了标注平台外部API增强功能的技术实现方案，包括：

项目初始化接口增加标签传入功能
增加多边形标注类型支持
创建长期有效的管理员Token脚本
编写API测试脚本

Architecture

系统架构图

graph TB
    subgraph External System
        ES[样本中心]
    end
    
    subgraph Backend API
        ER[External Router]
        ES_SVC[External Service]
        JWT[JWT Service]
    end
    
    subgraph Database
        DB[(MySQL)]
    end
    
    subgraph Scripts
        TOKEN_SCRIPT[generate_admin_token.py]
        TEST_SCRIPT[test_external_api.py]
    end
    
    ES -->|POST /api/external/projects/init| ER
    ER --> ES_SVC
    ES_SVC --> DB
    JWT --> ES_SVC
    TOKEN_SCRIPT --> JWT
    TEST_SCRIPT -->|HTTP Requests| ER

Components and Interfaces

1. 标签数据结构

class TagItem(BaseModel):
    """标签项"""
    tag: str  # 标签名称
    color: Optional[str] = None  # 颜色，可选，格式: #RRGGBB

2. 更新的项目初始化请求

class ProjectInitRequest(BaseModel):
    name: str
    description: Optional[str] = ""
    task_type: TaskType  # 新增 polygon 类型
    data: List[TaskDataItem]
    external_id: Optional[str] = None
    tags: Optional[List[TagItem]] = None  # 新增标签列表

3. 任务类型枚举更新

class TaskType(str, Enum):
    TEXT_CLASSIFICATION = "text_classification"
    IMAGE_CLASSIFICATION = "image_classification"
    OBJECT_DETECTION = "object_detection"
    NER = "ner"
    POLYGON = "polygon"  # 新增多边形标注

4. XML配置生成逻辑

根据任务类型和标签生成对应的XML配置：

def generate_config_with_tags(task_type: TaskType, tags: List[TagItem]) -> str:
    """根据任务类型和标签生成XML配置"""
    # 为没有颜色的标签生成随机颜色
    # 根据任务类型选择对应的标签组件
    # 生成完整的XML配置

5. 颜色生成工具

def generate_random_color() -> str:
    """生成随机颜色，返回 #RRGGBB 格式"""
    import random
    return f"#{random.randint(0, 0xFFFFFF):06x}"

Data Models

标签存储

标签信息直接嵌入到项目的XML配置中，不需要额外的数据库表。

XML配置示例

文本分类（带标签）：

<View>
  <Text name="text" value="$text"/>
  <Choices name="label" toName="text" choice="single">
    <Choice value="猫猫" style="background-color: #FF5733"/>
    <Choice value="狗狗" style="background-color: #33FF57"/>
  </Choices>
</View>

多边形标注：

<View>
  <Image name="image" value="$image"/>
  <PolygonLabels name="label" toName="image">
    <Label value="区域A" background="#FF5733"/>
    <Label value="区域B" background="#33FF57"/>
  </PolygonLabels>
</View>

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 项目初始化请求包含tags参数，创建的项目配置中应包含所有传入的标签，且：

指定颜色的标签使用指定颜色
未指定颜色的标签具有有效的颜色值（#RRGGBB格式）

Validates: Requirements 1.1, 1.2, 1.3, 1.4

Property 2: Polygon配置生成正确性

For any polygon类型的项目创建请求，生成的XML配置应包含PolygonLabels组件，且所有传入的标签都作为Label子元素存在。

Validates: Requirements 2.1, 2.2

Error Handling

错误场景

场景	错误码	HTTP状态码	处理方式
无效的颜色格式	INVALID_COLOR_FORMAT	400	返回错误信息，指出无效的颜色值
标签名称为空	INVALID_TAG_NAME	400	返回错误信息，要求提供有效的标签名
不支持的任务类型	INVALID_TASK_TYPE	400	返回错误信息，列出支持的任务类型

颜色格式验证

import re

def validate_color(color: str) -> bool:
    """验证颜色格式是否为有效的 #RRGGBB"""
    return bool(re.match(r'^#[0-9A-Fa-f]{6}$', color))

Testing Strategy

单元测试

颜色生成测试
- 验证生成的颜色格式正确
- 验证颜色值在有效范围内
XML配置生成测试
- 验证各任务类型的配置生成
- 验证标签正确嵌入配置
标签验证测试
- 验证颜色格式验证逻辑
- 验证标签名称验证逻辑

属性测试

使用 Hypothesis 库进行属性测试：

标签处理属性测试
- 生成随机标签列表
- 验证所有标签都出现在配置中
- 验证颜色处理正确
Polygon配置属性测试
- 生成随机polygon项目请求
- 验证配置包含PolygonLabels

集成测试

API端到端测试
- 测试5种任务类型的完整流程
- 验证标签传入功能
- 验证导出功能

测试配置

属性测试最少运行100次迭代
使用 pytest + hypothesis 框架
测试文件位于 backend/test/ 目录

Implementation Notes

脚本说明

generate_admin_token.py

"""
生成长期有效的管理员Token脚本

功能：
1. 查找或创建管理员用户
2. 生成99999天有效期的Token
3. 输出Token并验证有效性

使用方式：
python scripts/generate_admin_token.py
"""

test_external_api.py

"""
外部API测试脚本

功能：
1. 测试5种标注类型的项目创建
2. 测试进度查询接口
3. 测试数据导出接口
4. 验证标签传入功能

使用方式：
python scripts/test_external_api.py --base-url http://localhost:8003 --token <admin_token>
"""

文件变更清单

文件	变更类型	说明
backend/schemas/external.py	修改	添加TagItem、更新TaskType枚举、更新ProjectInitRequest
backend/services/external_service.py	修改	添加标签处理逻辑、添加polygon配置模板
backend/EXTERNAL_API_DOCUMENTATION.md	修改	更新API文档，添加tags参数说明
backend/scripts/generate_admin_token.py	新增	生成长期Token脚本
backend/scripts/test_external_api.py	新增	API测试脚本
backend/test/test_external_api_tags.py	新增	标签功能单元测试

design.md 6.5 KB História Raw