補齊 PChome retry verifier artifact materialization

routes/ai_routes.py

@@ -2247,6 +2247,63 @@ def api_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier
         }), 500
 
 
+@ai_bp.route('/api/ai/pchome-growth/mapping-backlog/direct-mapping-retry-candidate-exception-closeout-verifier-artifact-materialization-package')
+@login_required
+def api_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package():
+    """P2 AI-controlled verifier artifact materialization for retry exception closeout inputs."""
+    try:
+        from config import DATABASE_PATH
+        from services.pchome_revenue_growth_service import build_pchome_growth_opportunities
+        from services.pchome_mapping_backlog_service import (
+            build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package,
+        )
+
+        force_refresh = str(request.args.get('refresh') or '').strip().lower() in {'1', 'true', 'yes'}
+        execute_search = str(request.args.get('execute_search') or '').strip().lower() in {'1', 'true', 'yes'}
+        execute_retry_search = str(request.args.get('execute_retry_search') or '').strip().lower() in {'1', 'true', 'yes'}
+        materialize_artifacts = str(request.args.get('materialize_artifacts') or '').strip().lower() in {'1', 'true', 'yes'}
+        limit = request.args.get('limit', 20, type=int)
+        batch_size = request.args.get('batch_size', 5, type=int)
+        limit_per_product = request.args.get('limit_per_product', 8, type=int)
+        max_terms_per_product = request.args.get('max_terms_per_product', 5, type=int)
+        min_score = request.args.get('min_score', 0.45, type=float)
+        limit = max(5, min(limit, 50))
+
+        payload = None
+        if not force_refresh:
+            payload = _get_cached_pchome_growth_payload()
+
+        if payload is None:
+            engine = _create_icaim_dashboard_engine(DATABASE_PATH)
+            try:
+                payload = build_pchome_growth_opportunities(engine, limit=limit)
+            finally:
+                engine.dispose()
+            payload["cache_state"] = "fresh"
+            _set_pchome_growth_cache(payload)
+
+        package = build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package(
+            payload,
+            batch_size=batch_size,
+            execute_search=execute_search,
+            execute_retry_search=execute_retry_search,
+            limit_per_product=limit_per_product,
+            max_terms_per_product=max_terms_per_product,
+            min_score=min_score,
+            materialize_artifacts=materialize_artifacts,
+        )
+        package["source_endpoint"] = (
+            "/api/ai/pchome-growth/mapping-backlog/direct-mapping-retry-candidate-exception-closeout-verifier-artifact-preview-package"
+        )
+        return jsonify(package)
+    except Exception as exc:
+        logger.error("[PChomeGrowth] direct mapping retry candidate exception closeout verifier artifact materialization 讀取失敗: %s", exc, exc_info=True)
+        return jsonify({
+            "success": False,
+            "error": "PChome 商品對應 retry 例外 verifier artifact materialization 暫時無法讀取，請稍後再試。",
+        }), 500
+
+
 @ai_bp.route('/api/ai/pchome-growth/ai-automation-readiness')
 @login_required
 def api_pchome_growth_ai_automation_readiness():

services/pchome_mapping_backlog_service.py

@@ -59,6 +59,9 @@ DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_INPUT_POLICY = (
 DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW_POLICY = (
     "read_only_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview"
 )
+DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_MATERIALIZATION_POLICY = (
+    "ai_controlled_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization"
+)
 AI_AUTOMATION_READINESS_POLICY = "read_only_pchome_growth_ai_automation_readiness"
 EVIDENCE_ENRICHMENT_PREVIEW_POLICY = "read_only_pchome_growth_evidence_enrichment_preview"
 EVIDENCE_SOURCE_PREVIEW_POLICY = "read_only_pchome_growth_evidence_source_preview"
@@ -3098,6 +3101,8 @@ def build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_arti
             "writes_database": False,
         },
         "verifier_manifest": verifier_manifest,
+        "source_ready_no_write_verifier_receipts": ready_receipts,
+        "source_blocked_no_write_verifier_receipts": blocked_receipts,
         "source_verifier_input_summary": summary,
         "next_actions": [
             "Use ready artifact preview as the input to controlled apply preflight only after fresh production truth.",
@@ -3120,6 +3125,282 @@ def build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_arti
     }
 
 
+def _retry_exception_closeout_verifier_artifact_run_id(preview_package: dict[str, Any]) -> str:
+    preview = preview_package.get("retry_exception_closeout_verifier_artifact_preview") or {}
+    payload = {
+        "preview_id": preview.get("preview_id") or "",
+        "summary": preview_package.get("summary") or {},
+        "artifact_schema_keys": [
+            schema.get("key")
+            for schema in preview_package.get("artifact_schemas") or []
+        ],
+    }
+    digest = hashlib.sha256(
+        json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str).encode("utf-8")
+    ).hexdigest()
+    return f"pchome-retry-closeout-verifier-run-{digest[:16]}"
+
+
+def _canonical_retry_exception_artifact_bytes(payload: dict[str, Any]) -> bytes:
+    return (
+        json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2, default=str) + "\n"
+    ).encode("utf-8")
+
+
+def _resolve_retry_exception_artifact_path(root: Path, relative_path: str) -> Path:
+    relative = Path(relative_path)
+    if relative.is_absolute() or ".." in relative.parts:
+        raise ValueError(f"unsafe artifact path: {relative_path}")
+    return root / relative
+
+
+def _build_retry_exception_verifier_artifact_payloads(
+    preview_package: dict[str, Any],
+    run_id: str,
+) -> list[dict[str, Any]]:
+    preview = preview_package.get("retry_exception_closeout_verifier_artifact_preview") or {}
+    ready_receipts = list(preview_package.get("source_ready_no_write_verifier_receipts") or [])
+    blocked_receipts = list(preview_package.get("source_blocked_no_write_verifier_receipts") or [])
+    schemas_by_key = {
+        schema.get("key"): schema
+        for schema in preview_package.get("artifact_schemas") or []
+    }
+    subjects = [receipt.get("subject") or {} for receipt in ready_receipts]
+    target_ids = sorted(
+        {
+            str(subject.get("target_pchome_product_id"))
+            for subject in subjects
+            if subject.get("target_pchome_product_id")
+        }
+    )
+    momo_ids = sorted(
+        {
+            str(subject.get("momo_product_id") or subject.get("product_id"))
+            for subject in subjects
+            if subject.get("momo_product_id") or subject.get("product_id")
+        }
+    )
+    common = {
+        "run_id": run_id,
+        "preview_id": preview.get("preview_id"),
+        "source_policy": preview_package.get("policy"),
+        "created_from": "retry_exception_closeout_verifier_artifact_preview",
+        "created_at": preview_package.get("generated_at"),
+        "safety": {
+            "writes_database": False,
+            "syncs_external_offers": False,
+            "dispatches_telegram": False,
+            "requires_production_version_truth": True,
+        },
+    }
+    payloads = [
+        {
+            **common,
+            "artifact_key": "retry_exception_closeout_verifier_input_artifact",
+            "no_write_verifier_receipts": ready_receipts,
+            "source_closeout_receipt_ids": [
+                receipt.get("source_closeout_receipt_id")
+                for receipt in ready_receipts
+                if receipt.get("source_closeout_receipt_id")
+            ],
+            "verification_checks": [
+                {
+                    "receipt_id": receipt.get("receipt_id"),
+                    "checks": receipt.get("verification_checks") or [],
+                }
+                for receipt in ready_receipts
+            ],
+            "blocked_no_write_verifier_receipts": blocked_receipts,
+        },
+        {
+            **common,
+            "artifact_key": "retry_exception_identity_readback_artifact",
+            "target_pchome_product_ids": target_ids,
+            "momo_product_ids": momo_ids,
+            "identity_delta_status": "ready" if ready_receipts and not blocked_receipts else "blocked",
+            "source_receipt_ids": [
+                receipt.get("receipt_id")
+                for receipt in ready_receipts
+                if receipt.get("receipt_id")
+            ],
+        },
+        {
+            **common,
+            "artifact_key": "retry_exception_controlled_apply_preflight_artifact",
+            "ready_no_write_verifier_input_count": len(ready_receipts),
+            "blocked_no_write_verifier_input_count": len(blocked_receipts),
+            "rollback_plan_required": True,
+            "production_readback_required": True,
+            "ready_for_controlled_apply_now": False,
+            "next_gate": "retry_exception_controlled_apply_preflight",
+        },
+    ]
+    artifacts: list[dict[str, Any]] = []
+    for payload in payloads:
+        key = payload["artifact_key"]
+        schema = schemas_by_key.get(key) or {}
+        relative_path = str(schema.get("artifact_path_template") or "").format(run_id=run_id)
+        artifact_bytes = _canonical_retry_exception_artifact_bytes(payload)
+        artifacts.append({
+            "key": key,
+            "artifact_type": schema.get("artifact_type") or key,
+            "relative_path": relative_path,
+            "payload_sha256": hashlib.sha256(artifact_bytes).hexdigest(),
+            "byte_count": len(artifact_bytes),
+            "payload": payload,
+            "materialized": False,
+            "writes_database": False,
+        })
+    return artifacts
+
+
+def build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package(
+    payload: dict[str, Any],
+    batch_size: int = 5,
+    *,
+    execute_search: bool = False,
+    execute_retry_search: bool = False,
+    limit_per_product: int = 8,
+    max_terms_per_product: int = 5,
+    min_score: float = 0.45,
+    search_func: Any = None,
+    materialize_artifacts: bool = False,
+    artifact_root: str | Path | None = None,
+) -> dict[str, Any]:
+    """Build and optionally materialize verifier artifacts without database writes."""
+    preview_package = build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_package(
+        payload,
+        batch_size=batch_size,
+        execute_search=execute_search,
+        execute_retry_search=execute_retry_search,
+        limit_per_product=limit_per_product,
+        max_terms_per_product=max_terms_per_product,
+        min_score=min_score,
+        search_func=search_func,
+    )
+    preview = preview_package.get("retry_exception_closeout_verifier_artifact_preview") or {}
+    materialization_ready = bool(preview.get("ready_for_future_artifact_generation"))
+    run_id = _retry_exception_closeout_verifier_artifact_run_id(preview_package)
+    artifact_payloads = _build_retry_exception_verifier_artifact_payloads(preview_package, run_id)
+    root = Path(artifact_root) if artifact_root is not None else Path.cwd()
+    materialized_artifacts: list[dict[str, Any]] = []
+    if materialize_artifacts and materialization_ready:
+        for artifact in artifact_payloads:
+            target_path = _resolve_retry_exception_artifact_path(root, artifact["relative_path"])
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            target_path.write_bytes(_canonical_retry_exception_artifact_bytes(artifact["payload"]))
+            materialized_artifacts.append({
+                "key": artifact["key"],
+                "relative_path": artifact["relative_path"],
+                "absolute_path": str(target_path),
+                "payload_sha256": artifact["payload_sha256"],
+                "written_byte_count": target_path.stat().st_size,
+                "writes_database": False,
+            })
+            artifact["materialized"] = True
+            artifact["absolute_path"] = str(target_path)
+
+    if not materialization_ready:
+        result = "WAITING_FOR_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW"
+    elif materialize_artifacts and len(materialized_artifacts) == len(artifact_payloads):
+        result = "DIRECT_MAPPING_RETRY_EXCEPTION_VERIFIER_ARTIFACTS_MATERIALIZED"
+    elif materialize_artifacts:
+        result = "DIRECT_MAPPING_RETRY_EXCEPTION_VERIFIER_ARTIFACT_MATERIALIZATION_PARTIAL"
+    else:
+        result = "DIRECT_MAPPING_RETRY_EXCEPTION_VERIFIER_ARTIFACT_MATERIALIZATION_READY"
+
+    rollback_steps = [
+        {
+            "key": artifact["key"],
+            "action": "delete_materialized_artifact_file",
+            "relative_path": artifact["relative_path"],
+            "executes_in_package": False,
+            "writes_database": False,
+        }
+        for artifact in artifact_payloads
+    ]
+    verifier_checks = [
+        "artifact_payload_count_matches_schema_count",
+        "all_artifact_payloads_include_run_id",
+        "all_artifact_payloads_include_preview_id",
+        "all_payload_hashes_are_sha256",
+        "materialized_artifact_count_matches_payload_count_when_enabled",
+        "rollback_plan_references_all_artifacts",
+        "controlled_apply_preflight_artifact_present",
+        "production_truth_required_before_next_apply",
+        "database_write_count_is_zero",
+    ]
+    return {
+        "policy": DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_MATERIALIZATION_POLICY,
+        "result": result,
+        "success": bool(preview_package.get("success")),
+        "generated_at": preview_package.get("generated_at"),
+        "source_policy": preview_package.get("policy"),
+        "stats": preview_package.get("stats") or {},
+        "backlog": preview_package.get("backlog") or {},
+        "summary": {
+            "artifact_materialization_ready_count": 1 if materialization_ready else 0,
+            "artifact_payload_count": len(artifact_payloads),
+            "artifact_materialized_count": len(materialized_artifacts),
+            "artifact_write_count": len(materialized_artifacts),
+            "ready_closeout_no_write_verifier_input_count": int(
+                (preview_package.get("summary") or {}).get("ready_closeout_no_write_verifier_input_count") or 0
+            ),
+            "blocked_closeout_no_write_verifier_input_count": int(
+                (preview_package.get("summary") or {}).get("blocked_closeout_no_write_verifier_input_count") or 0
+            ),
+            "rollback_step_count": len(rollback_steps),
+            "post_materialization_verifier_check_count": len(verifier_checks),
+            "writes_database_count": 0,
+            "persists_candidate_count": 0,
+        },
+        "artifact_materialization_package": {
+            "run_id": run_id,
+            "source_preview_id": preview.get("preview_id"),
+            "stage": "P2_retry_exception_closeout_verifier_artifact_materialization",
+            "status": result,
+            "materialize_artifacts": bool(materialize_artifacts),
+            "artifact_root": str(root),
+            "ready_for_artifact_write": materialization_ready,
+            "ready_for_controlled_apply_now": False,
+            "writes_database": False,
+            "rollback_action": "delete_materialized_artifact_files",
+        },
+        "artifact_payloads": artifact_payloads,
+        "materialized_artifacts": materialized_artifacts,
+        "rollback_plan": {
+            "rollback_step_count": len(rollback_steps),
+            "rollback_steps": rollback_steps,
+            "executes_in_package": False,
+            "writes_database": False,
+        },
+        "post_materialization_verifier": {
+            "checks": verifier_checks,
+            "check_count": len(verifier_checks),
+            "executes_database_verifier": False,
+            "writes_database": False,
+        },
+        "source_preview_summary": preview_package.get("summary") or {},
+        "next_actions": [
+            "Use materialized verifier artifacts as the only input to retry exception controlled apply preflight.",
+            "Before any database persistence, require fresh production truth, rollback plan, and post-apply readback.",
+            "If materialized artifacts must be reverted, delete the listed artifact files; no database rollback is needed.",
+        ],
+        "safety": {
+            "ai_controlled_apply": True,
+            "materialize_artifacts": bool(materialize_artifacts),
+            "writes_artifact_count": len(materialized_artifacts),
+            "writes_database": False,
+            "persists_candidate": False,
+            "syncs_external_offers": False,
+            "dispatches_telegram": False,
+            "llm_calls_in_materialization": False,
+            "gemini_allowed": False,
+            "requires_production_version_truth": True,
+        },
+    }
+
+
 def build_pchome_evidence_enrichment_preview(payload: dict[str, Any], batch_size: int = 5) -> dict[str, Any]:
     """Build a read-only evidence enrichment package for mapping targets."""
     operator_preview = build_pchome_mapping_operator_preview(payload, batch_size=batch_size)

tests/test_pchome_mapping_backlog_report.py

@@ -76,6 +76,7 @@ from services.pchome_mapping_backlog_service import (
     build_pchome_direct_mapping_candidate_exception_resolution_closeout_package,
     build_pchome_direct_mapping_retry_candidate_decision_package,
     build_pchome_direct_mapping_retry_candidate_exception_auto_resolution_package,
+    build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package,
     build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_package,
     build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_input_package,
     build_pchome_direct_mapping_retry_candidate_exception_resolution_closeout_package,
@@ -880,6 +881,91 @@ def test_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_pre
     assert call_count["search"] == 2
 
 
+def test_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_writes_artifacts(tmp_path):
+    call_count = {"search": 0}
+
+    def fake_search(targets, limit_per_product, max_products, max_terms_per_product, min_score):
+        call_count["search"] += 1
+        if targets[0].get("source_artifact_id"):
+            if call_count["search"] > 2:
+                return True, "retry_clear", []
+            return True, "retry_found", [
+                {
+                    "product_id": "MOMO-RETRY-REVIEW",
+                    "name": "Direct mapping product 40ml 多款任選",
+                    "price": 499,
+                    "target_pchome_product_id": "PCH-2",
+                    "target_pchome_name": "Direct mapping product 40ml x2",
+                    "target_match_score": 0.74,
+                    "auto_compare_type": "manual_review",
+                    "target_hard_veto": False,
+                },
+                {
+                    "product_id": "MOMO-RETRY-REVIEW-2",
+                    "name": "Direct mapping product 40ml 限量組",
+                    "price": 520,
+                    "target_pchome_product_id": "PCH-2",
+                    "target_pchome_name": "Direct mapping product 40ml x2",
+                    "target_match_score": 0.91,
+                    "auto_compare_type": "manual_review",
+                    "target_hard_veto": False,
+                },
+            ]
+        return True, "found", [
+            {
+                "product_id": "MOMO-UNIT",
+                "name": "Direct mapping product 40ml",
+                "price": 499,
+                "target_pchome_product_id": "PCH-2",
+                "target_pchome_name": "Direct mapping product 40ml x2",
+                "target_match_score": 0.91,
+                "auto_compare_type": "unit_price",
+                "target_hard_veto": True,
+            }
+        ]
+
+    package = build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package(
+        _payload(),
+        batch_size=1,
+        execute_search=True,
+        execute_retry_search=True,
+        max_terms_per_product=6,
+        search_func=fake_search,
+        materialize_artifacts=True,
+        artifact_root=tmp_path,
+    )
+
+    materialization = package["artifact_materialization_package"]
+    assert package["policy"] == (
+        "ai_controlled_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization"
+    )
+    assert package["result"] == "DIRECT_MAPPING_RETRY_EXCEPTION_VERIFIER_ARTIFACTS_MATERIALIZED"
+    assert package["summary"]["artifact_materialization_ready_count"] == 1
+    assert package["summary"]["artifact_payload_count"] == 3
+    assert package["summary"]["artifact_materialized_count"] == 3
+    assert package["summary"]["artifact_write_count"] == 3
+    assert package["summary"]["rollback_step_count"] == 3
+    assert package["summary"]["post_materialization_verifier_check_count"] == 9
+    assert package["summary"]["writes_database_count"] == 0
+    assert materialization["run_id"].startswith("pchome-retry-closeout-verifier-run-")
+    assert materialization["ready_for_artifact_write"] is True
+    assert materialization["ready_for_controlled_apply_now"] is False
+    assert package["rollback_plan"]["writes_database"] is False
+    assert package["post_materialization_verifier"]["writes_database"] is False
+    assert package["safety"]["writes_artifact_count"] == 3
+    assert package["safety"]["writes_database"] is False
+    assert len(package["materialized_artifacts"]) == 3
+    for artifact in package["materialized_artifacts"]:
+        artifact_path = Path(artifact["absolute_path"])
+        assert artifact_path.exists()
+        assert hashlib.sha256(artifact_path.read_bytes()).hexdigest() == artifact["payload_sha256"]
+        payload = json.loads(artifact_path.read_text(encoding="utf-8"))
+        assert payload["run_id"] == materialization["run_id"]
+        assert payload["preview_id"] == materialization["source_preview_id"]
+        assert payload["safety"]["writes_database"] is False
+    assert call_count["search"] == 2
+
+
 def test_ai_automation_readiness_makes_automation_visible_without_manual_primary_flow():
     readiness = build_pchome_growth_ai_automation_readiness(_payload(), batch_size=1)
 
@@ -15336,6 +15422,40 @@ def test_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_pre
     assert payload["safety"]["writes_database"] is False
 
 
+def test_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_route_uses_cached_payload(monkeypatch):
+    from flask import Flask
+    from routes import ai_routes as routes
+
+    monkeypatch.setattr(routes, "_get_cached_pchome_growth_payload", lambda: _payload())
+
+    def fail_engine(database_path):
+        raise AssertionError("cached retry exception closeout verifier artifact materialization should not open a DB engine")
+
+    monkeypatch.setattr(routes, "_create_icaim_dashboard_engine", fail_engine)
+
+    app = Flask(__name__)
+    with app.test_request_context(
+        "/api/ai/pchome-growth/mapping-backlog/direct-mapping-retry-candidate-exception-closeout-verifier-artifact-materialization-package?batch_size=1"
+    ):
+        response = routes.api_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization_package.__wrapped__()
+
+    payload = response.get_json()
+    assert payload["success"] is True
+    assert payload["policy"] == (
+        "ai_controlled_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_materialization"
+    )
+    assert payload["source_endpoint"] == (
+        "/api/ai/pchome-growth/mapping-backlog/direct-mapping-retry-candidate-exception-closeout-verifier-artifact-preview-package"
+    )
+    assert payload["result"] == "WAITING_FOR_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW"
+    assert payload["summary"]["artifact_payload_count"] == 3
+    assert payload["summary"]["artifact_materialized_count"] == 0
+    assert payload["artifact_materialization_package"]["materialize_artifacts"] is False
+    assert payload["safety"]["writes_artifact_count"] == 0
+    assert payload["safety"]["writes_database"] is False
+    assert payload["safety"]["materialize_artifacts"] is False
+
+
 def test_ai_automation_readiness_route_defaults_to_no_search_and_uses_cached_payload(monkeypatch):
     from flask import Flask
     from routes import ai_routes as routes