web-map/src/pages/API_MAP_CONVERTER_README.md

# 地图转换API接口使用说明

## 接口地址
```
POST /api/map-converter/process-json-list
```

## 请求格式
请求体应为一个JSON数组，每个数组元素代表一个楼层的地图信息：

```json
[
  {
    "floors": 1,           // 楼层 (int, 必填, 不可重复)
    "type": "smap",        // 地图类型 (string, 必填, smap或scene)
    "placeholder1": "...",  // 地图文件内容 (string, 必填)
    "placeholder2": "...",  // 地图文件内容 (string, 选填)
    "OriginalProperties": "...."  // 原始地图内容 (string, 必填)
  }
]
```

### 字段说明

| 字段名 | 说明 | 类型 | 是否必填 | 其他要求 |
|--------|------|------|----------|----------|
| floors | 楼层 | int | 必填 | 不可重复，必须连续 |
| type | 地图类型 | string | 必填 | 可填smap或scene，在一层楼中placeholder有多个时，type必须为smap |
| placeholder1 | 上传的地图文件内容 | string | 必填 | 在一层楼中placeholder所加载的地图类型必须与type一致 |
| placeholder2 | 上传的地图文件内容 | string | 选填 | 在一层楼中placeholder所加载的地图类型必须与type一致 |
| placeholderX | 上传的地图文件内容 | string | 选填 | 在一层楼中placeholder所加载的地图类型必须与type一致 |
| OriginalProperties | 原始地图内容 | string | 必填 | 可以为空，用于保留原场景属性 |

### 请求验证规则

1. **楼层验证**：
   - 楼层编号必须唯一且连续
   - 如果存在楼层1、2、4，则缺少楼层3，请求将被拒绝

2. **机器人组验证**：
   - 同一机器人ID不能出现在不同组中（包括跨楼层情况）
   - 如果发现重复，将返回错误信息

3. **地图类型验证**：
   - 当一层楼有多个placeholder时，type必须为"smap"
   - 所有placeholder的内容类型必须与type一致

## 响应格式

成功响应可能有两种形式：

### 1. ZIP文件流响应（主要响应形式）
API处理成功后，默认返回ZIP文件流，包含处理后的地图文件：

```http
Content-Type: application/zip
Content-Disposition: attachment; filename=converted_map.zip
```

### 2. JSON格式响应（仅在特定情况下）
```json
{
  "success": true,
  "message": "请求处理成功",
  "timestamp": "2023-05-15T10:30:45.123456",
  "data": {
    // 处理结果数据
  }
}
```

## 错误响应
```json
{
  "success": false,
  "message": "错误描述",
  "timestamp": "2023-05-15T10:30:45.123456",
  "error": "详细错误信息"
}
```

## 处理逻辑

### 单楼层处理
1. **单个placeholder**：
   - 如果type为"scene"且OriginalProperties有值，将执行场景丰富化
   - 最终返回包含处理后scene文件的ZIP

2. **多个placeholder**：
   - 如果type为"smap"，将执行地图拼接
   - 最终返回包含拼接后scene文件的ZIP

### 多楼层处理
1. 所有楼层必须连续
2. 每个楼层按照单楼层逻辑处理
3. 最终返回包含所有处理后文件的ZIP

## 使用示例

### Python requests示例
```python
import requests
import json

# 准备请求数据
data = [
    {
        "floors": 1,
        "type": "smap",
        "placeholder1": '{"version": "1.0", "mapData": "..."}',
        "OriginalProperties": ""
    }
]

# 发送请求
response = requests.post(
    "http://localhost:8000/api/map-converter/process-json-list",
    json=data
)

# 处理响应
if response.headers.get('content-type', '').startswith('application/json'):
    # JSON响应
    result = response.json()
    print(json.dumps(result, indent=2, ensure_ascii=False))
else:
    # ZIP文件流响应
    with open('result.zip', 'wb') as f:
        f.write(response.content)
    print("文件已保存为 result.zip")
    
    # 解压ZIP文件（可选）
    import zipfile
    import os
    
    output_dir = "outputmap"
    os.makedirs(output_dir, exist_ok=True)
    
    with zipfile.ZipFile('result.zip', 'r') as zip_ref:
        zip_ref.extractall(output_dir)
    print(f"ZIP文件已解压到 {output_dir} 目录")
```

### cURL示例
```bash
curl -X POST "http://localhost:8000/api/map-converter/process-json-list" \
-H "Content-Type: application/json" \
-d '[
  {
    "floors": 1,
    "type": "scene",
    "placeholder1": "{\"version\": \"1.0\", \"mapData\": \"...\"}",
    "OriginalProperties": "{\"robotGroups\": [...]}"
  }
]' \
--output result.zip
```

## 启动服务

### 基本启动
```bash
cd d:\CodeProject\map-converter
python start_map_service.py
```

### 高级启动选项
```bash
# 指定主机和端口
python start_map_service.py --host 0.0.0.0 --port 8080

# 开发模式（启用热重载）
python start_map_service.py --reload
```

### 服务状态检查
```bash
# 检查服务是否运行
curl http://localhost:8000/
```

服务默认运行在 `http://127.0.0.1:8000`

## 测试工具

项目提供了模拟API请求的脚本，可用于测试：

```bash
python simulate_api_request.py
```

该脚本会：
1. 检查服务状态
2. 读取intput.json文件中的测试数据
3. 发送API请求
4. 处理并保存响应结果

## 注意事项

1. **文件大小限制**：大文件可能需要调整服务器配置
2. **超时设置**：复杂地图处理可能需要较长时间，建议设置适当的客户端超时
3. **编码格式**：所有文本内容应使用UTF-8编码
4. **JSON格式**：确保所有JSON内容格式正确，特别注意尾随逗号问题
5. **临时文件**：处理过程中会创建临时文件，系统会自动清理

## 错误排查

1. **楼层不连续错误**：检查floors字段是否连续
2. **机器人组重复错误**：检查OriginalProperties中的robotGroups配置
3. **地图类型不匹配错误**：确保placeholder内容与type字段一致
4. **JSON解析错误**：验证所有JSON内容格式正确

## 日志查看

服务运行日志会输出到控制台，包含详细的处理信息和错误堆栈，可用于问题排查。