Files
all-commons/README.md

546 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 云嘉 AI 智能体系统 · 外贸全链路自动化平台
> 面向全球IT配件经销商的 AI+RPA 智能体系统,覆盖从客户开发到采购备货的完整业务闭环。
---
## 目录
- [项目背景](#项目背景)
- [系统架构总览](#系统架构总览)
- [技能模块详解](#技能模块详解)
- [销售模块](#销售模块)
- [采购模块](#采购模块)
- [数据流与模块关系](#数据流与模块关系)
- [共享基础设施](#共享基础设施)
- [部署方式](#部署方式)
- [目录结构规范](#目录结构规范)
- [接口与集成说明](#接口与集成说明)
---
## 项目背景
本系统为云嘉科技定制开发服务于其全球IT配件经销业务。
核心目标:用 AI 智能体替代人工重复劳动,打通销售开发与采购备货两条业务线,实现数据互通、报价与成本自动对齐、全流程可追踪。
**适用角色:**
| 角色 | 关注点 |
|------|--------|
| 技术开发人员 | 各模块技术实现、接口规范、依赖关系 |
| 测试人员 | 各技能的输入输出、边界条件、异常处理 |
| 项目经理 | 模块划分、交付顺序、依赖关系 |
| 客户/业务方 | 系统能做什么、解决什么问题 |
| AI编程工具 | 仓库职责边界、数据结构、调用关系 |
---
## 系统架构总览
```
┌─────────────────────────────────────────────────────────────┐
│ 销售模块7个技能
│ │
│ search-buyers → mine-emails → send-outreach │
│ ↓ ↓ ↓ │
│ profile-customer ← track-followup → generate-quote │
│ ↓ │
│ schedule-tasks │
└──────────────────────────┬──────────────────────────────────┘
│ 共享数据层all-commons
┌──────────────────────────┴──────────────────────────────────┐
│ 采购模块7个技能
│ │
│ search-suppliers → screen-suppliers → archive-suppliers │
│ ↓ │
│ compare-prices → calculate-pricing → trigger-stocking │
│ ↓ │
│ track-purchase │
└─────────────────────────────────────────────────────────────┘
```
**核心设计原则:**
- 每个仓库是一个独立可运行的 Python 技能单元
- 所有技能通过 `all-commons` 共享数据结构、配置和工具函数
- 销售报价generate-quote自动拉取采购成本calculate-pricing实现利润闭环
- 每个技能支持单独触发,也支持串联编排
---
## 技能模块详解
### 销售模块
---
#### `search-buyers` · 多平台海外采购商搜索
**功能描述:**
从谷歌、领英、海关数据三大渠道自动搜索目标海外采购商,聚合去重后写入客户线索库。
**输入:**
- 产品关键词(如:`network switch`, `SFP module`
- 目标国家/地区
- 采购商规模筛选条件
**输出:**
- 结构化客户线索(公司名、官网、国家、联系人、来源渠道)
- 写入共享客户库
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 谷歌搜索采集 | Google Custom Search API 或 SerpAPI支持 dork 语法(`site:linkedin.com "IT distributor"` |
| 领英采集 | 基于 Playwright 模拟登录,支持多账号轮换,绕过频率限制 |
| 海关数据 | 对接 ImportYeti / Panjiva / 国内海关数据 API |
| 反爬策略 | 随机 User-Agent、请求间隔随机化2~8秒、代理IP池轮换 |
| 多账号管理 | 账号池配置,按任务分配账号,失败自动切换 |
| 指纹管理 | 使用 Playwright 的 stealth 插件模拟真实浏览器指纹Canvas、WebGL、字体 |
| 去重逻辑 | 以公司官网域名为唯一键,入库前做 MD5 比对 |
| 数据存储 | MySQL 8.0 `leads` 表,字段含来源渠道标记 |
---
#### `mine-emails` · 邮箱挖掘与清洗
**功能描述:**
从目标公司官网、领英主页、Hunter.io 等多源渠道抓取联系人邮箱经格式校验和MX记录验证后入库。
**输入:**
- 公司官网URL列表来自 `search-buyers` 输出)
**输出:**
- 有效邮箱列表(联系人姓名、职位、邮箱、来源)
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 官网爬取 | Playwright 动态渲染 + BeautifulSoup 静态解析,提取 mailto 和文本邮箱 |
| 邮箱发现API | Hunter.io API、Snov.io API 作为补充数据源 |
| 格式校验 | 正则匹配标准邮箱格式 |
| MX记录验证 | 通过 DNS 查询验证域名 MX 记录是否存在 |
| SMTP验证 | 可选SMTP VRFY 命令验证邮箱是否真实存在(需控制频率) |
| 反垃圾邮件过滤 | 过滤 noreply、info@、webmaster@ 等无效地址 |
| 去重 | 邮箱地址全局唯一,已存在则更新置信度分数 |
---
#### `send-outreach` · 智能开发信生成与发送
**功能描述:**
基于客户画像(行业、国家、产品类型)用 LLM 生成个性化英文开发信,通过多邮箱账号自动发送,记录发送状态。
**输入:**
- 客户信息(来自客户库)
- 产品信息(来自产品库)
- 邮件模板配置
**输出:**
- 邮件发送记录(时间、账号、状态)
- 触发 `track-followup` 监听回复
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 邮件生成 | 调用 LLMGPT-4o / Claude按 prompt 模板生成个性化内容 |
| 多邮箱账号管理 | 支持配置多个 Gmail / Outlook / 企业邮箱,按发送量均匀分配 |
| 发送频率控制 | 每账号每天限额默认≤50封避免触发邮件服务商封号 |
| 邮件预热 | 新账号支持预热模式,从低频开始逐步提升发送量 |
| SMTP / API发送 | 优先使用 SendGrid / Mailgun API备用 SMTP 直连 |
| 追踪像素 | 嵌入1x1追踪像素记录邮件打开事件 |
| 链接追踪 | 对邮件中的链接做重定向追踪,记录点击行为 |
| 退订管理 | 自动处理退订请求,标记客户状态 |
| 黑名单管理 | 全局退订列表,发送前自动过滤 |
---
#### `track-followup` · 回复解析与分层跟进
**功能描述:**
监听多邮箱账号的收件箱,用 LLM 解析回复内容,判断意向等级,自动触发对应跟进动作。
**输入:**
- 邮箱收件箱IMAP 监听)
- 历史沟通上下文
**输出:**
- 意向分级标签A/B/C/无效)
- 触发下一步动作(再次发信 / 生成报价 / 标记放弃)
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| IMAP监听 | 使用 `imaplib` 实时轮询或 IMAP IDLE 推送 |
| 回复解析 | LLM 提取意向信号关键词,判断:感兴趣 / 需更多信息 / 拒绝 / 无关 |
| 意向分层 | A类明确需求→ 立即报价B类模糊兴趣→ 追问产品细节C类冷淡→ 30天后再跟进 |
| 上下文管理 | 维护每个客户的完整对话历史LLM 调用时携带上下文 |
| 自动回复生成 | 针对不同意向等级LLM 生成对应回复草稿,人工审核后发送或全自动发送 |
| 跟进时间规则 | 可配置发信后3天无回复自动发第二封7天无回复发第三封 |
---
#### `generate-quote` · 报价单自动生成
**功能描述:**
根据客户询盘内容、产品库信息、采购成本和汇率自动计算报价并生成专业格式报价单PDF/Excel
**输入:**
- 客户询盘(产品型号、数量)
- 产品库成本价(来自 `calculate-pricing`
- 汇率接口实时数据
**输出:**
- 报价单文件PDF + Excel
- 报价记录写入数据库
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 成本拉取 | 实时调用 `calculate-pricing` 接口获取当前最低采购成本 |
| 利润率规则 | 可配置:按客户等级、产品类别、数量阶梯设定不同利润率 |
| 汇率实时获取 | 对接 ExchangeRate-API 或中国银行汇率接口 |
| 报价单生成 | 使用 `openpyxl` 生成 Excel`reportlab``WeasyPrint` 生成PDF |
| 模板管理 | 支持多套报价单模板(按品牌/客户定制) |
| 有效期管理 | 报价单自动标注有效期,过期后在系统中标记失效 |
| 版本控制 | 同一询盘支持多版本报价,记录历史修改 |
---
#### `profile-customer` · 客户画像建档
**功能描述:**
聚合各渠道获取的客户信息,构建结构化客户档案,持续更新互动记录,支持客户价值评分。
**输入:**
- 各技能产生的客户交互数据
**输出:**
- 完整客户档案CRM记录
- 客户价值评分RFM模型
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 数据聚合 | 订阅各技能的事件,自动更新客户档案 |
| RFM评分 | 按最近互动时间、互动频率、询盘金额计算客户价值分 |
| 公司信息补全 | 调用 Clearbit API 或 ZoomInfo 自动补全公司规模、行业、员工数 |
| 去重合并 | 同一公司多个联系人自动归并到同一客户账户下 |
| 标签体系 | 支持自定义标签:行业、产品偏好、国家、合作状态 |
---
#### `schedule-tasks` · 任务调度与提醒
**功能描述:**
管理所有跟进节点的时间计划,到期自动提醒相关人员,同步至外部日历,超期任务自动升级处理。
**输入:**
- 各技能触发的任务事件
**输出:**
- 提醒通知(邮件/企微/钉钉)
- 日历事件
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 任务队列 | 使用 Celery + Redis 管理定时任务 |
| 通知渠道 | 企业微信 Webhook、钉钉机器人、邮件 SMTP |
| 日历同步 | Google Calendar API / Outlook Calendar API |
| 超期升级 | 任务超期未处理自动通知上级,支持配置升级规则 |
| 任务优先级 | A类客户任务自动置顶C类客户任务自动降级 |
---
### 采购模块
---
#### `search-suppliers` · 全网供应商搜寻
**功能描述:**
自动聚合1688、阿里巴巴国际站、慧聪网、行业垂直平台的供应商信息按产品分类整理入库。
**输入:**
- 产品型号 / 品牌 / 关键词
- 采购数量参考区间
**输出:**
- 供应商候选列表(名称、平台、产品范围、联系方式)
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 平台爬取 | Playwright 模拟登录 + API 接口双通道 |
| 多账号管理 | 每个平台维护独立账号池,避免账号被封 |
| 指纹管理 | 浏览器指纹随机化,模拟不同设备环境 |
| 代理IP | 按平台地域选择对应IP国内平台用国内IP |
| 反爬策略 | 随机滑块验证码处理(打码平台对接)、请求频率控制 |
| 结果去重 | 以供应商官网/统一社会信用代码为唯一键去重 |
---
#### `screen-suppliers` · 资质筛选与风控评估
**功能描述:**
对候选供应商进行多维度资质核查,输出可信度评分,过滤高风险供应商。
**输入:**
- 供应商候选列表(来自 `search-suppliers`
**输出:**
- 供应商评分报告
- 推荐/排除标记
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 工商信息核查 | 对接天眼查/企查查 API验证营业执照、经营状态、法人信息 |
| 平台信用分 | 抓取1688/阿里平台综合评分、成交量、回购率 |
| 认证核查 | ISO / CE / FCC 等认证资料核实 |
| 负面信息筛查 | 检查失信被执行人名单、行政处罚记录 |
| 历史合作记录 | 与内部系统历史采购记录关联比对 |
| 评分模型 | 加权评分资质40% + 平台信用30% + 价格竞争力30% |
---
#### `archive-suppliers` · 供应商信息建档
**功能描述:**
将通过筛选的供应商信息结构化入库,建立完整档案,持续更新价格历史和合作记录。
**输入:**
- 筛选后的供应商数据
**输出:**
- 结构化供应商档案MySQL 8.0
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 数据模型 | 供应商主表 + 产品报价子表 + 联系人子表 + 合作记录表 |
| 价格历史 | 每次比价结果自动记录,支持价格趋势分析 |
| 标签分类 | 按产品类别、地区、规模、资质等级打标签 |
| 文件存储 | 营业执照、认证文件等附件存 MinIO / 阿里OSS |
| 变更追踪 | 供应商信息变更自动记录变更日志 |
---
#### `compare-prices` · 比价与价格汇总
**功能描述:**
针对同一产品型号,自动聚合多供应商报价,生成比价表,识别最优采购方案。
**输入:**
- 产品型号 + 采购数量
- 供应商库
**输出:**
- 比价汇总表Excel/在线看板)
- 推荐最优供应商
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 实时询价 | 自动向已建档供应商发送询价请求(邮件/平台消息) |
| 历史价格参考 | 结合历史采购价格,识别当前报价是否合理 |
| 阶梯价处理 | 支持不同采购数量对应不同单价的阶梯价比较 |
| 汇率换算 | 外币报价自动换算为人民币统一比较 |
| 可视化报表 | 输出 Excel 比价表,包含价格趋势折线图 |
---
#### `calculate-pricing` · 规则报价引擎
**功能描述:**
基于采购成本、运费、汇率、目标利润率规则,自动计算对外销售报价,供 `generate-quote` 调用。
**输入:**
- 采购成本(来自 `compare-prices`
- 定价规则配置
**输出:**
- 建议销售价(含不同利润率版本)
- 最低可接受价(成本线)
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 定价规则引擎 | 支持按客户等级、产品类别、数量区间配置不同利润率 |
| 成本构成 | 采购价 + 头程运费 + 关税 + 仓储费 + 平台佣金 |
| 汇率对接 | 实时汇率接口,支持配置汇率浮动保护系数 |
| 最低价保护 | 低于成本线的报价自动预警,需人工确认 |
| 规则版本管理 | 支持不同时期定价策略的版本切换 |
---
#### `trigger-stocking` · 锁货备货决策
**功能描述:**
根据销售端询盘量预测和库存安全线规则,自动判断是否需要提前锁货备货,并触发采购流程。
**输入:**
- 当前库存数据
- 近期询盘数据(来自销售模块)
- 供应商交期数据
**输出:**
- 备货建议单
- 自动触发采购订单(或推送人工审核)
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 需求预测 | 基于历史询盘量和季节性规律用简单时序模型预测未来30天需求 |
| 安全库存计算 | 安全库存 = 日均销量 × 供应商交期天数 × 安全系数 |
| 备货触发规则 | 库存 ≤ 安全库存时自动触发,支持手动调整阈值 |
| 供应商优选 | 自动选取综合评分最高且库存充足的供应商 |
| 审批流 | 金额超过阈值的备货单推送微信/钉钉审批,低于阈值自动执行 |
---
#### `track-purchase` · 采购进度跟踪
**功能描述:**
全程追踪采购订单的付款、发货、物流、到货各节点状态,异常自动预警,数据同步至销售端。
**输入:**
- 采购订单信息
**输出:**
- 实时订单状态
- 异常预警通知
**技术细节:**
| 技术点 | 说明 |
|--------|------|
| 物流追踪 | 对接 17Track / 快递100 API自动抓取物流轨迹 |
| 状态机 | 订单状态流转:待付款→已付款→备货中→已发货→运输中→已到货→已验收 |
| 异常预警 | 超期未发货、物流停滞超48小时自动触发预警 |
| 通知推送 | 关键节点变更自动推送企微/钉钉通知 |
| 与销售联动 | 到货确认后自动更新产品库存,解锁报价能力 |
---
## 数据流与模块关系
```
【销售端触发链路】
search-buyers
→ mine-emails
→ send-outreach
→ track-followup监听回复
├── A类客户 → generate-quote拉取 calculate-pricing 成本)
├── B类客户 → schedule-tasks安排再次跟进
└── 所有客户 → profile-customer更新画像
【采购端触发链路】
search-suppliers
→ screen-suppliers
→ archive-suppliers
→ compare-prices
→ calculate-pricing输出成本价给销售端
→ trigger-stocking触发备货
→ track-purchase跟踪到货
→ 库存更新 → 解锁 generate-quote
【销采闭环】
generate-quote ←→ calculate-pricing
(销售报价实时调用采购成本,利润实时可见)
```
---
## 共享基础设施
仓库:`all-commons`
```
all-commons/
├── config/
│ ├── settings.py # 全局配置数据库、API Key、邮箱账号池
│ ├── proxy_pool.py # 代理IP池管理
│ └── account_pool.py # 多账号池管理(领英、平台账号)
├── db/
│ ├── models.py # 所有数据表模型定义SQLAlchemy
│ └── migrations/ # 数据库迁移文件Alembic
├── utils/
│ ├── llm_client.py # LLM统一调用封装支持切换GPT/Claude
│ ├── browser.py # Playwright浏览器封装含指纹管理
│ ├── email_client.py # 邮件发送/接收统一封装
│ ├── notify.py # 企微/钉钉/邮件通知统一封装
│ └── exchange_rate.py # 汇率查询封装
├── schemas/
│ └── data_models.py # 技能间传递的数据结构定义Pydantic
└── README.md
```
**核心数据表:**
| 表名 | 说明 |
|------|------|
| `leads` | 客户线索库 |
| `customers` | 客户档案(含画像、评分) |
| `contacts` | 联系人(邮箱、职位) |
| `email_logs` | 邮件发送/接收记录 |
| `quotes` | 报价单记录 |
| `suppliers` | 供应商档案 |
| `supplier_prices` | 供应商历史报价 |
| `purchase_orders` | 采购订单 |
| `inventory` | 产品库存 |
| `tasks` | 跟进任务队列 |
---
## 部署方式
- **运行环境:** Python 3.11+本地私有服务器Windows/Linux均支持
- **数据库:** MySQL 8.0+
- **任务队列:** Redis + Celery
- **浏览器自动化:** PlaywrightChromium
- **文件存储:** 本地路径 或 MinIO
- **进程管理:** Supervisor 或 systemd
每个技能仓库均包含:
```
├── main.py # 技能入口
├── requirements.txt # 依赖列表
├── .env.example # 环境变量示例
├── README.md # 技能单独说明
└── tests/ # 测试用例
```
---
## 接口与集成说明
| 外部服务 | 用途 | 技能 |
|----------|------|------|
| SerpAPI / Google CSE | 谷歌搜索采集 | search-buyers |
| Hunter.io / Snov.io | 邮箱挖掘 | mine-emails |
| SendGrid / Mailgun | 邮件发送 | send-outreach |
| OpenAI / Anthropic | LLM生成内容 | send-outreach, track-followup, generate-quote |
| 天眼查 / 企查查 | 工商信息核查 | screen-suppliers |
| 17Track / 快递100 | 物流追踪 | track-purchase |
| ExchangeRate-API | 实时汇率 | generate-quote, calculate-pricing |
| 企业微信 / 钉钉 | 通知推送 | schedule-tasks, trigger-stocking, track-purchase |
| Google / Outlook Calendar | 日历同步 | schedule-tasks |
---
*文档版本v1.0 · 最后更新2026-06-03 · 维护方:云嘉科技 × 匠厂AI*