# 管理后台操作指南 - Dify智能体集成

## 概述

本指南详细说明如何让Dify智能体理解和调用管理后台的各项功能。系统已经创建了完整的操作定义表和API接口。

## 架构说明

### 1. 功能表定义 (`src/types/adminOperations.ts`)

定义了所有管理后台操作，包括：
- **产品管理**: 查询、创建、更新、删除、库存管理、价格管理等
- **订单管理**: 查询、更新状态、添加物流、取消、退款等
- **用户管理**: 查询、更新、角色管理、封禁等
- **售后管理**: 查询、审批、拒绝、添加备注等
- **分类/品牌/横幅管理**: 完整的CRUD操作
- **数据分析**: 销售、产品、用户、订单分析

每个操作包含:
- `type`: 操作类型标识
- `name`: 操作名称
- `description`: 操作描述
- `category`: 所属分类
- `params`: 参数定义（名称、类型、是否必需、描述）
- `examples`: 使用示例
- `permissions`: 所需权限

### 2. API接口 (`supabase/functions/admin-operations/index.ts`)

统一的Edge Function接口，处理所有管理操作：
- 自动验证用户权限（需要admin角色）
- 根据操作类型执行相应的数据库操作
- 返回统一格式的响应

### 3. 客户端工具 (`src/utils/adminOperationsClient.ts`)

提供便捷的前端调用方法：
- `executeAdminOperation`: 执行单个操作
- `executeBatchOperations`: 批量执行操作
- 分类的快捷方法（如 `productOperations.query()`）

## 在Dify中配置

### 步骤1: 添加输入变量

在Dify工作流中添加以下输入变量：

1. **system_schema** (文本)
   - 描述: 完整的系统架构和操作定义
   - 来源: 前端自动生成并传入

2. **statistics** (文本/JSON)
   - 描述: 当前系统统计数据
   - 包含: 产品数、订单数、用户数等

3. **products** (数组)
   - 描述: 产品列表数据

4. **orders** (数组)
   - 描述: 订单列表数据

5. **users** (数组)
   - 描述: 用户列表数据

6. **afterSales** (数组)
   - 描述: 售后请求列表数据

### 步骤2: 配置系统提示词

```
你是一个智能电商管理助手，负责帮助管理员管理后台系统。

## 系统架构
{{system_schema}}

## 当前数据统计
- 产品总数: {{products.length}}
- 订单总数: {{orders.length}}
- 用户总数: {{users.length}}
- 售后请求: {{afterSales.length}}

## 详细统计
{{statistics}}

## 你的能力
1. **数据查询**: 可以查询产品、订单、用户、售后等所有数据
2. **智能分析**: 可以分析销售、库存、用户行为等数据
3. **执行操作**: 可以更新产品、处理订单、管理用户、审批售后等
4. **批量处理**: 可以批量执行多个操作

## 操作规范
- 执行任何修改操作前，先确认数据的准确性
- 提供清晰的操作原因和影响说明
- 返回结构化的操作结果

## 返回格式
所有操作必须返回以下格式:
{
  "answer": "对用户的回复",
  "metadata": {
    "actions": [
      {
        "type": "操作类型",
        "params": { 操作参数 },
        "description": "操作说明",
        "reasoning": "执行该操作的原因"
      }
    ]
  }
}
```

### 步骤3: 配置工具调用

在Dify的LLM节点中，配置以下工具（Tools）：

#### 产品管理工具

```json
{
  "name": "product_query",
  "description": "查询产品信息",
  "parameters": {
    "type": "object",
    "properties": {
      "keyword": { "type": "string", "description": "搜索关键词" },
      "category": { "type": "string", "description": "产品分类" },
      "brand": { "type": "string", "description": "产品品牌" },
      "minPrice": { "type": "number", "description": "最低价格" },
      "maxPrice": { "type": "number", "description": "最高价格" },
      "isActive": { "type": "boolean", "description": "是否上架" }
    }
  }
}
```

```json
{
  "name": "product_update",
  "description": "更新产品信息",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "产品ID", "required": true },
      "name": { "type": "string", "description": "产品名称" },
      "price": { "type": "number", "description": "产品价格" },
      "stock_quantity": { "type": "number", "description": "库存数量" },
      "description": { "type": "string", "description": "产品描述" }
    },
    "required": ["id"]
  }
}
```

#### 订单管理工具

```json
{
  "name": "order_query",
  "description": "查询订单信息",
  "parameters": {
    "type": "object",
    "properties": {
      "status": { "type": "string", "description": "订单状态" },
      "userId": { "type": "string", "description": "用户ID" },
      "orderNumber": { "type": "string", "description": "订单号" }
    }
  }
}
```

```json
{
  "name": "order_update_status",
  "description": "更新订单状态",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "订单ID", "required": true },
      "status": { "type": "string", "description": "订单状态", "required": true }
    },
    "required": ["id", "status"]
  }
}
```

```json
{
  "name": "order_add_tracking",
  "description": "添加物流追踪号",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "订单ID", "required": true },
      "tracking_number": { "type": "string", "description": "物流单号", "required": true }
    },
    "required": ["id", "tracking_number"]
  }
}
```

#### 用户管理工具

```json
{
  "name": "user_query",
  "description": "查询用户信息",
  "parameters": {
    "type": "object",
    "properties": {
      "keyword": { "type": "string", "description": "搜索关键词（姓名、邮箱）" },
      "role": { "type": "string", "description": "用户角色" }
    }
  }
}
```

```json
{
  "name": "user_update_role",
  "description": "更新用户角色",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "用户ID", "required": true },
      "role": { "type": "string", "description": "角色（admin/user）", "required": true }
    },
    "required": ["id", "role"]
  }
}
```

#### 售后管理工具

```json
{
  "name": "aftersales_query",
  "description": "查询售后请求",
  "parameters": {
    "type": "object",
    "properties": {
      "status": { "type": "string", "description": "售后状态" },
      "type": { "type": "string", "description": "售后类型" }
    }
  }
}
```

```json
{
  "name": "aftersales_approve",
  "description": "批准售后请求",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "售后ID", "required": true },
      "refund_amount": { "type": "number", "description": "退款金额" },
      "admin_notes": { "type": "string", "description": "管理员备注" }
    },
    "required": ["id"]
  }
}
```

#### 数据分析工具

```json
{
  "name": "analytics_sales",
  "description": "分析销售数据",
  "parameters": {
    "type": "object",
    "properties": {
      "startDate": { "type": "string", "description": "开始日期" },
      "endDate": { "type": "string", "description": "结束日期" }
    }
  }
}
```

### 步骤4: 配置输出格式

在Dify的输出节点中，确保返回以下JSON格式：

```json
{
  "answer": "{{LLM输出.answer}}",
  "metadata": {
    "actions": "{{LLM输出.metadata.actions}}"
  }
}
```

## 使用示例

### 示例1: 查询库存不足的产品

**用户提问**: "查询库存少于10的产品"

**Dify返回**:
```json
{
  "answer": "我找到了3个库存不足的产品：\n1. iPhone 15 Pro - 当前库存：5\n2. MacBook Pro - 当前库存：3\n3. AirPods Pro - 当前库存：8",
  "metadata": {
    "actions": [
      {
        "type": "product.query",
        "params": { "maxStock": 10 },
        "description": "查询库存不足产品",
        "reasoning": "需要及时补货避免缺货"
      }
    ]
  }
}
```

### 示例2: 批量处理待发货订单

**用户提问**: "将所有待发货的订单标记为已发货"

**Dify返回**:
```json
{
  "answer": "已将5个待发货订单标记为已发货状态",
  "metadata": {
    "actions": [
      {
        "type": "batch_update",
        "params": {
          "table": "orders",
          "items": [
            { "id": "order1", "status": "shipped" },
            { "id": "order2", "status": "shipped" }
          ]
        },
        "description": "批量更新订单状态",
        "reasoning": "快速处理待发货订单"
      }
    ]
  }
}
```

### 示例3: 分析销售数据

**用户提问**: "分析本月销售情况"

**Dify返回**:
```json
{
  "answer": "本月销售总额为¥125,680，共完成订单156笔，平均订单金额¥806。销售额较上月增长18%。",
  "metadata": {
    "actions": [
      {
        "type": "analytics.sales",
        "params": {
          "startDate": "2025-01-01",
          "endDate": "2025-01-31"
        },
        "description": "分析本月销售数据",
        "reasoning": "了解销售趋势和业绩"
      }
    ]
  }
}
```

## 完整的操作类型列表

系统支持以下操作类型（详见 `src/types/adminOperations.ts`）：

### 产品管理 (8个操作)
- product.query
- product.create
- product.update
- product.delete
- product.updateStock
- product.updatePrice
- product.toggleStatus

### 订单管理 (6个操作)
- order.query
- order.update
- order.updateStatus
- order.addTracking
- order.cancel
- order.refund

### 用户管理 (5个操作)
- user.query
- user.update
- user.updateRole
- user.block
- user.unblock

### 售后管理 (5个操作)
- afterSales.query
- afterSales.update
- afterSales.approve
- afterSales.reject
- afterSales.addNotes

### 分类管理 (4个操作)
- category.query
- category.create
- category.update
- category.delete

### 品牌管理 (4个操作)
- brand.query
- brand.create
- brand.update
- brand.delete

### 横幅管理 (4个操作)
- banner.query
- banner.create
- banner.update
- banner.delete

### 数据分析 (4个操作)
- analytics.sales
- analytics.products
- analytics.users
- analytics.orders

**总计**: 40个管理操作

## API调用说明

所有操作都通过统一的 `admin-operations` Edge Function 调用：

```typescript
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke('admin-operations', {
  body: {
    operation: 'product.update',
    params: {
      id: 'product-id',
      price: 5999
    }
  }
});
```

或使用便捷方法：

```typescript
import { productOperations } from '@/utils/adminOperationsClient';

const result = await productOperations.updatePrice('product-id', 5999);
```

## 安全说明

1. **权限验证**: 所有操作都需要管理员权限
2. **JWT验证**: Edge Function 启用了 JWT 验证
3. **操作日志**: 建议记录所有管理操作（可扩展）
4. **数据验证**: 参数在后端进行验证

## 扩展指南

### 添加新操作

1. 在 `src/types/adminOperations.ts` 中定义新操作
2. 在 `supabase/functions/admin-operations/index.ts` 中实现处理逻辑
3. 在 `src/utils/adminOperationsClient.ts` 中添加便捷方法（可选）
4. 更新本文档的操作列表

### 添加新的Dify工具

按照上述格式在Dify中创建新的工具定义即可。

## 故障排查

### 问题1: 操作失败返回"未授权访问"
- 检查用户是否已登录
- 确认用户角色是否为 admin

### 问题2: 操作返回"不支持的操作类型"
- 检查操作类型拼写是否正确
- 确认该操作已在后端实现

### 问题3: Dify智能体无法理解系统架构
- 确认 system_schema 变量正确传入
- 检查系统提示词是否包含 {{system_schema}}

## 总结

通过这套系统，Dify智能体可以：
1. 深入理解管理后台的架构和功能
2. 根据自然语言指令生成准确的操作
3. 执行复杂的管理任务
4. 提供智能的数据分析和建议

所有操作都是类型安全的，有完整的文档和示例，便于维护和扩展。
