加 /api/cart/* 接口；加购链路完全归 trading

trading 新增 4 条购物车接口（POST /api/cart/{add,status,clear,remove}），全部 Bearer 鉴权、走 SiteInteractor（Playwright + storage_state）。同步把 SiteInteractor 从 gateway URL 解耦——lifespan 总是构造与启停，container 字段 worker_site → site，加 asyncio.Lock 让 HTTP 与 worker 共用同一把锁（同账号串行硬约束）。clear/remove 用 UI 点击 button[aria-label="削除"]，探针回报这是稳定 selector；真账号实测前先用此路径。抽 ichiba 加购字段解析到 app/shared/purchase_contract.py（常量 + inventory_flag_for + basket_domain_of + base_form_fields），原本 scraping 与 trading 重复实现同一段 __INITIAL_STATE__.purchase 解析。进一步发现 README 写的「purchase 块是两服务契约」实际未落地——trading 必须 Playwright 开页（httpx 被 TLS 指纹拦死），本地抽比再调 /api/item_detail 更快更新鲜。删除 scraping 端 PurchaseInfo/PurchaseOption/PurchaseOptionValue 模型、各站 _purchase_info 函数、tests/test_purchase.py。ItemDetailData 保留 purchase_condition / is_sold_out / purchase_unit / sku 等商品状态字段。 README「加购与下单」段重写。 328 测试全绿（含架构测试守住三方互不 import）。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-07-28 17:18:00 +08:00
parent 65e3ed31f8
commit 55c01ae4f5
14 changed files with 934 additions and 536 deletions
@@ -1,187 +0,0 @@
-"""加购信息（purchase 块）解析测试
-
-契约取自各站点前端构造加购请求的逻辑，四个来源的端点与字段名互不相同，
-因此这里逐来源验证「提交到哪里、带哪些固定字段、数量/规格/选项各用哪个字段名」。
-本服务只提供这些数据，不执行加购。
-"""
-from pathlib import Path
-
-import pytest
-
-from app.scraping.parsers.item import parse_item_detail, parse_purchase_options
-from app.scraping.parsers.subsites import parse_subsite_item
-from app.scraping.parsers.subsites.base import SubsitePage
-from app.scraping.parsers.subsites.brandavenue import _resolve_cart_url
-
-FIXTURES = Path(__file__).parent / "fixtures"
-
-ICHIBA_URL = "https://item.rakuten.co.jp/fafachai/tx-300/"
-
-
-def subsite(filename: str, host: str, shop_code: str, item_code: str):
-    return parse_subsite_item(
-        SubsitePage(
-            html=(FIXTURES / filename).read_text(encoding="utf-8"),
-            requested_url=f"https://item.rakuten.co.jp/{shop_code}/{item_code}/",
-            final_url=f"https://{host}/item/{item_code}/",
-            shop_code=shop_code,
-            item_code=item_code,
-            include_sku_variants=True,
-        )
-    )
-
-
-# ---- 市场 ----
-
-def test_ichiba_cart_url_comes_from_item_not_hardcoded(item_state):
-    """basketDomain 逐商品不同（不同店铺落在不同 basket 集群），不能写死"""
-    d = parse_item_detail(item_state, item_url=ICHIBA_URL, shop_code="fafachai", include_sku_variants=True)
-    assert d.purchase.cart_url == "https://ts.sp.basket.step.rakuten.co.jp/rms/mall/bss/cartadd/set"
-
-
-def test_ichiba_form_fields_match_site_contract(item_state):
-    d = parse_item_detail(item_state, item_url=ICHIBA_URL, shop_code="fafachai", include_sku_variants=True)
-    fields = d.purchase.form_fields
-    assert fields["shop_bid"] == str(d.shop.shop_id)
-    assert fields["item_id"] == d.item_id
-    assert fields["__event"] == "ES01_003_001"
-    assert d.purchase.quantity_field == "units"
-    assert d.purchase.variant_field == "variant_id"
-
-
-def test_ichiba_multi_sku_reports_inventory_flag_2_without_prefilled_variant(item_state):
-    """多规格商品必须由调用方选定 SKU，不能预填"""
-    d = parse_item_detail(item_state, item_url=ICHIBA_URL, shop_code="fafachai", include_sku_variants=True)
-    assert d.sku.inventory_type == "multiple"
-    assert d.purchase.form_fields["inventory_flag"] == "2"
-    assert "variant_id" not in d.purchase.form_fields
-
-
-def test_ichiba_single_sku_prefills_its_only_variant(item_state):
-    """单一库存商品规格固定，直接填好，调用方无需再选"""
-    item_state["purchase"]["sku"]["inventoryType"] = "single"
-    item_state["item"]["variantId"] = "4902370549263"
-    d = parse_item_detail(item_state, item_url=ICHIBA_URL, shop_code="fafachai", include_sku_variants=True)
-    assert d.purchase.form_fields["inventory_flag"] == "1"
-    assert d.purchase.form_fields["variant_id"] == "4902370549263"
-
-
-def test_ichiba_selected_variant_id_is_available_from_sku(item_state):
-    """调用方要往 variant_field 里填的值，来自 sku.variants[].variant_id"""
-    d = parse_item_detail(item_state, item_url=ICHIBA_URL, shop_code="fafachai", include_sku_variants=True)
-    assert d.sku.variants[0].variant_id
-
-
-def test_item_without_options_has_no_options_field(item_state):
-    d = parse_item_detail(item_state, item_url=ICHIBA_URL, shop_code="fafachai", include_sku_variants=True)
-    assert d.purchase.options == []
-    assert d.purchase.options_field == ""
-    assert d.purchase.has_required_options is False
-
-
-# ---- 商品选项 ----
-
-def test_options_are_parsed_with_types_and_required_flag(item_with_options_state):
-    d = parse_item_detail(
-        item_with_options_state,
-        item_url="https://item.rakuten.co.jp/kizamu/set-beermug-031/",
-        shop_code="kizamu",
-        include_sku_variants=True,
-    )
-    assert d.purchase.options_field == "choice"
-    assert d.purchase.has_required_options is True
-    types = {o.type for o in d.purchase.options}
-    assert {"select", "text"} <= types
-    required = [o for o in d.purchase.options if o.is_required]
-    assert required and required[0].name
-
-
-def test_select_option_carries_candidate_values(item_with_options_state):
-    d = parse_item_detail(
-        item_with_options_state, item_url="https://x", shop_code="kizamu", include_sku_variants=True
-    )
-    select = next(o for o in d.purchase.options if o.type == "select")
-    assert select.values
-    assert all(v.name for v in select.values)
-
-
-def test_text_option_has_no_candidate_values(item_with_options_state):
-    """自由文本选项由买家填写，没有候选值"""
-    d = parse_item_detail(
-        item_with_options_state, item_url="https://x", shop_code="kizamu", include_sku_variants=True
-    )
-    text = next(o for o in d.purchase.options if o.type == "text")
-    assert text.values == []
-
-
-def test_parse_purchase_options_tolerates_malformed_input():
-    assert parse_purchase_options(None) == []
-    assert parse_purchase_options([None, "x", 1]) == []
-    assert parse_purchase_options([{"id": 1, "name": "a", "type": "select", "values": [None]}])[0].values == []
-
-
-# ---- 楽天ブックス ----
-
-def test_books_item_id_comes_from_cart_form_not_url():
-    """加购要用表单里的 item_id；URL 上的编号是市场侧商品编号，拿去下单会失败"""
-    d = subsite("books_item.html", "books.rakuten.co.jp", "book", "17065211")
-    assert d.item_code == "17065211"
-    assert d.item_id == "20600328"
-    assert d.purchase.form_fields["item_id"] == "20600328"
-
-
-def test_books_cart_endpoint_and_shop_bid():
-    d = subsite("books_item.html", "books.rakuten.co.jp", "book", "17065211")
-    assert d.purchase.cart_url == "https://sp.books.step.rakuten.co.jp/rms/mall/book/bs/Cart"
-    assert d.purchase.form_fields["shop_bid"] == "213310"
-
-
-def test_books_cart_form_has_no_quantity_or_variant_field():
-    """该站表单不支持指定件数与规格，字段名留空以示不可用"""
-    d = subsite("books_item.html", "books.rakuten.co.jp", "book", "17065211")
-    assert d.purchase.quantity_field == ""
-    assert d.purchase.variant_field == ""
-
-
-# ---- Rakuten Fashion ----
-
-@pytest.mark.parametrize(
-    ("cart_url_type", "expected"),
-    [
-        ("6", "https://sp.basket.step.rakuten.co.jp/rms/mall/bss/cartadd/set"),
-        ("5", "https://basket.step.rakuten.co.jp/rms/mall/bs/cartadd/set"),
-        ("1", "https://ts.basket.step.rakuten.co.jp/rms/mall/bs/cartadd/set"),
-        ("https://custom.example.com/cart", "https://custom.example.com/cart"),
-        ("99", ""),
-        ("", ""),
-    ],
-)
-def test_brandavenue_cart_url_type_mapping(cart_url_type, expected):
-    """端点由 cart_url_type 编号映射得到；已经是 URL 时原样使用"""
-    assert _resolve_cart_url(cart_url_type) == expected
-
-
-def test_brandavenue_uses_same_contract_as_ichiba():
-    d = subsite("brandavenue_item.html", "brandavenue.rakuten.co.jp", "stylife", "md7606")
-    assert d.purchase.cart_url == "https://sp.basket.step.rakuten.co.jp/rms/mall/bss/cartadd/set"
-    assert d.purchase.form_fields["shop_bid"] == "279405"
-    assert d.purchase.form_fields["item_id"] == "14674748"
-    assert d.purchase.form_fields["inventory_flag"] == "2"
-    assert d.purchase.quantity_field == "units"
-    assert d.purchase.variant_field == "variant_id"
-
-
-def test_brandavenue_variant_ids_are_usable_for_cart():
-    """variant_field 要填的值就是 sku.variants[].variant_id（来自 inventory_list）"""
-    d = subsite("brandavenue_item.html", "brandavenue.rakuten.co.jp", "stylife", "md7606")
-    assert all(v.variant_id for v in d.sku.variants if v.quantity)
-
-
-# ---- ビックカメラ ----
-
-def test_biccamera_uses_its_own_json_endpoint_without_shop_bid():
-    d = subsite("biccamera_item.html", "biccamera.rakuten.co.jp", "biccamera", "4548736147041")
-    assert d.purchase.cart_url == "https://biccamera.step.rakuten.co.jp/cart/item"
-    assert d.purchase.form_fields == {"item_id": "13873289"}
-    assert d.purchase.quantity_field == "units"
-    assert "shop_bid" not in d.purchase.form_fields
@@ -1,7 +1,8 @@
-"""交易服务 API 测试：健康检查、登录态查询与重载、鉴权
+"""交易服务 API 测试：健康检查、登录态查询与重载、购物车接口、鉴权

-登录态会话被替换为桩，不触达真实站点、不需要真实账号。
+登录态会话与站点交互器都被替换为桩，不触达真实站点、不需要真实账号、不起 Playwright。
 AuthSession 自身的行为（cookie 加载、探测判据）在 tests/test_auth_session.py。
+SiteInteractor 的 DOM 解析纯函数在 tests/test_site_interact.py。
 """
 from __future__ import annotations

@@ -9,7 +10,7 @@ import pytest
 from fastapi.testclient import TestClient

 from app.shared.config import get_settings
-from app.shared.errors import NotLoggedInError
+from app.shared.errors import CartOperationError, NotLoggedInError
 from app.trading.main import create_app
 from app.trading.services.auth_session import AuthStatus

@@ -60,23 +61,91 @@ class StubAuthSession:
        """lifespan 收尾会调用；桩没有真实客户端要关"""


+class StubSiteInteractor:
+    """记录调用并返回固定结果的 SiteInteractor 桩
+
+    真实 SiteInteractor 起 Playwright，本桩不打外网、不开浏览器。
+    通过 fail_with 注入异常可测错误路径（5001/5002）。
+    """
+
+    def __init__(self) -> None:
+        self.add_calls: list[dict] = []
+        self.status_calls = 0
+        self.clear_calls = 0
+        self.remove_calls: list[str] = []
+        self.fail_with: Exception | None = None
+
+    async def add_to_cart_payload(
+        self,
+        *,
+        item_url: str,
+        quantity: int = 1,
+        variant_id: str | None = None,
+        choice: str | list[str] | None = None,
+    ) -> dict:
+        self.add_calls.append(
+            {
+                "item_url": item_url,
+                "quantity": quantity,
+                "variant_id": variant_id,
+                "choice": choice,
+            }
+        )
+        if self.fail_with:
+            raise self.fail_with
+        return {
+            "item_id": "10000382",
+            "shop_bid": "284609",
+            "basket_domain": "https://sp.basket.step.rakuten.co.jp/rms/mall/bss/cartadd/set",
+            "cart_count": 1,
+        }
+
+    async def cart_status(self) -> dict:
+        self.status_calls += 1
+        if self.fail_with:
+            raise self.fail_with
+        return {"logged_in": True, "count": 1, "raw_status": "100"}
+
+    async def clear_cart(self) -> dict:
+        self.clear_calls += 1
+        if self.fail_with:
+            raise self.fail_with
+        return {"removed_count": 1, "cart_count": 0}
+
+    async def remove_item(self, item_id: str) -> dict:
+        self.remove_calls.append(item_id)
+        if self.fail_with:
+            raise self.fail_with
+        return {"removed": True, "item_id": item_id}
+
+    async def close(self) -> None:
+        """lifespan 收尾会调用；桩没有真实浏览器要关"""
+
+
@pytest.fixture
-def client_and_stub():
+def client_and_stubs():
    app = create_app()
    with TestClient(app) as client:
        stub = StubAuthSession()
+        stub_site = StubSiteInteractor()
        app.state.container.auth_session = stub
-        yield client, stub
+        app.state.container.site = stub_site
+        yield client, stub, stub_site


@pytest.fixture
-def client(client_and_stub):
-    return client_and_stub[0]
+def client(client_and_stubs):
+    return client_and_stubs[0]


@pytest.fixture
-def stub(client_and_stub):
-    return client_and_stub[1]
+def stub(client_and_stubs):
+    return client_and_stubs[1]
+
+
+@pytest.fixture
+def stub_site(client_and_stubs):
+    return client_and_stubs[2]


 # ---- 健康检查 ----
@@ -155,3 +224,129 @@ def test_reload_reloads_then_probes(client, stub):
    # 重载后必须立刻探测一次，否则调用方拿不到「这次登录到底成没成」
    assert stub.reloaded == ["rakuten"]
    assert stub.checked == ["rakuten"]
+
+
+# ---- 购物车接口 ----
+
+
+@pytest.mark.parametrize(
+    "path",
+    ["/api/cart/add", "/api/cart/status", "/api/cart/clear", "/api/cart/remove"],
+)
+def test_cart_endpoints_reject_missing_token(client, path):
+    """所有 cart 接口都要 Bearer token"""
+    response = client.post(path, json={})
+    assert response.status_code == 401
+    assert response.json()["code"] == 1001
+
+
+def test_cart_add_happy_path(client, stub_site):
+    """加购成功：返回 added=true 与 cart_count"""
+    response = client.post(
+        "/api/cart/add",
+        json={"item_url": "https://item.rakuten.co.jp/shop/x/", "quantity": 2},
+        headers=AUTH,
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["data"]["added"] is True
+    assert body["data"]["item_id"] == "10000382"
+    assert body["data"]["shop_bid"] == "284609"
+    assert body["data"]["cart_count"] == 1
+    # 桩记下了入参
+    assert stub_site.add_calls == [
+        {
+            "item_url": "https://item.rakuten.co.jp/shop/x/",
+            "quantity": 2,
+            "variant_id": None,
+            "choice": None,
+        }
+    ]
+
+
+def test_cart_add_missing_item_url(client):
+    """item_url 必填，缺失时 Pydantic 在校验层挡下（422）"""
+    response = client.post("/api/cart/add", json={"quantity": 1}, headers=AUTH)
+    assert response.status_code == 422
+    assert response.json()["code"] == 1002
+
+
+def test_cart_add_propagates_not_logged_in(client, stub_site):
+    """SiteInteractor 抛 NotLoggedInError（5001）→ HTTP 401"""
+    stub_site.fail_with = NotLoggedInError(site="rakuten", detail="stub")
+    response = client.post(
+        "/api/cart/add",
+        json={"item_url": "https://item.rakuten.co.jp/shop/x/"},
+        headers=AUTH,
+    )
+    assert response.status_code == 401
+    assert response.json()["code"] == 5001
+
+
+def test_cart_add_propagates_cart_error(client, stub_site):
+    """SiteInteractor 抛 CartOperationError（5002）→ HTTP 400"""
+    stub_site.fail_with = CartOperationError("商品不可购买：purchaseCondition=disabled")
+    response = client.post(
+        "/api/cart/add",
+        json={"item_url": "https://item.rakuten.co.jp/shop/x/"},
+        headers=AUTH,
+    )
+    assert response.status_code == 400
+    assert response.json()["code"] == 5002
+
+
+def test_cart_status_happy_path(client, stub_site):
+    response = client.post("/api/cart/status", json={}, headers=AUTH)
+    assert response.status_code == 200
+    body = response.json()
+    assert body["data"]["logged_in"] is True
+    assert body["data"]["count"] == 1
+    assert body["data"]["raw_status"] == "100"
+    assert stub_site.status_calls == 1
+
+
+def test_cart_clear_happy_path(client, stub_site):
+    response = client.post("/api/cart/clear", json={}, headers=AUTH)
+    assert response.status_code == 200
+    body = response.json()
+    assert body["data"]["removed_count"] == 1
+    assert body["data"]["cart_count"] == 0
+    assert stub_site.clear_calls == 1
+
+
+def test_cart_remove_happy_path(client, stub_site):
+    response = client.post(
+        "/api/cart/remove", json={"item_id": "10000382"}, headers=AUTH
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["data"]["removed"] is True
+    assert body["data"]["item_id"] == "10000382"
+    assert stub_site.remove_calls == ["10000382"]
+
+
+def test_cart_remove_missing_item_id(client):
+    response = client.post("/api/cart/remove", json={}, headers=AUTH)
+    assert response.status_code == 422
+    assert response.json()["code"] == 1002
+
+
+def test_cart_remove_propagates_cart_error(client, stub_site):
+    """指定 item_id 不在购物车里 → 5002"""
+    stub_site.fail_with = CartOperationError("购物车里没有 item_id=99999")
+    response = client.post(
+        "/api/cart/remove", json={"item_id": "99999"}, headers=AUTH
+    )
+    assert response.status_code == 400
+    assert response.json()["code"] == 5002
+
+
+def test_cart_endpoints_unavailable_when_site_is_none(client):
+    """SiteInteractor 未就绪（container.site 为 None）→ UpstreamRequestError 3001
+
+    生产环境 lifespan 一定构造了 site；本测试模拟异常启动路径。
+    """
+    client.app.state.container.site = None
+    response = client.post("/api/cart/status", json={}, headers=AUTH)
+    assert response.status_code == 400
+    assert response.json()["code"] == 3001