# Admin AI 自然语言操作指南

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         用户交互                                 │
│  管理员输入: "显示价格最高的10个Apple商品"                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    AdminAIAssistant                              │
│  1. 发送消息到 dify-chat-admin                                   │
│  2. 接收 Dify 返回的响应                                         │
│  3. 解析响应中的动作标记块                                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Dify 工作流                                   │
│  1. 调用 system-info/system-actions 获取能力定义                 │
│  2. 理解用户意图                                                 │
│  3. 生成带有动作标记块的响应                                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    统一动作系统                                  │
│  extractUnifiedActions() → executeUnifiedActions()               │
│  - 页面动作: 导航、筛选、排序、搜索                              │
│  - 数据动作: 创建、更新、删除 → admin-operations                 │
└─────────────────────────────────────────────────────────────────┘
```

## 动作类型

### 1. 页面动作 (PAGE_ACTION)

用于控制 Admin 页面的导航、筛选、排序和搜索。

#### 格式
```
[PAGE_ACTION]{"type":"...", "params":{...}}[/PAGE_ACTION]
```

#### 支持的类型

| type | 描述 | 必需参数 |
|------|------|----------|
| `navigate` | 导航到页面 | `tab` |
| `search` | 搜索 | `tab`, `keyword` |
| `sort` | 排序 | `tab`, `field`, `direction` |
| `filter` | 筛选 | `tab`, `filters` |
| `set_page_state` | 综合设置 | `tab`, 可选: `filters`, `sort`, `search` |

#### 有效的 tab 值
- `products` - 商品管理
- `orders` - 订单管理
- `users` - 用户管理
- `categories` - 分类管理
- `brands` - 品牌管理
- `banners` - 横幅管理
- `coupons` - 优惠券管理
- `aftersales` - 售后管理

#### 示例

**导航**
```json
[PAGE_ACTION]{"type":"navigate","params":{"tab":"orders"}}[/PAGE_ACTION]
```

**搜索**
```json
[PAGE_ACTION]{"type":"search","params":{"tab":"products","keyword":"iPhone"}}[/PAGE_ACTION]
```

**综合状态**
```json
[PAGE_ACTION]{"type":"set_page_state","params":{
  "tab":"products",
  "filters":{"brand":"Apple"},
  "sort":{"field":"price","direction":"desc"}
}}[/PAGE_ACTION]
```

### 2. 数据动作 (DATA_ACTION)

用于执行数据库 CRUD 操作。

#### 格式
```
[DATA_ACTION]{"type":"...", "params":{...}}[/DATA_ACTION]
```

#### 支持的类型

| type | 描述 | 必需参数 |
|------|------|----------|
| `create_product` | 创建商品 | `name`, `price` |
| `update_product` | 更新商品 | `id` |
| `delete_product` | 删除商品 | `id` |
| `update_order` | 更新订单 | `id` |
| `cancel_order` | 取消订单 | `id` |
| `create_category` | 创建分类 | `name` |
| `create_brand` | 创建品牌 | `name` |
| `create_banner` | 创建横幅 | `title` |
| `approve_aftersales` | 批准售后 | `id` |
| `reject_aftersales` | 拒绝售后 | `id`, `reason` |

#### 示例

**创建商品**
```json
[DATA_ACTION]{"type":"create_product","params":{
  "name":"iPhone 16 Pro",
  "price":8999,
  "brand":"Apple",
  "category":"手机",
  "stock_quantity":100
}}[/DATA_ACTION]
```

**更新订单状态**
```json
[DATA_ACTION]{"type":"update_order","params":{
  "id":"order-uuid-here",
  "status":"shipped"
}}[/DATA_ACTION]
```

## Dify 工作流配置

### 1. 添加 HTTP 请求节点

在 Dify 工作流中添加 HTTP 请求节点来获取系统能力：

**URL**: `https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-actions`

**Method**: GET

**Headers**:
```
Authorization: Bearer <SUPABASE_ANON_KEY>
```

### 2. 系统提示词模板

```
你是一个智能管理后台助手，可以帮助管理员执行各种操作。

## 可用能力

### 页面操作
当用户想要查看数据、导航到页面、搜索或筛选时，使用 PAGE_ACTION：
{{system_actions_response.pageActions}}

### 数据操作
当用户想要创建、更新、删除数据时，使用 DATA_ACTION：
{{system_actions_response.dataActions}}

## 响应格式

在回复末尾添加动作标记块：

1. 页面操作：[PAGE_ACTION]{"type":"...", "params":{...}}[/PAGE_ACTION]
2. 数据操作：[DATA_ACTION]{"type":"...", "params":{...}}[/DATA_ACTION]

## 注意事项

- 确保 JSON 格式正确
- 必需参数必须提供
- 可以在一条回复中包含多个动作
- 先给用户自然语言回复，再附加动作标记块
```

### 3. 示例对话

**用户**: 打开商品管理页面

**AI响应**:
```
好的，我来帮您打开商品管理页面。

[PAGE_ACTION]{"type":"navigate","params":{"tab":"products"}}[/PAGE_ACTION]
```

**用户**: 显示所有Apple品牌的商品，按价格从高到低排序

**AI响应**:
```
好的，我来帮您筛选Apple品牌的商品并按价格排序。

[PAGE_ACTION]{"type":"set_page_state","params":{"tab":"products","filters":{"brand":"Apple"},"sort":{"field":"price","direction":"desc"}}}[/PAGE_ACTION]
```

**用户**: 创建一个新商品：华为Mate 60 Pro，价格6999元

**AI响应**:
```
好的，我来帮您创建这个商品。

[DATA_ACTION]{"type":"create_product","params":{"name":"华为Mate 60 Pro","price":6999,"brand":"Huawei","category":"手机"}}[/DATA_ACTION]
```

## 能力同步机制

1. **前端定义**: 能力定义在 `src/utils/capabilitiesSync.ts` 中
2. **自动同步**: Admin 页面加载时通过 `useCapabilitiesSync` 钩子同步到数据库
3. **Edge Function 读取**: `system-actions` 函数从 `system_capabilities` 表读取最新能力

### 添加新能力

1. 在 `src/types/adminOperations.ts` 中添加新的操作类型
2. 在 `src/ai/dataActions.ts` 中添加动作类型映射
3. 在 `src/utils/adminOperationsClient.ts` 中添加客户端方法
4. 确保 `admin-operations` Edge Function 支持新操作
5. 刷新 Admin 页面触发同步

## 调试

### 查看解析的动作

在 AdminAIAssistant 中，解析到的动作会打印到控制台：
```
识别到统一动作: [{kind: "page_action", type: "navigate", params: {tab: "products"}}]
```

### 查看能力同步结果

同步完成后会在控制台打印：
```
Capabilities sync completed: 25 synced, 0 errors
```

### 手动测试 Edge Function

```bash
curl -X GET "https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-actions" \
  -H "Authorization: Bearer <ANON_KEY>"
```
