# Design Document: External API Enhancement

## Overview

本设计文档描述了标注平台外部API增强功能的技术实现方案，包括：
1. 项目初始化接口增加标签传入功能
2. 增加多边形标注类型支持
3. 创建长期有效的管理员Token脚本
4. 编写API测试脚本

## Architecture

### 系统架构图

```mermaid
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. 标签数据结构

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

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

```python
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. 任务类型枚举更新

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

### 4. XML配置生成逻辑

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

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

### 5. 颜色生成工具

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

## Data Models

### 标签存储

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

### 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>
```

**多边形标注：**
```xml
<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 | 返回错误信息，列出支持的任务类型 |

### 颜色格式验证

```python
import re

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

## Testing Strategy

### 单元测试

1. **颜色生成测试**
   - 验证生成的颜色格式正确
   - 验证颜色值在有效范围内

2. **XML配置生成测试**
   - 验证各任务类型的配置生成
   - 验证标签正确嵌入配置

3. **标签验证测试**
   - 验证颜色格式验证逻辑
   - 验证标签名称验证逻辑

### 属性测试

使用 Hypothesis 库进行属性测试：

1. **标签处理属性测试**
   - 生成随机标签列表
   - 验证所有标签都出现在配置中
   - 验证颜色处理正确

2. **Polygon配置属性测试**
   - 生成随机polygon项目请求
   - 验证配置包含PolygonLabels

### 集成测试

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

### 测试配置

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

## Implementation Notes

### 脚本说明

#### generate_admin_token.py

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

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

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

#### test_external_api.py

```python
"""
外部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 | 新增 | 标签功能单元测试 |