rakuten-api/app/scraping/api/routes/rakuma.py

"""抓取路由：ラクマ（fril.jp）的搜索、分类、商品详情与卖家

单独挂在 /api/rakuma 前缀下，不与乐天市场的接口合并：两站的筛选参数体系
差异很大（乐天有 genre_id / 成色 / SuperDEAL，ラクマ 有 category_id /
brand_id / 匿名配送 / 鉴定服务），合并会让大半字段对另一站无效。
"""
from fastapi import APIRouter, Depends

from app.shared.api import ApiResponse, get_container, require_bearer_token
from app.scraping.container import ScrapingContainer
from app.scraping.models.scrape import (
    RakumaCategoryData,
    RakumaCategoryRequest,
    RakumaItemDetailData,
    RakumaItemDetailRequest,
    RakumaSearchRequest,
    RakumaSearchResultData,
    RakumaShopDetailData,
    RakumaShopDetailRequest,
    RakumaShopItemsData,
    RakumaShopItemsRequest,
)

router = APIRouter(prefix="/api/rakuma", tags=["rakuma"])


@router.post(
    "/search",
    response_model=ApiResponse[RakumaSearchResultData],
    dependencies=[Depends(require_bearer_token)],
)
async def search(
    payload: RakumaSearchRequest,
    container: ScrapingContainer = Depends(get_container),
) -> ApiResponse[RakumaSearchResultData]:
    """搜索 ラクマ 商品列表

    支持关键词、分类、品牌、价格区间、商品状态（6 档成色，可多选）、
    在售/售罄、免运费、匿名配送等筛选；也可以直接传 search_url 透传一条
    fril.jp 搜索页地址。

    每页固定 40 条，站点侧最多翻到第 100 页（page > 100 直接 404）。
    """
    data = await container.rakuma_client.search(payload)
    return ApiResponse[RakumaSearchResultData](
        success=True,
        msg="success",
        data=data,
        code=0,
    )


@router.post(
    "/categories",
    response_model=ApiResponse[RakumaCategoryData],
    dependencies=[Depends(require_bearer_token)],
)
async def categories(
    payload: RakumaCategoryRequest,
    container: ScrapingContainer = Depends(get_container),
) -> ApiResponse[RakumaCategoryData]:
    """获取 ラクマ 分类树，用于取得 /api/rakuma/search 需要的 category_id

    不传 category_id 返回 14 个顶层分类；传入后返回该分类的名称、祖先路径与
    直接子分类。分类共三层，逐层下钻即可定位到叶子分类。

    站点一次请求就返回整棵树，所以把 include_descendants 置为 true 可以直接
    拿到该分类下的完整子树，不会多花请求。

    站点分类数据里没有商品数（要逐个分类另抓一次页面才有），因此本接口不返回。
    """
    data = await container.rakuma_client.categories(payload)
    return ApiResponse[RakumaCategoryData](
        success=True,
        msg="success",
        data=data,
        code=0,
    )


@router.post(
    "/item_detail",
    response_model=ApiResponse[RakumaItemDetailData],
    dependencies=[Depends(require_bearer_token)],
)
async def item_detail(
    payload: RakumaItemDetailRequest,
    container: ScrapingContainer = Depends(get_container),
) -> ApiResponse[RakumaItemDetailData]:
    """获取 ラクマ 商品详情

    传 item_id（商品页 URL 的最后一段 hash），或直接传 item_url。
    返回名称、价格、描述、图片、成色、配送信息与出品者摘要。

    ラクマ 是 C2C 集市，每件商品都是单件的：没有 SKU 组合，也没有库存数量。
    响应里的 seller.shop_id 可直接用于 /api/rakuma/shop_detail。
    """
    data = await container.rakuma_client.item_detail(payload)
    return ApiResponse[RakumaItemDetailData](
        success=True,
        msg="success",
        data=data,
        code=0,
    )


@router.post(
    "/shop_detail",
    response_model=ApiResponse[RakumaShopDetailData],
    dependencies=[Depends(require_bearer_token)],
)
async def shop_detail(
    payload: RakumaShopDetailRequest,
    container: ScrapingContainer = Depends(get_container),
) -> ApiResponse[RakumaShopDetailData]:
    """获取 ラクマ 卖家（出品者）详情

    传 shop_id（店铺页 URL 的最后一段 hash），或直接传 shop_url。
    返回店铺名、昵称、头像与封面、简介、评分与评价数、本人确认状态、
    以及该卖家的商品总数。

    评价明细（最新 100 条）与好评/普通/差评分档计数在站点的单独子页上，
    需要多打一次请求，把 include_reviews 置为 true 才会返回。
    """
    data = await container.rakuma_client.shop_detail(payload)
    return ApiResponse[RakumaShopDetailData](
        success=True,
        msg="success",
        data=data,
        code=0,
    )


@router.post(
    "/shop_items",
    response_model=ApiResponse[RakumaShopItemsData],
    dependencies=[Depends(require_bearer_token)],
)
async def shop_items(
    payload: RakumaShopItemsRequest,
    container: ScrapingContainer = Depends(get_container),
) -> ApiResponse[RakumaShopItemsData]:
    """获取 ラクマ 卖家名下的商品列表

    传 shop_id 或 shop_url，按页取该卖家的全部商品（含已售出，
    用每条的 is_sold_out 区分）。

    站点在店铺页不提供排序与筛选参数，因此这里只有页码；需要筛选请改用
    /api/rakuma/search。
    """
    data = await container.rakuma_client.shop_items(payload)
    return ApiResponse[RakumaShopItemsData](
        success=True,
        msg="success",
        data=data,
        code=0,
    )