Metadata-Version: 2.4
Name: walmart-keyword
Version: 0.1.2
Summary: 沃尔玛关键词排名监控工具 - 自动监控 Young Electric 产品搜索排名
Project-URL: Homepage, https://github.com/yourusername/walmart-keyword
Project-URL: Repository, https://github.com/yourusername/walmart-keyword
Author: Leo
License: MIT
License-File: LICENSE
Keywords: dingtalk,keyword-ranking,spider,walmart
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.9
Requires-Dist: alibabacloud-dingtalk>=2.0.0
Requires-Dist: croniter>=2.0.0
Requires-Dist: dingtalkchatbot>=1.5.0
Requires-Dist: drissionpage>=4.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 沃尔玛关键词排名监控工具

每天定时从钉钉表格读取关键词，搜索沃尔玛并提取 Young Electric 产品的广告和自然排名，结果写回钉钉表格。

## 功能特性

- 定时任务自动执行（支持 Cron 表达式）
- 从钉钉表格读取关键词分组和 SKU 映射
- 自动搜索 Walmart 并提取排名
- 区分广告排名（Sponsored）和自然排名
- 智能防爬验证处理（Logo点击、验证码、按住验证等）
- 排名数据按关键词分组写回钉钉表格
- 钉钉机器人通知（启动/完成/异常）
- 失败关键词自动重试
- 多实例并发支持

## 快速开始

### 1. 安装

```bash
# 使用 uvx 一键运行（推荐）
uvx walmart-keyword

# 或使用 pip 安装
pip install walmart-keyword

# 或克隆项目手动安装
git clone <repo-url>
cd WalmartKeyword
pip install -e .
```

### 2. 配置

复制 `.env-example` 为 `.env`，填入配置：

```bash
cp .env-example .env
```

**必填配置项：**

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `CRON_EXPRESSION` | 定时任务表达式 | `0 8 * * *`（每天8点） |
| `DINGTALK_WEBHOOK` | 钉钉机器人 Webhook | `https://oapi.dingtalk.com/robot/send?access_token=...` |
| `DINGTALK_SECRET` | 钉钉机器人密钥 | `SECxxxx` |
| `DINGTALK_DOC_URL` | 钉钉表格链接 | `https://alidocs.dingtalk.com/i/nodes/xxx` |
| `DINGTALK_APP_KEY` | 钉钉应用 AppKey | `dingxxxx` |
| `DINGTALK_APP_SECRET` | 钉钉应用 AppSecret | `xxxx` |
| `DINGTALK_OPERATOR_ID` | 操作人 UnionId | `xxxx` |
| `KEYWORD_SHEET_NAME` | 关键词工作表名 | `关键词` |
| `SKU_MAPPING_SHEET_NAME` | SKU映射工作表名 | `SKU映射表` |

**可选配置项：**

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `WALMART_ZIP_CODE` | Walmart 位置邮编 | 空 |
| `DINGTALK_AT_MOBILES` | @指定人员手机号 | 空 |
| `CHROME_USER_DATA_PATH` | Chrome 用户数据目录 | 空（自动管理） |
| `RATE_LIMIT_PER_MINUTE` | 每分钟请求限制 | `15` |
| `RATE_LIMIT_PER_HOUR` | 每小时请求限制 | `500` |
| `PROXY_ENABLED` | 是否启用代理 | `false` |
| `PROXY_POOL` | 代理地址池 | 空 |

### 3. 运行

```bash
# 首次运行：设置 Walmart 配送位置
walmart-keyword --setup
# 或
wkm --setup

# 单次执行模式
walmart-keyword --once
wkm --once

# 定时任务模式（默认）
walmart-keyword
wkm
```

## 钉钉表格结构

### 关键词 Sheet

| 行 | A列 | B列 | C列 | ... |
|----|-----|-----|-----|-----|
| 1 | Bike Rack | Power Jack | ... | 关键词组名 |
| 2 | bicycles rack | power jack | ... | 关键词 |
| 3+ | bike rack for hitch | ... | ... | 关键词 |

### 排名结果 Sheet（以 Bike Rack 为例）

每个关键词占 4 列（B~E 为第一个关键词，F~I 为第二个，依次类推）：

- 第1列：广告排名位置（如 `1&2`）
- 第2列：广告 SKU（如 `SKU1/SKU2`）
- 第3列：自然排名位置
- 第4列：自然 SKU

### SKU映射表 Sheet

将 `data-dca-id` 映射为可读的 SKU 编号。

## 多实例运行

```bash
# Windows CMD
set INSTANCE_ID=0 && walmart-keyword --once   # 端口 9333
set INSTANCE_ID=1 && walmart-keyword --once   # 端口 9334

# Windows PowerShell
$env:INSTANCE_ID=1; walmart-keyword --once

# Linux/macOS
INSTANCE_ID=1 walmart-keyword --once
```

## 目录结构

```
WalmartKeyword/
├── app/
│   ├── cli.py                       # 入口（定时任务/单次执行/位置设置）
│   ├── config.py                    # 配置管理
│   ├── notifier.py                  # 钉钉通知
│   ├── dingtalk_doc_reader.py       # 钉钉文档API
│   ├── models/
│   │   └── ranking_result.py        # 排名结果模型
│   ├── readers/
│   │   ├── keyword_reader.py        # 关键词读取器
│   │   └── sku_mapping_reader.py    # SKU映射读取器
│   ├── recorders/
│   │   └── ranking_recorder.py      # 排名记录器（写入钉钉表格）
│   ├── selectors/
│   │   ├── walmart_selectors.py     # 页面选择器
│   │   └── walmart_search_selectors.py  # 搜索页选择器
│   ├── spiders/
│   │   ├── base_spider.py           # 爬虫基类
│   │   ├── walmart_search_spider.py # 搜索排名爬虫
│   │   └── walmart_bot_handler.py   # 防爬处理器
│   └── utils/
│       ├── rate_limiter.py          # 频率限制
│       └── behavior_simulator.py    # 人类行为模拟
├── data/                            # 数据目录（日志、浏览器数据、备份）
├── run.py                           # 启动脚本
├── .env-example                     # 配置示例
└── pyproject.toml                   # 项目配置
```

## 技术栈

- **Python** >= 3.9
- **DrissionPage** - 浏览器自动化
- **alibabacloud-dingtalk** - 钉钉文档 API
- **dingtalkchatbot** - 钉钉通知
- **croniter** - 定时任务

## License

MIT
