166 lines
3.8 KiB
Markdown
166 lines
3.8 KiB
Markdown
|
# 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 调用和响应
|