e093995368
主要改进: - Agent 增强: 订单查询、售后支持、客服路由等功能优化 - 新增语言检测和 Token 管理模块 - 改进 Chatwoot webhook 处理和用户标识 - MCP 服务器增强: 订单 MCP 和 Strapi MCP 功能扩展 - 新增商城客户端、知识库、缓存和同步模块 - 添加多语言提示词系统 (YAML) - 完善项目结构: 整理文档、脚本和测试文件 - 新增调试和测试工具脚本 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
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 调用和响应
|