feat(ai): add PixelRAG marketplace adapter preflight

tests/test_ai_automation_smoke_service.py

@@ -1311,6 +1311,7 @@ def test_collect_ai_automation_smoke_uses_worst_status(monkeypatch):
     monkeypatch.setattr(smoke, "_external_mcp_rag_integration_check", lambda: smoke._check("external mcp rag", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_rag_candidate_replay_check", lambda: smoke._check("pixelrag replay", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_source_contract_replay_worker_check", lambda: smoke._check("pixelrag source contract", "ok", "ok"))
+    monkeypatch.setattr(smoke, "_pixelrag_marketplace_adapter_preflight_check", lambda: smoke._check("pixelrag marketplace adapter preflight", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_ocr_vlm_replay_check", lambda: smoke._check("pixelrag ocr vlm", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_vlm_route_readiness_check", lambda: smoke._check("pixelrag vlm route", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_vlm_replay_worker_check", lambda: smoke._check("pixelrag vlm worker", "ok", "ok"))
@@ -1320,7 +1321,7 @@ def test_collect_ai_automation_smoke_uses_worst_status(monkeypatch):
     result = smoke.collect_ai_automation_smoke(record_history=False)
 
     assert result["status"] == "critical"
-    assert result["summary"] == {"ok": 36, "warning": 1, "critical": 1, "total": 38}
+    assert result["summary"] == {"ok": 37, "warning": 1, "critical": 1, "total": 39}
 
 
 def test_pchome_controlled_apply_drift_monitor_reports_verified_zero_drift(monkeypatch):
@@ -3850,6 +3851,7 @@ def test_collect_ai_automation_smoke_persists_recent_history(tmp_path, monkeypat
     monkeypatch.setattr(smoke, "_external_mcp_rag_integration_check", lambda: smoke._check("external mcp rag", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_rag_candidate_replay_check", lambda: smoke._check("pixelrag replay", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_source_contract_replay_worker_check", lambda: smoke._check("pixelrag source contract", "ok", "ok"))
+    monkeypatch.setattr(smoke, "_pixelrag_marketplace_adapter_preflight_check", lambda: smoke._check("pixelrag marketplace adapter preflight", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_ocr_vlm_replay_check", lambda: smoke._check("pixelrag ocr vlm", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_vlm_route_readiness_check", lambda: smoke._check("pixelrag vlm route", "ok", "ok"))
     monkeypatch.setattr(smoke, "_pixelrag_vlm_replay_worker_check", lambda: smoke._check("pixelrag vlm worker", "ok", "ok"))
@@ -3910,7 +3912,7 @@ def test_scheduled_automation_health_summary_reads_history_without_side_effects(
         json.dumps({
             "generated_at": datetime.now().isoformat(timespec="seconds"),
             "status": "ok",
-                "summary": {"ok": 38, "warning": 0, "critical": 0, "total": 38},
+                "summary": {"ok": 39, "warning": 0, "critical": 0, "total": 39},
             "checks": [
                 {
                     "name": "PChome 受控落地 drift monitor",
@@ -4040,6 +4042,27 @@ def test_scheduled_automation_health_summary_reads_history_without_side_effects(
                             "primary_human_gate_count": 0,
                         },
                     },
+                    {
+                        "name": "PixelRAG marketplace adapter preflight",
+                        "status": "ok",
+                        "summary": "PixelRAG marketplace adapter preflight candidates=1, ready=1, blocked=0, dry_run=1, executed=0, receipts=0",
+                        "details": {
+                            "policy": "controlled_pixelrag_marketplace_source_contract_adapter_preflight_v1",
+                            "candidate_count": 1,
+                            "ready_count": 1,
+                            "blocked_count": 0,
+                            "dry_run_count": 1,
+                            "executed_count": 0,
+                            "receipt_written_count": 0,
+                            "capture_runtime_gap_count": 0,
+                            "network_call_performed": False,
+                            "model_call_performed": False,
+                            "artifact_write_performed": False,
+                            "next_machine_action": "run_marketplace_source_contract_adapter_preflight_execute",
+                            "writes_database_count": 0,
+                            "primary_human_gate_count": 0,
+                        },
+                    },
                     {
                         "name": "PixelRAG OCR/VLM replay contract",
                         "status": "ok",
@@ -4154,7 +4177,7 @@ def test_scheduled_automation_health_summary_reads_history_without_side_effects(
     )
     assert summary["policy"] == "read_only_ai_automation_scheduled_health_summary"
     assert summary["status"] == "ok"
-    assert summary["summary"]["total"] == 35
+    assert summary["summary"]["total"] == 36
     assert summary["summary"]["primary_human_gate_count"] == 0
     assert summary["summary"]["writes_database_count"] == 0
     assert pchome_family["status"] == "ok"
@@ -6491,6 +6514,11 @@ def test_surface_html_readback_check_is_part_of_ai_smoke(monkeypatch):
         "ok",
         "pixelrag source contract ok",
     ))
+    monkeypatch.setattr(smoke, "_pixelrag_marketplace_adapter_preflight_check", lambda: smoke._check(
+        "PixelRAG marketplace adapter preflight",
+        "ok",
+        "pixelrag marketplace adapter preflight ok",
+    ))
     monkeypatch.setattr(smoke, "_pixelrag_ocr_vlm_replay_check", lambda: smoke._check(
         "PixelRAG OCR/VLM replay contract",
         "ok",
@@ -6531,7 +6559,7 @@ def test_surface_html_readback_check_is_part_of_ai_smoke(monkeypatch):
         item for item in result["checks"]
         if item["name"] == "Sitewide visual QA readback"
     )
-    assert result["summary"]["total"] == 38
+    assert result["summary"]["total"] == 39
     assert surface_check["status"] == "ok"
     assert surface_check["details"]["checked_surface_count"] == 10
     assert sitewide_check["status"] == "ok"

tests/test_pixelrag_marketplace_source_contract_adapter_preflight_service.py

@@ -0,0 +1,232 @@
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+
+def _write_source_contract_replay_receipt(
+    root,
+    *,
+    platform="coupang_tw",
+    manifest_id="coupang-403",
+    adapter_code="coupang",
+    barrier_type="access_denied",
+    capture_runtime_unavailable=False,
+):
+    receipt_dir = root / platform / manifest_id
+    receipt_dir.mkdir(parents=True)
+    payload = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "policy": "controlled_pixelrag_source_contract_replay_worker_v1",
+        "worker_status": "executed_source_contract_replay_ready",
+        "platform": platform,
+        "manifest_id": manifest_id,
+        "adapter_code": adapter_code,
+        "source_worker_receipt_path": (
+            f"runtime_artifacts/pixelrag_platform_probe_worker_receipts/"
+            f"{platform}/{manifest_id}/platform_probe_worker_receipt.json"
+        ),
+        "source_receipt_path": (
+            f"runtime_artifacts/pixelrag_visual_evidence/"
+            f"{platform}/{manifest_id}/capture_receipt.json"
+        ),
+        "source_contract_check_count": 8,
+        "source_contract_check_pass_count": 8,
+        "source_contract_checks": {
+            "blocked_page_not_product_data": True,
+            "database_write_disallowed": True,
+            "dry_run_only_contract": True,
+            "network_request_deferred": True,
+            "source_count_positive": True,
+            "source_receipt_path_present": True,
+            "source_worker_receipt_path_present": True,
+            "structured_source_package_available": True,
+        },
+        "source_contract_preview": {
+            "source_contract_version": "pixelrag_marketplace_source_contract_v1",
+            "contract_id": f"{platform}:{manifest_id}:{adapter_code}",
+            "adapter_code": adapter_code,
+            "barrier_type": barrier_type,
+            "capture_runtime_unavailable": capture_runtime_unavailable,
+            "source_count": 2,
+            "expected_offer_fields": [
+                "platform",
+                "platform_product_id",
+                "title",
+                "url",
+                "image_url",
+                "price",
+                "currency",
+                "availability",
+                "seller",
+                "promotion_badges",
+                "shipping_badges",
+                "evidence_time",
+                "source_method",
+                "confidence",
+            ],
+            "required_before_data_promotion": [
+                "public_source_boundary",
+                "rate_limit_contract",
+                "provenance_contract",
+                "identity_matcher_replay",
+                "promotion_gate",
+                "embedding_signature_guard",
+            ],
+        },
+        "promotion_boundary": {
+            "direct_ai_insights_write_allowed": False,
+            "direct_price_write_allowed": False,
+        },
+        "writes_database": False,
+        "network_call_performed": False,
+        "model_call_performed": False,
+    }
+    path = receipt_dir / "source_contract_replay_receipt.json"
+    path.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+    return path
+
+
+def test_marketplace_source_contract_adapter_preflight_dry_run_reads_receipts(tmp_path):
+    from services.pixelrag_marketplace_source_contract_adapter_preflight_service import (
+        POLICY,
+        run_pixelrag_marketplace_source_contract_adapter_preflight,
+    )
+
+    source_root = tmp_path / "source_contracts"
+    _write_source_contract_replay_receipt(source_root)
+    _write_source_contract_replay_receipt(
+        source_root,
+        platform="shopee_tw",
+        manifest_id="shopee-runtime-gap",
+        adapter_code="shopee",
+        barrier_type="language_or_region_interstitial",
+        capture_runtime_unavailable=True,
+    )
+
+    payload = run_pixelrag_marketplace_source_contract_adapter_preflight(
+        source_contract_replay_receipt_root=source_root,
+        platform=("coupang_tw", "shopee_tw"),
+    )
+    by_platform = {item["platform"]: item for item in payload["worker_items"]}
+
+    assert payload["policy"] == POLICY
+    assert payload["status"] == "ok"
+    assert payload["summary"]["candidate_count"] == 2
+    assert payload["summary"]["ready_count"] == 2
+    assert payload["summary"]["dry_run_count"] == 2
+    assert payload["summary"]["capture_runtime_gap_count"] == 1
+    assert payload["summary"]["writes_database_count"] == 0
+    assert payload["controlled_apply"]["network_call"] is False
+    assert payload["controlled_apply"]["writes_database"] is False
+    assert payload["next_machine_action"] == (
+        "run_marketplace_source_contract_adapter_preflight_execute"
+    )
+    assert by_platform["coupang_tw"]["worker_status"] == (
+        "dry_run_ready_for_adapter_preflight"
+    )
+    assert by_platform["coupang_tw"]["adapter_preflight_checks"][
+        "rate_limit_contract_required"
+    ] is True
+    assert by_platform["shopee_tw"]["adapter_preflight"][
+        "capture_runtime_unavailable"
+    ] is True
+
+
+def test_marketplace_source_contract_adapter_preflight_execute_writes_receipt(tmp_path):
+    from services.pixelrag_marketplace_source_contract_adapter_preflight_service import (
+        run_pixelrag_marketplace_source_contract_adapter_preflight,
+    )
+
+    source_root = tmp_path / "source_contracts"
+    output_root = tmp_path / "adapter_preflight"
+    _write_source_contract_replay_receipt(source_root)
+
+    payload = run_pixelrag_marketplace_source_contract_adapter_preflight(
+        source_contract_replay_receipt_root=source_root,
+        output_root=output_root,
+        platform="coupang_tw",
+        execute=True,
+        write_receipt=True,
+    )
+
+    assert payload["status"] == "ok"
+    assert payload["summary"]["executed_count"] == 1
+    assert payload["summary"]["receipt_written_count"] == 1
+    assert payload["controlled_apply"]["artifact_write"] is True
+    assert payload["controlled_apply"]["writes_database"] is False
+    assert payload["next_machine_action"] == "run_marketplace_source_contract_adapter_dry_run"
+    receipt_path = (
+        output_root
+        / "coupang_tw"
+        / "coupang-403"
+        / "marketplace_adapter_preflight_receipt.json"
+    )
+    assert receipt_path.exists()
+    receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
+    assert receipt["worker_status"] == "executed_adapter_preflight_ready"
+    assert receipt["artifact_write_performed"] is True
+    assert receipt["writes_database"] is False
+    assert receipt["adapter_preflight"]["adapter_preflight_version"] == (
+        "pixelrag_marketplace_adapter_preflight_v1"
+    )
+
+
+def test_marketplace_source_contract_adapter_preflight_cli_outputs_json(tmp_path):
+    source_root = tmp_path / "source_contracts"
+    _write_source_contract_replay_receipt(source_root)
+
+    completed = subprocess.run(
+        [
+            sys.executable,
+            "scripts/ops/run_pixelrag_marketplace_source_contract_adapter_preflight.py",
+            "--source-contract-replay-receipt-root",
+            str(source_root),
+            "--platform",
+            "coupang_tw",
+        ],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+
+    assert completed.returncode == 0
+    payload = json.loads(completed.stdout)
+    assert payload["summary"]["candidate_count"] == 1
+    assert payload["summary"]["ready_count"] == 1
+    assert payload["controlled_apply"]["writes_database"] is False
+
+
+def test_marketplace_source_contract_adapter_preflight_route_returns_readback(
+    tmp_path,
+    monkeypatch,
+):
+    from flask import Flask
+    from routes import system_public_routes as routes
+    from services import pixelrag_marketplace_source_contract_adapter_preflight_service as service
+
+    source_root = tmp_path / "source_contracts"
+    _write_source_contract_replay_receipt(source_root)
+    monkeypatch.setattr(
+        service,
+        "DEFAULT_SOURCE_CONTRACT_REPLAY_RECEIPT_ROOT",
+        str(source_root),
+    )
+
+    app = Flask(__name__)
+    with app.test_request_context(
+        "/api/ai-automation/pixelrag-marketplace-source-contract-adapter-preflight?platform=coupang_tw"
+    ):
+        response = (
+            routes
+            .ai_automation_pixelrag_marketplace_source_contract_adapter_preflight_api
+            .__wrapped__()
+        )
+    payload = response.get_json()
+
+    assert payload["policy"] == (
+        "controlled_pixelrag_marketplace_source_contract_adapter_preflight_v1"
+    )
+    assert payload["summary"]["candidate_count"] == 1
+    assert payload["summary"]["ready_count"] == 1
+    assert payload["controlled_apply"]["writes_database"] is False