# 项目档案 · Project Overview

> 智能电商管理系统的"一页纸"总览。新人入门或 AI Agent 启动时优先阅读本文档。

---

## 一、项目定位

一个 **AI 驱动的电商运营平台**，由两侧组成：

| 侧 | 用户 | 核心交互 |
|---|---|---|
| **C 端** | 消费者 | 与"小智"对话买手机，AI 推荐 + 卡片渲染 |
| **B 端** | 商城运营团队 | 自然语言指挥 5 个部门 Agent 完成全部运营 |

**核心理念**：业务由 AI 主导执行，人类负责审批和兜底。

---

## 二、技术栈

| 层 | 技术 |
|---|---|
| 前端 | React 18 + Vite 5 + TypeScript 5 + Tailwind 3 + shadcn/ui |
| 后端 | Supabase（Postgres + Auth + Storage + Edge Functions / Deno） |
| AI 引擎 | Dify（C 端主 + 兜底 Coze）· Coze Workflow（B 端主） · Lovable AI Gateway（备用） |
| 记忆 | Mem0 长期用户记忆 |
| 通信 | SSE 流式 + Supabase Realtime（告警广播） |

---

## 三、五大业务 Agent（B 端）

| 代号 | 名称 | 职责 | 主要 Edge Function |
|---|---|---|---|
| 小管 | 商城经理 | 全局监控、目标设定、跨部门协调 | `manager-genui`, `manager-insights` |
| 小品 | 商品经理 | 商品上下架、库存、SKU、规格 | `product-genui`, `product-operations` |
| 小营 | 营销经理 | 优惠券、秒杀、拼团、支付有礼 | `marketing-genui`, `marketing-operations` |
| 小财 | 财务经理 | 订单收款、充值、对账 | `finance-genui` |
| 小服 | 客服经理 | 售后、退换、投诉处理 | `service-genui`, `service-operations` |

**协作模式**：小管设定目标 → 各专业 Agent 自动执行 → 高风险操作走审批。

---

## 四、关键数据流

### C 端：买家问"我想买苹果手机"
```
用户 → ChatPage → dify-chat-stream (SSE)
     → Dify Workflow（含商品检索、Mem0 上下文）
     → 返回 picks[{product_id}]
     → 前端校验 UUID → ProductCard 渲染
     → 失败兜底 → coze-chat
```

### B 端：运营说"创建一张满 100 减 20 的券"
```
管理员 → AdminAIAssistant → coze-langchain
       → Coze Workflow 解析意图
       → 返回 DATA_ACTION (create_coupon) + PAGE_ACTION (navigate)
       → executePageAction.ts 顺序执行
       → admin-operations Edge Function 写库
       → workbenchEventBus 推送 GenUI 到对应工作台
```

---

## 五、关键约定（Critical Conventions）

> 这些是"红线"，违反会导致系统崩溃或数据混乱。

1. **数据库是唯一真相源（SSOT）** — AI 严禁编造 UUID，找不到就返回空数组
2. **Office 命名法** — UI 文案用"经理办公室/财务室"，禁用"驾驶舱/Dashboard"
3. **DATA_ACTION 先于 PAGE_ACTION** — 数据写完再跳转
4. **C 端不全量 GenUI** — 只 AI 选数据，固定 React 组件渲染（性能 + 一致性）
5. **B 端走 GenUI** — AI 输出 schema，DynamicRenderer 渲染
6. **Admin / C 端完全隔离** — 独立 auth、路由、布局
7. **Root Admin** — 手机号 `17316420589`

---

## 六、核心数据库表

| 表 | 用途 |
|---|---|
| `products` | 商品（含 pgvector embedding） |
| `orders` / `order_items` | 订单 |
| `coupons` / `user_coupons` | 优惠券 |
| `flash_sales` / `group_buy_*` / `payment_gifts` | 营销活动 |
| `after_sales_requests` | 售后工单 |
| `agent_context` | 多 Agent 共享上下文（乐观锁） |
| `business_alerts` | 主动监控告警 |
| `goals` | Agent 目标管理 |
| `system_guide` | 系统宪法（AI 启动必读） |
| `genui_components` / `api_registry` | GenUI 与 API 注册中心 |
| `knowledge_base` | 向量化文档知识库（RAG 检索源） |

---

## 七、入口文件速查

| 模块 | 文件 |
|---|---|
| 路由 | `src/App.tsx` |
| C 端聊天 | `src/pages/ChatPage.tsx` + `src/components/chat/*` |
| B 端入口 | `src/pages/AdminPage.tsx` + `src/components/admin/*` |
| AI 助手 | `src/components/admin/AdminAIAssistant.tsx` |
| GenUI 渲染器 | `src/ai/genui/DynamicRenderer.tsx` |
| 工作台总线 | `src/services/workbenchEventBus.ts` |
| Dify 客户端 | `src/utils/difyStreamClient.ts` |
| Coze 客户端 | `src/utils/cozeStreamClient.ts` |

---

## 八、当前痛点 & 路线图（2026-04）

参考最近一次架构审计，**优先级 P0**：
1. AI 输出 JSON Schema 强约束（替代正则兜底）
2. Edge Function 共享中间件（CORS / auth / trace_id）
3. 全局错误监控（Sentry 或 `error_logs` 表）
4. C 端"幻觉商品 ID" → 改用 pgvector RAG 映射

详见近期对话记录中的 19 项改进清单。

---

**维护**：本文档过时时请同时更新 [docs/README.md](./README.md) 索引和 `mem://index.md`。
