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>

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 不覆盖子站加购）：