# Order MCP 实现计划

## 概述

根据实际 API 接口分析，需要重构 order_mcp 以适配真实的 Gaia888 商城 API。

## 当前问题

### 1. API 端点不匹配
- **当前**: `POST /orders/query`
- **实际**: `GET /mall/api/order/show?orderId=xxx`

### 2. 请求方法不匹配
- **当前**: POST with JSON body
- **实际**: GET with query parameters

### 3. 缺少必要的 Headers
实际 API 需要以下 Headers：
```
Authorization: Bearer {token}
tenant-Id: {tenant_id}
currency-code: {currency}
language-id: {language_id}
source: {source}
Device-Type: {device_type}
```

## 实施计划

### 步骤 1: 更新 shared/hyperf_client.py

**目标**: 支持自定义 Headers 和更灵活的 API 配置

**修改内容**:
1. 添加可选的 tenant_id, currency_code, language_id, source, device_type 配置
2. 在请求中自动添加这些 Headers
3. 支持不同的 base_url（Gaia888 API）

**代码变更**:
```python
class HyperfSettings(BaseSettings):
    hyperf_api_url: str
    hyperf_api_token: str
    tenant_id: int = 2
    currency_code: str = "EUR"
    language_id: int = 1
    source: str = "us.qa1.gaia888.com"
    device_type: str = "pc"
```

### 步骤 2: 更新 order_mcp/server.py

**目标**: 重构 query_order 工具以适配真实 API

**修改内容**:
1. 将 POST 请求改为 GET 请求
2. 将 JSON body 参数改为 query string 参数
3. 更新端点路径为 `/mall/api/order/show`
4. 添加 get_order_detail 工具（如果需要）

**新工具设计**:

#### query_order - 订单查询
```python
@mcp.tool()
async def query_order(
    order_id: str,
    user_id: Optional[str] = None
) -> dict:
    """查询订单详情
    
    Args:
        order_id: 订单号
        user_id: 用户ID（可选，用于权限验证）
    
    Returns:
        订单详细信息
    """
```

#### get_order_list - 订单列表查询（新增）
```python
@mcp.tool()
async def get_order_list(
    user_id: str,
    status: Optional[str] = None,
    page: int = 1,
    page_size: int = 10
) -> dict:
    """查询用户订单列表
    
    Args:
        user_id: 用户ID
        status: 订单状态筛选
        page: 页码
        page_size: 每页数量
    
    Returns:
        订单列表和分页信息
    """
```

### 步骤 3: 更新环境变量配置

**.env 文件需要添加**:
```bash
# Order MCP 配置
TENANT_ID=2
CURRENCY_CODE=EUR
LANGUAGE_ID=1
SOURCE=us.qa1.gaia888.com
DEVICE_TYPE=pc
```

### 步骤 4: 更新 docker-compose.yml

**确保环境变量传递**:
```yaml
order_mcp:
  environment:
    HYPERF_API_URL: ${HYPERF_API_URL}
    HYPERF_API_TOKEN: ${HYPERF_API_TOKEN}
    TENANT_ID: ${TENANT_ID:-2}
    CURRENCY_CODE: ${CURRENCY_CODE:-EUR}
    LANGUAGE_ID: ${LANGUAGE_ID:-1}
    SOURCE: ${SOURCE:-us.qa1.gaia888.com}
    DEVICE_TYPE: ${DEVICE_TYPE:-pc}
```

## API 端点映射

| 功能 | 当前端点 | 实际端点 | 方法 |
|------|----------|----------|------|
| 订单详情 | /orders/query | /mall/api/order/show | GET |
| 订单列表 | /orders/query | /mall/api/order/list | GET |
| 物流跟踪 | /orders/{id}/logistics | /mall/api/order/logistics | GET |
| 取消订单 | /orders/{id}/cancel | /mall/api/order/cancel | POST |

## 数据模型

### 订单详情响应格式
```json
{
  "orderId": "202071324",
  "status": "shipped",
  "totalAmount": 5000.00,
  "items": [...],
  "shippingAddress": {...},
  "trackingNumber": "SF1234567890",
  "createdAt": "2026-01-10 10:00:00"
}
```

## 测试计划

1. 单元测试 - 测试 HyperfClient 的 Header 生成
2. 集成测试 - 测试与真实 API 的连接
3. 端到端测试 - 通过 agent 调用 order_mcp 工具

## 注意事项

1. **安全性**: JWT token 需要定期刷新
2. **错误处理**: 需要处理 API 返回的各种错误码
3. **缓存**: 考虑添加订单查询缓存以减少 API 调用
4. **日志**: 记录所有 API 调用和响应