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>

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)