# CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。

## 项目概述

Amazon 商品数据爬虫系统（Python）。采集 ASIN 详情、搜索词、卖家账号、BSR 排名等数据，覆盖多个亚马逊站点（us、uk、de、fr、es、it）。数据流：Amazon HTML → 解析 → Kafka → PostgreSQL/MySQL/Doris/StarRocks。

## 架构

### 模块职责

- `amazon_spider/` — 核心爬虫类。每个文件是一个独立爬虫（ASIN 详情、搜索词、卖家反馈等）。爬虫继承自 `Requests_param_val`（`utils/requests_param.py`），后者继承 `BaseUtils`。
- `amazon_save_db/` — 数据入库逻辑。接收解析后的数据，通过 `RemoteEngine` 写入 PostgreSQL/MySQL。
- `amazon_every_day_spider/` — 定时/日常任务：cookie 清理、类目下载、BSR 排名采集、Selenium 爬虫。
- `amazon_params/` — `params.py` 存放所有数据库连接配置（MySQL、PG、Doris、StarRocks、Redis）及表名映射。配置按 `platform.system()` 区分（Windows=内网，Linux=外网）。
- `amzon_parse_db_html/` — HTML 解析及 AI 分析（GPT 提示词脚本）。
- `threading_spider/` — 爬虫启动入口，通过 `multiprocessing.Process` 启动多进程。`Poll_site_spider.py` 是主要的编排模式。包含 `DolphinschedulerHelper` 用于触发海豚调度工作流。
- `utils/` — 公共工具：
  - `db_connect.py` → `BaseUtils` 类：所有 DB/Redis/Kafka 连接
  - `secure_db_client.py` → `RemoteEngine` / `get_remote_engine()`：基于 HTTP 的数据库代理客户端（替代直连 SQLAlchemy）
  - `requests_param.py` → `Requests_param_val`：cookie 管理、请求头组装、Amazon 页面校验、Kafka 发送
  - `asin_parse.py` → `ParseAsinUs`：基于 lxml 的 ASIN 详情 HTML 解析器
  - `user.py` → DolphinScheduler API 默认用户凭证
- `pyspark_job/` — Spark ETL 任务（独立于爬虫代码）

### 核心模式

- **继承链**：爬虫 → `Save_asin_detail`（存储层）→ `Requests_param_val` → `BaseUtils`。每个爬虫因此可访问数据库引擎、Redis、Kafka、cookie 及请求工具。
- **RemoteEngine 数据库访问**：数据库操作通过 HTTP 代理服务器（`secure_db_client.py`）。`get_remote_engine(site_name, db_type)` 返回 `RemoteEngine`，提供 `read_sql()`、`to_sql()`、`read_then_update()`、`begin()`（事务）。代理服务器地址在 `DEFAULT_SERVERS` 中。
- **多站点支持**：站点名（`us`、`uk`、`de`、`fr`、`es`、`it`）驱动表名（如 `{site}_asin_detail_month_2026`）、库名（`selection`、`selection_uk` 等）及 Amazon 域名。
- **表命名规则**：`{站点}_{表类型}_{周期}_{年份}` 或 `{站点}_{表类型}_{周期}_{日期}`，如 `us_asin_detail_month_2026_02`、`us_all_syn_st_day_2026_02_10`。
- **IP 轮换**：VPS 爬虫通过 PPPoE 重拨（`VPS_IP.py` → `pppoe_ip()`）在批次间切换 IP。`is_internet_available()` 在切换后检测网络连通性。
- **多进程执行**：`threading_spider/Poll_site_*.py` 脚本启动 N 个工作进程，跑完一批后切换 IP，循环执行。
- **Cookie 管理**：cookie 存储在 MySQL（`{site}_cookies` 表），加载到 `Queue`，逐请求消费。检测到中国邮编的 cookie 会被删除。
- **Kafka 主题命名**：如 `{site}_asin_detail_month_2026_{month}` 或 `asin_html_2026_{month}`，用于传输解析数据和原始 HTML。
- **工作流编排**：`DolphinschedulerHelper` 在爬虫批次完成后通过 REST API 触发海豚调度流程。
- **sys.path 处理**：几乎每个文件开头都有 `sys.path.append(os.path.dirname(sys.path[0]))` 以支持从项目根目录的跨模块导入。

## 运行脚本

脚本以 Python 文件直接运行，在 VPS 或本地机器上执行：

```bash
# 运行爬虫入口（示例）
python threading_spider/Poll_site_spider.py

# 必须从项目根目录运行，否则 sys.path 导入会失败
cd py_spider
python amazon_spider/asin_detail_pg.py
```

无构建步骤、无测试框架、无 linter 配置。脚本部署到 VPS 服务器，通过海豚调度或手动运行。

## 主要依赖库

- `curl_cffi` — 抗 TLS 指纹识别的 HTTP 请求（用于 `requests_param.py`）
- `lxml` / `etree` — HTML 解析
- `kafka-python` — Kafka 生产者
- `redis` — Redis 客户端
- `sqlalchemy` — 旧版数据库连接（正在被 `RemoteEngine` 替代）
- `orjson` — 高性能 JSON 序列化（用于数据库代理）
- `pandas` — 爬虫与数据库层之间的数据处理
- `func_timeout` — 爬虫函数超时控制

## 注意事项

- `amazon_params/params.py` 包含硬编码的数据库凭证，Windows（内网）和 Linux（外网）配置不同。
- `secure_db_client.py` 中的 `RemoteEngine` 是当前标准的数据库访问方式，旧的 SQLAlchemy 直连代码已注释保留。
- `Servers/` 目录和 `pyspark_job/` 是辅助模块，不属于核心爬虫流程。
