# Shrinkwrap接口优化说明

## 问题描述
`/api/creo/shrinkwrap/shell` 接口在处理复杂模型时容易出现500内部错误，主要原因：
1. 固定30秒超时对复杂模型不够
2. 错误信息不明确，难以定位问题原因

## 优化方案

### 1. 动态超时机制
- **新增参数**: `timeout_seconds`（可选）
- **默认值**: 30秒
- **有效范围**: 10-300秒（自动限制）
- **使用方式**: 在请求JSON中添加 `"timeout_seconds": 120`

### 2. 增强错误处理
区分不同类型的OTK异常，提供明确错误信息：
- `pfcXToolkitError`: "OTK Toolkit Error: Creo operation failed..."
- `pfcXBadArgument`: "Invalid Parameters: One or more shrinkwrap parameters..."
- `xBadAlloc`: "Memory Error: Insufficient memory to process the model..."
- `std::bad_alloc`: "System Memory Error: Out of memory..."
- 通用错误: "Unknown Error: An unexpected error occurred..."

### 3. 修改的文件

#### ShrinkwrapManager.h
```cpp
struct ShrinkwrapShellRequest {
    // ... 其他字段
    int timeout_seconds = 30;  // 新增超时参数
};
```

#### ShellExportHandler.cpp
```cpp
// 解析超时参数，默认30秒，最大300秒
request.timeout_seconds = ExtractJsonIntValue(json_body, "timeout_seconds", 30);
if (request.timeout_seconds < 10) {
    request.timeout_seconds = 10;  // 最小10秒
}
if (request.timeout_seconds > 300) {
    request.timeout_seconds = 300; // 最大300秒
}
```

#### MFCCreoDll.cpp
```cpp
// 动态解析超时参数
int timeout_seconds = 30;
std::regex timeout_regex("\"timeout_seconds\"\\s*:\\s*(\\d+)");
// ... 解析逻辑

// 使用动态超时
int timeout_ms = timeout_seconds * 1000;
```

#### ShrinkwrapManager.cpp
```cpp
// 细分异常处理
try {
    shrinkwrap_model = ExecuteOTKShrinkwrap(current_model, processed_request);
} catch (const pfcXToolkitError& e) {
    result.error_message = "OTK Toolkit Error: Creo operation failed...";
} catch (const pfcXBadArgument& e) {
    result.error_message = "Invalid Parameters: One or more shrinkwrap parameters...";
} catch (const pfcXToolkitOutOfMemory& e) {
    result.error_message = "Memory Error: Insufficient memory to process the model...";
} catch (const std::bad_alloc& e) {
    result.error_message = "System Memory Error: Out of memory...";
}
// ... 其他异常类型
```

## 使用示例

### 标准请求（使用默认30秒超时）
```json
{
  "software_type": "creo",
  "quality": 5,
  "output_file_path": "output.prt"
}
```

### 长时间操作（使用120秒超时）
```json
{
  "software_type": "creo", 
  "quality": 8,
  "output_file_path": "complex_model.prt",
  "timeout_seconds": 120
}
```

### 快速操作（使用15秒超时）
```json
{
  "software_type": "creo",
  "preset": "fast",
  "output_file_path": "simple_model.prt",
  "timeout_seconds": 15
}
```

## 测试方法

### 使用Python测试
```bash
python test_timeout.py
python test_timeout.py 120  # 测试120秒超时
```

### 使用批处理测试
```bash
test_timeout.bat
```

### 使用curl测试
```bash
curl -X POST http://localhost:12345/api/creo/shrinkwrap/shell \
  -H "Content-Type: application/json" \
  -d '{"software_type":"creo","quality":5,"output_file_path":"test.prt","timeout_seconds":60}'
```

## 向后兼容性
- 所有现有API调用保持完全兼容
- `timeout_seconds`参数为可选，未指定时使用默认30秒
- 响应格式不变

## 预期效果
1. **复杂模型处理**: 通过增加超时时间减少504错误
2. **错误诊断**: 通过细分错误类型快速定位问题
3. **用户体验**: 提供明确的错误信息和解决建议
4. **系统稳定性**: 更好的异常处理避免系统崩溃

## 注意事项
1. 超时时间过长会占用更多系统资源
2. 复杂模型建议配合 `preset: "fast"` 使用
3. 内存不足时应减少quality参数或简化模型
4. 服务端最大允许300秒超时，超过将被限制