Webapp バックエンド解説

webapp/ は Flask 製の ゲスト閲覧 UI です。ビジネスロジックの本体は mercari ライブラリにあり、webapp は フォーム／SPA → kwargs → MercariClient の薄い層です。

起動

cd /path/to/mercari_search
pip install -e .
# ライブ（ゲスト DPoP）
python -m webapp.app
# dry_run（ネットワークなし）
MERCARI_WEB_DRY_RUN=1 python -m webapp.app

既定ポートはアプリ実装に依存（多くの場合 5050 前後）。create_app(dry_run=..., client=...) でテスト注入も可能です。

アーキテクチャ

Browser (SPA spa.js / legacy templates)
        │  HTTP
        ▼
Flask routes (webapp/app.py)
        │  form_to_search_kwargs / mapping.py
        ▼
MercariClient.search / .item / souba / facets
        │  DPoP guest (+ optional proxy)
        ▼
api.mercari.jp

層	役割
`webapp/static/spa.js`	相場 UI・検索 UI のフロント
`webapp/mapping.py`	クエリパラメータ → `search(**kwargs)`
`webapp/app.py`	ルート、JSON API、テンプレート
`mercari.*`	プロトコル・認証・相場・SOUBA

主な API ルート

ルート	役割	ライブラリ相当
`GET /api/search`	出品検索 + 画面上価格 stats	`c.search_with_stats(...)` / `run_search`
`GET /api/market`	売切寄り相場 + レコメンド	`c.market_search(...)`
`GET /api/market/filters`	特徴 facet サンプル	`c.sample_facets(...)`
`GET /api/item/<id>`	商品詳細	`c.item(id)`
`GET/POST /api/souba`	SOUBA 一覧・追加	`load_souba` / `add_souba_*`
`POST /api/souba/draft-pattern`	パターン下書き	`prepare_souba_entry` / Gemini
`POST /api/souba/test-pattern`	タイトル試行	`title_matches_souba_entry`
`GET /api/health`	死活	—

SPA シェル: /, /market, /item/<id>
レガシ HTML: /legacy, /search, /legacy/item/<id>

mapping の流れ

クエリ category_id, keyword, condition, status_mode, attributes_json, …
form_to_search_kwargs → MercariClient.search 用 dict
search_kwargs_to_request_dict → デバッグ用 build_search_dict
hits_from_search_result → 画面用 items
price_stats / average_prices → 平均・中央値など

ライブラリから同じことをする例:

import mercari

c = mercari.MercariClient()
# webapp /api/search に近い
print(c.search_with_stats(keyword="iPhone", category_id=3833, sort="新しい順"))

# 高度な condition JSON
print(c.search_from_condition({
    "category_id": [3833],
    "item_condition_id": [2, 3, 4],
    "sort": 1,
    "order": 0,
    "status": [],
}))

dry_run と webapp

MERCARI_WEB_DRY_RUN=1 または create_app(dry_run=True) のとき:

MercariClient(dry_run=True) を共有
/api/search の mode は dry_run、items は空
リクエスト組み立てと auth 表示のデバッグ向け

詳細: dry_run とは

ゲスト・プロキシ

プロセス内で 1 つの MercariClient を使い回し（DPoP 鍵再利用）
プロキシが必要なら起動前に:

import mercari
mercari.set_proxy("http://127.0.0.1:8080")
# その後 webapp を起動、または create_app(client=MercariClient(proxy="..."))

SOUBA

既定ファイル: data/souba.json（default_souba_path()）
UI から pattern 下書き・試行・追加
ポーラ examples/22_souba_poller.py と同じ JSON を共有可能

テスト

python -m unittest tests.test_webapp_mapping -v

Flask ルートを dry_run クライアント注入で叩くテストが含まれます。

ライブラリで webapp 機能を使う対応表

やりたいこと	ライブラリ
キーワード検索	`c.search(keyword=..., category_id=...)`
condition JSON 貼り付け	`c.search_from_condition({...})`
検索 + stats	`c.search_with_stats(...)`
相場（売切）	`c.market_search(...)`
特徴フィルタ選択肢	`c.sample_facets(...)`
商品詳細	`c.item("m...")`
相場中央値	`recommended_market_price(market_price_stats(hits))`
SOUBA	`load_souba` / `match_souba` / `prepare_souba_entry`
HTTP プロキシ	`mercari.set_proxy(...)`

関連: 高度な検索 · アーキテクチャ · ゲスト認証

起動​

アーキテクチャ​

主な API ルート​

mapping の流れ​

dry_run と webapp​

ゲスト・プロキシ​

SOUBA​

テスト​

ライブラリで webapp 機能を使う対応表​

起動