walmart-monitor 0.1.6

Walmart/Amazon 商品监控系统 - 支持多站点商品状态检测和钉钉通知

Walmart/Amazon 双平台商品监控系统

一个基于 FastAPI 的商品监控系统，支持 Walmart 和 Amazon 双平台商品状态检测，使用 DrissionPage 进行页面检测，并通过钉钉机器人发送异常通知。

文档导航

文档	说明
配置指南	环境变量和系统配置详解
重试机制	三轮重试逻辑详解
钉钉集成	钉钉文档读取和通知配置
邮编功能	多站点邮编自动设置指南
通知格式	钉钉通知消息格式说明
优化说明	DrissionPage 爬虫优化总结
打包发布	PyPI 打包与发布指南

---

项目概述

本系统主要用于监控 Walmart 和 Amazon 商品页面的状态，包括：

• 双平台支持: Walmart + Amazon 商品监控
• 商品库存状态检测
• 购物车按钮可用性检测
• 价格监控
• 异常情况实时通知（支持 @指定人员）
• 支持多店铺配置
• 支持钉钉文档集成
• 支持 18+ 个 Amazon 站点
• 终端进度显示（CLI/定时任务模式）

运行模式

系统支持 5 种运行模式：

模式	环境变量	说明	终端UI
web	RUN_MODE=web	uvicorn Web 服务（默认）	不支持
cli	RUN_MODE=cli	单平台单次执行	支持
cli-dual	RUN_MODE=cli-dual	双平台单次执行	支持
scheduler	RUN_MODE=scheduler	单平台定时任务	支持
scheduler-dual	RUN_MODE=scheduler-dual	双平台定时任务	支持

# Web 服务模式（默认）
RUN_MODE=web python run.py

# 单平台 CLI 执行
RUN_MODE=cli python run.py

# 双平台 CLI 执行（推荐）
RUN_MODE=cli-dual python run.py

# 单平台定时任务
RUN_MODE=scheduler CRON_EXPRESSION="0 */2 * * *" python run.py

# 双平台定时任务（推荐）
RUN_MODE=scheduler-dual CRON_EXPRESSION="0 */2 * * *" python run.py

技术架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   FastAPI       │    │   DrissionPage   │    │   钉钉机器人     │
│   Web 接口      │───▶│   浏览器自动化    │───▶│   异常通知      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │
         ▼                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Amazon SP-API  │    │   Chrome 浏览器   │    │   终端进度UI    │
│  商品数据获取    │    │   页面检测       │    │   Rich 分屏     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

核心技术栈

• Web框架: FastAPI
• 浏览器自动化: DrissionPage
• Amazon API: python-Amazon-sp-api
• 通知系统: dingtalkchatbot + alibabacloud-dingtalk
• 终端UI: Rich (分屏进度显示)
• 定时任务: croniter
• 配置管理: python-dotenv

---

快速开始

方式一：uvx 一键运行（推荐）

无需安装，直接运行：

# 安装 uv（如果还没有）
# Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

# 一键运行（需要先配置 .env 文件）
uvx walmart-monitor

# 或使用简写
uvx wm

配置文件位置（按优先级）：

./.env                             # 当前目录
~/.walmart-monitor/.env            # 用户主目录

方式二：pip 安装

pip install walmart-monitor
walmart-monitor

方式三：从源码运行

1. 安装依赖

pip install -r requirements.txt

2. 配置环境

copy .env-example .env
# 编辑 .env 文件，填入你的配置

详细配置说明请参考 配置指南

3. 启动服务

# 推荐：使用统一入口
python run.py

# 或直接启动 Web 服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

4. 访问接口

打开浏览器访问 http://localhost:8000/docs 查看 API 文档

---

环境变量配置

核心配置

# 运行模式
RUN_MODE=cli-dual

# 定时任务 Cron 表达式
CRON_EXPRESSION=0 */2 * * *

# 钉钉通知
DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=xxx
DINGTALK_SECRET=SECxxx

# 钉钉 @ 指定人员（多个用逗号分隔，为空则 @所有人）
DINGTALK_AT_MOBILES=13800138000,13900139000

# 数据源 Sheet 列表
DATA_SHEETS=WM-FIT,WM-Uriah

完整配置请参考 .env-example 文件。

---

API 接口

接口	方法	说明
/get-all-product-urls	POST	从 SP-API 获取商品链接
/test-dingtalk	GET	测试钉钉文档连接
/process	POST	执行监控任务
/task/progress	GET	获取任务进度
/health	GET	健康检查

执行监控任务

# 从钉钉文档读取 URL（推荐）
curl -X POST http://localhost:8000/process

# 指定 URL 列表
curl -X POST http://localhost:8000/process \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.amazon.com/dp/B0DFP79LBL"]}'

---

项目结构

├── app/
│   ├── main.py              # FastAPI 主应用
│   ├── cli.py               # CLI 入口点（uvx 使用）
│   ├── config.py            # 配置管理
│   ├── spider.py            # 单平台爬虫核心逻辑
│   ├── spiders/             # 爬虫模块
│   │   ├── base_spider.py   # 基础爬虫类
│   │   ├── walmart_spider.py # Walmart 爬虫
│   │   └── dual_platform_spider.py # 双平台爬虫
│   ├── selectors/           # 选择器模块
│   │   ├── amazon_selectors.py
│   │   └── walmart_selectors.py
│   ├── readers/             # 数据读取模块
│   ├── recorders/           # 结果记录模块
│   ├── notifiers/           # 通知模块
│   ├── amazon_sp_api.py     # Amazon SP-API 客户端
│   ├── notifier.py          # 钉钉通知模块
│   ├── terminal_ui.py       # 终端进度显示模块
│   └── retry_strategy.py    # 重试策略模块
├── scripts/
│   └── publish.py           # 一键发布脚本
├── data/                    # 数据存储目录
├── docs/                    # 文档目录
├── run.py                   # 本地开发入口
├── pyproject.toml           # 包配置
├── .env-example             # 环境变量示例
└── requirements.txt         # 依赖包列表

---

打包发布

一键发布到 PyPI

# 发布补丁版本 (0.1.0 -> 0.1.1)
python scripts/publish.py patch

# 发布次版本 (0.1.0 -> 0.2.0)
python scripts/publish.py minor

# 发布主版本 (0.1.0 -> 1.0.0)
python scripts/publish.py major

可选参数

参数	说明
--dry-run	只构建不发布，用于测试
--test-pypi	发布到 TestPyPI 而非正式 PyPI
--no-git	跳过 git 提交和推送

详见 打包发布指南

---

主要功能

商品状态检测

• 库存检测: 识别商品是否有库存
• 购物车按钮检测: 检查 "Add to Cart" 按钮是否可用
• 价格监控: 检测商品价格变化
• 页面异常检测: 处理验证码、页面错误等情况
• 智能重试机制: 对失败的检测进行二次验证

通知系统

• 分级通知: 根据异常类型发送不同级别的通知
• 购物车异常: @指定人员或@所有人的紧急通知
• 库存异常: 普通通知
• 任务完成: 包含详细统计的完成报告
• 支持 @指定人员: 通过 DINGTALK_AT_MOBILES 配置

多站点支持

支持 18+ 个 Amazon 站点，自动根据 URL 设置对应邮编。详见 邮编功能

---

故障排除

Chrome 启动失败

• 检查 CHROME_USER_DATA_PATH 路径是否正确
• 运行 python test_chrome_config.py 验证配置

API 认证失败

• 验证 .env 文件中的 SP-API 凭证
• 检查 refresh_token 是否过期

钉钉通知失败

• 检查 DINGTALK_WEBHOOK 和 DINGTALK_SECRET
• 确认钉钉机器人有发送消息权限

更多问题请查看 配置指南

---

许可证

MIT License