# System Translate API 使用说明文档

## 接口概述

translate接口用于将中文节点名称翻译成符合数据库规范的英文名称，主要用于数据建模和表名/字段名的英文化处理。

## 接口信息

### 访问路径
```
POST /api/system/translate
```

### 请求头
```
Content-Type: application/json
```

## 输入参数

### 请求体参数

| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| node_name | string | 是 | 需要翻译的中文节点名称 | "用户数据表" |

### 请求体示例
```json
{
    "node_name": "用户数据表"
}
```

## 输出参数

### 成功响应

| 字段名 | 类型 | 描述 |
|--------|------|------|
| code | integer | 响应状态码，成功时为200 |
| message | string | 响应消息，成功时为"翻译成功" |
| data | object | 翻译结果数据对象 |
| data.original | string | 原始输入的中文名称 |
| data.translated | string | 翻译后的英文名称（主要结果） |
| data.translated_list | array | 翻译结果数组（兼容性字段） |

### 错误响应

| 字段名 | 类型 | 描述 |
|--------|------|------|
| code | integer | 错误状态码 |
| message | string | 错误描述信息 |
| data | null | 错误时数据为空 |

## 样例代码

### cURL 示例

```bash
curl -X POST \
  http://localhost:5000/api/system/translate \
  -H 'Content-Type: application/json' \
  -d '{
    "node_name": "用户数据表"
  }'
```

### JavaScript (Fetch API) 示例

```javascript
// 发送翻译请求
async function translateNodeName(nodeName) {
    try {
        const response = await fetch('/api/system/translate', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                node_name: nodeName
            })
        });
        
        const result = await response.json();
        
        if (result.code === 200) {
            console.log('翻译成功:', result.data.translated);
            return result.data.translated;
        } else {
            console.error('翻译失败:', result.message);
            return null;
        }
    } catch (error) {
        console.error('请求失败:', error);
        return null;
    }
}

// 使用示例
translateNodeName('用户数据表').then(translated => {
    if (translated) {
        console.log('英文名称:', translated); // 输出: user_data_table
    }
});
```

### Python 示例

```python
import requests
import json

def translate_node_name(node_name):
    """
    调用翻译API
    
    Args:
        node_name (str): 需要翻译的中文名称
        
    Returns:
        str: 翻译后的英文名称，失败时返回None
    """
    url = 'http://localhost:5000/api/system/translate'
    headers = {
        'Content-Type': 'application/json'
    }
    data = {
        'node_name': node_name
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        result = response.json()
        
        if result['code'] == 200:
            print(f"翻译成功: {result['data']['translated']}")
            return result['data']['translated']
        else:
            print(f"翻译失败: {result['message']}")
            return None
    except Exception as e:
        print(f"请求失败: {str(e)}")
        return None

# 使用示例
translated_name = translate_node_name('用户数据表')
if translated_name:
    print(f"英文名称: {translated_name}")  # 输出: user_data_table
```

### Java 示例

```java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class TranslateAPI {
    
    public static String translateNodeName(String nodeName) {
        try {
            // 构建请求体
            JsonObject requestBody = new JsonObject();
            requestBody.addProperty("node_name", nodeName);
            
            // 创建HTTP请求
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("http://localhost:5000/api/system/translate"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody.toString()))
                .build();
            
            // 发送请求
            HttpClient client = HttpClient.newHttpClient();
            HttpResponse<String> response = client.send(request, 
                HttpResponse.BodyHandlers.ofString());
            
            // 解析响应
            Gson gson = new Gson();
            JsonObject result = gson.fromJson(response.body(), JsonObject.class);
            
            if (result.get("code").getAsInt() == 200) {
                String translated = result.getAsJsonObject("data")
                    .get("translated").getAsString();
                System.out.println("翻译成功: " + translated);
                return translated;
            } else {
                String message = result.get("message").getAsString();
                System.err.println("翻译失败: " + message);
                return null;
            }
        } catch (Exception e) {
            System.err.println("请求失败: " + e.getMessage());
            return null;
        }
    }
    
    // 使用示例
    public static void main(String[] args) {
        String translated = translateNodeName("用户数据表");
        if (translated != null) {
            System.out.println("英文名称: " + translated); // 输出: user_data_table
        }
    }
}
```

## 返回状态和编码

### HTTP状态码

| 状态码 | 描述 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

### 业务状态码

| 业务码 | 描述 | 场景 |
|--------|------|------|
| 200 | 成功 | 翻译操作成功完成 |
| 400 | 参数错误 | node_name参数为空或格式错误 |
| 500 | 服务器错误 | LLM服务调用失败或其他内部错误 |

## 响应示例

### 成功响应

```json
{
    "code": 200,
    "message": "翻译成功",
    "data": {
        "original": "用户数据表",
        "translated": "user_data_table",
        "translated_list": ["user_data_table"]
    }
}
```

### 参数错误响应

```json
{
    "code": 400,
    "message": "node_name参数不能为空",
    "data": null
}
```

### 服务器错误响应

```json
{
    "code": 500,
    "message": "翻译失败: LLM服务调用超时",
    "data": null
}
```

## 使用场景

1. **数据库表名翻译**：将中文表名翻译为符合数据库规范的英文表名
2. **字段名翻译**：将中文字段名翻译为英文字段名
3. **数据建模**：在数据建模过程中自动生成英文标识符
4. **系统集成**：为第三方系统提供标准化的英文名称

## 翻译规则

翻译结果遵循以下规则：
- 使用小写字母
- 多个单词用下划线连接
- 符合PostgreSQL数据库命名规范
- 优先使用简短、准确的英文单词
- "表"字统一翻译为"table"

## 注意事项

1. 请确保输入的`node_name`为有效的字符串
2. 翻译结果适用于数据库表名和字段名，符合SQL命名规范
3. 如果翻译服务不可用，接口会返回相应的错误信息
4. 建议在生产环境中实现重试机制以提高可靠性

## 版本信息

- API版本：v1.0
- 文档版本：1.0.0
- 最后更新：2025年