仓宝阁 · AI 跨境选品工作台 v2

基于「国内货源优先」策略的 Amazon 跨境电商 10步SOP 智能选品平台。
集成智赢插件实时数据、Playwright 自动化审计、ROI 测算、国内反查比价于一体。

---

一、当前版本状态（2026-04）

✅ 已完成功能

阶段	模块	状态
Phase A	国内货源录入表单（1688/淘宝/京东）	✅
Phase A	关键词智能提取（中英文）	✅
Phase B	Playwright + CDP 连接真实 Chrome（含插件）	✅
Phase B	智赢插件数据读取（商标、FBM/FBA、卖家来源、价格、上架天数）	✅
Phase B	Amazon 商品自动审计（ASIN、价格、评分、竞品数）	✅
Phase B	截图采集（全屏 + 主图）	✅
Phase C	国内反查（淘宝图搜 + 1688关键词搜 + pHash相似度验证）	✅
Phase C	国内比价 Tab（最优匹配卡片 + 货源列表）	✅
Phase D	ROI 测算 v2（实时汇率 + 燕文/云途物流报价）	✅
Phase D	5区域品牌风险分析（规则引擎 v2）	✅
UI	Manus 风格双栏工作台（对话流 + 6个业务Tab）	✅
UI	SOP 10步进度条（A→J）	✅
运维	Cloudflare Named Tunnel 固定域名穿透	✅

🚧 待完成（tasks.md 中）

任务	优先级
Phase A：1688/淘宝完全自动爬取（无需手动填写）	P1
Phase D：ERP 草稿自动生成与提交	P2
批量候选池管理（多ASIN并发审计）	P2
OCR / 视觉模型识别商品图片	P3

---

二、技术架构

┌─────────────────────────────────────────────┐
│              前端（单页 SPA）                 │
│  static/index.html  +  static/app.js        │
│  • 左侧：AI对话流 + SOP步骤条                │
│  • 右侧：6个Tab（工作台/选品/搜索/风险/利润/国内比价）│
└──────────────┬──────────────────────────────┘
               │ HTTP/SSE
┌──────────────▼──────────────────────────────┐
│         后端（FastAPI · Port 8002）           │
│  app/main.py  ←  所有 API 路由               │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐ │
│  │ amazon/  │  │ analysis/│  │ domestic/ │ │
│  │automation│  │ roi v2   │  │ reverse   │ │
│  │zhiying   │  │ risk v2  │  │ search    │ │
│  └──────────┘  └──────────┘  └───────────┘ │
└──────────────┬──────────────────────────────┘
               │ CDP (port 9222)
┌──────────────▼──────────────────────────────┐
│     真实 Chrome（含智赢插件 · 已登录）         │
│     通过 启动调试Chrome.bat 开启              │
└─────────────────────────────────────────────┘

技术栈

• 后端：FastAPI + uvicorn（Windows SelectorEventLoop）
• 前端：原生 HTML / CSS / JS（无框架）
• 浏览器自动化：Playwright via connect_over_cdp
• 数据库：SQLite（mvp.db）
• 图像处理：Pillow + imagehash（pHash相似度）
• 汇率：open.er-api.com 实时接口（1小时缓存）
• 内网穿透：cloudflared

---

三、快速启动

前提条件

1. Python 3.12+，已安装依赖：

   pip install -r requirements.txt

2. 已安装 Playwright 浏览器：

   playwright install chromium

Step 1：启动调试版 Chrome（含智赢插件）

双击运行：

启动调试Chrome.bat

此脚本会以 --remote-debugging-port=9222 启动 Chrome，保留用户Profile和插件登录状态。
首次使用请先在 Chrome 中登录 Amazon 账号，并确认智赢插件面板已显示数据。

Step 2：启动后端服务

python run_server.py

或使用脚本：

scripts\启动主服务8002.bat

服务启动后访问：http://127.0.0.1:8002

Step 3：（可选）启动 Cloudflare 公网穿透

scripts\启动Cloudflare穿透.bat

配置文件：config/cloudflare/tunnel.env

---

四、项目结构

AI自动化/
├── app/
│   ├── main.py                    # FastAPI 主服务，所有 API 路由
│   ├── models.py                  # SQLite 数据模型
│   ├── amazon/
│   │   ├── automation.py          # Playwright CDP 自动化审计核心
│   │   ├── crawler.py             # Amazon 静态爬取（轻量备用）
│   │   ├── search.py              # Amazon 搜索结果解析
│   │   ├── zhiying_reader.py      # 智赢插件 DOM 数据提取
│   │   └── plugin_bridge.py       # 插件通信桥接
│   ├── analysis/
│   │   ├── profit_calculator_v2.py  # ROI 测算（实时汇率 + 物流报价）
│   │   ├── risk_analyzer_v2.py      # 品牌风险分析
│   │   └── rule_engine_v2.py        # 规则引擎（5区域）
│   ├── domestic/
│   │   ├── crawler.py             # 1688/淘宝基础爬取
│   │   ├── keyword_extractor.py   # 国内关键词提取
│   │   └── reverse_search.py      # 国内反查（图搜+关键词+pHash）
│   └── sop/
│       ├── pipeline.py            # SOP 流程状态机
│       ├── category_config.py     # 品类配置（允许/排除规则）
│       ├── domestic_sourcing.py   # 国内货源评估
│       ├── env_checker.py         # 环境与浏览器健康检查
│       ├── image_sourcing.py      # 以图搜图
│       ├── keyword_extractor.py   # SOP 关键词处理
│       └── sourcing_validator.py  # 货源有效性验证
├── static/
│   ├── index.html                 # 前端主页面
│   ├── app.js                     # 前端交互逻辑（SOP流程 + 渲染）
│   ├── styles.css                 # 全局样式
│   └── screenshots/               # 审计截图（自动生成）
│       └── debug/
├── scripts/
│   ├── service_manager.py         # 服务管理统一入口
│   ├── 启动主服务8002.bat          # 快捷启动后端
│   ├── 启动全部服务.bat            # 后端 + Cloudflare
│   ├── 停止全部服务.bat
│   ├── 查看全部服务状态.bat
│   ├── 启动Cloudflare穿透.bat
│   ├── 停止Cloudflare穿透.bat
│   └── 查看Cloudflare穿透状态.bat
├── config/
│   └── cloudflare/
│       ├── tunnel.env             # Cloudflare 配置（Named/Quick Tunnel）
│       ├── tunnel.env.example     # 配置模板
│       └── README.txt             # Cloudflare 配置说明
├── openspec/
│   └── changes/sop-automation-v2/ # 当前迭代规划文档
│       ├── proposal.md
│       ├── design.md
│       └── tasks.md
├── docs/                          # 历史设计文档
├── migrations/                    # 数据库迁移脚本
├── logs/                          # 运行日志
├── 启动调试Chrome.bat              # ⭐ 启动含插件的调试 Chrome
├── run_server.py                  # ⭐ 启动后端服务（Windows兼容）
├── mvp.db                         # SQLite 本地数据库
├── requirements.txt               # Python 依赖
└── README.md                      # 本文件

---

五、主要 API 接口

方法	路径	说明
GET	/api/health	健康检查
POST	/api/v1/sourcing/domestic	国内货源信息录入，创建 Session
POST	/api/v1/amazon/audit	触发 Amazon 商品自动审计（CDP）
POST	/api/v1/amazon/search	Amazon 关键词搜索
POST	/api/v1/risk/analyze	品牌风险分析
POST	/api/v1/profit/roi	ROI 测算 v2（实时汇率 + 物流）
GET	/api/v1/exchange_rate	查询实时 USD→CNY 汇率
POST	/api/v1/domestic/reverse_search	国内反查（图搜+关键词+pHash）
POST	/api/v1/profit/calculate	利润测算（旧版兼容）
POST	/api/v1/profit/batch	多渠道利润批量对比
POST	/api/v1/category/check	品类合规性检查
GET	/api/v1/env/check	环境与浏览器状态检查

---

六、SOP 工作流程（10步）

A → B → C → D → E → F → G → H → I → J
选品  关键词  搜索  验证  风险  分析  利润  国内   决策  入库
起点  提取    AMZ   竞品  扫描  审计  ROI   反查

1. A 选品起点：录入国内货源（标题/价格/图片/关键词）
2. B 关键词提取：AI 生成 Amazon 英文搜索词
3. C Amazon 搜索：自动搜索，获取候选 ASIN 列表
4. D 商品验证：品类合规、价格区间校验
5. E 风险分析：5区域品牌词扫描，生成风险评分
6. F Amazon 审计：Playwright + 智赢插件，读取商标/FBM/卖家来源/上架天数
7. G 利润测算：实时汇率 + 燕文/云途物流报价 → ROI
8. H 国内反查：以图搜图 + 关键词搜索 → pHash 相似度匹配
9. I 人工决策：加入候选池 / 标记观察 / 放弃
10. J 结果入库：记录到 SQLite，可导出至 ERP

---

七、智赢插件读取说明

系统通过 CDP（Chrome DevTools Protocol） 连接真实 Chrome，读取智赢插件注入的 DOM 数据。

读取字段：

• 商标状态（Registered / Unregistered / Loading）
• 卖家来源（国旗 SVG 路径解析，如 /flags/CN.svg → 中国卖家）
• FBA / FBM 标识
• 商品上架天数（最新识别值）
• 价格（.a-offscreen 隐藏元素 textContent）

启动方式：

# 双击：启动调试Chrome.bat
# 等价命令：
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --profile-directory="CangbaogeDebug"

---

七.5 核心字段字典

以下字段在 candidate_products 表与 API 返回体中均可直接使用。

价格三件套（OpenSpec change: price-triple-with-zhiying-quotes）

字段	类型	含义	来源
listing_price_usd	REAL	挂牌价：Amazon PDP 当前售价	Amazon 抓取（与 current_price_usd 双写）
recommended_price_usd	REAL	推荐报价：竞品最低价（不含本 ASIN）	智赢库存监控 → min(quotes.price_usd)
minimum_price_usd	REAL	最低入场价：保 20 元利润所需最低售价	profit_calculator_v2 倒推

价格可行性（规则引擎输出）

字段	类型	含义
price_feasibility_level	TEXT	ok / warn / major / reject / inconclusive（无数据）
price_feasibility_ratio	REAL	(minimum − recommended) / recommended

档位（app/analysis/rule_engine_v2.py::evaluate_price_feasibility）：

level	条件（ratio）	打分	是否否决
ok	≤ 0	+5	否
warn	0 ~ 10%	−10	否
major	10% ~ 30%	−30	否
reject	> 30%	强制 0	是
inconclusive	缺少某一侧数据	0	否

竞品报价表 competitor_quotes（1:N 到 candidate_products）

字段	说明
product_id	外键 → candidate_products.id
rank	在"库存监控"面板中的顺序
seller_name	卖家名称（留空 = 本 ASIN）
price_usd	该卖家挂牌价（USD）
quantity	库存数量（可能为空）
is_current_asin	0/1，是否为当前 ASIN 自己
raw_text	原始行文本，便于排错

相关 API

• GET /api/v1/candidates?feasibility_level=ok,warn 按可行性多选筛选
• GET /api/v1/candidates/{id}/competitor_quotes 读竞品报价
• 启动环境变量 ENABLE_PRICE_FEASIBILITY=0 可关闭该维度（默认开启）

---

八、ROI 计算公式

收入(CNY)  = Amazon售价(USD) × 汇率 × 0.75（固定系数）
佣金(CNY)  = Amazon售价(USD) × 15% × 汇率
成本(CNY)  = 采购价 + 运费 + 佣金 + FBA费用
净利润(CNY) = 收入 - 成本
净利润率   = 净利润 / 收入 × 100%
最低入场价(USD) = (采购价 + 运费 + 最低利润¥20) ÷ (汇率 × 0.75 × 0.85)
建议售价(USD)   = 最低入场价 × 1.2

物流报价规则（燕文/云途）：

渠道	0.3kg 参考价	时效
云途经济	¥18	18-30工作日
燕文挂号小包	¥20	15-25工作日
云途标准	¥25	10-18工作日

---

九、服务管理

# 启动后端
python run_server.py

# 服务管理（统一入口）
python scripts/service_manager.py backend-start
python scripts/service_manager.py backend-stop
python scripts/service_manager.py backend-status
python scripts/service_manager.py all-start      # 后端 + Cloudflare
python scripts/service_manager.py all-stop
python scripts/service_manager.py all-status

---

十、依赖安装

pip install -r requirements.txt
playwright install chromium

主要依赖：

• fastapi uvicorn httpx playwright
• beautifulsoup4 pillow imagehash
• sqlalchemy pydantic

---

📁 迭代规划文档：openspec/changes/sop-automation-v2/tasks.md
📋 设计方案文档：openspec/changes/sop-automation-v2/design.md
🐞 问题追踪：见 docs/ 目录历史报告