Init

app/parsers/rakuma/__init__.py

@@ -0,0 +1,8 @@
+"""ラクマ（fril.jp）页面解析器
+
+站点是服务端渲染的 HTML，没有内联状态 JSON，因此各模块都走 DOM 解析：
+- base   — 埋点属性与文本取值的公共工具
+- search — 搜索页（商品卡片解析同时被店铺页复用）
+- item   — 商品详情页
+- shop   — 店铺页与评价页
+"""

app/parsers/rakuma/base.py

@@ -0,0 +1,144 @@
+"""ラクマ（fril.jp）页面解析的公共工具
+
+站点是服务端渲染的 HTML，没有 `window.__INITIAL_STATE__` 之类的内联状态，
+因此全部走 DOM 解析。好在页面上挂了成套的埋点属性（`data-rat-*` 与
+`onclick` 里的 dataLayer JSON），它们比可见文案稳定得多，也带有可见 DOM
+上没有的字段（商品数值 ID、卖家 ID、分类 ID、品牌 ID），所以优先取这些。
+"""
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any
+
+from selectolax.parser import Node
+
+# 「約1,190,000件中 1 - 40件」里的总数与区间
+_COUNT_RE = re.compile(r"([\d,]+)\s*件中\s*([\d,]+)\s*[-−–]\s*([\d,]+)\s*件")
+_DIGITS_RE = re.compile(r"-?\d+")
+# 页面级埋点属性 data-rat-cp-{key}="{value}"
+_RAT_PARAM_RE = re.compile(r'data-rat-cp-([\w]+)="([^"]*)"')
+
+
+def parse_int(text: str | int | float | None) -> int:
+    """从 "¥6,299" / "6399" / 6399 这类值里取出整数金额或计数"""
+    if isinstance(text, bool) or text is None:
+        return 0
+    if isinstance(text, (int, float)):
+        return int(text)
+    digits = _DIGITS_RE.findall(text.replace(",", ""))
+    return int(digits[0]) if digits else 0
+
+
+def parse_float(text: str | int | float | None) -> float:
+    """从 "5.0" 这类文本里取出评分"""
+    if isinstance(text, bool) or text is None:
+        return 0.0
+    if isinstance(text, (int, float)):
+        return float(text)
+    match = re.search(r"\d+(?:\.\d+)?", text.replace(",", ""))
+    return float(match.group()) if match else 0.0
+
+
+def node_text(node: Node | None) -> str:
+    """取节点的可见文本，压掉多余空白；节点不存在时返回空串"""
+    if node is None:
+        return ""
+    return re.sub(r"\s+", " ", node.text(strip=True)).strip()
+
+
+def attr(node: Node | None, name: str) -> str:
+    """取节点属性，缺失时返回空串"""
+    if node is None:
+        return ""
+    return (node.attributes.get(name) or "").strip()
+
+
+def image_url(node: Node | None) -> str:
+    """取图片地址：站点用 lazy load，真实地址在 data-original 上，src 是占位图"""
+    if node is None:
+        return ""
+    return attr(node, "data-original") or attr(node, "src")
+
+
+def parse_total_count(text: str) -> tuple[int, int, int]:
+    """解析「N件中 X - Y件」，返回 (总数, 起, 止)；解析不出时全为 0
+
+    注意搜索页这里的总数是四舍五入后的展示值（約1,190,000件），
+    精确值要从埋点属性 data-rat-cp-totalresults 取；店铺页则是精确值。
+    """
+    match = _COUNT_RE.search(text.replace("\xa0", " "))
+    if match is None:
+        return 0, 0, 0
+    return (
+        parse_int(match.group(1)),
+        parse_int(match.group(2)),
+        parse_int(match.group(3)),
+    )
+
+
+def event_payload(node: Node | None) -> dict[str, Any]:
+    """从埋点里取出商品参数字典
+
+    商品链接的 onclick / data-gtm-click 上挂着一段 dataLayer JSON，形如：
+        {"event":"fireEvent","eventData":{"event_parameter":{
+            "item_id":"844649627","seller_user_id":"12073120",
+            "category_id":"788","brand_id":"5296","price":6299, ...}}}
+    这里面有可见 DOM 上没有的数值 ID，是搜索结果里最可靠的数据来源。
+    """
+    if node is None:
+        return {}
+
+    for source in (node.attributes.get("data-gtm-click"), node.attributes.get("onclick")):
+        if not source:
+            continue
+        for raw in _iter_json_objects(html.unescape(source)):
+            parameter = (
+                raw.get("eventData", {}).get("event_parameter")
+                if isinstance(raw.get("eventData"), dict)
+                else None
+            )
+            if isinstance(parameter, dict) and "item_id" in parameter:
+                return parameter
+    return {}
+
+
+def find_item_payload(tree: Any) -> dict[str, Any]:
+    """在整页里找出第一段带 item_id 的埋点参数
+
+    详情页的这段 JSON 挂在哪个元素上并不固定（在售商品挂在品牌链接上，
+    已售商品的页面结构不同），因此按属性扫描而不是写死选择器。
+    """
+    for node in tree.css("[data-gtm-click], [onclick]"):
+        payload = event_payload(node)
+        if payload:
+            return payload
+    return {}
+
+
+def rat_params(html_text: str) -> dict[str, str]:
+    """取出页面级埋点属性 `data-rat-cp-*`
+
+    详情页把成色、运费负担、发货地等信息也写在这组属性里。已售出商品的
+    页面会换成另一套布局、规格表消失，但这组属性仍在，可用作兜底。
+    """
+    return {
+        match.group(1): html.unescape(match.group(2))
+        for match in _RAT_PARAM_RE.finditer(html_text)
+    }
+
+
+def _iter_json_objects(text: str):
+    """从一段掺杂着 JS 代码的文本里增量解析出所有顶层 JSON 对象"""
+    decoder = json.JSONDecoder()
+    index = text.find("{")
+    while index >= 0:
+        try:
+            value, end = decoder.raw_decode(text, index)
+        except ValueError:
+            index = text.find("{", index + 1)
+            continue
+        if isinstance(value, dict):
+            yield value
+        index = text.find("{", max(end, index + 1))

app/parsers/rakuma/item.py

@@ -0,0 +1,211 @@
+"""ラクマ 商品详情页 HTML → RakumaItemDetailData
+
+页面数据分三处，各取所长：
+- `<script type="application/ld+json">` 的 Product 微数据：名称、价格、描述、图片
+- `.item__details` 规格表：成色、尺码、配送方式与地区（每行 th 上的
+  `item-status-{key}` class 是稳定键，比日文标签文案可靠）
+- 埋点属性 `data-rat-cp-*` 与 dataLayer JSON：数值 ID、分类 ID、品牌 ID
+
+售罄判定用页面上的 SOLD OUT 标记，而不是 ld+json 的 availability——
+实测已售出商品的 ld+json 仍写 InStock，不可信。
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from selectolax.parser import HTMLParser
+
+from app.core import rakuma_site as site
+from app.core.errors import ScrapeParseError
+from app.models.scrape import Breadcrumb, RakumaItemDetailData, RakumaSeller
+from app.parsers.rakuma.base import (
+    attr,
+    find_item_payload,
+    image_url,
+    node_text,
+    parse_float,
+    parse_int,
+    rat_params,
+)
+from app.utils.rakuma_urls import split_shop_url
+
+_LD_JSON_RE = re.compile(
+    r'<script[^>]*type="application/ld\+json"[^>]*>(.*?)</script>', re.S
+)
+# 商品主图：站点用 slider 展示，主图挂在 .sp-image 上（推荐位的图不在其中）
+_MAIN_IMAGE_SELECTOR = ".sp-slide img.sp-image, .item-photos img, .slider img.sp-image"
+
+# 规格表里 th 图标 class 上的稳定键 → 模型字段
+_SPEC_KEYS = {
+    "item-status-status": "condition",
+    "item-status-size": "size",
+    "item-status-carriage": "shipping_payer",
+    "item-status-delivery_method": "shipping_method",
+    "item-status-delivery_date": "shipping_date_estimate",
+    "item-status-delivery_area": "shipping_from",
+}
+
+# 站点上表示「没有填写该项」的占位文案
+_SPEC_EMPTY_VALUES = ("なし", "未定", "指定なし", "-", "―")
+
+# 规格表缺失时的兜底：页面级埋点属性 data-rat-cp-{key} → 模型字段。
+# 注意这组值的措辞与规格表不完全一致（如运费负担规格表写「送料込」，
+# 埋点写「出品者」），原样透出，不做归一。
+_RAT_SPEC_KEYS = {
+    "condition": "item_condition",
+    "shipping_payer": "shipping_cost_payer",
+    "shipping_date_estimate": "shipping_date_estimate",
+    "shipping_from": "shipping_from",
+}
+
+
+def _parse_ld_product(html: str) -> dict[str, Any]:
+    """取出 ld+json 里的 Product 节点"""
+    for match in _LD_JSON_RE.finditer(html):
+        try:
+            data = json.loads(match.group(1))
+        except ValueError:
+            continue
+        if isinstance(data, dict) and data.get("@type") == "Product":
+            return data
+    return {}
+
+
+def _parse_specs(tree: HTMLParser, rat: dict[str, str]) -> dict[str, str]:
+    """解析商品情報规格表
+
+    每行的 th 里有个 `<i class="icon-status ... item-status-{key}">`，
+    这个 key 比日文标签稳定，用它做映射。
+
+    已售出商品的页面会换成另一套布局、规格表整体消失，此时退回页面级埋点
+    属性——它给的项少一些（没有配送方法与尺码），但成色、运费负担与发货地
+    仍在，好过整片留空。
+    """
+    specs: dict[str, str] = {}
+    for row in tree.css("table.item__details tr"):
+        icon = row.css_first("th i")
+        value_node = row.css_first("td")
+        if icon is None or value_node is None:
+            continue
+        classes = attr(icon, "class").split()
+        field = next((_SPEC_KEYS[name] for name in classes if name in _SPEC_KEYS), None)
+        if field is None:
+            continue
+        value = node_text(value_node)
+        specs[field] = "" if value in _SPEC_EMPTY_VALUES else value
+
+    for field, key in _RAT_SPEC_KEYS.items():
+        if not specs.get(field) and rat.get(key):
+            specs[field] = rat[key]
+    return specs
+
+
+def _parse_breadcrumbs(tree: HTMLParser) -> tuple[list[Breadcrumb], str]:
+    """解析分类面包屑，并返回最具体的一级分类 ID
+
+    取规格表里的分类行而非页头面包屑：页头那条会把品牌也混进来，
+    规格表里的是纯分类链。
+    """
+    crumbs: list[Breadcrumb] = []
+    category_id = ""
+    for row in tree.css("table.item__details tr"):
+        icon = row.css_first("th i")
+        if icon is None or "item-status-category" not in attr(icon, "class"):
+            continue
+        for link in row.css("td a"):
+            url = attr(link, "href")
+            crumbs.append(Breadcrumb(name=node_text(link), url=url))
+            segments = [segment for segment in url.split("/") if segment]
+            if segments:
+                category_id = segments[-1]
+        break
+    return crumbs, category_id
+
+
+def _parse_seller(tree: HTMLParser, payload: dict[str, Any]) -> RakumaSeller:
+    """解析出品者信息块"""
+    link = tree.css_first("a.shop_link, a[href*='/shop/']")
+    shop_url = attr(link, "href")
+    shop_id = ""
+    if shop_url:
+        try:
+            shop_id = split_shop_url(shop_url)
+        except Exception:
+            shop_id = ""
+
+    seller_user_id = payload.get("seller_user_id")
+    return RakumaSeller(
+        shop_id=shop_id,
+        user_id=str(seller_user_id) if seller_user_id is not None else "",
+        shop_name=node_text(tree.css_first(".header-shopinfo__shop-name")),
+        user_name=node_text(tree.css_first(".header-shopinfo__user-name")),
+        shop_url=shop_url,
+        icon_url=image_url(tree.css_first(".header-shopinfo__user-icon img")),
+        seller_type=str(payload.get("seller_user_type") or ""),
+        review_score=parse_float(node_text(tree.css_first(".shop_score__score"))),
+        # 商品页只给评分不给评价数，需要评价数请调 /api/rakuma/shop_detail
+        is_verified=tree.css_first(".header-shopinfo__verified-badge-item") is not None,
+    )
+
+
+def parse_item_detail(html: str, *, item_id: str, item_url: str) -> RakumaItemDetailData:
+    """把商品详情页 HTML 解析为商品详情
+
+    Raises:
+        ScrapeParseError: 页面不是商品详情页
+    """
+    tree = HTMLParser(html)
+    info = tree.css_first(f".{site.ITEM_PAGE_MARKER}")
+    if info is None:
+        raise ScrapeParseError("页面不是商品详情页（缺少商品信息区块）")
+
+    product = _parse_ld_product(html)
+    # 这段埋点挂在哪个元素上因页面状态而异，按属性全页扫描
+    payload = find_item_payload(tree)
+    rat = rat_params(html)
+    specs = _parse_specs(tree, rat)
+    breadcrumbs, category_id = _parse_breadcrumbs(tree)
+
+    images = [
+        url
+        for url in dict.fromkeys(image_url(node) for node in tree.css(_MAIN_IMAGE_SELECTOR))
+        if url and "img.fril.jp" in url
+    ]
+    if not images and isinstance(product.get("image"), str):
+        images = [product["image"]]
+
+    # ld+json 的 availability 对已售商品仍写 InStock，只能按页面标记判断
+    page_text = info.text()
+    is_sold_out = any(marker in page_text for marker in site.SOLD_OUT_MARKERS)
+
+    brand = product.get("brand") if isinstance(product.get("brand"), dict) else {}
+    offers = product.get("offers") if isinstance(product.get("offers"), dict) else {}
+
+    return RakumaItemDetailData(
+        item_id=item_id,
+        item_number=str(payload.get("item_id") or ""),
+        item_name=str(product.get("name") or "") or node_text(tree.css_first("h1.item__name")),
+        description=str(product.get("description") or "")
+        or node_text(tree.css_first(".item__description__line-limited")),
+        item_url=item_url,
+        price=parse_int(offers.get("price")) or parse_int(node_text(tree.css_first(".item__price"))),
+        is_sold_out=is_sold_out,
+        images=images,
+        condition=specs.get("condition", ""),
+        size=specs.get("size", ""),
+        brand_id=str(payload.get("brand_id") or "") or rat.get("brand_id", ""),
+        brand_name=str(brand.get("name") or "") or str(payload.get("brand_name") or ""),
+        category_id=category_id or str(payload.get("category_id") or ""),
+        breadcrumbs=breadcrumbs,
+        shipping_payer=specs.get("shipping_payer", ""),
+        shipping_method=specs.get("shipping_method", ""),
+        shipping_date_estimate=specs.get("shipping_date_estimate", ""),
+        shipping_from=specs.get("shipping_from", ""),
+        is_anonymous_shipping=tree.css_first(".item__icon.anonymous") is not None,
+        like_count=parse_int(node_text(tree.css_first(".like_button_set"))),
+        comment_count=parse_int(node_text(tree.css_first(".go-to-comment-button"))),
+        posted_at=node_text(tree.css_first(".time_ago")),
+        seller=_parse_seller(tree, payload),
+    )

app/parsers/rakuma/search.py

@@ -0,0 +1,135 @@
+"""ラクマ 搜索页 / 店铺商品列表 HTML → 商品列表
+
+搜索页与店铺页的商品卡片是同一套 `.item-box` 结构（只有链接的 class 前缀
+不同：搜索页 link_search_image、店铺页 link_shop_image），因此共用一个卡片
+解析函数。
+
+页面上的可见总数是四舍五入的展示值（約1,190,000件），精确值在埋点属性
+`data-rat-cp-totalresults` 上，优先取后者。
+"""
+from __future__ import annotations
+
+import re
+
+from selectolax.parser import HTMLParser, Node
+
+from app.core import rakuma_site as site
+from app.core.errors import ScrapeParseError
+from app.models.scrape import RakumaSearchItem, RakumaSearchResultData
+from app.parsers.rakuma.base import (
+    attr,
+    event_payload,
+    image_url,
+    node_text,
+    parse_int,
+    parse_total_count,
+)
+from app.utils.rakuma_urls import item_id_from_url
+
+# 埋点属性里的精确命中总数
+_TOTAL_RESULTS_RE = re.compile(r'data-rat-cp-totalresults="(\d+)"')
+
+
+def _as_str(value: object) -> str:
+    """埋点 JSON 里的值可能是数字、字符串或 null，统一收敛为字符串"""
+    if value is None or isinstance(value, bool):
+        return ""
+    if isinstance(value, (int, float)):
+        return str(int(value))
+    return value.strip() if isinstance(value, str) else ""
+
+
+def parse_item_card(card: Node) -> RakumaSearchItem:
+    """解析一张商品卡片
+
+    优先从埋点 JSON 取结构化字段（数值 ID、分类、品牌、价格），
+    可见 DOM 只用于取图片与售罄标记。
+    """
+    link = (
+        card.css_first("a.link_search_image")
+        or card.css_first("a.link_shop_image")
+        or card.css_first("a[href*='item.fril.jp']")
+    )
+    payload = event_payload(link)
+
+    item_url = attr(link, "href")
+    category_names = [
+        name
+        for name in (
+            _as_str(payload.get("first_category")),
+            _as_str(payload.get("second_category")),
+            _as_str(payload.get("third_category")),
+        )
+        if name
+    ]
+
+    # 价格优先取埋点里的数值，回退到卡片上的展示价
+    price = parse_int(payload.get("price")) or parse_int(
+        node_text(card.css_first(".item-box__item-price"))
+    )
+
+    return RakumaSearchItem(
+        item_id=item_id_from_url(item_url),
+        item_number=_as_str(payload.get("item_id")),
+        item_name=_as_str(payload.get("item_name"))
+        or node_text(card.css_first(".item-box__item-name, .item-box__item-name__limited-three-lines")),
+        item_url=item_url,
+        price=price,
+        image_url=image_url(card.css_first("img")),
+        is_sold_out=card.css_first(".item-box__soldout_ribbon") is not None,
+        brand_id=_as_str(payload.get("brand_id")),
+        brand_name=_as_str(payload.get("brand_name"))
+        or node_text(card.css_first(".item-box__item-sub-name")),
+        category_id=_as_str(payload.get("category_id")),
+        category_names=category_names,
+        seller_user_id=_as_str(payload.get("seller_user_id")),
+        seller_type=_as_str(payload.get("seller_user_type")),
+    )
+
+
+def parse_item_cards(tree: HTMLParser) -> list[RakumaSearchItem]:
+    """解析页面上的全部商品卡片
+
+    只取有真实商品链接的卡片：页面上还有一批用于占位的骨架卡片
+    （懒加载的推荐位），它们没有 item.fril.jp 链接。
+    """
+    items: list[RakumaSearchItem] = []
+    for card in tree.css(".item-box"):
+        link = card.css_first("a[href*='item.fril.jp']")
+        if link is None:
+            continue
+        items.append(parse_item_card(card))
+    return items
+
+
+def parse_search(html: str, *, request_url: str, page: int, keyword: str) -> RakumaSearchResultData:
+    """把搜索页 HTML 解析为搜索结果
+
+    Raises:
+        ScrapeParseError: 页面不是搜索结果页（站点对无法识别的参数值会静默返回首页）
+    """
+    tree = HTMLParser(html)
+    count_node = tree.css_first(f".{site.SEARCH_PAGE_MARKER}")
+    if count_node is None:
+        raise ScrapeParseError(
+            "页面不是搜索结果页（缺少命中数区块）；"
+            "站点对无法识别的筛选取值会静默返回首页，请检查筛选参数"
+        )
+
+    items = parse_item_cards(tree)
+
+    # 展示值是四舍五入过的（約1,190,000件），埋点里才是精确命中数
+    display_total, start, end = parse_total_count(node_text(count_node))
+    match = _TOTAL_RESULTS_RE.search(html)
+    total_count = int(match.group(1)) if match else display_total
+
+    return RakumaSearchResultData(
+        keyword=keyword,
+        page=page,
+        page_size=len(items),
+        total_count=total_count,
+        # 站点 page>100 直接 404，超出可达窗口时没有下一页
+        has_more=bool(items) and page < site.MAX_PAGE and (end or start + len(items) - 1) < total_count,
+        request_url=request_url,
+        items=items,
+    )

app/parsers/rakuma/shop.py

@@ -0,0 +1,223 @@
+"""ラクマ 店铺页 HTML → 卖家详情与卖家商品列表
+
+C2C 集市里的「商家」就是个人卖家，页面在 fril.jp/shop/{hash}：
+- 店铺页本身：卖家资料 + 该卖家的商品分页列表（含已售出）
+- /review 子页：评价明细与好评/普通/差评分档计数
+
+商品卡片与搜索页共用 `.item-box` 结构，直接复用 search 里的解析。
+"""
+from __future__ import annotations
+
+import json
+import re
+
+from selectolax.parser import HTMLParser
+
+from app.core import rakuma_site as site
+from app.core.errors import ScrapeParseError
+from app.models.scrape import (
+    RakumaRatingBreakdown,
+    RakumaReview,
+    RakumaShopDetailData,
+    RakumaShopItemsData,
+)
+from app.parsers.rakuma.base import (
+    attr,
+    event_payload,
+    image_url,
+    node_text,
+    parse_float,
+    parse_int,
+    parse_total_count,
+)
+from app.parsers.rakuma.search import parse_item_cards
+
+# 评价条目标题左侧的图标 class → 评价档位
+_RATING_ICONS = {
+    "icon_review_sun": "good",  # よい
+    "icon_review_cloud": "normal",  # ふつう
+    "icon_review_rain": "bad",  # わるい
+}
+
+# /review 页上三组分档计数的容器 id 前缀
+_ALL_RATINGS_PREFIX = "all"
+_SELLER_RATINGS_PREFIX = "seller"
+
+_LD_JSON_RE = re.compile(
+    r'<script[^>]*type="application/ld\+json"[^>]*>(.*?)</script>', re.S
+)
+
+
+def _require_shop_page(html: str) -> HTMLParser:
+    tree = HTMLParser(html)
+    if tree.css_first(f".{site.SHOP_PAGE_MARKER}") is None:
+        raise ScrapeParseError("页面不是店铺页（缺少店铺资料区块）")
+    return tree
+
+
+def _parse_rating_breakdown(tree: HTMLParser, prefix: str) -> RakumaRatingBreakdown:
+    """解析一组好评/普通/差评计数
+
+    页面用 `<ul class="nav-pills">` 里的三个链接展示，锚点形如
+    `#all-good` / `#seller-normal`，按锚点前缀区分「全部」与「出品」两组。
+    """
+    counts = {"good": 0, "normal": 0, "bad": 0}
+    for link in tree.css("ul.nav-pills a"):
+        href = attr(link, "href")
+        for rating in counts:
+            if href == f"#{prefix}-{rating}":
+                counts[rating] = parse_int(node_text(link))
+    return RakumaRatingBreakdown(**counts)
+
+
+def _parse_reviews(tree: HTMLParser) -> list[RakumaReview]:
+    """解析评价列表
+
+    站点在「すべての評価」标签页里最多展示最新 100 条，且三个标签页
+    （全部/出品/购入）的条目在 DOM 里重复出现，这里只取第一个激活面板。
+    """
+    panel = tree.css_first("#all-all") or tree.css_first(".tab-pane.active")
+    if panel is None:
+        return []
+
+    reviews: list[RakumaReview] = []
+    for article in panel.css("article.review-item"):
+        title_node = article.css_first(".review-item-title")
+        icon = title_node.css_first("i") if title_node else None
+        classes = attr(icon, "class").split() if icon else []
+        rating = next((_RATING_ICONS[name] for name in classes if name in _RATING_ICONS), "")
+
+        reviews.append(
+            RakumaReview(
+                rating=rating,
+                title=node_text(title_node),
+                comment=node_text(article.css_first(".review-item-text")),
+                reviewer_name=node_text(article.css_first(".review-item-name")),
+                reviewed_at=node_text(article.css_first(".review-item-date")),
+            )
+        )
+    return reviews
+
+
+def _parse_store_rating(html: str) -> tuple[float, int]:
+    """从店铺页的 ld+json Store 节点取评分与评价数
+
+    评价数只有这里给得出来——可见 DOM 上只有星级和分数，没有条数。
+    """
+    for match in _LD_JSON_RE.finditer(html):
+        try:
+            data = json.loads(match.group(1))
+        except ValueError:
+            continue
+        if not isinstance(data, dict) or data.get("@type") != "Store":
+            continue
+        rating = data.get("aggregateRating")
+        if isinstance(rating, dict):
+            return parse_float(rating.get("ratingValue")), parse_int(rating.get("ratingCount"))
+    return 0.0, 0
+
+
+def parse_shop_detail(
+    html: str, *, shop_id: str, shop_url: str, review_html: str | None = None
+) -> RakumaShopDetailData:
+    """把店铺页 HTML 解析为卖家详情
+
+    Args:
+        review_html: /review 子页的 HTML；给出时才填充评价明细与分档计数
+
+    Raises:
+        ScrapeParseError: 页面不是店铺页
+    """
+    tree = _require_shop_page(html)
+
+    total_count, _, _ = parse_total_count(node_text(tree.css_first(".page-count")))
+    badge = tree.css_first(".badge-status")
+    verification_label = node_text(badge)
+
+    # 简介在侧栏「プロフィール」区块；卖家未填写时站点会写一句占位文案
+    introduction = node_text(tree.css_first("[data-test=profile-text-top]"))
+    if "設定されていません" in introduction:
+        introduction = ""
+
+    score, review_count = _parse_store_rating(html)
+    detail = RakumaShopDetailData(
+        shop_id=shop_id,
+        shop_name=node_text(tree.css_first(".profile-area__shop-name")),
+        user_name=node_text(tree.css_first("[data-test=profile_user_name], .profile-area__user-name")),
+        shop_url=shop_url,
+        icon_url=image_url(tree.css_first(".profile-area__user-icon img")),
+        cover_url=_cover_url(tree),
+        introduction=introduction,
+        review_score=score or parse_float(node_text(tree.css_first(".shop_score__score"))),
+        review_count=review_count,
+        is_verified="未完了" not in verification_label and bool(verification_label),
+        verification_label=verification_label,
+        item_count=total_count,
+    )
+
+    # 用户数值 ID：优先取商品卡片埋点里的 seller_user_id（店铺页所有商品都属于
+    # 该卖家），卖家未设头像时头像地址是站点默认图，取不到 ID。
+    detail.user_id = _seller_user_id(tree) or _user_id_from_icon(detail.icon_url)
+
+    if review_html is not None:
+        review_tree = HTMLParser(review_html)
+        detail.rating_breakdown = _parse_rating_breakdown(review_tree, _ALL_RATINGS_PREFIX)
+        detail.seller_rating_breakdown = _parse_rating_breakdown(review_tree, _SELLER_RATINGS_PREFIX)
+        detail.reviews = _parse_reviews(review_tree)
+
+    return detail
+
+
+def _cover_url(tree: HTMLParser) -> str:
+    """封面图挂在 inline style 的 background url() 里"""
+    cover = tree.css_first(".profile-area__shop-cover")
+    style = attr(cover, "style")
+    start = style.find("url(")
+    if start < 0:
+        return ""
+    end = style.find(")", start)
+    return style[start + 4 : end].strip("'\" ") if end > start else ""
+
+
+def _seller_user_id(tree: HTMLParser) -> str:
+    """从店铺页商品卡片的埋点里取卖家数值 ID"""
+    for node in tree.css("[data-gtm-click], [onclick]"):
+        payload = event_payload(node)
+        user_id = payload.get("seller_user_id")
+        if user_id:
+            return str(user_id)
+    return ""
+
+
+def _user_id_from_icon(icon_url: str) -> str:
+    """从头像地址 https://img.fril.jp/user/{id}/s/{id}.jpg 里取用户数值 ID"""
+    marker = "/user/"
+    start = icon_url.find(marker)
+    if start < 0:
+        return ""
+    rest = icon_url[start + len(marker) :]
+    user_id = rest.split("/", 1)[0]
+    return user_id if user_id.isdigit() else ""
+
+
+def parse_shop_items(
+    html: str, *, shop_id: str, request_url: str, page: int
+) -> RakumaShopItemsData:
+    """把店铺页 HTML 解析为该卖家的商品列表
+
+    Raises:
+        ScrapeParseError: 页面不是店铺页
+    """
+    tree = _require_shop_page(html)
+    items = parse_item_cards(tree)
+    total_count, _, end = parse_total_count(node_text(tree.css_first(".page-count")))
+
+    return RakumaShopItemsData(
+        shop_id=shop_id,
+        shop_name=node_text(tree.css_first(".profile-area__shop-name")),
+        page=page,
+        total_count=total_count,
+        has_more=bool(items) and bool(end) and end < total_count,
+        request_url=request_url,
+        items=items,
+    )