From b577d3ac8df4dff6bc7bb8ef590dd96bafc3d954 Mon Sep 17 00:00:00 2001 From: Jerry Yan <792602257@qq.com> Date: Fri, 28 Aug 2026 16:07:33 +0800 Subject: [PATCH] =?UTF-8?q?fix(trading):=20=E5=BF=85=E5=A1=AB=E9=80=89?= =?UTF-8?q?=E9=A1=B9=E8=87=AA=E5=8A=A8=E5=A1=AB=E5=80=BC=E8=B7=B3=E8=BF=87?= =?UTF-8?q?=E3=80=8C=E9=81=B8=E6=8A=9E=E3=81=97=E3=81=A6=E3=81=8F=E3=81=A0?= =?UTF-8?q?=E3=81=95=E3=81=84=E3=80=8D=E5=8D=A0=E4=BD=8D=E9=A1=B9=EF=BC=8C?= =?UTF-8?q?=E5=B9=B6=E6=8A=8A=E9=80=89=E9=A1=B9=E5=BC=80=E6=94=BE=E7=BB=99?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit trading 自动填 choice 时取 values[0]，而必填 select 的 values[0] 恒为 id=0 的 「選択してください」——等于把「请选择」当答案提交。4 份真实样本一致（真值从 id=200 起）。同时 /api/item_detail 完全不返回 options，调用方即使想显式指定 choice 也无从知道合法取值。 - purchase_contract.py：新增 ItemOption / ItemOptionValue 与 parse_options / auto_choice_for / format_choice。占位判定以结构为主（value_id == 0），日文 文案仅作兜底。放 shared 是因为「接口声明的合法取值」与「下单实际提交的值」 必须同源，否则两边各判一次迟早再次分叉 - item.py / scrape.py：ItemDetailData 增 options、has_required_options、 unfillable_required_options；只解析一次，两个派生结果都取自同一份结果 - site_interact.py：auto_choice_for 取第一个非占位候选；必填项填不出值时 报错点名是哪些选项，让调用方知道该在 intent.choice 里补什么 - auto_choice_for 只自动填必填项：非必填项要不要选是业务决定，不是我们该替 调用方做的选择 - README / docs：补 options[] → intent.choice、variants[] → intent.variant_id 的对照，修掉 order-gateway 示例里已不存在的 "options": {} 字段 真账号验证（scripts/probe_option_choice.py，仅加购不结算不支付）：两个商品 提交 確認した / 了解致しました。均被站点接受，购物车 count=2，跑完清空恢复 原状。探针刻意走生产的 add_to_cart_payload 并从其日志截获实际 payload—— probe_purchase_block_v2.py 自己抄了一遍字段构造，与生产代码同错，正是这个 bug 当初藏住的原因。 未覆盖：这两家店铺本身不校验该选项（旧的占位值当年也被收下），所以只证明新值 走得通、语义上才是真答案，证明不了旧值会被拒；必填自由文本项（ unfillable_required_options）无真实样本，仅离线测试覆盖。 Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 26 ++- app/scraping/models/scrape.py | 55 ++++++- app/scraping/parsers/item.py | 43 ++++- app/shared/purchase_contract.py | 176 +++++++++++++++++++- app/trading/worker/site_interact.py | 46 ++++-- docs/order-gateway.md | 4 +- scripts/probe_option_choice.py | 245 ++++++++++++++++++++++++++++ tests/test_parsers.py | 73 +++++++++ tests/test_site_interact.py | 89 ++++++++++ 9 files changed, 731 insertions(+), 26 deletions(-) create mode 100644 scripts/probe_option_choice.py diff --git a/README.md b/README.md index 9409aa9..9e81611 100644 --- a/README.md +++ b/README.md @@ -373,6 +373,20 @@ docker compose --profile gateway up -d 搜索结果中的 `shop.shop_code` + `item_code` 可直接用作本接口入参。 +**下单前要决定的参数全在响应里**（规格与选项是两套东西，下单时走不同字段）： + +| 字段 | 下单时对应 | 说明 | +| --- | --- | --- | +| `sku.variants[].variant_id` | `intent.variant_id` | 规格组合（颜色 × 尺码等） | +| `options[]` | `intent.choice` | 店铺自定义选项，格式「选项名:取值名」 | +| `has_required_options` | — | `true` 时不给 `choice` 会被站点拒绝加购 | +| `unfillable_required_options` | — | 必填但无法自动选值的选项名，**必须**由调用方给值 | + +`options[].values[].is_placeholder` 标出「選択してください」这类占位项——它们不是 +合法取值，拼 `choice` 时要跳过（`selectable_value_count` 已是剔除占位项后的数量）。 +`type="text"` 的选项是自由文本（如「【お名前】4文字まで」），站点不给候选值， +必填时只能由调用方给值。 + 部分官方店的商品页会跳转到独立子站，响应里的 `source` / `source_url` 会标明数据来源， 字段覆盖差异见下一节。 @@ -432,6 +446,7 @@ docker compose --profile gateway up -d | `review` | ✅ | ✅ | ❌ 异步加载 | ❌ 异步加载 | | `sku.variants`（规格组合） | ✅ | — 图书无规格 | ✅ 颜色 × 尺码 | — 单一规格 | | `sku.attributes`（规格表） | ✅ | ✅ 出版社/ISBN 等 | 挂在各 variant 上 | ❌ | +| `options`（店铺自定义选项） | ✅ | ❌ 未解析 | ❌ 未解析 | ❌ 未解析 | | `shipping` 运费明细 | ✅ | ❌ 仅库存措辞 | ❌ | 仅「是否含运费」 | | `shop.shop_id` | ✅ | ❌ | ✅ | ✅ | | `breadcrumbs[].url` | ✅ | ✅ | ❌ 站内分类编码，拼不出链接 | ✅ | @@ -602,6 +617,8 @@ docker compose --profile gateway up -d | `purchase_unit` | 起订单位 | | `sku.inventory_type` | `multiple` 表示多规格，要看 `sku.variants[]` | | `sku.variants[].variant_id` | 多规格商品的规格 ID（trading 加购多规格时按此选择） | +| `options[]` | 店铺自定义选项（必填项不给值站点拒绝加购），加购时走 `choice` 字段 | +| `unfillable_required_options` | 必填但无法自动选值的选项名，必须由调用方显式给值 | 交易服务对外接口（:31108，全部需要 Bearer token）： @@ -611,8 +628,13 @@ docker compose --profile gateway up -d - `POST /api/cart/clear` — 清空购物车（UI 点击 `button[aria-label="削除"]`） - `POST /api/cart/remove` — 删除指定 `item_id` -底层共用 `app/shared/purchase_contract.py` 的常量与字段构造（与 scraping 模型解耦）。 -trading 加购时的字段选择策略：多规格挑第一个非售罄的 variant；必填选项拼「名:值」。 +底层共用 `app/shared/purchase_contract.py` 的常量、字段构造与**选项解析**（与 scraping +模型解耦）——`/api/item_detail` 对外暴露的 `options[]` 和 trading 自动填 `choice` 用的 +是同一份解析与占位项判定，避免「接口说能选的值」与「下单实际填的值」不一致。 +trading 加购时的字段选择策略：多规格挑第一个非售罄的 variant；必填选项拼「名:值」， +取第一个**非占位**候选值（`values[0]` 往往是「選択してください」，填它等于没选）。 +必填项自动填不出来（自由文本项、候选值只剩占位项）且调用方没给 `choice` 时当场报错 +并点名是哪几项，不拿占位值凑数去撞站点。 站点端点 `basketDomain` 逐商品不同（实测有 `sp.basket…` 与 `ts.sp.basket…`），不能写死。 几点子站差异（仅信息，trading 不覆盖子站加购）： diff --git a/app/scraping/models/scrape.py b/app/scraping/models/scrape.py index 67c7877..1d932c7 100644 --- a/app/scraping/models/scrape.py +++ b/app/scraping/models/scrape.py @@ -338,6 +338,43 @@ class SkuInfo(BaseModel): 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): """配送与运费信息""" @@ -365,7 +402,8 @@ class ItemDetailData(BaseModel): 加购（构造 cart 请求）不在本服务范围内——加购需要已登录的乐天账号会话， 归 trading 服务（app.trading）。本响应只描述「商品状态」：能不能买 - （purchase_condition / is_sold_out）、规格（sku.variants）、起订单位等。 + （purchase_condition / is_sold_out）、规格（sku.variants）、起订单位、 + 店铺自定义选项（options）等，即「下单前需要先决定哪些参数」。 """ source: str = Field(default="ichiba", description="数据来源站点：ichiba / books / brandavenue / biccamera") @@ -390,6 +428,21 @@ class ItemDetailData(BaseModel): 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): diff --git a/app/scraping/parsers/item.py b/app/scraping/parsers/item.py index cafc121..ee34ab5 100644 --- a/app/scraping/parsers/item.py +++ b/app/scraping/parsers/item.py @@ -11,9 +11,13 @@ from __future__ import annotations from typing import Any from app.shared.errors import ScrapeParseError +from app.shared.purchase_contract import ItemOption as SharedItemOption +from app.shared.purchase_contract import auto_choice_for, parse_options from app.scraping.models.scrape import ( Breadcrumb, ItemDetailData, + ItemOption, + ItemOptionValue, ReviewSummary, ShippingInfo, ShopSummary, @@ -31,6 +35,33 @@ _PURCHASABLE_CONDITION = "enabled" # 库存类型 → 加购表单里的 inventory_flag（常量与基础字段构造在 app.shared.purchase_contract） +def _to_item_options(options: list[SharedItemOption]) -> list[ItemOption]: + """把共用契约的 ItemOption dataclass 搬成对外的 pydantic 模型 + + 解析与占位项判定都在 `app.shared.purchase_contract.parse_options`——trading + 下单时用同一份逻辑挑 choice 取值，两侧对「哪个取值是合法的」必须完全一致， + 否则本接口告诉上游能选的值、下单时却填了别的。本函数只做搬运，不加判断。 + """ + return [ + ItemOption( + option_id=option.option_id, + name=option.name, + type=option.type, + is_required=option.is_required, + values=[ + ItemOptionValue( + value_id=value.value_id, + name=value.name, + is_placeholder=value.is_placeholder, + ) + for value in option.values + ], + selectable_value_count=len(option.selectable_values), + ) + for option in options + ] + + def _parse_attributes(raw: Any) -> list[SkuAttribute]: return [ SkuAttribute(title=as_str(attr.get("title")), value=as_str(attr.get("value"))) @@ -115,6 +146,13 @@ def parse_item_detail( sell_type = _pick_sell_type(as_dict(purchase.get("sellType"))) purchase_condition = as_str(sell_type.get("purchaseCondition")) + purchase_information = as_dict(purchase.get("information")) + # 只解析一次，两个派生结果都从这份结果来 + shared_options = parse_options(purchase_information) + # 无法自动选值的必填项：与 trading 自动填 choice 时的判定同源，上游据此知道 + # 「哪些项必须自己给值」，而不是等下单时才被站点拒绝 + _, unfillable_required = auto_choice_for(shared_options) + raw_sku = as_dict(purchase.get("sku")) variants = _parse_variants(raw_sku.get("variants")) sku = SkuInfo( @@ -188,7 +226,7 @@ def parse_item_detail( purchase_condition=purchase_condition, # purchaseCondition 是站点判定能否下单的直接依据；缺失时不臆断为售罄 is_sold_out=bool(purchase_condition) and purchase_condition != _PURCHASABLE_CONDITION, - purchase_unit=as_int(as_dict(purchase.get("information")).get("unit")), + purchase_unit=as_int(purchase_information.get("unit")), images=images, shop=shop, review=review, @@ -196,4 +234,7 @@ def parse_item_detail( breadcrumbs=breadcrumbs, shipping=shipping, sku=sku, + options=_to_item_options(shared_options), + has_required_options=any(option.is_required for option in shared_options), + unfillable_required_options=unfillable_required, ) diff --git a/app/shared/purchase_contract.py b/app/shared/purchase_contract.py index 990d6f5..0a41eee 100644 --- a/app/shared/purchase_contract.py +++ b/app/shared/purchase_contract.py @@ -9,11 +9,13 @@ - `inventory_flag_for(inventory_type)` — 多规格判定 - `basket_domain_of(sell_type)` — 抽 basketDomain + 反转义 `\\u002F` - `base_form_fields(shop_id, item_id, inventory_flag)` — 加购表单四件套 +- `parse_options(information)` — 店铺自定义选项（`purchase.information.options[]`） + 的结构化解析，含占位值识别；scraping 用它对外暴露选项，trading 用它自动填 choice +- `auto_choice_for(options)` / `format_choice(...)` — choice 表单值的构造 **不**放这里： - `PurchaseInfo` pydantic 模型 — 是 scraping 的对外契约，4 个子站共用，留在 scraping/models -- variant_id / choice 自动选择策略 — trading 独有（scraping 把决策权留给上游） -- options 结构化解析 — scraping 独有（trading 用原始 dict） +- variant_id 自动选择策略 — trading 独有（scraping 把决策权留给上游） - 子站（books/biccamera/brandavenue）的加购契约 — 各自独立，不走这里 依赖约束：仅 `typing.Any`（标准库），不 import scraping / trading / gateway， @@ -21,6 +23,7 @@ """ from __future__ import annotations +from dataclasses import dataclass, field from typing import Any # 站点前端构造加购表单时固定带的事件标识（普通购买 normalPurchase） @@ -76,3 +79,172 @@ def base_form_fields( "inventory_flag": inventory_flag, "__event": NORMAL_PURCHASE_EVENT, } + + +# ---- 店铺自定义选项（purchase.information.options[]）---- +# +# 「規格（SKU）」与「選項（option）」是两套完全不同的东西，加购表单里也走不同字段： +# - 規格：sku.variants[].variantId → 表单 variant_id +# - 選項：店铺自己配的下拉/文本框（名入れ文字、配送方式确认、レビュー依頼 等） +# → 表单 choice，格式「名:值」，多项用「,」连接 +# +# 2026-08-28 用 .probe/ 下 3 份真实商品页样本 + tests/fixtures/item_with_options_state.json +# 核对过结构，得到两条**结构性**判据（比按日文文案猜稳）： +# +# 1. `values[].id == 0` 是「請選擇」占位项，不是可提交的取值。三份真实样本里所有 +# 必填 select 的 values[0] 都是 id=0 的「選択してください」，真实可选值从 id=200 +# 起编号。此前 trading 侧自动填 choice 时取的就是 values[0]，等于把「選択して +# ください」当答案提交上去（.probe/checkout/probe-v2.txt 里两条 "成功" 记录的 +# choice 值就是它）——站点当时收下了，但那是店铺没做校验，不代表填对了。 +# 2. `type == "text"` 的选项没有 values[]（自由文本，如「【お名前】4文字まで」）， +# **无法**自动填。必填且为 text 时只能交由调用方给值，不猜。 +# +# 占位项文案本身（「選択してください」）作为辅助判据一起保留：id 编号规则是从 4 份 +# 样本归纳的，万一某店铺不按 200 起编号，文案还能兜一层。两条判据命中任一即占位。 +_PLACEHOLDER_VALUE_ID: int = 0 +_PLACEHOLDER_VALUE_NAMES: frozenset[str] = frozenset({"選択してください", "選択して下さい"}) + +# 选项类型：下拉（有候选值）与自由文本（无候选值） +OPTION_TYPE_SELECT: str = "select" +OPTION_TYPE_TEXT: str = "text" + +# choice 表单值的分隔符：项间用「,」，名与值之间用「:」 +_CHOICE_PAIR_SEPARATOR: str = "," +_CHOICE_NAME_VALUE_SEPARATOR: str = ":" + + +@dataclass(slots=True) +class ItemOptionValue: + """选项的一个候选取值 + + `is_placeholder=True` 表示这是「選択してください」这类占位项，提交它等于没选。 + """ + + value_id: int | None + name: str + is_placeholder: bool = False + + +@dataclass(slots=True) +class ItemOption: + """一个店铺自定义选项 + + `is_free_text` 为 True 时 values 必然为空（站点 type="text"），取值只能由 + 调用方给；`selectable_values` 是剔掉占位项后真正可提交的候选。 + """ + + option_id: int | None + name: str + type: str + is_required: bool + values: list[ItemOptionValue] = field(default_factory=list) + + @property + def is_free_text(self) -> bool: + return self.type == OPTION_TYPE_TEXT + + @property + def selectable_values(self) -> list[ItemOptionValue]: + return [value for value in self.values if not value.is_placeholder] + + @property + def can_auto_fill(self) -> bool: + """能否在不问调用方的情况下自动给出一个合法取值""" + return bool(self.selectable_values) + + +def _coerce_option_id(raw: Any) -> int | None: + """选项/取值的 id 收敛为 int；给不出数字时返回 None（不编造 0——0 有含义）""" + if isinstance(raw, bool) or not isinstance(raw, (int, float, str)): + return None + try: + return int(raw) + except (TypeError, ValueError): + return None + + +def _parse_option_value(raw: Any) -> ItemOptionValue | None: + """解析单个候选取值；不是 dict 或没有名字的直接丢掉""" + if not isinstance(raw, dict): + return None + name = raw.get("name") + if not isinstance(name, str) or not name: + return None + value_id = _coerce_option_id(raw.get("id")) + is_placeholder = value_id == _PLACEHOLDER_VALUE_ID or name.strip() in _PLACEHOLDER_VALUE_NAMES + return ItemOptionValue(value_id=value_id, name=name, is_placeholder=is_placeholder) + + +def parse_options(information: Any) -> list[ItemOption]: + """从 `purchase.information` 解析店铺自定义选项列表 + + `information` 传站点原始 dict（不是 options 数组本身）；结构不符合预期时返回 + 空列表——**没有选项与解析不出选项在站点数据上长得一样**（缺 options 键）， + 这一层区分不出来，也不该假装能区分。 + """ + if not isinstance(information, dict): + return [] + raw_options = information.get("options") + if not isinstance(raw_options, list): + return [] + + options: list[ItemOption] = [] + for raw in raw_options: + if not isinstance(raw, dict): + continue + name = raw.get("name") + if not isinstance(name, str) or not name: + continue + raw_type = raw.get("type") + option_type = raw_type if isinstance(raw_type, str) else "" + values = [ + value + for value in (_parse_option_value(item) for item in raw.get("values") or []) + if value is not None + ] + options.append( + ItemOption( + option_id=_coerce_option_id(raw.get("id")), + name=name, + type=option_type, + is_required=bool(raw.get("isRequired")), + values=values, + ) + ) + return options + + +def format_choice(pairs: Any) -> str: + """把「名:值」序列拼成站点 choice 表单值 + + 接受 str（原样透传，调用方自己拼好的）或可迭代的字符串序列。 + """ + if isinstance(pairs, str): + return pairs + return _CHOICE_PAIR_SEPARATOR.join(str(pair) for pair in pairs) + + +def auto_choice_for(options: list[ItemOption]) -> tuple[str, list[str]]: + """为必填选项自动挑取值，返回 (choice 表单值, 无法自动填的必填项名) + + 策略：每个必填选项取**第一个非占位**候选值，拼成「名:值」。自由文本必填项 + （type="text"，没有候选值）与候选值全是占位项的选项都自动填不了，其名字进 + 第二个返回值——调用方据此决定报错还是要求上游显式给 choice，**不拿占位值 + 凑数**（那正是本次修复的问题）。 + + 只处理必填项：非必填项站点不强制，替上游擅自选（比如「置き配を希望する」） + 等于替人做了业务决定。 + """ + pairs: list[str] = [] + unfillable: list[str] = [] + for option in options: + if not option.is_required: + continue + selectable = option.selectable_values + if not selectable: + unfillable.append(option.name) + continue + pairs.append( + f"{option.name}{_CHOICE_NAME_VALUE_SEPARATOR}{selectable[0].name}" + ) + return format_choice(pairs), unfillable diff --git a/app/trading/worker/site_interact.py b/app/trading/worker/site_interact.py index cbd11ea..4ef34a2 100644 --- a/app/trading/worker/site_interact.py +++ b/app/trading/worker/site_interact.py @@ -109,9 +109,12 @@ from app.shared.errors import ( from app.shared.purchase_contract import ( INVENTORY_FLAG_DEFAULT, INVENTORY_FLAG_MULTIPLE, + auto_choice_for, base_form_fields, basket_domain_of, + format_choice, inventory_flag_for, + parse_options, ) from app.shared.proxy import playwright_launch_proxy from app.shared.task_state import OrderState @@ -1102,10 +1105,18 @@ class SiteInteractor: raise CartOperationError( "多规格商品未选 variant，且 sku.variants 全部售罄或为空" ) - # 必填选项要求填了 choice - if fields["has_required_options"] and not fields["form_fields"].get(fields["options_field"]): + # 必填选项要求填了 choice。调用方没给 choice 时，只要存在「自动填不了」 + # 的必填项（自由文本项，或候选值只剩占位项）就当场失败并点名是哪几项—— + # 这些项非人工给值不可能成功，继续 POST 只会拿站点的 + # 「未選択の項目からどれか１つ選んでください。」错误页，排查成本更高 + if fields["has_required_options"] and not fields["form_fields"].get( + fields["options_field"] + ): + unfillable = fields["unfillable_required_options"] + detail = f"：{unfillable}" if unfillable else "" raise CartOperationError( - "商品有必填选项但未提供 choice，且选项无候选值" + "商品有必填选项但未提供 choice，且这些必填项无法自动选值" + f"（需在 intent.choice 里按「选项名:取值名」显式给出）{detail}" ) payload = dict(fields["form_fields"]) @@ -2421,22 +2432,18 @@ def _extract_purchase_fields(state: dict, *, intent_override: dict | None) -> di elif inventory_flag == INVENTORY_FLAG_DEFAULT and item.get("variantId"): form_fields["variant_id"] = str(item.get("variantId")) - # 必填选项：调用方覆盖 > 自动填第一个候选值 - options = information.get("options") or [] - required_options = [o for o in options if o.get("isRequired")] - has_required = bool(required_options) + # 必填选项：调用方覆盖 > 自动填第一个**非占位**候选值 + # 解析与占位项判定走 app.shared.purchase_contract（与 scraping 的 + # /api/item_detail 同源），旧实现直接取 values[0]，而必填 select 的 values[0] + # 恰恰是「選択してください」占位项，等于把「请选择」当答案提交上去。 + options = parse_options(information) + has_required = any(option.is_required for option in options) + auto_choice, unfillable_required = auto_choice_for(options) if intent_override.get("choice"): - # 调用方给的可能是 list 或 str - c = intent_override["choice"] - form_fields["choice"] = ",".join(c) if isinstance(c, list) else str(c) - elif has_required: - pairs: list[str] = [] - for opt in required_options: - values = opt.get("values") or [] - if values: - pairs.append(f"{opt.get('name')}:{values[0].get('name')}") - if pairs: - form_fields["choice"] = ",".join(pairs) + # 调用方给的可能是 list 或 str，两种都交给共用的格式化 + form_fields["choice"] = format_choice(intent_override["choice"]) + elif auto_choice: + form_fields["choice"] = auto_choice return { "basket_domain": basket_domain, @@ -2446,6 +2453,9 @@ def _extract_purchase_fields(state: dict, *, intent_override: dict | None) -> di "options_field": "choice" if options else "", "options": options, "has_required_options": has_required, + # 必填但自动填不了的选项名（自由文本项，或候选值只有占位项）。调用方没给 + # choice 时这就是「非人工介入不可能成功」的直接依据，见 _add_to_cart_with_fields + "unfillable_required_options": unfillable_required, "inventory_flag": inventory_flag, "purchase_condition": sell_type.get("purchaseCondition"), "min_price": sell_type.get("minPrice"), diff --git a/docs/order-gateway.md b/docs/order-gateway.md index 2f9914d..2a5bee6 100644 --- a/docs/order-gateway.md +++ b/docs/order-gateway.md @@ -114,8 +114,8 @@ CREATE TABLE workers ( "intent": { // gateway 原样透传，结构由 trading 侧定义 "item_url": "https://item.rakuten.co.jp/shop/code/", "quantity": 1, - "variant_id": "...", // 多规格商品必填 - "options": {}, + "variant_id": "...", // 多规格商品必填，取自 /api/item_detail 的 sku.variants[] + "choice": ["名入れ:希望する"], // 店铺自定义必填选项，格式「选项名:取值名」，取自 /api/item_detail 的 options[] "max_total_yen": 30000 // 可选，覆盖本次的金额上限 }, "callback_url": "https://upstream.example.com/hooks/rakuten-order" // 可选，终结类事件通知，见 §4.8 diff --git a/scripts/probe_option_choice.py b/scripts/probe_option_choice.py new file mode 100644 index 0000000..87cf7c2 --- /dev/null +++ b/scripts/probe_option_choice.py @@ -0,0 +1,245 @@ +"""必填选项 choice 取值的真账号验证：占位项修复是否真的被站点接受 + +背景：2026-08-28 发现 trading 自动填 choice 时取 `values[0]`，而必填 select 的 +values[0] 恒为 id=0 的「選択してください」占位项，等于把「请选择」当答案提交。 +修复后取第一个非占位候选（见 app/shared/purchase_contract.py::auto_choice_for）。 + +离线测试只能证明「我们填的值变了」，证明不了「站点接受这个值」——后者必须真账号 +实测。本探针就为这一件事。 + +**刻意走生产代码路径**（SiteInteractor.add_to_cart_payload），不重写字段构造逻辑： +上一版探针 scripts/probe_purchase_block_v2.py 自己抄了一遍 form 构造，结果那份 +抄写与生产代码一起用了 values[0]，两边同错就测不出问题。实际提交的 payload 从 +生产代码自己的 INFO 日志里抓（「加购请求：basket=... payload=...」），确保记录的 +就是真正发出去的东西。 + +安全边界： +- 只做「清空购物车 → 加购 → 校验 → 清空购物车」，**绝不进入结算/支付** +- 加购完立即清空，账号购物车恢复原状（加购本身可逆，不产生订单、不扣款） +- 不触碰 enter_checkout / submit_order / pay + +用法： + .venv/Scripts/python.exe scripts/probe_option_choice.py +""" +from __future__ import annotations + +import asyncio +import json +import logging +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from app.shared.config import get_settings # noqa: E402 +from app.shared.errors import AppError # noqa: E402 +from app.shared.purchase_contract import auto_choice_for, parse_options # noqa: E402 +from app.trading.services.auth_session import AuthSession # noqa: E402 +from app.trading.worker.site_interact import ( # noqa: E402 + SiteInteractor, + _parse_initial_state, +) + +PROBE_DIR = Path(__file__).resolve().parent.parent / ".probe" / "options_choice" +PROBE_DIR.mkdir(parents=True, exist_ok=True) + +# 目标商品：从 .probe/checkout/ 的历史样本里挑「有必填选项且占位项在 values[0]」的两个。 +# 这两个正是旧实现填「選択してください」也被站点收下的商品——它们不能证明旧值是对的 +# （店铺没做校验），但可以验证新值同样被接受，且是站点自己给的唯一非占位候选。 +TARGETS = ( + "https://item.rakuten.co.jp/waabbit/088-4p", + "https://item.rakuten.co.jp/aoimorinomise/121", +) + + +class _PayloadCapture(logging.Handler): + """截获生产代码 `加购请求：basket=%s payload=%s` 这条 INFO 日志 + + 目的是记录**真正发出去的 payload**，而不是探针自己再算一遍。 + """ + + def __init__(self) -> None: + super().__init__(level=logging.INFO) + self.payloads: list[dict] = [] + + def emit(self, record: logging.LogRecord) -> None: + if record.msg == "加购请求：basket=%s payload=%s": + basket, payload = record.args + self.payloads.append({"basket_domain": basket, "payload": dict(payload)}) + + +def save(name: str, content: str) -> Path: + path = PROBE_DIR / name + path.write_text(content, encoding="utf-8") + print(f" saved -> {path.name} ({len(content)} bytes)") + return path + + +async def inspect_options(site: SiteInteractor, item_url: str) -> list[dict]: + """只读打开商品页，把解析出的选项结构落盘，供人工核对占位项判定是否符合真实页面""" + page = await site._context.new_page() + try: + await page.goto(item_url, wait_until="domcontentloaded", timeout=30_000) + await page.wait_for_function( + "() => window.__INITIAL_STATE__ && window.__INITIAL_STATE__.purchase", + timeout=10_000, + ) + html = await page.content() + finally: + await page.close() + + state = _parse_initial_state(html) or {} + information = (state.get("purchase") or {}).get("information") or {} + options = parse_options(information) + auto_choice, unfillable = auto_choice_for(options) + + slug = item_url.rstrip("/").replace("https://item.rakuten.co.jp/", "").replace("/", "_") + save( + f"options-{slug}.json", + json.dumps( + { + "item_url": item_url, + "raw_options": information.get("options"), + "parsed": [ + { + "name": option.name, + "type": option.type, + "is_required": option.is_required, + "values": [ + { + "value_id": value.value_id, + "name": value.name, + "is_placeholder": value.is_placeholder, + } + for value in option.values + ], + } + for option in options + ], + "auto_choice": auto_choice, + "unfillable_required_options": unfillable, + }, + ensure_ascii=False, + indent=1, + ), + ) + + for option in options: + if not option.is_required: + continue + names = [ + f"{value.name}{'(占位)' if value.is_placeholder else ''}" for value in option.values + ] + print(f" 必填项「{option.name[:30]}」候选={names}") + print(f" auto_choice = {auto_choice!r}") + if unfillable: + print(f" !! 自动填不了的必填项：{unfillable}") + return [{"name": o.name, "is_required": o.is_required} for o in options] + + +async def run() -> int: + settings = get_settings() + capture = _PayloadCapture() + logging.basicConfig(level=logging.WARNING) + # 必须显式把这个 logger 抬到 INFO：basicConfig 把 root 设成 WARNING，而目标 + # logger 自身是 NOTSET，有效级别继承 root——INFO 记录会在到达 handler 之前 + # 就被丢掉，capture 全程收不到东西（第一次跑就是这样，choice 打印成 None） + target_logger = logging.getLogger("app.trading.worker.site_interact") + target_logger.setLevel(logging.INFO) + target_logger.addHandler(capture) + + auth = AuthSession(settings) + await auth.start() + + print("=== 0. 登录态探测（storage_state 落盘于 2026-08-11，可能已过期）===") + status = await auth.check("rakuten") + print(f" logged_in={status.logged_in} detail={status.detail}") + if not status.logged_in: + print(" 登录态已失效——需要先跑 scripts/login.py 重新登录（可能要人工过验证码）") + await auth.close() + return 2 + + site = SiteInteractor(auth_session=auth, settings=settings) + await site.start() + + results: list[dict] = [] + try: + print("\n=== 1. 清空购物车（排除历史残留污染校验）===") + cleared = await site.clear_cart() + print(f" removed={cleared['removed_count']} cart_count={cleared['cart_count']}") + + for index, item_url in enumerate(TARGETS, start=1): + print(f"\n=== 2.{index} {item_url} ===") + print(" -- 只读核对选项结构 --") + try: + await inspect_options(site, item_url) + except Exception as exc: # noqa: BLE001 + print(f" 选项结构读取失败（不影响加购验证）：{type(exc).__name__}: {exc}") + + print(" -- 走生产路径加购（add_to_cart_payload）--") + before = len(capture.payloads) + entry: dict = {"item_url": item_url} + try: + added = await site.add_to_cart_payload(item_url=item_url, quantity=1) + entry["ok"] = True + entry["item_id"] = added["item_id"] + entry["cart_count"] = added["cart_count"] + print( + f" 加购成功 item_id={added['item_id']} cart_count={added['cart_count']}" + ) + save(f"add-response-{index}.html", added.get("response_html") or "") + except AppError as exc: + entry["ok"] = False + entry["error"] = exc.message + print(f" 加购失败：{exc.message}") + except Exception as exc: # noqa: BLE001 + entry["ok"] = False + entry["error"] = f"{type(exc).__name__}: {exc}" + print(f" 加购异常：{type(exc).__name__}: {exc}") + + # 真正发出去的 payload（从生产代码日志截获） + sent = capture.payloads[before:] + if not sent: + # 抓不到就等于这次验证什么也没证明——必须显眼报出来，不能让 + # 「加购成功」把它盖过去（第一次跑就是 logger 级别没抬导致静默为 None） + entry["capture_failed"] = True + print(" !! 未截获到 payload 日志，本次无法确认实际提交的 choice") + else: + entry["sent_payload"] = sent[-1]["payload"] + choice = sent[-1]["payload"].get("choice") + print(f" 实际提交 choice = {choice!r}") + if choice is None: + print(" !! payload 里没有 choice 字段") + elif "選択してください" in choice: + print(" !! 提交值里仍含占位项——修复未生效") + results.append(entry) + + print("\n=== 3. 购物车状态（确认商品真的进车了）===") + try: + status_after = await site.cart_status() + print(f" {status_after}") + except AppError as exc: + print(f" 查询失败：{exc.message}") + + print("\n=== 4. 清空购物车（恢复账号原状，不进入结算）===") + final = await site.clear_cart() + print(f" removed={final['removed_count']} cart_count={final['cart_count']}") + finally: + await site.close() + await auth.close() + + save("summary.json", json.dumps(results, ensure_ascii=False, indent=1)) + print("\n========== 汇总 ==========") + for entry in results: + mark = "OK " if entry.get("ok") else "FAIL" + choice = (entry.get("sent_payload") or {}).get("choice") + print(f" {mark} {entry['item_url']}") + print(f" choice={choice!r}") + if not entry.get("ok"): + print(f" error={entry.get('error')}") + print(f"\n探针输出目录：{PROBE_DIR}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(asyncio.run(run())) diff --git a/tests/test_parsers.py b/tests/test_parsers.py index a03bbc5..46288b1 100644 --- a/tests/test_parsers.py +++ b/tests/test_parsers.py @@ -142,6 +142,79 @@ def test_item_detail_falls_back_to_request_shop_code_when_state_lacks_it(item_st assert detail.shop.shop_code == "fallback" +# ---- 店铺自定义选项（下单必填项）---- + +def test_item_detail_exposes_shop_options_for_ordering(item_with_options_state): + """下单要用的选项必须能从接口拿到：名字、类型、是否必填、候选取值""" + detail = parse_item_detail( + item_with_options_state, item_url="https://x", shop_code="kizamu", + include_sku_variants=True, + ) + assert detail.has_required_options is True + # 真实样本：1 个必填 select（名入れ）+ 1 个非必填 select + 2 个自由文本 + assert [option.name for option in detail.options] == [ + "名入れ", + " 【お名前】※漢字・かな文字：4文字まで", + "【定型】", + "【定型】※〇寿・〇婚式・〇長を選択の場合のみ(1文字まで)", + ] + required = detail.options[0] + assert required.is_required is True + assert required.type == "select" + assert required.option_id == 100 + + +def test_item_detail_marks_placeholder_option_values_as_unselectable(item_with_options_state): + """「選択してください」是占位项，不能作为下单取值——这是 choice 填错的根因""" + detail = parse_item_detail( + item_with_options_state, item_url="https://x", shop_code="kizamu", + include_sku_variants=True, + ) + required = detail.options[0] + placeholder, first_real = required.values[0], required.values[1] + assert placeholder.name == "選択してください" + assert placeholder.is_placeholder is True + assert first_real.name == "希望する【次の項目で入力】" + assert first_real.is_placeholder is False + # 3 个候选里只有 2 个真正可提交 + assert len(required.values) == 3 + assert required.selectable_value_count == 2 + + +def test_item_detail_free_text_option_has_no_values(item_with_options_state): + """type=text 是自由文本，站点不给候选值，无法自动选""" + detail = parse_item_detail( + item_with_options_state, item_url="https://x", shop_code="kizamu", + include_sku_variants=True, + ) + free_text = detail.options[1] + assert free_text.type == "text" + assert free_text.values == [] + assert free_text.selectable_value_count == 0 + + +def test_item_detail_reports_required_options_that_cannot_be_auto_filled(item_with_options_state): + """必填自由文本项无法自动选值，必须点名交给调用方，不能静默蒙一个值""" + options = item_with_options_state["purchase"]["information"]["options"] + # 把那个自由文本项改成必填：店铺要求填「お名前」时就是这种形态 + options[1]["isRequired"] = True + detail = parse_item_detail( + item_with_options_state, item_url="https://x", shop_code="kizamu", + include_sku_variants=True, + ) + assert detail.unfillable_required_options == [" 【お名前】※漢字・かな文字：4文字まで"] + + +def test_item_detail_without_options_reports_empty(item_state): + """没有选项的商品（真实样本 purchase.information 只有 unit）不应凭空造出选项""" + detail = parse_item_detail( + item_state, item_url="https://x", shop_code="s", include_sku_variants=False, + ) + assert detail.options == [] + assert detail.has_required_options is False + assert detail.unfillable_required_options == [] + + def test_item_detail_rejects_state_without_item_node(): with pytest.raises(ScrapeParseError): parse_item_detail({}, item_url="https://x", shop_code="s", include_sku_variants=True) diff --git a/tests/test_site_interact.py b/tests/test_site_interact.py index 95a169c..6f220ef 100644 --- a/tests/test_site_interact.py +++ b/tests/test_site_interact.py @@ -180,6 +180,95 @@ def test_extract_fields_required_options_auto_picks_first_value(): assert fields["form_fields"]["choice"] == "サイズ:S" +def test_extract_fields_required_options_skips_placeholder_value(): + """回归：必填 select 的 values[0] 是「選択してください」占位项，不能当答案提交 + + 真实商品页（.probe/checkout/03-add-fail-2.html 等 3 份样本）里必填 select 的 + 第一个候选恒为 id=0 的占位项，真实取值从 id=200 起。旧实现直接取 values[0]， + 等于把「請選擇」填进 choice 提交上去。 + """ + state = { + "item": {"itemId": 1, "variantId": "v"}, + "purchase": { + "sku": {"inventoryType": "single"}, + "sellType": {"normalPurchase": {"basketDomain": "https://x/add", "purchaseCondition": "enabled"}}, + "information": { + "options": [ + { + "id": 100, + "name": "この商品は「トライタン製／プラスチック」です", + "type": "select", + "isRequired": True, + "values": [ + {"id": 0, "name": "選択してください"}, + {"id": 200, "name": "確認した"}, + ], + } + ] + }, + }, + "shop": {"information": {"shopId": 1}}, + } + fields = _extract_purchase_fields(state, intent_override={}) + assert fields["has_required_options"] is True + assert fields["form_fields"]["choice"] == "この商品は「トライタン製／プラスチック」です:確認した" + assert fields["unfillable_required_options"] == [] + + +def test_extract_fields_required_free_text_option_cannot_be_auto_filled(): + """必填自由文本项（type=text，无候选值）自动填不了，要点名报出来""" + state = { + "item": {"itemId": 1, "variantId": "v"}, + "purchase": { + "sku": {"inventoryType": "single"}, + "sellType": {"normalPurchase": {"basketDomain": "https://x/add", "purchaseCondition": "enabled"}}, + "information": { + "options": [ + {"id": 101, "name": "【お名前】", "type": "text", "isRequired": True}, + ] + }, + }, + "shop": {"information": {"shopId": 1}}, + } + fields = _extract_purchase_fields(state, intent_override={}) + assert fields["has_required_options"] is True + # 填不出来就不填，也不拿占位/空值凑数 + assert "choice" not in fields["form_fields"] + assert fields["unfillable_required_options"] == ["【お名前】"] + + +def test_extract_fields_skips_optional_options_when_auto_filling(): + """非必填项不替上游做业务决定（如「置き配を希望する」），只自动填必填项""" + state = { + "item": {"itemId": 1, "variantId": "v"}, + "purchase": { + "sku": {"inventoryType": "single"}, + "sellType": {"normalPurchase": {"basketDomain": "https://x/add", "purchaseCondition": "enabled"}}, + "information": { + "options": [ + { + "id": 100, + "name": "必須確認", + "type": "select", + "isRequired": True, + "values": [{"id": 0, "name": "選択してください"}, {"id": 200, "name": "了解"}], + }, + { + "id": 101, + "name": "「置き配」希望について", + "type": "select", + "isRequired": False, + "values": [{"id": 200, "name": "置き配を希望しない"}], + }, + ] + }, + }, + "shop": {"information": {"shopId": 1}}, + } + fields = _extract_purchase_fields(state, intent_override={}) + assert fields["form_fields"]["choice"] == "必須確認:了解" + + def test_extract_fields_intent_choice_override_accepts_list_and_str(): state = { "item": {"itemId": 1, "variantId": "v"},