# 亚马逊全国家详情页标签监控工具：新版规格

## 1. 工具定位

新版工具不再定位为“批量查一次有没有标签”，而是定位为：

```text
按国家、按 ASIN/MSKU 持续检测 Amazon 详情页标签，并识别标签新增、减少、仍存在、持续无标签等状态变化。
```

核心价值：

- 发现新增高退货标签
- 发现新增高保留标签
- 发现标签消失
- 保留每次检测快照，便于追溯
- 支持跨 Amazon 站点统一监控

## 2. 支持站点

第一版建议支持以下站点：

| 国家 | 域名 | 内部代码 |
|---|---|---|
| 美国 | amazon.com | US |
| 加拿大 | amazon.ca | CA |
| 墨西哥 | amazon.com.mx | MX |
| 英国 | amazon.co.uk | UK |
| 德国 | amazon.de | DE |
| 法国 | amazon.fr | FR |
| 意大利 | amazon.it | IT |
| 西班牙 | amazon.es | ES |
| 荷兰 | amazon.nl | NL |
| 瑞典 | amazon.se | SE |
| 波兰 | amazon.pl | PL |
| 比利时 | amazon.com.be | BE |
| 土耳其 | amazon.com.tr | TR |
| 日本 | amazon.co.jp | JP |
| 澳洲 | amazon.com.au | AU |
| 新加坡 | amazon.sg | SG |
| 阿联酋 | amazon.ae | AE |
| 沙特 | amazon.sa | SA |
| 巴西 | amazon.com.br | BR |

URL 生成规则：

```text
https://www.{domain}/dp/{ASIN}
```

例外：

```text
US: https://www.amazon.com/dp/{ASIN}
UK: https://www.amazon.co.uk/dp/{ASIN}
JP: https://www.amazon.co.jp/dp/{ASIN}
```

如果用户提供完整详情页链接，则优先使用用户链接，并从域名反推国家。

## 3. 输入清单字段

文件：`亚马逊标签监控_输入清单模板.csv`

| 字段 | 必填 | 说明 |
|---|---|---|
| enabled | 是 | 是否启用，TRUE/FALSE |
| sku | 否 | 本地 SKU 或 MSKU |
| spu | 否 | SPU 或产品组 |
| asin | 是 | ASIN |
| country | 是 | 国家，如 美国、德国、日本 |
| product_url | 否 | 完整详情页链接；有链接时优先使用 |
| check_frequency | 否 | 检测频率，如 manual、daily、weekly |
| owner | 否 | 负责人 |
| note | 否 | 备注 |

## 4. 关键词配置

文件：`亚马逊标签监控_关键词配置模板.csv`

关键词不写死在代码里，全部放配置表，便于后续补充多语言表达。

| 字段 | 必填 | 说明 |
|---|---|---|
| country | 是 | 国家；ALL 表示全国家通用 |
| tag_type | 是 | high_return / high_retention / captcha |
| keyword | 是 | 页面文本命中关键词 |
| match_mode | 是 | contains / regex |
| enabled | 是 | TRUE/FALSE |
| note | 否 | 说明 |

第一版默认关键词：

| tag_type | keyword |
|---|---|
| high_return | Frequently returned |
| high_retention | usually keep this item |
| high_retention | Highly retained |
| captcha | triggered an automated robot |
| captcha | api-services-support@amazon.com |

## 5. 检测明细字段

文件：`亚马逊标签监控_检测明细模板.csv`

每一次检测都新增一行，不覆盖历史。

| 字段 | 说明 |
|---|---|
| batch_id | 检测批次 ID |
| checked_at | 检测时间 |
| sku | SKU / MSKU |
| spu | SPU |
| asin | ASIN |
| country | 国家 |
| request_url | 实际请求 URL |
| http_status | HTTP 状态码 |
| fetch_status | success / failed / blocked |
| tag_status | tagged / untagged / captcha / failed |
| tag_type | high_return / high_retention / none / captcha / unknown |
| tag_label | 展示给业务看的标签 |
| matched_keyword | 命中的关键词 |
| error_message | 错误信息 |
| response_elapsed_ms | 请求耗时 |
| raw_snapshot_path | 可选，保存 HTML 快照路径 |

## 6. 变化汇总字段

文件：`亚马逊标签监控_变化汇总模板.csv`

变化基于“本次有效结果”和“上一次有效结果”对比。

| 字段 | 说明 |
|---|---|
| batch_id | 当前批次 |
| sku | SKU / MSKU |
| spu | SPU |
| asin | ASIN |
| country | 国家 |
| previous_checked_at | 上次有效检测时间 |
| current_checked_at | 本次检测时间 |
| previous_tag_status | 上次标签状态 |
| current_tag_status | 本次标签状态 |
| previous_tag_type | 上次标签类型 |
| current_tag_type | 本次标签类型 |
| change_type | 变化类型 |
| action_level | 建议处理级别 |
| action_note | 建议动作 |

## 7. 变化类型口径

| change_type | 判定规则 | 业务含义 |
|---|---|---|
| new_high_return_tag | 上次无标签，本次高退货 | 新增高退货风险 |
| new_high_retention_tag | 上次无标签，本次高保留 | 新增高保留信号 |
| high_return_tag_removed | 上次高退货，本次无标签 | 高退货标签消失 |
| high_retention_tag_removed | 上次高保留，本次无标签 | 高保留标签消失 |
| tag_type_changed | 上次和本次都有标签，但类型不同 | 标签类型变化 |
| tag_still_exists | 上次和本次都有同类标签 | 标签仍存在 |
| still_untagged | 上次和本次都无标签 | 持续无标签 |
| first_seen_high_return | 没有历史，本次高退货 | 首次检测即高退货 |
| first_seen_high_retention | 没有历史，本次高保留 | 首次检测即高保留 |
| first_seen_untagged | 没有历史，本次无标签 | 首次检测无标签 |
| current_failed | 本次请求失败 | 不参与标签减少判断 |
| current_captcha | 本次验证码/机器人拦截 | 需要降低频率或更换请求方式 |

关键原则：

```text
请求失败、验证码、页面异常不应被当作“标签消失”。
```

只有本次结果明确为 `untagged`，且上次有效结果是某类标签，才判定为标签消失。

## 8. 请求与限速策略

默认策略：

| 参数 | 默认值 |
|---|---|
| 单请求超时 | 20 秒 |
| 单个站点请求间隔 | 5 到 12 秒随机 |
| 跨国家请求间隔 | 2 到 5 秒随机 |
| 单 URL 最大重试 | 1 次 |
| 连续验证码熔断 | 同国家 3 次 |
| 全局验证码熔断 | 全批次 5 次 |
| 连续请求失败熔断 | 同国家 5 次 |

请求头第一版沿用原工具基础配置：

```text
User-Agent: Chrome 桌面浏览器 UA
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8
Accept-Language: 按国家配置，默认 en-US,en;q=0.9
Connection: keep-alive
Upgrade-Insecure-Requests: 1
```

后续可扩展：

- Cookie
- 代理
- 国家级 Accept-Language
- HTML 快照保存
- 浏览器渲染模式

## 9. 结果判定流程

```text
读取输入清单
过滤 enabled = TRUE
标准化 ASIN、站点、URL
生成 batch_id

逐条请求详情页
    如果请求失败:
        写 failed
        不参与标签消失判断

    如果命中验证码关键词:
        写 captcha
        累计验证码计数
        达到阈值则站点熔断或全局停止

    如果命中 high_return 关键词:
        写 high_return

    否则如果命中 high_retention 关键词:
        写 high_retention

    否则:
        写 untagged

写入检测明细
读取上一条有效历史
生成变化汇总
导出本批次结果
```

## 10. 推荐实现形态

第一版推荐：本地 HTML + Node.js 后端。

原因：

- 便于导入 CSV/XLSX
- 便于展示进度、暂停、继续、停止
- 比 VBA 更适合跨平台
- 可以保存历史数据库
- 后续可加定时任务

数据存储建议：

- 轻量版：CSV 文件
- 稳定版：SQLite

第一版可以先用 CSV，确认口径后升级 SQLite。

## 11. 第一版交付范围

建议第一版只做这些：

- 导入输入清单 CSV
- 导入关键词配置 CSV
- 手动开始检测
- 支持全国家 URL 生成
- 支持串行请求和限速
- 输出检测明细 CSV
- 输出变化汇总 CSV
- 支持 HTML 页面查看本批次进度
- 支持停止任务

暂不做：

- 自动定时
- 登录态 Cookie 管理
- 代理池
- 浏览器渲染
- 云端部署

## 12. 验收标准

1. 同一个 ASIN + 站点，每次检测都保留历史，不覆盖旧数据
2. 能正确区分：
   - 新增标签
   - 标签消失
   - 标签仍存在
   - 持续无标签
   - 请求失败
   - 验证码
3. 请求失败和验证码不能误判为标签消失
4. 支持至少 美国、英国、德国、法国、意大利、西班牙、日本、加拿大、墨西哥、澳洲
5. 关键词可通过配置表新增，不需要改代码
6. 输出表能直接给运营查看和筛选