# Keepa 扩采集需求单（SaaS → 采集侧）— 2026-09-26

**移交对象**：mercury（104.194.81.222）采集侧维护人
**提出方**：SaaS（mars）——本文档只定义需求与验收，不含采集侧实现
**背景**：用户指令「去 keepa 网站照抄 Keepa 所有筛选条件」。官网 productFinder 页为 JS 空壳无法抓取，用户随后上传 5 张 Keepa 页面 PDF 作为权威源（已存档 `/opt/saas/workspace/zipforce-hub/keepa-ui-archive/`，含 5 份逐字文本 + PNG，可追溯）。对照库内 `aba_keepa_full` 43 列：**≈25 项核心筛选已支持**（类目可读化/BSR 当前+90均+drops/四价格当前值/BuyBox 自营FBA/报价数/缺货/月销/评分评论/FBA费/重量/批量ASIN/CSV/排序/排除词——排除词为库独有增强），本单列出**无数据的 90+ 项**。

**命名声明（铁律：不猜）**：PDF 为中文 locale UI 存档，本单全部用 **UI 原文逐字**（中文）列项。落地时的英文列名/API 参数名**以 Keepa 官方 API 文档（keepa.com/api → Product Finder / Product 参数节）为准**，采集侧核对后命名，本单不提供猜测的英文名。库内已有命名惯例（如 `sales_rank_drops_30`）可作同族参照。

**优先级依据**：P0=直接影响选品决策核心维度；P1=竞品分析常用；P2=长尾增强。

---

## R1（P0）价格/排行窗口族 —— 库内只有当前值

Keepa 每个价格类型提供 9 个窗口变体，库内 `price_*_current` 仅存当前值（BSR 已有 90 天均值与 drops30-365，是唯一例外）。

- **价格 30/90/180/365 天平均值**（6 价格类型：Amazon / 全新品 / 非全新品 / Used / List / 收藏品价）
- **价格 1/7/30/90 天下降 %**（同 6 价格类型）
- **BSR 30/180/365 天平均值**（库已有 90 天均值；Keepa 榜单页另有 30/90/180 天平均档位）
- **报价类"上次更改"日期**：全新品计数 FBA / FBM / 非全新品 / 翻新品 / 收藏品 各自的上次更改日期
- **报价窗口均值**：总报价数 / 全新品计数的 目前/30/90/180/365 天平均值

## R2（P0）BuyBox（黄金购买框）统计族 —— 库内只有价格 + 两个布尔

- **卖家筛选**：All / Amazon / 第三方 / 特定卖家ID（库内仅 `buy_box_is_amazon` 布尔）
- **发货国家**（黄金购买框发货国家筛选）
- **7 项统计 × 30/90/180/365 天窗口**：% 亚马逊、% 畅销、获胜者计数、标准偏差、波动性、合格报价数量、顶级卖家ID
- **状态布尔**：不合格 / 预订 / 缺货待补 / Prime 专属 / Prime 资格 / 订阅并保存（各 全部/是/否）
- **二手 BuyBox 全套**：卖家（All / Amazon Warehouse / 第三方 / 卖家ID）、状况（非全新品-像新一样 / 非常好 / 好 / 可以）、是否FBA
- **BuyBox 缺货 / 被抑制**（30 / 90 天）

## R3（P1）卖家维度整块 —— 库内完全没有卖家数据

对应 Keepa 两整页工具（热销商家列表 / 卖家查询），`aba_keepa_full` 为产品维度无卖家表。

- **卖家筛选字段**：卖家ID（含"包含历史报价"开关）、卖家ID FBA、卖家ID FBM、最低 FBA 卖家、最低 FBM 卖家
- **热销商家列表（卖家榜）**：名称、评分、评分数量、黄金购买框占有情况（使用期限 / 30 / 90 / 365 天）、主要销售（全新品 / 非全新品）、使用FBA %、经过验证的列表、类别、品牌、卖家 ID、国家 —— PDF 实测 1000 行/页
- **卖家查询索引**：按 卖家名称 / 卖家ID / 增值税号 / 工商登记号 / 电子邮箱 / 地址 搜索（页面标注：此商城可搜索卖家 1,769,628 个，活跃 825,878）

## R4（P1）产品属性族 —— "是以下之一"多值筛选，库内无列

主类别/子类别层级、PartNumber、品牌店铺名称、品牌店铺URL名称、单元详细信息 单元类型、香味、产品形式、图案、风格、材料、目标受众、版本、格式、作者、捆绑、语言、网站显示组 标识符、**UPC / EAN / GTIN / 代码前缀**（产品查看器加载入口）、子类别（类目树深层级——库内只有 root + reference/display_group 两级）

## R5（P1）布尔/合规族 —— 各 全部/是/否 三态

是否为 Amazon Renewed、有主视频、有A+内容、来自制造商的A+、是否需要电池、是否包含电池、是否危险品、对热敏感、成人用品、是 Merch on Demand、产品类型（实物产品 / 数字产品 / 电子书）

## R6（P2）变体/媒体

变体（All / 无变体 / 是变体 + "每个产品只显示一个变体"开关；库内有 parent_asin 可派生部分）、变体计数、图片计数、视频数量

## R7（P2）日期族

最后价格变动、追踪开始日期、上市时间、发行日期、发布日期（各 从/到 范围）

## R8（P2）销售/评论扩展

月度销售趋势、月销量日期（最后已知 / 峰值）、月销量（峰值）、销售排行下降 %、退货率（低/高）、评分 - 上次更改、评分数量 - 上次更改、评论 - 格式特定、90天缺货百分比 OOS%（库有绝对次数 `oos_amazon_*`，无百分比）

## R9（P2）优惠/促销族

优惠类型 13 枚举（PDF 原文逐字）：App Only / Clearance No Returns / Countdown Ends In / Early Access With Prime / Generic Offer Promo / Limited Time Deal / Prime Day / Prime Day Early / Prime Exclusive / Prime Selling Fast / Selling Fast / Special Event Sale / Unknown；一次性优惠券、商业折扣（直接减价 / 百分比）、订阅并保存 %

## R10（P2）尺寸/Amazon报价/其它

- **尺寸**：包裹 尺寸(cm³)/长度/宽度/高度(cm)、物品 尺寸(cm³)/长度/宽度/高度(cm)（库已有 item_weight / package_weight 两个重量）
- **Amazon 报价可用性**：无亚马逊报价 / 有库存且可发货 / 为预购 / "未知" / 已下单 / 发货延迟（+ 发货延迟 30/90 天计数）
- **其它**：经常一起购买（"指定一个ASIN以获取经常与其一起购买的产品"+ 计数）、最短延迟（天）、Total、物品数量、页数
- **Best Sellers List 专属**：月度销售趋势列、子类别销售排行、上个月购买、90天变化% 每月、历史记录月份锚点（如 Aug 2026）、每个产品只显示一个变体开关

---

## 验收（采集侧执行）

1. 每字段组落地 DB 列（`aba_keepa_full` 扩列或新表，RLS/租户隔离随库规约），Keepa 拉取链路（`keepa_product_full` → `UPSERT_FULL_SQL`）覆盖写入
2. 采集侧核对 Keepa API 文档确定字段英文名与取值域后，**回报 SaaS 一份字段映射表**（中文 UI 名 ↔ 英文列名 ↔ 取值域），SaaS 侧再接 explore fields/conds 下发
3. 覆盖率口径：落地后跑同窗口全量刷新，非空率按字段回报（预期属性族/布尔族非空率高，窗口族依赖历史积累需注明首采起点）
4. SaaS 侧复验：explore fields 元数据出现新字段 + conds 筛选命中 + 无数据字段在 UI 显式「无数据（需扩采集）」不显示误导 0

## 附：权威源

- `/opt/saas/workspace/zipforce-hub/keepa-ui-archive/产品搜索工具.txt`（4133 字符，筛选面板全量逐字）
- `热销商家列表.txt`（卖家榜列头+32行样本）/ `Best Sellers List.txt`（榜单列头+类目树39节点）/ `卖家查询.txt` / `产品查看.txt`
- 三档对照结论详见 `memory-longterm.md` 2026-09-26 续9 节

---

## 追记（2026-09-27）：英文参数名已从 Keepa 官方 UI 实测提取 —— 本单「命名声明」作废，改用下表

登录态遍历 Keepa（三轮，存档 `keepa-ui-archive/traverse*/`）+ 点开 Keepa 自带「显示API请求」弹层拿到**官方明文查询格式**，并用库内真 API key 验证 **HTTP 200 通过**。前文「英文参数名不提供猜测」的约束已解除——以下全部为实测值。

### 线格式（官方 UI 原样给出 + 真 key 验证）

```
GET https://api.keepa.com/query?key=<KEY>&domain=1&selection=<URL编码的JSON>
```

- `selection` 内：数值范围用后缀 **`_gte` / `_lte`**（如 `couponOneTimePercent_gte: 5`）；文本多值 OR = `###` 分隔字符串（Keepa UI 原文：「您可以输入多个值（最多50个）。使用 ### 分隔。每个值的作用类似于 OR 筛选器」——SaaS A 项 2026-09-26 已照抄）；`sort: [[字段,asc|desc],…]` 多级排序数组；`perPage` 最小 50（实测 3 报 400 "too small"）；`page` 0 基
- **响应**（gzip）：`asinList`（本页 ASIN 数组）+ `totalResults` + tokens 计量（实测 title=keyboard@.com → totalResults=1,286,300，50 ASIN/11 tokens/20ms）。产品明细需再用 `asinList` 调 `/product`
- UI 自动附加保鲜条件 `lastOffersUpdate_gte`（Keepa 分钟时间戳）

### 字段名实测表（DOM id 前缀 = widget 类型，去前缀 = selection 键名骨架）

- **widget 前缀**：`numberFrom-/numberTo-`（范围）`dateFrom-/dateTo-`（日期范围）`boolean-*-checkbox`（三态）`singleChoice-`（下拉）`text-`（文本）`textArray-`+`textArrayType-`（多值+匹配类型：是以下之一/不是以下任何一个/无数值/有数值/全部是）`autocomplete-`+`autocompleteType-`
- **29 个窗口族**（各 14 变体：current/avg30/avg90/avg180/avg365/deltaPercent1/7/30/90/isLowest/isLowest90/outOfStock/outOfStockPercentage90/lastPriceChange）：
  `SALES`(月销) `RATING`(评分) `COUNT_REVIEWS`(评论) `AMAZON`(亚马逊价) `NEW`(全新品) `NEW_FBA` `NEW_FBM_SHIPPING` `USED`(非全新) `USED_NEW_SHIPPING`(像新) `USED_VERY_GOOD_SHIPPING` `USED_GOOD_SHIPPING` `USED_ACCEPTABLE_SHIPPING` `REFURBISHED`(翻新) `COLLECTIBLE`(收藏) `LISTPRICE`(List价) `BUY_BOX_SHIPPING`(BuyBox含运费) `BUY_BOX_USED_SHIPPING`(二手BuyBox) `WAREHOUSE`(Amazon Warehouse) `LIGHTNING_DEAL`(秒杀价) `PRIME_EXCL`(Prime专属价) `EBAY_NEW_SHIPPING` `EBAY_USED_SHIPPING` `COUNT_NEW`(全新计数) `COUNT_NEW_FBA` `COUNT_NEW_FBM` `COUNT_USED` `COUNT_REFURBISHED` `COUNT_COLLECTIBLE`
- **105 个非窗口字段**（全表 `finder-field-names-unique.txt`，节选关键）：
  - BuyBox 统计：`buyBoxStatsAmazon{30,90,180,365}`(%亚马逊) `buyBoxStatsSellerCount*`(获胜者计数) `buyBoxStatsTopSeller*`/`buyBoxStatsTopSellerId*`(顶级卖家) `buyBoxStandardDeviation{30,90,365}` `buyBoxEligibleOfferCounts.0~3`(合格报价: NEW_FBA/NEW_FBM/USED_FBA/USED_FBM) `buyBoxShippingCountry`(发货国家)
  - 销量族：`monthlySold` `monthlySoldLastKnown(+Date)` `monthlySoldPeak(+Date)` `deltaPercent90_monthlySold` `salesRankDrops{30,90,180,365}` `srAvg`+`srAvgMonth` `classificationRank` `rootCategory` `categories`/`categories_exclude` `classificationCategories` `salesRankDisplayGroup`(Name)
  - 优惠：`couponOneTimeAbsolute/Percent` `couponSNSPercent` `businessDiscount` `LIGHTNING_DEAL`(族内) `fbaFees` `flipability{30,90,365}`
  - 卖家：`sellerIds(+FBA/FBM/LowestFBA/LowestFBM)`(textArray×5, 含「包含历史报价」开关=historicalSellerIds) `totalOfferCount`
  - 尺寸/重量：`packageDimension/Length/Width/Height/Weight` `itemDimension/Length/Width/Height/Weight`
  - 日期：`lastPriceChange` `listedSince` `trackingSince` `releaseDate` `publicationDate`
  - 属性：`title` `brand` `brandStoreName` `brandStoreUrlName` `manufacturer` `model` `color` `size` `scent` `style` `pattern` `material` `itemForm` `itemTypeKeyword` `targetAudienceKeyword` `author` `edition` `format` `languages` `binding` `type` `unitCount.unitType` `numberOfItems` `numberOfPages` `partNumber`(=PartNumber)
  - 布尔/合规（三态全在 DOM）：`isAmazonReneweded` 类——Renewed/主视频/A+内容/制造商A+/需电池/含电池/危险品/对热敏感/成人用品/Merch on Demand/产品类型(实物/数字/电子书)
  - 变体/媒体：`singleVariation`(每产品一变体开关) `variationCount` `imageCount` `videoCount`
  - 其它：`frequentlyBoughtTogetherFilter`(指定ASIN+计数) `availabilityAmazonDelay`(最短延迟天) `outOfStockCountAmazon{30,90}` `allowOutdatedOfferData`(允许过期价格)
- **排序可用键**（UI 内建排序）：`current_SALES` `monthlySold` 等 —— 形如 `current_<窗口族>` / 裸字段名

### 采集侧回报要求（更新）

原验收第 2 条「回报字段映射表」简化：**英文键名直接抄上表/DOM 全表**（`finder-field-ids-full.txt` 1486 个控件逐条），采集侧只需回报「哪些字段已落库 + 非空率」。

### 佐证文件

- `keepa-ui-archive/traverse/`（15 路由截图+DOM）/ `traverse2/`（WS 通道证实 push.keepa.com 二进制） / `traverse3/`（筛选填值→「显示API请求」明文→「查找产品」真实查询 4,599 命中截图）
- `keepa-ui-archive/finder-field-ids-full.txt`（1486 控件）/ `finder-field-names-unique.txt`（429 唯一字段名）
- `/tmp/keepa-query-sample.json`（真 key /query 200 响应样本，容器内）
