# Flow
### AI 原生跨境出口电商平台
**一套代码，两个产品：买家商城 + 卖家 AI 工作台。**
从开店、上架、成交、履约、客服到复盘，整条运营闭环都在这里。
[](CHANGELOG.md)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://react.dev/)
[](https://nestjs.com/)
[](https://www.postgresql.org/)
[](server)
[**English**](README.md) · [**简体中文**](README.zh-CN.md)
[**70 秒演示视频**](docs/video/demo.mp4) · [**产品截图**](docs/screenshots) · [**架构说明**](docs/ARCHITECTURE.md) · [**部署指南**](docs/DEPLOY.md)
**镜像**：[GitHub](https://github.com/X33834/Flow) · [Gitee](https://gitee.com/badhope/Flow) · [GitCode](https://gitcode.com/badhope/Flow)
---
## 你会得到什么
| | 买家商城 | 卖家 AI 工作台 |
|---|---|---|
| **面向** | 海外消费者，四种语言（en / zh / es / pt） | 经营店铺的商家 |
| **核心** | 搜索、筛选、SKU 规格、购物车、优惠券、结算、物流、退款、评价 | 看板、商品、订单、退款、集合、优惠券、CMS、审计、AI |
| **AI** | 导购：先推荐，加购前必须确认 | 五个专业 Agent + 带人工审批的工具调用副驾 |
**不配置任何 AI Key 也能完整使用。** 所有非 AI 功能正常运行；AI 端点诚实返回「请填写模型」，绝不返回假数据。
---
## 差异化在哪里
多数开源电商项目要么只有商城，要么只有后台。Flow 在同一套数据模型上同时交付两者，并且把 AI 写进运营闭环，而不是挂一个聊天窗口。
### 1. 会干活，但绝不擅自干
对它说「把低库存商品清仓」，它会查低库存、建清仓券、下架滞销品，把整串动作**合成一个待审批批次**，一次批准按序执行，失败即停。
```
卖家自然语言
└─ Agent 规划多步工具调用
├─ 只读工具 → 直接查本店真实数据
└─ 写工具 → copilot_actions(status = pending)
└─ 卖家批准 → 走既有业务服务
（状态机 / 库存 / 积分 / 审计保持一致）
```
- **12 个工具**：店铺概况、订单、商品、低库存、待批退款、状态流转、退款审批、上下架、建券、建草稿、回复咨询
- **参数强校验**：每个工具声明类型 / 枚举 / 范围 / 长度，未知参数一律拒绝，挡住模型幻觉与参数注入
- **归属校验**：读工具按卖家隔离，写工具执行前二次校验归属，管理员保留跨店权限
- **全链路留痕**：对话、工具结果、动作、执行结果逐条落库
### 2. 五个真实 Agent，不是五个按钮
| Agent | 做什么 | 关键实现 |
|---|---|---|
| **Copywriter** | 标题 / 卖点 / 长描述 / SEO 关键词 | 强制 JSON 输出，写回多语言字段 |
| **Support** | 智能客服 | FAQ 政策匹配 + 商品检索 + 订单摘要，先查真实数据再回答 |
| **Trend** | 销售分析 | 近 30 天 SQL 聚合 + LLM 解读，报告落库 |
| **Select** | 选品建议 | 类目 + Top 20 热销 + 库存上下文，输出结构化推荐 |
| **Translation** | 多语言翻译 | 12 种目标语言，按跨境场景调优 |
全部经同一网关收口，统一处理服务商差异（推理模型 token 预算、响应字段回退、带版本段的 Base URL）。用量按每次调用、按 Agent 计量。
### 3. 真正被执行的护栏
| 边界 | 行为 |
|---|---|
| 租户隔离 | 所有卖家侧查询强制作用域，管理员保留跨店视图 |
| 模型配置 | 密钥按 `userId:` 存储，任何卖家读不到、也覆盖不了他人配置 |
| 演示支付 | 仅 `development` / `test` 放行，生产环境一律 403，任何开关都不能绕过 |
| 出站请求 | webhook、通知地址、LLM Base URL 统一拒绝环回 / 私网 / CGNAT / 链路本地 / 云元数据，并绑定 DNS 解析结果、不跟随重定向 |
| 上架门禁 | 六项完整性校验（图片、库存、文案、类目、价格、规格）全部通过才允许上架 |
---
## 产品截图
### 买家商城
| 首页（英文） | 首页（中文） |
|:---:|:---:|
|  |  |
| **商品列表** | **商品详情** |
|  |  |
| **购物车** | **结算** |
|  |  |
| **订单跟踪** | **运营楼层** |
|  |  |
### 卖家工作台
| 数据看板 | AI 运营副驾 |
|:---:|:---:|
|  |  |
| **商品管理** | **订单管理** |
|  |  |
| **AI 分析中心** | **退款管理** |
|  |  |
全部 31 张截图在 [`docs/screenshots/`](docs/screenshots)，由 `npm run capture:all` 针对真实数据库重新生成，不会与代码脱节。仓库社交预览图由 `npm run capture:social` 渲染。
---
## 快速开始
### Docker（推荐）
```bash
git clone https://github.com/X33834/Flow.git
cd Flow
cp .env.example .env # 必须替换 JWT_SECRET 与 POSTGRES_PASSWORD
docker compose up -d --build
```
- 买家商城 →