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>

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"),