fix(trading): 必填选项自动填值跳过「選択してください」占位项，并把选项开放给接口

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) <noreply@anthropic.com>
2026-08-28 16:07:33 +08:00
parent 8381896eeb
commit b577d3ac8d
9 changed files with 731 additions and 26 deletions
@@ -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)
@@ -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"},