# Lovable-Coze 协同开发指南

## 概述

本文档定义了 Lovable AI 与 Coze LangChain Agent 之间的协同开发规范，确保两者能够高效配合完成电商管理系统的开发和运营。

## 角色分工

### Lovable AI 职责
| 领域 | 具体工作 |
|------|----------|
| **代码实现** | React 组件、TypeScript 逻辑、CSS 样式 |
| **数据库** | Schema 设计、迁移脚本、RLS 策略 |
| **Edge Function** | 后端逻辑、API 代理、数据聚合 |
| **系统规范** | 维护 system-info API、更新组件库定义 |
| **测试验证** | 单元测试、集成测试、浏览器测试 |

### Coze LangChain Agent 职责
| 领域 | 具体工作 |
|------|----------|
| **意图理解** | 解析自然语言，识别用户意图 |
| **多轮对话** | 维护对话上下文，处理追问和澄清 |
| **UI 生成** | 根据意图和数据生成 GenUI Schema |
| **业务推理** | 基于数据分析提供洞察和建议 |

## 协同架构

```
┌─────────────────────────────────────────────────────────────┐
│                        用户请求                             │
│                           ↓                                 │
├─────────────────────────────────────────────────────────────┤
│                   coze-langchain Edge Function              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 1. 意图识别 → 确定 agent_type                       │    │
│  │ 2. 数据获取 → 从 Supabase 获取实时业务数据           │    │
│  │ 3. Prompt 注入 → 组件库规范 + 数据上下文             │    │
│  │ 4. 调用 Coze API → 发送增强后的请求                  │    │
│  │ 5. 解析响应 → 提取 ui_schema                        │    │
│  │ 6. 降级处理 → Coze 失败时使用 Lovable AI Gateway    │    │
│  └─────────────────────────────────────────────────────┘    │
│                           ↓                                 │
├─────────────────────────────────────────────────────────────┤
│                      前端 DynamicRenderer                    │
│  • 自动 normalize Schema 格式                               │
│  • 渲染对应的 React 组件                                    │
│  • 处理用户交互事件                                         │
└─────────────────────────────────────────────────────────────┘
```

## 共享知识库

### 1. system-info API

Coze Agent 应在每次会话开始时调用此 API 获取最新系统规范：

```bash
GET https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-info
```

返回内容包括：
- `collaborationProtocol` - 协同开发协议
- `genUIComponents` - 可用组件库
- `operations` - 可执行操作定义
- `database` - 数据模型
- `statistics` - 系统当前状态

### 2. agent_context 表

共享会话状态：

| 字段 | 用途 |
|------|------|
| `session_id` | 会话唯一标识 |
| `conversation_context` | 对话历史和当前意图 |
| `domain_context` | 各部门业务状态 |
| `selected_items` | 用户当前选中的实体 |
| `version` | 乐观锁版本号 |

### 3. system_guide 表

系统技术规范文档（只读）：
- ID: `nebula_arch_v1_0_1`
- 包含架构设计、数据模型、业务规则等

## GenUI Schema 规范

### 响应格式

```json
{
  "answer": "对用户问题的简洁回答",
  "ui_schema": {
    "layout": "vertical",
    "gap": "md",
    "components": [
      { "type": "stats_row", "props": { "items": [...] } },
      { "type": "data_table", "props": { "columns": [...], "rows": [...] } }
    ]
  },
  "suggested_actions": ["查看详情", "导出报表"]
}
```

### 组件规则

1. **必须包含 type 和 props**
   ```json
   // ✅ 正确
   { "type": "stats_row", "props": { "items": [...] } }
   
   // ❌ 错误 - 缺少 props
   { "type": "stats_row", "items": [...] }
   ```

2. **属性必须在 props 内部**
   ```json
   // ✅ 正确
   { "type": "data_table", "props": { "title": "标题", "columns": [...] } }
   
   // ❌ 错误 - title 在顶层
   { "type": "data_table", "title": "标题", "props": { "columns": [...] } }
   ```

3. **使用有效的组件类型**
   - `stats_row` - 统计指标行
   - `data_table` - 数据表格
   - `chart` - 图表 (pie/bar/line/area)
   - `alert` - 警告/提示
   - `insight_card` - 洞察卡片
   - `progress_bar` - 进度条
   - `text` - 文本块
   - `container` - 容器（嵌套组件）
   - `insight_feed` - 洞察流
   - `approval_list` - 审批列表

## 数据上下文注入

coze-langchain Edge Function 根据意图自动注入相关数据：

| Agent Type | 注入数据 |
|------------|----------|
| `manager` | 营收统计、订单状态、用户列表、待审批事项 |
| `product` | 低库存商品、热销商品、分类统计 |
| `marketing` | 活动状态、优惠券列表、销售趋势 |
| `finance` | 收入统计、订单分布、充值方案 |
| `service` | 待处理售后、物流跟踪、投诉统计 |

数据以 Markdown 格式注入到 LLM Prompt 中。

## 变更通知机制

当 Lovable 修改系统时：

1. **版本号更新**: `system-info.version` 字段更新
2. **组件库同步**: `GENUI_COMPONENT_LIBRARY` prompt 自动更新
3. **刷新建议**: Coze 应定期刷新 system-info（建议每小时）

当前系统版本: **3.0.0**

## 错误处理

| 场景 | 处理方式 |
|------|----------|
| Coze API 调用失败 | 自动降级到 Lovable AI Gateway |
| Schema 格式错误 | DynamicRenderer 自动 normalize |
| 数据获取失败 | 返回纯文本回复，不返回 ui_schema |

## 调用示例

### Coze 端配置

```python
# Coze 工作流示例
def handle_user_message(message: str, session_id: str):
    # 1. 调用 coze-langchain (已包含规范注入)
    response = requests.post(
        "https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/coze-langchain",
        json={
            "text": message,
            "session_id": session_id
        },
        headers={"Content-Type": "application/json"}
    )
    
    # 2. 返回结果包含 ui_schema
    return response.json()
```

### 前端调用

```typescript
import { routeAndCallGenUI } from '@/services/genUIRouter';

// 自动路由到 coze-langchain，失败时降级
const response = await routeAndCallGenUI(message, { conversation_id });

// 渲染 UI
if (response.ui_schema) {
  <DynamicRenderer schema={response.ui_schema} context={context} />
}
```

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-02-03 | 初始协同开发协议 |

---

**维护者**: Lovable AI  
**最后更新**: 2026-02-03
