# 智能电商管理系统 - 系统架构文档

> 版本: 2.0.0 | 最后更新: 2026-01-28
> 技术栈: React 18 + TypeScript + Vite + Supabase + Tailwind CSS

---

## 1. 产品概述

### 1.1 产品定位
智能电商管理系统是一个**AI驱动的多Agent协作电商管理平台**，通过5个专业AI Agent实现店铺运营自动化，结合GenUI动态界面渲染技术提供自然语言交互体验。

### 1.2 核心特性
- **多Agent协作**: 5个专业AI Agent分工协作，覆盖店铺管理全场景
- **GenUI动态渲染**: AI返回结构化UI Schema，前端动态渲染丰富交互界面
- **自然语言操作**: 通过对话式交互完成复杂业务操作
- **智能审批工作流**: AI生成活动需人工审核，平衡效率与风险控制
- **实时数据分析**: AI洞察生成、趋势预测、异常告警

### 1.3 目标用户
- 电商店铺运营人员
- 店铺管理者/店长
- 电商企业决策者

---

## 2. 系统架构

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        前端应用 (React + Vite)                    │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐         │
│  │ 店铺经理  │  │ 商品经理  │  │ 营销经理  │  │ 客服经理  │  ...    │
│  │ Dashboard │  │ Dashboard │  │ Dashboard │  │ Dashboard │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘         │
│       │             │             │             │                │
│  ┌────┴─────────────┴─────────────┴─────────────┴────┐          │
│  │              GenUI 动态渲染引擎                      │          │
│  │  (DynamicRenderer + Component Registry)           │          │
│  └────────────────────────┬──────────────────────────┘          │
│                           │                                      │
│  ┌────────────────────────┴──────────────────────────┐          │
│  │           统一 Agent 通信层 (agentClient.ts)        │          │
│  └────────────────────────┬──────────────────────────┘          │
└───────────────────────────┼─────────────────────────────────────┘
                            │ HTTPS/SSE
┌───────────────────────────┼─────────────────────────────────────┐
│                    Supabase Edge Functions                       │
├───────────────────────────┼─────────────────────────────────────┤
│  ┌─────────────┐  ┌───────┴─────┐  ┌─────────────┐              │
│  │ system-info │  │coze-langchain│  │ *-genui     │              │
│  │ (系统元数据) │  │ (Agent入口)  │  │ (Agent接口) │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
│  ┌──────┴────────────────┴────────────────┴──────┐              │
│  │          *-operations (业务操作函数)            │              │
│  │   admin-operations | product-operations       │              │
│  │   marketing-operations | service-operations   │              │
│  └───────────────────────┬───────────────────────┘              │
└───────────────────────────┼─────────────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────────────┐
│                     Supabase PostgreSQL                          │
├───────────────────────────┼─────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐             │
│  │products │  │ orders  │  │ coupons │  │ goals   │  ...        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘             │
│                                                                  │
│  RLS Policies + Triggers + Functions                             │
└──────────────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────────────┐
│                    外部 AI 服务                                   │
├───────────────────────────┼─────────────────────────────────────┤
│  ┌─────────────────┐  ┌───┴───────────────┐                     │
│  │  Coze LangChain │  │  Lovable AI Gateway│                     │
│  │  (复杂对话工作流)  │  │  (洞察生成/审计)   │                     │
│  └─────────────────┘  └───────────────────┘                     │
└──────────────────────────────────────────────────────────────────┘
```

### 2.2 技术栈详情

| 层级 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 前端框架 | React | 18.3.1 | UI组件渲染 |
| 构建工具 | Vite | latest | 开发构建 |
| 类型系统 | TypeScript | 5.x | 类型安全 |
| 样式方案 | Tailwind CSS | 3.x | 原子化CSS |
| UI组件库 | shadcn/ui | latest | 基础组件 |
| 状态管理 | TanStack Query | 5.83 | 服务端状态 |
| 路由 | React Router | 6.30 | 前端路由 |
| 后端服务 | Supabase | 2.57 | BaaS平台 |
| 数据库 | PostgreSQL | 15 | 数据存储 |
| 边缘函数 | Deno | 1.x | Serverless |
| AI服务 | Coze/Lovable AI | - | 智能对话 |

---

## 3. AI Agent 系统

### 3.1 Agent 架构概述

系统采用**多Agent协作架构**，5个专业Agent分别负责不同业务域：

| Agent | 标识 | 角色 | 核心职责 |
|-------|------|------|----------|
| 小管 | manager | 店铺经理 | 全局运营、跨部门协调、战略决策、KPI管理 |
| 小品 | product | 商品经理 | 选品管理、定价策略、库存管理、品类规划 |
| 小营 | marketing | 营销经理 | 活动策划、促销推广、用户增长、数据复盘 |
| 小服 | service | 客服经理 | 售后服务、订单查询、退换货处理、投诉管理 |
| 小财 | finance | 财务经理 | 收入分析、成本核算、利润管理、资金流转 |

### 3.2 Agent 协作模式

```
                    ┌──────────────┐
                    │  小管 (经理)   │
                    │  Store Manager│
                    └───────┬──────┘
                            │ 目标分配/审批
          ┌─────────────────┼─────────────────┐
          │                 │                 │
    ┌─────┴─────┐    ┌─────┴─────┐    ┌─────┴─────┐
    │ 小品 (商品) │    │ 小营 (营销) │    │ 小服 (客服) │
    └───────────┘    └───────────┘    └───────────┘
          │                 │                 │
          └─────────────────┴─────────────────┘
                            │
                    ┌───────┴──────┐
                    │  小财 (财务)   │
                    │ 交易监控/对账  │
                    └──────────────┘
```

**协作规则**:
1. 小管(经理)可协调所有其他Agent
2. 每个Agent专注自己的业务域
3. 跨域操作需通过小管协调
4. 高风险操作需人工审批

### 3.3 Agent Edge Functions

| 函数名 | Agent | 功能 |
|--------|-------|------|
| `coze-langchain` | 通用入口 | LangChain Agent对话，SSE流式返回 |
| `manager-genui` | 小管 | 经理专属GenUI接口 |
| `product-genui` | 小品 | 商品管理GenUI接口 |
| `marketing-genui` | 小营 | 营销管理GenUI接口 |
| `service-genui` | 小服 | 客服管理GenUI接口 |
| `finance-genui` | 小财 | 财务管理GenUI接口 |
| `product-operations` | 小品 | 商品CRUD操作 |
| `marketing-operations` | 小营 | 营销活动操作 |
| `service-operations` | 小服 | 售后服务操作 |
| `admin-operations` | 通用 | 通用管理操作 |

---

## 4. GenUI 动态界面系统

### 4.1 设计理念

GenUI(Generative UI)是系统的核心创新，允许AI返回结构化的UI Schema，前端根据Schema动态渲染丰富的交互界面。

**优势**:
- AI可自主决定展示形式(表格/图表/卡片等)
- 界面与逻辑解耦，易于扩展
- 支持复杂嵌套布局
- 保持UI一致性

### 4.2 组件类型

```typescript
type ComponentType = 
  // 展示组件
  | 'stats_row'      // 统计行 - 多指标展示
  | 'data_table'     // 数据表格 - 结构化数据
  | 'chart'          // 图表 - 可视化
  | 'progress_bar'   // 进度条 - 目标进度
  | 'text'           // 文本块 - 富文本
  | 'alert'          // 提示框 - 警告/提示
  | 'insight_card'   // 洞察卡片 - AI分析
  | 'divider'        // 分隔线
  
  // 操作组件
  | 'action_buttons' // 操作按钮组
  | 'approval_card'  // 审批卡片
  
  // Agent组件
  | 'agent_status'       // Agent状态
  | 'agent_capabilities' // Agent能力
  | 'agent_thinking'     // Agent思考过程
  | 'agent_settings_card'// Agent设置
  
  // 特殊组件
  | 'sandbox_result' // 沙箱执行结果
  | 'container'      // 嵌套容器
```

### 4.3 UI Schema 结构

```typescript
interface UISchema {
  version?: string;
  layout?: 'vertical' | 'horizontal' | 'grid';
  gap?: 'sm' | 'md' | 'lg';
  components: UIComponent[];
}

interface UIComponent<T extends ComponentType> {
  id?: string;
  type: T;
  props: ComponentPropsMap[T];
}
```

### 4.4 渲染流程

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  AI 返回      │ ──> │ Schema 解析  │ ──> │ 组件注册表    │
│  UI Schema   │     │              │     │ 查找组件     │
└──────────────┘     └──────────────┘     └───────┬──────┘
                                                   │
┌──────────────┐     ┌──────────────┐     ┌───────┴──────┐
│  渲染到DOM    │ <── │ 递归渲染     │ <── │ DynamicRenderer│
└──────────────┘     │ 子组件       │     └──────────────┘
                     └──────────────┘
```

---

## 5. 数据模型

### 5.1 核心业务表

| 表名 | 描述 | 负责Agent | 核心字段 |
|------|------|-----------|----------|
| products | 商品表 | 小品 | name, price, stock_quantity, category, brand |
| orders | 订单表 | 小服/小财 | order_number, status, total_amount, user_id |
| profiles | 用户表 | 通用 | display_name, role, phone |
| after_sales_requests | 售后表 | 小服 | type, status, reason, refund_amount |
| coupons | 优惠券表 | 小营 | code, type, discount_value, status |
| marketing_campaigns | 营销活动表 | 小营 | name, type, status, ai_strategy |
| flash_sales | 秒杀活动表 | 小营 | flash_price, stock_limit, start_time |
| group_buy_activities | 拼团活动表 | 小营 | group_price, min_group_size |
| goals | 目标表 | 小管 | title, target_value, current_value, agent_type |
| agent_settings | Agent设置表 | 小管 | agent_type, auto_execute_enabled, max_auto_amount |

### 5.2 状态机定义

**订单状态流转**:
```
pending ──> paid ──> shipped ──> completed
    │                    │
    └──> cancelled <─────┘
```

**售后状态流转**:
```
pending ──> processing ──> approved ──> completed
                │
                └──> rejected
```

**营销活动状态流转**:
```
draft ──> pending ──> active ──> completed
              │          │
              └──> rejected
                         │
              paused <───┘
```

### 5.3 RLS 安全策略

所有表启用Row Level Security(RLS)，核心规则：
- 用户只能访问自己的数据 (`auth.uid() = user_id`)
- 管理员可访问所有数据 (`profiles.role = 'admin'`)
- 公开数据可匿名读取 (`is_active = true`)

---

## 6. API 设计

### 6.1 Edge Functions 列表

| 函数名 | 方法 | 认证 | 描述 |
|--------|------|------|------|
| system-info | GET | 否 | 获取系统元数据、统计、能力定义 |
| system-actions | GET | 否 | 获取可执行操作定义 |
| coze-langchain | POST | 是 | LangChain Agent对话(SSE) |
| admin-operations | POST | 是 | 执行管理操作 |
| product-operations | POST | 是 | 商品域操作 |
| marketing-operations | POST | 是 | 营销域操作 |
| service-operations | POST | 是 | 客服域操作 |
| *-genui | POST | 是 | 各Agent GenUI接口 |
| *-insights | POST | 是 | AI洞察生成 |
| context-read | POST | 是 | 读取Agent上下文 |
| context-commit | POST | 是 | 提交Agent上下文变更 |

### 6.2 操作类型定义

```typescript
const ADMIN_OPERATIONS = {
  product: {
    query: { params: ['keyword', 'category', 'brand', 'minPrice', 'maxPrice', 'isActive'] },
    create: { params: ['name', 'price', 'description', 'category', 'brand', 'stock_quantity'] },
    update: { params: ['id', 'name', 'price', ...] },
    delete: { params: ['id'] },
    updateStock: { params: ['id', 'quantity'] },
    toggleStatus: { params: ['id', 'isActive'] }
  },
  order: {
    query: { params: ['orderNumber', 'userId', 'status', 'startDate', 'endDate'] },
    updateStatus: { params: ['id', 'status'] },
    addTracking: { params: ['id', 'tracking_number'] },
    cancel: { params: ['id', 'reason'] },
    refund: { params: ['id', 'amount', 'reason'] }
  },
  // ... 更多操作类型
};
```

---

## 7. 前端架构

### 7.1 目录结构

```
src/
├── ai/                    # AI相关模块
│   ├── genui/            # GenUI渲染系统
│   │   ├── components/   # GenUI组件库
│   │   ├── DynamicRenderer.tsx
│   │   ├── registry.tsx  # 组件注册表
│   │   └── types.ts      # 类型定义
│   ├── dashboardActions.ts
│   ├── dataActions.ts
│   └── pageActions.ts
├── components/
│   ├── admin/            # 管理后台组件
│   │   ├── marketing/    # 营销模块
│   │   ├── products/     # 商品模块
│   │   ├── finance/      # 财务模块
│   │   ├── aftersales/   # 售后模块
│   │   ├── manager/      # 经理模块
│   │   └── shared/       # 共享组件
│   ├── chat/             # 聊天组件
│   └── ui/               # shadcn组件
├── contexts/             # React Context
├── hooks/                # 自定义Hooks
├── pages/                # 页面组件
├── services/             # 业务服务
├── types/                # 类型定义
└── utils/                # 工具函数
```

### 7.2 核心Hook

| Hook | 功能 |
|------|------|
| useDashboardState | Dashboard组件状态管理 |
| useGoals | Agent目标管理 |
| useConversations | 对话历史管理 |
| useCapabilitiesSync | 能力同步 |

### 7.3 状态管理策略

- **服务端状态**: TanStack Query管理API数据
- **本地UI状态**: React useState/useReducer
- **全局状态**: React Context (Auth, Cart)
- **URL状态**: React Router (导航、筛选)

---

## 8. 安全架构

### 8.1 认证授权

- **认证方式**: Supabase Auth (Email/Password)
- **角色类型**: `user` | `admin` | `super_admin`
- **Token管理**: JWT自动刷新

### 8.2 数据安全

- **传输加密**: HTTPS/TLS
- **数据隔离**: RLS策略强制
- **敏感数据**: 服务端处理，不暴露给前端
- **API密钥**: 存储于Supabase Secrets

### 8.3 操作审计

- `context_changes` 表记录所有Agent操作
- `ai_read_log` 表记录AI读取行为
- 包含操作者、时间、变更内容

---

## 9. 部署架构

### 9.1 环境配置

| 环境 | 用途 | URL |
|------|------|-----|
| Development | 本地开发 | localhost:5173 |
| Preview | 测试预览 | *.lovable.app |
| Production | 正式环境 | prod-assist-chat.lovable.app |

### 9.2 CI/CD流程

```
代码提交 ──> Lovable自动构建 ──> Preview部署 ──> 验证通过 ──> Publish生产
```

### 9.3 Edge Functions部署

- 自动部署：代码变更后自动同步
- 手动部署：使用`deploy_edge_functions`工具

---

## 10. 扩展指南

### 10.1 添加新Agent

1. 在`src/types/agents.ts`添加Agent定义
2. 创建`supabase/functions/{agent}-genui/index.ts`
3. 创建`supabase/functions/{agent}-operations/index.ts`
4. 在`supabase/config.toml`注册函数
5. 创建对应Dashboard组件

### 10.2 添加新GenUI组件

1. 在`src/ai/genui/types.ts`添加类型定义
2. 在`src/ai/genui/components/`创建组件
3. 在`src/ai/genui/registry.tsx`注册组件
4. 在`system-info`函数更新组件文档

### 10.3 添加新操作类型

1. 在对应`*-operations`函数添加处理逻辑
2. 更新`system-info`的操作定义
3. 在`agentClient.ts`添加路由映射

---

## 附录

### A. 环境变量

| 变量名 | 描述 | 必须 |
|--------|------|------|
| SUPABASE_URL | Supabase项目URL | 是 |
| SUPABASE_ANON_KEY | Supabase匿名密钥 | 是 |
| LOVABLE_API_KEY | Lovable AI Gateway密钥 | 是 |
| COZE_API_TOKEN | Coze API密钥 | 是 |

### B. 常用命令

```bash
# 本地开发
npm run dev

# 类型检查
npm run typecheck

# 构建
npm run build
```

### C. 相关文档

- [GenUI API指南](./genui-api-guide.md)
- [Dify集成指南](./dify-lovable-integration.md)
- [管理操作指南](./admin-operations-guide.md)
- [E2B沙箱集成](./e2b-sandbox-integration-guide.md)
