

# GenUI 后端对接说明文档

## 📋 文档概述

本文档面向需要与 GenUI 系统对接的后端开发者（如 LangChain/Coze/Dify Agent），说明如何通过 Edge Functions 生成标准 UI Schema，供前端动态渲染界面。

---

## 🏗️ 系统架构

```text
┌─────────────────────────────────────────────────────────────────┐
│                        GenUI 数据流                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────┐    ┌──────────────────┐    ┌─────────────────┐   │
│   │  Agent   │───▶│  Edge Function   │───▶│   Frontend      │   │
│   │(LangChain│    │ ({agent}-genui)  │    │ (DynamicRenderer│   │
│   │  /Coze)  │    │                  │    │    组件)        │   │
│   └──────────┘    └──────────────────┘    └─────────────────┘   │
│        │                   │                       │             │
│        │                   ▼                       ▼             │
│        │          ┌──────────────┐        ┌──────────────┐      │
│        │          │  ui_schema   │        │  Component   │      │
│        └─────────▶│    JSON      │───────▶│   Registry   │      │
│                   └──────────────┘        └──────────────┘      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 📡 可用的 Edge Function 端点

系统提供 5 个独立的 GenUI Edge Function，每个对应一个 AI Agent：

| Agent | Edge Function | 职责范围 |
|-------|--------------|---------|
| 店长 (小管) | `manager-genui` | 全局概览、跨部门统计、审批汇总 |
| 商品 (小品) | `product-genui` | 商品列表、库存分析、分类/品牌管理 |
| 营销 (小营) | `marketing-genui` | 营销活动、优惠券、促销分析 |
| 客服 (小服) | `service-genui` | 售后工单、发货管理、客户服务 |
| 财务 (小财) | `finance-genui` | 财务报表、订单统计、会员分析 |

---

## 🔌 API 调用规范

### 请求端点

```
POST https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/{agent}-genui
```

### 请求头

```http
Content-Type: application/json
Authorization: Bearer {SUPABASE_ANON_KEY}
```

### 请求体 (Request Body)

```json
{
  "message": "用户的自然语言输入或意图指令",
  "conversation_id": "可选，用于多轮对话上下文保持",
  "view": "可选，指定当前视图 (dashboard/products/orders等)",
  "context": {
    "current_view": "当前页面视图",
    "selected_id": "选中项的ID",
    "filters": {
      "category": "筛选分类",
      "status": "筛选状态"
    }
  }
}
```

### 响应体 (Response Body)

```json
{
  "success": true,
  "answer": "AI 的文字回复（可选）",
  "ui_schema": {
    "layout": "vertical",
    "gap": "md",
    "components": [
      {
        "type": "stats_row",
        "id": "overview-stats",
        "props": {
          "items": [
            { "label": "本月营收", "value": "¥12,580", "color": "success" }
          ]
        }
      }
    ]
  },
  "insights": [
    {
      "id": "insight_1",
      "type": "warning",
      "priority": "high",
      "title": "库存预警",
      "description": "5款商品库存低于安全线"
    }
  ],
  "intent": "dashboard",
  "stats": { },
  "conversation_id": "conv_xxx",
  "message_id": "msg_xxx"
}
```

---

## 📦 UI Schema 结构定义

### 顶层结构

```typescript
interface UISchema {
  version?: string;                           // Schema 版本
  layout?: 'vertical' | 'horizontal' | 'grid'; // 布局方式
  gap?: 'sm' | 'md' | 'lg';                   // 组件间距
  components: UIComponent[];                   // 组件数组
}

interface UIComponent {
  id?: string;                                 // 组件唯一标识
  type: ComponentType;                         // 组件类型
  props: Record<string, any>;                  // 组件属性
}
```

### 支持的组件类型

前端注册了以下组件类型白名单：

| 类型 | 用途 | 示例场景 |
|------|------|---------|
| `stats_row` | 统计指标行 | KPI 展示、数据概览 |
| `data_table` | 数据表格 | 商品列表、订单列表 |
| `chart` | 图表 | 销售趋势、分类分布 |
| `alert` | 警告提示 | 库存预警、系统通知 |
| `action_buttons` | 操作按钮组 | 批量操作、快捷入口 |
| `approval_card` | 审批卡片 | 待审批项目展示 |
| `insight_card` | 洞察卡片 | AI 生成的数据洞察 |
| `progress_bar` | 进度条 | 目标完成进度 |
| `text` | 文本块 | 说明文字、Markdown内容 |
| `divider` | 分隔线 | 内容分隔 |
| `container` | 容器 | 嵌套布局组合 |
| `insight_feed` | 洞察流 | 批量洞察展示 |
| `approval_list` | 审批列表 | 批量审批项展示 |

---

## 📐 组件详细规范

### 1. stats_row (统计行)

```json
{
  "type": "stats_row",
  "props": {
    "items": [
      {
        "label": "本月营收",
        "value": "¥156,800",
        "color": "success",
        "trend": {
          "direction": "up",
          "value": "+12.5%"
        }
      },
      {
        "label": "待处理订单",
        "value": "23单",
        "color": "warning"
      }
    ],
    "columns": 4
  }
}
```

**Props 说明：**
- `items[]`: 统计项数组
  - `label`: 指标名称
  - `value`: 指标值（字符串或数字）
  - `color`: `'default'` | `'success'` | `'warning'` | `'error'` | `'info'`
  - `trend.direction`: `'up'` | `'down'` | `'neutral'`
  - `trend.value`: 趋势数值文本
- `columns`: 每行列数 (2-6)

### 2. data_table (数据表格)

```json
{
  "type": "data_table",
  "props": {
    "title": "低库存商品",
    "columns": [
      { "key": "name", "label": "商品名称" },
      { "key": "stock_quantity", "label": "当前库存" }
    ],
    "rows": [
      { "name": "iPhone 15", "stock_quantity": 3 },
      { "name": "AirPods Pro", "stock_quantity": 5 }
    ],
    "emptyText": "暂无数据"
  }
}
```

### 3. chart (图表)

```json
{
  "type": "chart",
  "props": {
    "title": "近7日销售趋势",
    "type": "area",
    "data": [
      { "label": "1/15", "value": 5200 },
      { "label": "1/16", "value": 6100 },
      { "label": "1/17", "value": 4800 }
    ],
    "xKey": "label",
    "yKey": "value",
    "height": 200
  }
}
```

**图表类型：** `'bar'` | `'line'` | `'pie'` | `'area'`

### 4. alert (警告框)

```json
{
  "type": "alert",
  "props": {
    "type": "warning",
    "title": "库存预警",
    "message": "有5件商品库存不足10件，请及时补货"
  }
}
```

**类型：** `'info'` | `'warning'` | `'success'` | `'error'`

### 5. container (容器布局)

```json
{
  "type": "container",
  "props": {
    "layout": "horizontal",
    "gap": "md",
    "children": [
      { "type": "chart", "props": { ... } },
      { "type": "chart", "props": { ... } }
    ]
  }
}
```

**Layout 选项：**
- `vertical`: 垂直堆叠
- `horizontal`: 水平排列
- `grid`: 网格布局（配合 `columns` 使用）

### 6. insight_feed (洞察流)

```json
{
  "type": "insight_feed",
  "props": {
    "title": "AI 洞察",
    "insights": [
      {
        "id": "insight_1",
        "type": "warning",
        "priority": "high",
        "title": "库存预警",
        "description": "5款商品库存低于安全线",
        "agent": "小品",
        "actionLabel": "补货",
        "actionId": "restock"
      }
    ],
    "layout": "list",
    "groupBy": "priority"
  }
}
```

---

## 🔄 典型调用流程

### 前端调用示例

```typescript
// 前端通过 Supabase SDK 调用
const { data, error } = await supabase.functions.invoke('manager-genui', {
  body: {
    message: '显示店长工作台概览',
    conversation_id: conversationId,
  },
  headers: {
    Authorization: `Bearer ${session.access_token}`
  }
});

// 获取 ui_schema 并传递给 DynamicRenderer
if (data.ui_schema) {
  <DynamicRenderer 
    schema={data.ui_schema} 
    context={{ onAction: handleAction }}
  />
}
```

### 后端生成示例

```typescript
// Edge Function 内部生成 ui_schema
function generateUISchema(intent: string, data: any): UISchema {
  switch (intent) {
    case 'dashboard':
      return {
        layout: 'vertical',
        gap: 'md',
        components: [
          {
            type: 'stats_row',
            props: {
              items: [
                { label: '本月营收', value: `¥${data.revenue}` },
                { label: '订单数', value: data.orderCount }
              ]
            }
          },
          {
            type: 'chart',
            props: {
              title: '销售趋势',
              type: 'area',
              data: data.trendData
            }
          }
        ]
      };
  }
}
```

---

## ⚠️ 注意事项

### 组件白名单机制

- 前端只渲染注册在 `componentRegistry` 中的组件类型
- 未注册的组件类型会显示 "未知组件类型" 警告
- 新增组件需要同时修改后端 Schema 和前端 Registry

### 数据传递规范

- `ui_schema` 是核心字段，前端依赖此字段渲染界面
- `answer` 可选，用于聊天场景的文字回复
- `insights` 可选，用于展示 AI 生成的洞察列表

### 错误处理

```json
{
  "success": false,
  "error": "错误描述信息"
}
```

---

## 📁 相关代码位置

| 文件 | 说明 |
|------|------|
| `supabase/functions/{agent}-genui/index.ts` | 5个 Edge Function 入口 |
| `src/ai/genui/types.ts` | TypeScript 类型定义 |
| `src/ai/genui/registry.tsx` | 组件注册表 |
| `src/ai/genui/DynamicRenderer.tsx` | 动态渲染引擎 |
| `src/components/admin/{agent}/` | 各 Agent 工作台组件 |
| `docs/genui-api-guide.md` | 现有 API 指南文档 |

