linkfox-seerfar-ozon-category-search

Seerfar Ozon 类目商品搜索是一个面向 Ozon 平台的类目级商品数据查询技能，数据来源于 Seerfar 分析数据库。给定一个 categoryId，它会返回该类目的商品列表及表现指标，同时附带类目级聚合数据，是类目选品分析、类目爆品挖掘、类目容量与价格带分析的起点。

一、用途 本技能用于分析单个 Ozon 类目的商品与聚合数据，典型场景包括：类目规模评估（总销量、总销售额、平均价格）、类目最畅销商品挖掘（按销量排序）、类目销售额最高商品（按销售额排序）、类目价格带/客单价分析（按价格排序）、类目评分最高商品（按评分排序）、类目历史月份数据对比、按配送方式筛选商品。

二、主要能力

1. 类目级聚合：返回 totalSales（总销量）、totalRevenue（总销售额）、avgPrice（平均价格）、rating（评分）、seasonalityAmplitude 与 seasonalityCoef（季节性）、startDate/endDate（数据时间范围）。
2. 商品级明细：分页返回每个商品的 sku、标题、价格、销量、销售额、评分、评论数、品牌、卖家、配送方式等。
3. 排序与分页：通过 page.orders 指定排序字段（sales、price、revenue、reviewRating）与方向（DESC/ASC）；page.page 翻页，page.pageSize 默认 20、最大 20。
4. 历史月份查询：date 参数传 yyyy-MM（如 2026-02）查询历史月份快照，省略则默认最近 30 天。
5. 配送方式筛选：fulfillment 参数可选 FBO / FBS / RFBS / FBP / OZON，省略则查询全部。

三、使用方式

1. API 端点：POST /seerfar/ozon/categorySearch（完整参数、响应与错误码见 references/api.md）。
2. Python 脚本：python scripts/seerfar_ozon_category_search.py '<JSON 参数>' [--inline]。
3. 必填参数：categoryId 与 page。categoryId 为 Ozon 类目标识，层级用 _ 连接（如 15621032_15621049_115951147），可从 Ozon 类目文档或其他 Seerfar Ozon 工具获取；若用户只有类目名称，需先从上游 Seerfar Ozon 来源解析为 categoryId。
4. 可选参数：page.page（页码，默认 1）、page.pageSize（默认 20，最大 20）、page.orders（排序规则数组，元素含 field 与 direction）、date（历史月份 yyyy-MM）、fulfillment（单个字符串）、uId、memberId。
5. 输出策略：脚本始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-category-search-<timestamp>.json；响应体 ≤ 8 KB 时完整 JSON 打印到 stdout，> 8 KB 时只输出摘要；加 --inline 可强制全量打印。建议先看摘要，再用 jq 或 ConvertFrom-Json 从保存的 json 文件按需抽取字段。
6. 成本约束：本工具消耗算力，同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存；失败或空结果不得自动换关键词、翻页或改邮编连续试探，需要继续检索时应先向用户说明会产生额外消耗。每次调用消耗 15 算力，用户会因算力消耗而支付费用，高频调用或用户对消耗预期不足时需提醒用户。

四、适用场景 适用于已有 categoryId（或已从上游解析出 categoryId），并希望按销量、价格、评分等对该类目商品进行枚举、排序或规模评估的情况。若需要单个店铺/卖家的商品目录、市场级关键词发现、关键词挖掘或单个商品的完整详情，则应改用对应的 Seerfar Ozon 技能。

五、限制

1. categoryId 与 page 均为必填，缺任一项返回 errcode 400。
2. pageSize 最大 20，超出返回 errcode 1002。
3. 不支持类目内文本/关键词过滤，仅按类目（及可选 fulfillment、date）筛选。
4. total 为当前页行数，并非类目商品总数，需用 hasNextPage 判断是否还有更多页。
5. sellerType 实际是配送方式分布（FBO、RFBS、FBP、FBS、OZON 的商品数量映射），不包含本土/跨境信息；categoryInfo 携带类目名称路径（中/英/俄）与 crossBorderSellable。
6. 价格与销售额单位为俄罗斯卢布（₽）。
7. 不存在的 categoryId 会返回成功但 total=0 且无数据，应提示用户 id 可能有误，而非报告系统错误。
8. 认证与算力异常（未配置 API Key、401/402、算力或余额不足等）需按 references/onboarding.md 引导解决。

六、展示规则 仅呈现数据，不做主观建议。先给出类目上下文（类目名称、totalSales、totalRevenue、avgPrice、rating、季节性、时间范围及配送方式分布），再列出商品表格（sku、标题、价格、销量、销售额、评分、评论数、品牌、卖家）。价格与销售额以卢布符号呈现；fulfillment 为数组，多值用 / 连接；productId/rating/brand/monthlySalesUnits/monthlySalesRevenue/productPageUrl 与 sku/reviewRating/brandName/sales/revenue/productUrl 为镜像字段，展示一组即可，优先使用原始字段。hasNextPage 为 true 时提示用户可通过 page.page 翻页，并提醒 pageSize 上限为 20。