feat: 增强 Agent 系统和完善项目结构

主要改进: - Agent 增强: 订单查询、售后支持、客服路由等功能优化 - 新增语言检测和 Token 管理模块 - 改进 Chatwoot webhook 处理和用户标识 - MCP 服务器增强: 订单 MCP 和 Strapi MCP 功能扩展 - 新增商城客户端、知识库、缓存和同步模块 - 添加多语言提示词系统 (YAML) - 完善项目结构: 整理文档、脚本和测试文件 - 新增调试和测试工具脚本 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-16 16:28:47 +08:00
parent 0e59f3067e
commit e093995368
48 changed files with 5263 additions and 395 deletions
--- a/plans/order-mcp-implementation.md
+++ b/plans/order-mcp-implementation.md
@@ -0,0 +1,165 @@
+# 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 调用和响应