feat(market-intel): add match review plan preview

services/market_intel/match_review_plan.py

@@ -0,0 +1,147 @@
+"""市場情報商品比對審核 preview。
+
+只定義比對訊號、分數門檻與人工覆核流程；不查 DB、不寫 DB、不呼叫 MCP。
+"""
+
+
+MATCH_SCORING_SIGNALS = (
+    {
+        "key": "platform_product_id_or_i_code",
+        "label": "平台商品 ID / MOMO i_code 精準命中",
+        "weight": 0.35,
+        "source": "market_campaign_products + products",
+    },
+    {
+        "key": "brand_and_series",
+        "label": "品牌、系列與型號 token 一致",
+        "weight": 0.24,
+        "source": "normalized product name",
+    },
+    {
+        "key": "spec_token_overlap",
+        "label": "容量、入數、尺寸、顏色等規格 token overlap",
+        "weight": 0.22,
+        "source": "ProductNameParser / parser diagnostics",
+    },
+    {
+        "key": "price_band_reasonable",
+        "label": "跨平台價格落在合理區間，避免不同規格誤配",
+        "weight": 0.12,
+        "source": "price history / competitor price cache",
+    },
+    {
+        "key": "image_or_url_hint",
+        "label": "圖片網址、活動 URL 或來源頁提示",
+        "weight": 0.07,
+        "source": "campaign product metadata",
+    },
+)
+
+
+MATCH_THRESHOLDS = {
+    "auto_match_candidate_min": 0.88,
+    "needs_review_min": 0.62,
+    "reject_suggestion_below": 0.38,
+    "auto_confirm_enabled": False,
+}
+
+
+def build_match_review_plan_preview(
+    *,
+    runtime_status,
+    mcp_tool_contract,
+    legacy_source_bridge,
+    schema_smoke,
+):
+    """建立商品比對審核計畫；不產生 match rows、不自動確認。"""
+    schema_passed = bool(
+        schema_smoke.get("passed")
+        or (schema_smoke.get("schema_smoke") or {}).get("passed")
+    )
+    contract_tools = mcp_tool_contract.get("tools") or []
+    match_lookup_ready = any(
+        item.get("name") == "market_product_match_lookup"
+        and item.get("read_only")
+        and item.get("router_tools_whitelisted")
+        for item in contract_tools
+    )
+    legacy_bridge_safe = (
+        legacy_source_bridge.get("mode") == "legacy_source_bridge_planned"
+        and not legacy_source_bridge.get("read_only_query_executed")
+        and not legacy_source_bridge.get("database_write_executed")
+    )
+    gate_checks = {
+        "schema_smoke_passed": schema_passed,
+        "market_product_matches_table_planned": "market_product_matches"
+        in (schema_smoke.get("expected_tables") or []),
+        "mcp_match_lookup_contract_ready": match_lookup_ready,
+        "legacy_bridge_planned_safe": legacy_bridge_safe,
+        "database_write_still_blocked": not bool(
+            runtime_status.database_write_allowed
+        ),
+        "scheduler_detached": not bool(runtime_status.scheduler_attached),
+        "auto_confirm_disabled": not MATCH_THRESHOLDS["auto_confirm_enabled"],
+        "manual_operator_approval": False,
+    }
+    blocked_reasons = [
+        key for key, passed in gate_checks.items()
+        if not passed
+    ]
+
+    return {
+        "mode": "match_review_plan_preview",
+        "ready_for_review_queue": False,
+        "review_queue_created": False,
+        "auto_match_executed": False,
+        "auto_confirm_executed": False,
+        "database_session_created": False,
+        "database_write_executed": False,
+        "database_commit_executed": False,
+        "external_network_executed": False,
+        "scheduler_attached": False,
+        "writes_executed": False,
+        "would_write_database": False,
+        "thresholds": MATCH_THRESHOLDS,
+        "scoring_signals": list(MATCH_SCORING_SIGNALS),
+        "planned_status_flow": [
+            "needs_review",
+            "confirmed",
+            "rejected",
+        ],
+        "gate_checks": gate_checks,
+        "blocked_reasons": blocked_reasons,
+        "review_actions": [
+            {
+                "key": "confirm_match",
+                "label": "人工確認競品商品與 MOMO 商品為同款或等效規格",
+                "writes_database": True,
+                "requires_operator": True,
+            },
+            {
+                "key": "reject_match",
+                "label": "人工拒絕誤配候選，保留 reason 供規則調整",
+                "writes_database": True,
+                "requires_operator": True,
+            },
+            {
+                "key": "merge_duplicate_candidate",
+                "label": "合併同一競品商品的重複候選",
+                "writes_database": True,
+                "requires_operator": True,
+            },
+        ],
+        "operator_sequence": [
+            "先完成 market_* schema 與 seed 寫入",
+            "以 read-only bridge 盤點 PChome / MOMO 舊資料來源",
+            "用 market_product_match_lookup 只讀查詢候選，不直接建立 match rows",
+            "人工審核 needs_review queue 後才允許 confirmed / rejected 寫入",
+            "任何 auto_match 只能產生候選分數，不得自動 confirmed",
+        ],
+        "safe_boundaries": [
+            "do_not_auto_confirm_matches",
+            "do_not_write_match_rows_from_preview",
+            "do_not_call_external_mcp_from_preview",
+            "do_not_attach_scheduler_for_match_review",
+            "do_not_use_price_only_as_match_reason",
+        ],
+    }

services/market_intel/service.py

@@ -20,6 +20,7 @@ from services.market_intel.adapters import (
 from services.market_intel.candidate_preview import build_candidate_preview_from_discovery
 from services.market_intel.discovery_runner import ManualDiscoveryRunner
 from services.market_intel.legacy_source_bridge import build_legacy_source_bridge_plan
+from services.market_intel.match_review_plan import build_match_review_plan_preview
 from services.market_intel.mcp_activation_runbook import build_mcp_activation_runbook_preview
 from services.market_intel.mcp_contract import build_mcp_tool_contract_preview
 from services.market_intel.mcp_deploy_preflight import build_mcp_deploy_preflight_plan
@@ -69,7 +70,7 @@ class MarketIntelRuntimeStatus:
 class MarketIntelService:
     """市場情報入口服務，先集中 feature gate 與安全狀態。"""
 
-    phase = "phase_33_scheduler_plan_preview"
+    phase = "phase_34_match_review_plan_preview"
 
     def get_runtime_status(self) -> MarketIntelRuntimeStatus:
         return MarketIntelRuntimeStatus(
@@ -377,6 +378,21 @@ class MarketIntelService:
         plan["phase"] = self.phase
         return plan
 
+    def build_match_review_plan(self):
+        """回報商品比對審核計畫；不建立 queue、不自動確認。"""
+        schema_smoke = self.build_schema_smoke()
+        plan = build_match_review_plan_preview(
+            runtime_status=self.get_runtime_status(),
+            mcp_tool_contract=self.build_mcp_tool_contract(),
+            legacy_source_bridge=self.build_legacy_source_bridge(),
+            schema_smoke={
+                **schema_smoke["schema_smoke"],
+                "expected_tables": schema_smoke["expected_tables"],
+            },
+        )
+        plan["phase"] = self.phase
+        return plan
+
     def build_platform_seed_writer_plan(self, platform_code="all"):
         """建立 platform seed writer dry-run plan，不建立 DB session。"""
         seed_plan = self.build_platform_seed_plan(platform_code=platform_code)
@@ -457,6 +473,7 @@ class MarketIntelService:
         mcp_activation_runbook = self.build_mcp_activation_runbook()
         mcp_fetch_gate = self.build_mcp_fetch_gate()
         scheduler_plan = self.build_scheduler_plan()
+        match_review_plan = self.build_match_review_plan()
         checks = {
             "schema_smoke_passed": bool(schema_smoke["passed"]),
             "feature_flags_default_safe": bool(
@@ -507,6 +524,12 @@ class MarketIntelService:
                 and not scheduler_plan["crawler_job_started"]
                 and not scheduler_plan["database_write_executed"]
             ),
+            "match_review_plan_preview_safe": bool(
+                match_review_plan["mode"] == "match_review_plan_preview"
+                and not match_review_plan["review_queue_created"]
+                and not match_review_plan["auto_confirm_executed"]
+                and not match_review_plan["database_write_executed"]
+            ),
         }
         ready_for_production_deploy = all(checks.values())
         blocked_reasons = [
@@ -636,6 +659,7 @@ class MarketIntelService:
                 "/api/market_intel/mcp_activation_runbook",
                 "/api/market_intel/mcp_fetch_gate",
                 "/api/market_intel/scheduler_plan",
+                "/api/market_intel/match_review_plan",
             ],
             "status": status.to_dict(),
             "schema_smoke": schema_smoke,
@@ -656,4 +680,5 @@ class MarketIntelService:
             "mcp_activation_runbook": mcp_activation_runbook,
             "mcp_fetch_gate": mcp_fetch_gate,
             "scheduler_plan": scheduler_plan,
+            "match_review_plan": match_review_plan,
         }