"""抓取侧 API 数据模型：请求体和响应体定义 字段命名贴合乐天站点自身的语义（item_code / shop_code / genre_id / sku 等）， 不做跨站点的字段名归一，避免解析层与对外契约之间反复翻译。 响应信封 `ApiResponse` 在 app/shared/api.py，与交易侧共用；登录态、订单等需要 账号的模型在 app/trading/models.py，不在这里。 """ from __future__ import annotations from enum import StrEnum from typing import Any from pydantic import BaseModel, Field, HttpUrl, model_validator class SortOption(StrEnum): """搜索排序方式，对应搜索页 `s=` 参数""" STANDARD = "standard" # 站点默认相关度排序 PRICE_ASC = "price_asc" PRICE_DESC = "price_desc" NEWEST = "newest" REVIEW_COUNT = "review_count" REVIEW_SCORE = "review_score" PRICE_WITH_SHIPPING_ASC = "price_with_shipping_asc" PRICE_WITH_SHIPPING_DESC = "price_with_shipping_desc" class ItemCondition(StrEnum): """商品成色筛选""" NEW = "new" USED = "used" RENTAL = "rental" class SearchRequest(BaseModel): """搜索请求参数 三种用法（优先级从高到低）： 1. 传 search_url：直接透传一条乐天搜索页 URL，服务端原样抓取， 此时除 page 与 exclude_ads 外的筛选字段全部忽略； page 若显式指定（>1），会覆盖 URL 中的页码。 2. 传 keyword（可叠加任意筛选字段） 3. 只传 genre_id：抓取该分类下的商品 """ keyword: str = Field(default="", description="搜索关键词") page: int = Field(default=1, ge=1, le=150, description="页码，站点侧最多约 150 页（subset 6750 / 45）") sort: SortOption = Field(default=SortOption.STANDARD, description="排序方式，对应搜索页 `s=` 参数") genre_id: str | None = Field(default=None, description="乐天分类 ID，如 565950") min_price: int | None = Field(default=None, ge=0, description="最低价格（日元）") max_price: int | None = Field(default=None, ge=0, description="最高价格（日元）") shop_id: int | None = Field(default=None, description="限定店铺（对应 `sid` 参数，取搜索结果的 shop.shop_id）") exclude_keyword: str | None = Field(default=None, description="排除词（`nitem`）") title_only: bool = Field(default=False, description="仅在商品标题中匹配（`sf=1`）") or_query: bool = Field(default=False, description="关键词之间用 OR 而非 AND（`st=O`）") min_review_score: int | None = Field(default=None, ge=1, le=5, description="最低评分") condition: ItemCondition | None = Field(default=None, description="商品成色筛选：新品 / 中古 / 租赁") include_sold_out: bool = Field(default=False, description="包含售罄商品") free_shipping: bool = Field(default=False, description="仅免运费") has_review: bool = Field(default=False, description="仅有评论") next_day_delivery: bool = Field(default=False, description="仅次日达") super_deal: bool = Field(default=False, description="仅 SuperDEAL") tags: list[str] = Field(default_factory=list, description="站点标签 ID（`tg`）") search_url: HttpUrl | None = Field( default=None, description="直接透传一条乐天搜索页 URL，服务端原样抓取；此时除 page 与 exclude_ads 外的筛选字段全部忽略", ) exclude_ads: bool = Field(default=True, description="剔除搜索结果中混入的 CPC 广告位") @model_validator(mode="after") def check_search_target(self) -> SearchRequest: if ( not self.search_url and not self.keyword.strip() and not self.genre_id and self.shop_id is None ): raise ValueError("keyword、genre_id、shop_id、search_url 至少需要提供一个") if self.min_price is not None and self.max_price is not None and self.min_price > self.max_price: raise ValueError("min_price 不能大于 max_price") return self class ShopDetailRequest(BaseModel): """乐天商家详情请求参数：传店铺代码（店铺 URL 的路径段），或直接传店铺页 URL""" shop_code: str | None = Field(default=None, description="店铺代码，如 edion") shop_url: HttpUrl | None = Field(default=None, description="店铺页 URL；与 shop_code 二选一") @model_validator(mode="after") def check_shop_target(self) -> ShopDetailRequest: if not self.shop_url and not (self.shop_code or "").strip(): raise ValueError("需要提供 shop_code 或 shop_url") return self class ShopItemsRequest(BaseModel): """乐天商家商品列表请求参数 站点没有单独的「店铺内商品」接口，本服务转成一次限定店铺的搜索 （搜索页的 `sid` 参数），因此支持与 /api/search 相同的排序与筛选。 shop_id 与 shop_code 至少提供一个；只给 shop_code 时会先取一次店铺详情 换出 shop_id，多花一次请求，能直接给 shop_id 时优先给。 """ shop_id: int | None = Field(default=None, description="店铺 ID，取自搜索结果或商家详情的 shop.shop_id") shop_code: str | None = Field(default=None, description="店铺代码，如 edion") keyword: str = Field(default="", description="在店铺内按关键词过滤") page: int = Field(default=1, ge=1, le=150, description="页码") sort: SortOption = Field(default=SortOption.STANDARD, description="排序方式") genre_id: str | None = Field(default=None, description="乐天分类 ID，如 565950") min_price: int | None = Field(default=None, ge=0, description="最低价格（日元）") max_price: int | None = Field(default=None, ge=0, description="最高价格（日元）") condition: ItemCondition | None = Field(default=None, description="商品成色筛选") include_sold_out: bool = Field(default=False, description="包含售罄商品") free_shipping: bool = Field(default=False, description="仅免运费") exclude_ads: bool = Field(default=True, description="剔除搜索结果中混入的 CPC 广告位") @model_validator(mode="after") def check_shop_target(self) -> ShopItemsRequest: if self.shop_id is None and not (self.shop_code or "").strip(): raise ValueError("需要提供 shop_id 或 shop_code") if self.min_price is not None and self.max_price is not None and self.min_price > self.max_price: raise ValueError("min_price 不能大于 max_price") return self def to_search_request(self, shop_id: int) -> SearchRequest: """转成一次限定店铺的搜索请求 站点没有独立的「店铺内商品」页可供分页抓取，店铺商品实际就是 `sid=` 限定后的搜索结果，因此这里复用同一条抓取链路。 """ return SearchRequest( keyword=self.keyword, page=self.page, sort=self.sort, genre_id=self.genre_id, min_price=self.min_price, max_price=self.max_price, shop_id=shop_id, condition=self.condition, include_sold_out=self.include_sold_out, free_shipping=self.free_shipping, exclude_ads=self.exclude_ads, ) class ShopDetailData(BaseModel): """乐天商家详情数据""" shop_id: int | None = Field(default=None, description="店铺 ID") shop_code: str = Field(default="", description="店铺代码，如 edion") shop_name: str = Field(default="", description="店铺名") shop_url: str = Field(default="", description="店铺页地址") introduction: str = Field(default="", description="店铺简介") signboard_url: str = Field(default="", description="店铺招牌图地址") logo_url: str = Field(default="", description="店铺 Logo 图地址") review_score: float = Field(default=0.0, description="综合评分") review_count: int = Field(default=0, description="评价数") # 站点在评价数过少时不展示评分；此时 review_score 不可信 review_displayed: bool = Field(default=False, description="站点是否展示了评分；未展示时 review_score 不可信") is_39_shop: bool = Field(default=False, description="39ショップ（满 3980 日元免运费）") age_verification_required: bool = Field(default=False, description="购买该店铺商品需要年龄确认") status: int | None = Field(default=None, description="站点店铺状态码，1 = 营业中") holidays: list[str] = Field(default_factory=list, description="店铺休息日") class ItemDetailRequest(BaseModel): """商品详情请求参数：传 shop_code + item_code，或直接传商品页 URL""" shop_code: str | None = Field(default=None, description="店铺代码，如 edion（商品 URL 的第一段）") item_code: str | None = Field(default=None, description="店铺内商品编号，如 4902370549263（商品 URL 的第二段）") item_url: HttpUrl | None = Field(default=None, description="商品页 URL；不传时需同时提供 shop_code 与 item_code") include_sku_variants: bool = Field( default=True, description="是否返回 SKU 组合明细；SKU 组合可能多达数百条，不需要时可关闭" ) @model_validator(mode="after") def check_item_target(self) -> ItemDetailRequest: if not self.item_url and not (self.shop_code and self.item_code): raise ValueError("需要提供 item_url，或同时提供 shop_code 与 item_code") return self class GenreRequest(BaseModel): """分类查询参数 不传 genre_id 时返回 39 个顶层分类；传入时返回该分类的信息、祖先路径与直接子分类。 """ genre_id: str | None = Field( default=None, description="分类 ID。不传返回 39 个顶层分类；传入返回该分类的信息、祖先路径与直接子分类", ) class GenreNode(BaseModel): """分类树上的一个节点""" genre_id: str = Field(default="", description="分类 ID") name: str = Field(default="", description="分类名") # 该分类下的商品数。顶层列表不返回该值：站点给出的是「当前查询在该分类下的 # 命中数」，与分类自身的商品总量不是一回事，避免误用。 item_count: int | None = Field(default=None, description="该分类下的商品数；顶层列表不返回该值") shortcut: str = Field(default="", description="站点分类短代码，如 game / flower") is_leaf: bool = Field(default=False, description="叶子分类，没有下级") url: str = Field(default="", description="分类页地址") class GenreData(BaseModel): """分类查询结果""" genre_id: str = Field(default="", description="分类 ID，空串表示顶层") name: str = Field(default="", description="分类名") full_name: str = Field(default="", description="站点给出的完整分类名，仅分类页有") description: str = Field(default="", description="站点分类描述，仅分类页有") is_leaf: bool = Field(default=False, description="叶子分类，没有下级") url: str = Field(default="", description="分类页地址") ancestors: list[GenreNode] = Field(default_factory=list, description="祖先分类路径，从顶层到父级，不含自身") children: list[GenreNode] = Field(default_factory=list, description="直接子分类") class ShopSummary(BaseModel): """店铺信息""" shop_id: int | None = Field(default=None, description="店铺 ID") shop_code: str = Field(default="", description="店铺 URL 代码，如 edion；与 item_code 一起可定位商品") shop_name: str = Field(default="", description="店铺名") shop_url: str = Field(default="", description="店铺页地址") review_score: float = Field(default=0.0, description="综合评分") review_count: int = Field(default=0, description="评价数") class ReviewSummary(BaseModel): """评价信息""" score: float = Field(default=0.0, description="评分") count: int = Field(default=0, description="评价数") url: str = Field(default="", description="评价页地址") class SearchItem(BaseModel): """搜索结果中的单个商品""" item_id: str = Field(default="", description="乐天内部商品 ID（搜索结果的 code 字段）") item_code: str = Field(default="", description="商品 URL 第二段，调详情接口用") item_name: str = Field(default="", description="商品名") item_url: str = Field(default="", description="真实商品页地址；广告位已还原为 originalItemUrl") catch_copy: str = Field(default="", description="商品副标题") price: int = Field(default=0, description="价格（日元）") price_range: str = Field(default="", description="多 SKU 时的价格区间，如「1000~2000」") has_price_range: bool = Field(default=False, description="是否为多 SKU 价格区间") image_url: str = Field(default="", description="主图地址") image_urls: list[str] = Field(default_factory=list, description="图片地址列表") shop: ShopSummary = Field(default_factory=ShopSummary, description="所属店铺信息") review: ReviewSummary = Field(default_factory=ReviewSummary, description="商品评价信息") genre_id: str = Field(default="", description="分类 ID") genre_path: str = Field(default="", description="分类路径，形如 /0/101205/565950/566404") genre_names: list[str] = Field(default_factory=list, description="分类名列表") shipping_fee: int | None = Field(default=None, description="运费（日元）；站点未给出时为 null") delivery_message: str = Field(default="", description="配送说明") point_count: int = Field(default=0, description="乐天积分倍率（站点 point.count 原值）") is_sold_out: bool = Field(default=False, description="已售罄") is_ad: bool = Field(default=False, description="CPC 广告位") has_multi_sku: bool = Field(default=False, description="有多个 SKU") variant_id: str = Field(default="", description="SKU 组合 ID（站点 variantId 原值）") item_options: dict[str, Any] = Field(default_factory=dict, description="站点 itemOptions 原样透出") class SearchResultData(BaseModel): """搜索结果数据""" keyword: str = Field(default="", description="搜索关键词") page: int = Field(default=1, description="当前页码") page_size: int = Field(default=0, description="每页条数") total_count: int = Field(default=0, description="站点声明的命中总数") reachable_count: int = Field(default=0, description="实际可翻页取到的上限（站点 subset，随查询条件变化）") has_more: bool = Field(default=False, description="是否还有下一页") # 请求页码超出 reachable_count 对应的页数。站点此时不会返回空列表，而是 # 静默回绕到第 1 页；这里识别出来并把 items 置空，避免上游把重复数据当新数据。 out_of_range: bool = Field( default=False, description="请求页码超出可翻页范围；此时 items 置空（站点会静默回绕到第 1 页，已识别）" ) ad_count: int = Field(default=0, description="本页被识别出的广告位数量（exclude_ads=true 时已从 items 剔除）") request_url: str = Field(default="", description="实际抓取的乐天页面地址，便于排查") items: list[SearchItem] = Field(default_factory=list, description="本页商品列表") class SkuAttribute(BaseModel): """SKU 属性项""" title: str = Field(default="", description="属性名") value: str = Field(default="", description="属性值") class SkuAxisValue(BaseModel): """SKU 选择轴上的一个取值""" value: str = Field(default="", description="取值原值") label: str = Field(default="", description="取值展示名") is_sold_out: bool = Field(default=False, description="该取值已售罄") class SkuAxis(BaseModel): """SKU 选择轴，如「颜色」「尺码」""" key: str = Field(default="", description="轴标识") label: str = Field(default="", description="轴展示名") values: list[SkuAxisValue] = Field(default_factory=list, description="可选取值列表") class SkuVariant(BaseModel): """一个具体的 SKU 组合""" variant_id: str = Field(default="", description="SKU 组合 ID") selector_values: list[str] = Field(default_factory=list, description="与 axis 顺序对应的取值") price: int = Field(default=0, description="价格（日元）") quantity: int = Field(default=0, description="库存数量") is_sold_out: bool = Field(default=False, description="已售罄") delivery_message: str = Field(default="", description="配送说明") attributes: list[SkuAttribute] = Field(default_factory=list, description="SKU 属性列表") class SkuInfo(BaseModel): """商品 SKU 信息""" inventory_type: str = Field(default="", description="库存类型：single / multiple") quantity: int = Field(default=0, description="库存数量") show_inventory: bool = Field(default=False, description="站点是否展示库存") delivery_message: str = Field(default="", description="配送说明") attributes: list[SkuAttribute] = Field(default_factory=list, description="SKU 属性列表") axis: list[SkuAxis] = Field(default_factory=list, description="SKU 选择轴，如「颜色」「尺码」") variants: list[SkuVariant] = Field(default_factory=list, description="SKU 组合明细；include_sku_variants=false 时为空") variant_count: int = Field(default=0, description="SKU 组合总数；不受 include_sku_variants 影响，始终为真实组合数") class ItemOptionValue(BaseModel): """店铺自定义选项的一个候选取值""" value_id: int | None = Field(default=None, description="站点 values[].id 原值；给不出数字时为 null") name: str = Field(default="", description="取值展示名，下单时 choice 里要用这个原文") is_placeholder: bool = Field( default=False, description="是否为「選択してください」这类占位项。占位项不是合法取值，" "提交它等于没选，构造 choice 时必须跳过", ) class ItemOption(BaseModel): """一个店铺自定义选项（下单必填项的来源） 与 SKU 规格不是一回事：规格走 `sku.variants[].variant_id`，选项走下单接口的 `choice` 字段。店铺用它承载「名入れ文字」「配送方式确认」「レビュー依頼」等， `is_required=true` 的选项不给值时站点会直接拒绝加购。 """ option_id: int | None = Field(default=None, description="站点 options[].id 原值") name: str = Field(default="", description="选项名，下单时 choice 的「名」部分要用这个原文") type: str = Field( default="", description="站点原值：select（下拉，看 values）/ text（自由文本，values 为空）", ) is_required: bool = Field(default=False, description="是否必填；必填项不给值时站点拒绝加购") values: list[ItemOptionValue] = Field( default_factory=list, description="候选取值；type=text 时为空" ) selectable_value_count: int = Field( default=0, description="剔除占位项后真正可提交的候选数。为 0 且 is_required=true 时" "无法自动选值，必须由调用方在 choice 里显式给出", ) class ShippingInfo(BaseModel): """配送与运费信息""" shipping_fee: int | None = Field(default=None, description="运费（日元）；站点未给出时为 null") is_shipping_free: bool = Field(default=False, description="免运费") is_asuraku: bool = Field(default=False, description="あす楽（次日达）") is_next_day_delivery: bool = Field(default=False, description="次日达") free_shipping_threshold: int | None = Field(default=None, description="免运费门槛（日元）") prefecture_id: int | None = Field(default=None, description="站点默认收货地（13 = 东京都）") delivery_message: str = Field(default="", description="配送说明") class Breadcrumb(BaseModel): """分类面包屑""" name: str = Field(default="", description="分类名") url: str = Field(default="", description="分类页地址") class ItemDetailData(BaseModel): """商品详情数据 部分乐天官方店的商品页会跳转到独立子站，各子站页面结构不同、可提供的字段也 不同。source 标明这条数据由哪个站点解析而来，字段覆盖差异见 README。 加购（构造 cart 请求）不在本服务范围内——加购需要已登录的乐天账号会话， 归 trading 服务（app.trading）。本响应只描述「商品状态」：能不能买 （purchase_condition / is_sold_out）、规格（sku.variants）、起订单位、 店铺自定义选项（options）等，即「下单前需要先决定哪些参数」。 """ source: str = Field(default="ichiba", description="数据来源站点：ichiba / books / brandavenue / biccamera") source_url: str = Field(default="", description="实际解析的页面地址；跳转时与 item_url 不同") item_id: str = Field(default="", description="乐天内部商品 ID") item_code: str = Field(default="", description="店铺内商品编号（商品 URL 第二段）") item_name: str = Field(default="", description="商品名") catch_copy: str = Field(default="", description="商品副标题") description: str = Field(default="", description="店铺自填的商品说明，含 HTML") item_url: str = Field(default="", description="商品页地址") price: int = Field(default=0, description="最低售价（日元，含税；多 SKU 时为最低价）") pre_tax_price: int = Field(default=0, description="税前价格（日元）") tax_flag: bool = Field(default=False, description="价格是否含税（站点 taxFlag 原值）") tax_rate: float = Field(default=0.0, description="税率") purchase_condition: str = Field(default="", description="站点原值，enabled 表示可购买") is_sold_out: bool = Field(default=False, description="已售罄") purchase_unit: int = Field(default=0, description="起订单位") images: list[str] = Field(default_factory=list, description="商品图片地址列表") shop: ShopSummary = Field(default_factory=ShopSummary, description="所属店铺信息") review: ReviewSummary = Field(default_factory=ReviewSummary, description="商品评价信息") genre_id: str = Field(default="", description="分类 ID") breadcrumbs: list[Breadcrumb] = Field(default_factory=list, description="分类面包屑") shipping: ShippingInfo = Field(default_factory=ShippingInfo, description="该商品的配送与运费信息") sku: SkuInfo = Field(default_factory=SkuInfo, description="SKU 信息") options: list[ItemOption] = Field( default_factory=list, description="店铺自定义选项（站点 purchase.information.options）。与 SKU 规格不同：" "规格选 sku.variants[].variant_id，选项走下单接口的 choice 字段。" "空列表表示该商品页没有选项；子站（books / brandavenue / biccamera）暂不解析", ) has_required_options: bool = Field( default=False, description="是否存在必填选项。为 true 时下单必须给 choice，否则站点拒绝加购", ) unfillable_required_options: list[str] = Field( default_factory=list, description="必填但无法自动选值的选项名（自由文本项，或候选值只有占位项）。" "非空时**必须**由调用方在下单 intent.choice 里显式给出这些项的取值", ) class HealthData(BaseModel): """抓取服务健康检查响应数据 这里不含登录态——登录态属于交易服务，查它请打交易服务的 /health。 """ status: str = Field(description="服务状态，正常为 ok") browser_fallback_enabled: bool = Field(description="是否启用浏览器兜底抓取") browser_fallback_ready: bool = Field(description="浏览器兜底是否就绪") browser_fallback_error: str | None = Field(default=None, description="浏览器兜底不可用的原因；正常为 null") sessions: dict[str, Any] = Field(default_factory=dict, description="各站点抓取会话状态（rakuten / rakuma）") # ========================================================================== # ラクマ（fril.jp） # # 乐天市场是 B2C 商城（店铺 × 商品 × SKU），ラクマ 是 C2C 二手集市： # 每件商品都是独一无二的一件，没有 SKU、没有库存数量、没有店铺代码， # 卖家用一串 hash 标识。字段因此单独建模，不与市场侧强行合并。 # ========================================================================== class RakumaSortOption(StrEnum): """ラクマ 搜索排序方式，对应搜索页 `sort=` + `order=` 两个参数""" STANDARD = "standard" # おすすめ順（站点默认） NEWEST = "newest" # 新着順 PRICE_ASC = "price_asc" PRICE_DESC = "price_desc" LIKE_COUNT = "like_count" # いいね数順 class RakumaCondition(StrEnum): """ラクマ 商品状态（出品者自己申告的成色，6 档）""" NEW = "new" # 新品、未使用 ALMOST_NEW = "almost_new" # 未使用に近い NO_DAMAGE = "no_damage" # 目立った傷や汚れなし SLIGHT_DAMAGE = "slight_damage" # やや傷や汚れあり DAMAGED = "damaged" # 傷や汚れあり POOR = "poor" # 全体的に状態が悪い class RakumaTransaction(StrEnum): """ラクマ 售卖状态筛选""" ON_SALE = "on_sale" # 販売中のみ SOLD_OUT = "sold_out" # 売切れのみ class RakumaAuthenticity(StrEnum): """ラクマ 正品鉴定服务类型""" BEFORE_DELIVERY = "before_delivery" # お届け前鑑定 AFTER_DELIVERY = "after_delivery" # 後から鑑定 class RakumaSearchRequest(BaseModel): """ラクマ 搜索请求参数 两种用法（优先级从高到低）： 1. 传 search_url：透传一条 fril.jp 搜索页 URL，此时除 page 外的筛选字段全部忽略 2. 传 keyword / category_id / brand_id（可叠加任意筛选字段） keyword、category_id、brand_id、search_url 四者至少提供一个。 """ keyword: str = Field(default="", description="搜索关键词") page: int = Field(default=1, ge=1, le=100, description="页码，站点侧 page>100 直接 404") sort: RakumaSortOption = Field(default=RakumaSortOption.STANDARD, description="排序方式") category_id: str | None = Field(default=None, description="ラクマ 分类 ID，如 788") brand_id: str | None = Field(default=None, description="ラクマ 品牌 ID，如 5296") min_price: int | None = Field(default=None, ge=0, description="最低价格（日元）") max_price: int | None = Field(default=None, ge=0, description="最高价格（日元）") exclude_keyword: str | None = Field( default=None, description="排除词（站点 `excluded_query`，需与 keyword 同时使用）" ) conditions: list[RakumaCondition] = Field(default_factory=list, description="商品状态筛选，可多选") transaction: RakumaTransaction | None = Field(default=None, description="售卖状态筛选，不传表示不限") free_shipping: bool = Field(default=False, description="仅「送料込み」（卖家承担运费）") anonymous_shipping: bool = Field(default=False, description="仅匿名配送") except_for_no_brand: bool = Field(default=False, description="排除无品牌商品；与 brand_id 互斥") authenticity_types: list[RakumaAuthenticity] = Field(default_factory=list, description="正品鉴定服务类型筛选，可多选") search_url: HttpUrl | None = Field( default=None, description="直接透传一条 fril.jp 搜索页 URL；此时除 page 外的筛选字段全部忽略" ) @model_validator(mode="after") def check_search_target(self) -> RakumaSearchRequest: if not self.search_url and not self.keyword.strip() and not self.category_id and not self.brand_id: raise ValueError("keyword、category_id、brand_id、search_url 至少需要提供一个") if self.min_price is not None and self.max_price is not None and self.min_price > self.max_price: raise ValueError("min_price 不能大于 max_price") # 站点前端在无关键词时会拒绝下发 excluded_query，服务端也不认，这里提前拦下 if self.exclude_keyword and not self.keyword.strip(): raise ValueError("exclude_keyword 必须与 keyword 同时使用") return self class RakumaItemDetailRequest(BaseModel): """ラクマ 商品详情请求参数：传 item_id（商品 URL 的最后一段），或直接传商品页 URL""" item_id: str | None = Field(default=None, description="商品页 hash，如 4aca1d6db3e422f3a251a8a8b61e1eff") item_url: HttpUrl | None = Field(default=None, description="商品页 URL；与 item_id 二选一") @model_validator(mode="after") def check_item_target(self) -> RakumaItemDetailRequest: if not self.item_url and not (self.item_id or "").strip(): raise ValueError("需要提供 item_id 或 item_url") return self class RakumaShopDetailRequest(BaseModel): """ラクマ 卖家详情请求参数：传 shop_id（店铺 URL 的最后一段），或直接传店铺页 URL""" shop_id: str | None = Field(default=None, description="店铺页 hash，如 422750cb7921557bc8dba2416915d968") shop_url: HttpUrl | None = Field(default=None, description="店铺页 URL；与 shop_id 二选一") # 评价明细在单独的 /review 页上，需要多打一次请求，默认不取 include_reviews: bool = Field( default=False, description="是否返回评价明细；评价在单独的 /review 页，会多打一次请求" ) @model_validator(mode="after") def check_shop_target(self) -> RakumaShopDetailRequest: if not self.shop_url and not (self.shop_id or "").strip(): raise ValueError("需要提供 shop_id 或 shop_url") return self class RakumaShopItemsRequest(BaseModel): """ラクマ 卖家商品列表请求参数 店铺页按上架顺序分页展示该卖家的全部商品（含已售出），站点不提供 排序与筛选参数，因此这里只有页码。 """ shop_id: str | None = Field(default=None, description="店铺页 hash") shop_url: HttpUrl | None = Field(default=None, description="店铺页 URL；与 shop_id 二选一") page: int = Field(default=1, ge=1, description="页码") @model_validator(mode="after") def check_shop_target(self) -> RakumaShopItemsRequest: if not self.shop_url and not (self.shop_id or "").strip(): raise ValueError("需要提供 shop_id 或 shop_url") return self class RakumaCategoryRequest(BaseModel): """ラクマ 分类查询参数 不传 category_id 时返回 14 个顶层分类；传入时返回该分类的名称、祖先路径与 直接子分类。站点一次请求就返回整棵树，因此 include_descendants 只是换一种 组织方式，不会多打请求。 """ category_id: str | None = Field( default=None, description="分类 ID。不传返回 14 个顶层分类；传入返回该分类的名称、祖先路径与直接子分类", ) include_descendants: bool = Field( default=False, description="返回该分类下的完整子树（不止直接子级）；分类树共三层，顶层分类的子树可达上百条", ) class RakumaCategoryNode(BaseModel): """ラクマ 分类树上的一个节点 站点只给 id / parentId / name / hasChild 四个字段，没有商品数—— 商品数要逐个分类去抓 `/category/{id}` 页面，成本过高，本接口不提供。 """ category_id: str = Field(default="", description="分类 ID") name: str = Field(default="", description="分类名") parent_id: str = Field(default="", description="父分类 ID，「0」表示顶层分类") is_leaf: bool = Field(default=False, description="叶子分类，没有下级") url: str = Field(default="", description="分类页地址") children: list[RakumaCategoryNode] = Field( default_factory=list, description="下级分类；include_descendants=true 时填充，否则始终为空" ) class RakumaCategoryData(BaseModel): """ラクマ 分类查询结果""" category_id: str = Field(default="", description="分类 ID，空串表示顶层") name: str = Field(default="", description="分类名") full_name: str = Field( default="", description="从顶层拼到自身的路径名，如「エンタメ/ホビー / ゲームソフト/ゲーム機本体 / 家庭用ゲームソフト」", ) is_leaf: bool = Field(default=False, description="叶子分类，没有下级") url: str = Field(default="", description="分类页地址") total_count: int = Field(default=0, description="站点分类树的节点总数，用于确认取到的是全量树") ancestors: list[RakumaCategoryNode] = Field( default_factory=list, description="祖先分类路径，从顶层到父级，不含自身" ) children: list[RakumaCategoryNode] = Field( default_factory=list, description="直接子分类；include_descendants=true 时带子树" ) class RakumaSeller(BaseModel): """ラクマ 卖家（出品者）摘要""" shop_id: str = Field(default="", description="店铺页 hash，可直接用于 /api/rakuma/shop_detail") user_id: str = Field(default="", description="站点内部数值用户 ID") shop_name: str = Field(default="", description="店铺名，卖家可自定义") user_name: str = Field(default="", description="用户昵称") shop_url: str = Field(default="", description="店铺页地址") icon_url: str = Field(default="", description="头像地址") seller_type: str = Field(default="", description="卖家类型（站点原值），如 一般 / 事業者") review_score: float = Field(default=0.0, description="综合评分") review_count: int = Field(default=0, description="评价数") is_verified: bool = Field(default=False, description="本人確認済") class RakumaSearchItem(BaseModel): """ラクマ 搜索结果中的单个商品""" item_id: str = Field(default="", description="商品页 hash，调详情接口用") item_number: str = Field(default="", description="站点内部数值商品 ID") item_name: str = Field(default="", description="商品名") item_url: str = Field(default="", description="商品页地址") price: int = Field(default=0, description="价格（日元）") image_url: str = Field(default="", description="主图地址") is_sold_out: bool = Field(default=False, description="已售出") brand_id: str = Field(default="", description="品牌 ID") brand_name: str = Field(default="", description="品牌名") category_id: str = Field(default="", description="分类 ID") category_names: list[str] = Field(default_factory=list, description="分类名列表") seller_user_id: str = Field(default="", description="卖家数值 ID；店铺 hash 需从详情页取") seller_type: str = Field(default="", description="卖家类型（站点原值），如 一般 / 事業者") class RakumaSearchResultData(BaseModel): """ラクマ 搜索结果数据""" keyword: str = Field(default="", description="搜索关键词") page: int = Field(default=1, description="当前页码") page_size: int = Field(default=0, description="每页条数") # 站点声明的命中总数。页面上展示为「約1,190,000件」的四舍五入值， # 这里取的是埋点属性里的精确值。 total_count: int = Field(default=0, description="站点声明的命中总数（埋点属性里的精确值）") has_more: bool = Field(default=False, description="是否还有下一页") request_url: str = Field(default="", description="实际抓取的页面地址，便于排查") items: list[RakumaSearchItem] = Field(default_factory=list, description="本页商品列表") class RakumaItemDetailData(BaseModel): """ラクマ 商品详情数据 C2C 集市的商品是单件的：没有 SKU 组合，没有库存数量， 「規格」在站点上只体现为一个可选的尺码字段。 """ item_id: str = Field(default="", description="商品页 hash") item_number: str = Field(default="", description="站点内部数值商品 ID") item_name: str = Field(default="", description="商品名") description: str = Field(default="", description="商品说明（卖家自填）") item_url: str = Field(default="", description="商品页地址") price: int = Field(default=0, description="价格（日元）") is_sold_out: bool = Field(default=False, description="已售出") images: list[str] = Field(default_factory=list, description="商品图片地址列表") condition: str = Field(default="", description="商品の状態，站点原文如「目立った傷や汚れなし」") size: str = Field(default="", description="サイズ，无尺码时为空") brand_id: str = Field(default="", description="品牌 ID") brand_name: str = Field(default="", description="品牌名") category_id: str = Field(default="", description="最具体的一级分类 ID") breadcrumbs: list[Breadcrumb] = Field(default_factory=list, description="分类面包屑") shipping_payer: str = Field(default="", description="配送料の負担，如「送料込」") shipping_method: str = Field(default="", description="配送方法") shipping_date_estimate: str = Field(default="", description="発送日の目安") shipping_from: str = Field(default="", description="発送元の地域") is_anonymous_shipping: bool = Field(default=False, description="匿名配送") like_count: int = Field(default=0, description="いいね数") comment_count: int = Field(default=0, description="评论数") posted_at: str = Field(default="", description="站点展示的相对时间，如「約1時間前」") seller: RakumaSeller = Field(default_factory=RakumaSeller, description="卖家（出品者）信息") class RakumaReview(BaseModel): """ラクマ 卖家的一条交易评价""" rating: str = Field(default="", description="评价档位：good / normal / bad") title: str = Field(default="", description="站点原文标题，如「よい出品者です」") comment: str = Field(default="", description="评价内容") reviewer_name: str = Field(default="", description="评价者昵称") reviewed_at: str = Field(default="", description="站点展示的日期，如 2026/05/04") class RakumaRatingBreakdown(BaseModel): """评价数量分档""" good: int = Field(default=0, description="好评数") normal: int = Field(default=0, description="中评数") bad: int = Field(default=0, description="差评数") class RakumaShopDetailData(BaseModel): """ラクマ 卖家详情数据""" shop_id: str = Field(default="", description="店铺页 hash") user_id: str = Field(default="", description="站点内部数值用户 ID") shop_name: str = Field(default="", description="店铺名，卖家可自定义") user_name: str = Field(default="", description="用户昵称") shop_url: str = Field(default="", description="店铺页地址") icon_url: str = Field(default="", description="头像地址") cover_url: str = Field(default="", description="封面图地址") introduction: str = Field(default="", description="プロフィール文（自我介绍）") review_score: float = Field(default=0.0, description="综合评分") review_count: int = Field(default=0, description="评价数") is_verified: bool = Field(default=False, description="本人確認済") verification_label: str = Field(default="", description="站点原文，如「本人確認済」/「本人確認未完了」") item_count: int = Field(default=0, description="该卖家在售 + 已售商品总数") # 以下三项需 include_reviews=true 才会填充 rating_breakdown: RakumaRatingBreakdown = Field( default_factory=RakumaRatingBreakdown, description="评价数量分档（全部评价）" ) seller_rating_breakdown: RakumaRatingBreakdown = Field( default_factory=RakumaRatingBreakdown, description="评价数量分档（仅作为卖家收到的评价）" ) reviews: list[RakumaReview] = Field(default_factory=list, description="评价明细列表") class RakumaShopItemsData(BaseModel): """ラクマ 卖家商品列表数据""" shop_id: str = Field(default="", description="店铺页 hash") shop_name: str = Field(default="", description="店铺名") page: int = Field(default=1, description="当前页码") total_count: int = Field(default=0, description="该卖家的商品总数") has_more: bool = Field(default=False, description="是否还有下一页") request_url: str = Field(default="", description="实际抓取的页面地址，便于排查") items: list[RakumaSearchItem] = Field(default_factory=list, description="本页商品列表")