# KB-AMAZON-001：Amazon US 产品详情与父子 ASIN 采集

| 项目 | 内容 |
|---|---|
| 平台/站点 | Amazon 美国站 `www.amazon.com` |
| 页面 | 商品详情页 `/dp/{ASIN}`、`/gp/product/{ASIN}` |
| 对应 Tool | `amazon_collect_product_detail` |
| 对应脚本 | `amazon-product-detail-collector.user.js` 1.0.0 |
| 字段 | 父/子 ASIN、当前变体、标题、品牌、卖点、描述、价格、评分、Review、排名、Coupon、库存/配送/退货提示、图片、A+、概览和详情 |
| 整理日期 | 2026-09-14 |
| 当前证据等级 | 真实 Amazon 页面选择器与 twister 数据 + 脱敏快照 + 合成 DOM/生成脚本测试；真实飞书写入尚未实测 |

## 1. 不能越过的证据边界

仓库样本位于 `tests/fixtures/amazon-us-product-detail/`：合成脱敏样本明确标为 `static_fixture_only`；`live-variant-2026-09-12.json` 来自真实浏览器页面，只保留字段相关 selector 快照和变体切换值，不含账号、Cookie 或完整 DOM。

真实验证仍不能证明 Amazon 所有账号、地区和 A/B 页面都采用相同 DOM。脚本只返回页面当前明确披露的字段；缺失值用 `null`、空数组或空对象表示，不用 0 或猜测值补齐。

## 2. 字段语义与提取顺序

### 当前选中变体 ASIN

优先读取变体区被选中节点的 `data-defaultasin` 或 `data-csa-c-asin`，再回退到 `input#ASIN` / `#ASIN` 的值，最后从 `/dp/` 或 `/gp/product/` URL 提取。只接受 10 位字母数字。

“当前选中”不能简单等同于初始 URL ASIN；切换变体后 DOM 属性优先级高于 URL。Tool 若收到期望 ASIN且与当前结果不一致，必须报错，不能返回另一个变体。

### 标题

优先读取 `#productTitle`，回退到 `meta[property="og:title"]`。合并空白并保留可见文本；没有标题时页面不满足最小商品证据，任务失败。

### 价格和币种

只在核心购买区的价格节点中按保守顺序查找，不使用全页 `.a-price`，以免误取推荐商品价格。真实页面表明 `www.amazon.com` 会随配送/币种偏好显示 `CNY308.45`，切换变体后可显示 `$39.99`；因此不能把美国站硬编码成 USD。解析器按页面明确的 USD/CNY/CAD/AUD/EUR/GBP/JPY/INR 代码返回币种，明确 `$` / `US$` 时返回 USD。

页面无报价、价格节点缺失或文本没有明确币种标记时，`price` 和 `currency` 返回 `null`，同时列入 `missing_fields`；不得返回 `0`。`0` 是真实数值，不是缺失值替代品。

### 父 ASIN、子 ASIN 与变体属性

解析器只从商品页 `twister-js-init-dpx-data` 中的 `parentAsin`、`currentAsin`、`dimensions`、`variationDisplayLabels` 和 `dimensionValuesDisplayData` 读取父子关系。返回的 `variations` 包含子 ASIN、Size/Color 等属性和当前选中状态；页面未披露完整关系时不猜测。

父页的 twister 数据能列出子 ASIN 和变体属性，但不能证明每个子 ASIN 自己的标题、卖点、图片和价格。如果用户要“每个 ASIN 的页面信息”，应先运行一次取得 `variations[].asin`，再由 SellerFeeds 批量展开，让每个子 ASIN 独立运行同一 Tool。这样每行都有自己的页面证据，也能控制请求数和续跑范围。

### 其他页面字段

- 品牌来自 byline、商品概览或详情表。
- 卖点来自 `About this item` 列表；商品描述、A+ 文字和 A+ 图片分开返回。
- 评分、Review/Rating 数量、Best Sellers Rank、Coupon、库存文案、配送信息和高退货提示都是当次页面快照，不是历史数据。
- 主图优先取 `data-old-hires` 或动态图片元数据中的高分辨率 URL；附图和 A+ 图片去重后返回。
- `product_overview` 和 `product_details` 保留页面键值表，因商品类目不同，键名是动态的。

### 飞书回传和机器人通知

飞书不是采集必要条件。`baseUrl` 和 `baseToken` 都留空时只返回采集结果，不请求飞书；只填一项时在采集前拒绝；两项完整时每个实际采集的 ASIN 追加一行，并在权限允许时自动创建缺失文本列。

成功写表且有有效 `table_url` 时，飞书机器人发送报告文件，摘要可附带多维表格链接。写入失败时返回 `output_error`，保留采集结果；任务中心和 MCP 的 JSON、Excel、Markdown 下载不受影响。

## 3. 页面状态与等待

`page` Tool 初次解析缺少 ASIN/标题时，使用 MutationObserver 最多等待 10 秒；页面卡片对变体相关 DOM 变化做 180ms 防抖刷新。出现标题 `Robot Check`、`#captchacharacters` 或验证表单时标记 `challenge` 并失败。

下列情况当前不保证：地区配送或登录弹窗遮挡、优惠券后的到手价、Subscribe & Save、Deal 多价格、二手/多卖家报价、逗号小数等本地化数字格式、Amazon A/B 新布局。遇到这些页面需补充证据后扩展解析器。

## 4. 已复现结果

- 选中变体样本：从变体属性得到 `B0VARI2345`，标题为 `Sample USB-C Hub`，价格 `29.99`，币种 `USD`。
- 缺失价格样本：ASIN 和标题可用，价格与币种为 `null`，`missing_fields` 包含两项。
- Robot Check 样本：抛出 `AMAZON_CHALLENGE`，不作为商品结果。
- 页面助手源码测试：复制处理器中没有飞书函数；Tool 的关闭分支位于读取飞书配置和写入之前；包含重复挂载清理与 observer 断开。
- 真实页面：`B07NHW8Z3N` 选择 Black Pack 后，URL 与 `input#ASIN` 更新为 `B08GJ8MW12`；核心价格节点更新为 `$39.99`。此前初始选择价格为 `CNY308.45`，证明币种需读取页面而非按站点猜测。
- 2026-09-14 真实页面：`B0D9VTFCBK` 的 twister 数据披露父 ASIN `B0D9VVS7RG`、Size/Color 维度和 243 个子体；另一真实商品页可见标题、About this item、主图、概览和详情区。这只证明当时页面结构，不是 Amazon 公开 API 承诺。

运行 `node --test tests/amazon-product-detail.test.mjs` 可复现解析断言。真实浏览器验证截图保存在本地 `output/playwright/amazon-us-variant-b08gj8mw12-2026-09-12.png`；测试中的 live selector 快照可随 Git 追溯。该实测仅证明上述字段和一次变体切换，不等同于扩展端到端安装验收。

## 5. 实际页面需要补充什么

对未覆盖或改版页面，请提供可公开使用的 URL、站点/地区、登录状态、当前变体、脱敏的商品区 DOM 或页面诊断，以及人工看到的预期字段。不要提供 Cookie、登录凭据、PersonalBaseToken 或订单隐私数据。