補齊 PChome retry verifier artifact preview

routes/ai_routes.py

@@ -2192,6 +2192,61 @@ 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-preview-package')
+@login_required
+def api_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_package():
+    """P2 no-write verifier artifact preview 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_preview_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'}
+        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_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,
+        )
+        package["source_endpoint"] = (
+            "/api/ai/pchome-growth/mapping-backlog/direct-mapping-retry-candidate-exception-closeout-verifier-input-package"
+        )
+        return jsonify(package)
+    except Exception as exc:
+        logger.error("[PChomeGrowth] direct mapping retry candidate exception closeout verifier artifact preview 讀取失敗: %s", exc, exc_info=True)
+        return jsonify({
+            "success": False,
+            "error": "PChome 商品對應 retry 例外 verifier artifact preview 暫時無法讀取，請稍後再試。",
+        }), 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

@@ -56,6 +56,9 @@ DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_RESOLUTION_CLOSEOUT_POLICY = (
 DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_INPUT_POLICY = (
     "read_only_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_input"
 )
+DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW_POLICY = (
+    "read_only_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview"
+)
 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"
@@ -2875,6 +2878,248 @@ def build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_inpu
     }
 
 
+def _retry_exception_closeout_verifier_artifact_preview_id(verifier_package: dict[str, Any]) -> str:
+    payload = {
+        "policy": verifier_package.get("policy") or "",
+        "result": verifier_package.get("result") or "",
+        "summary": verifier_package.get("summary") or {},
+        "source_policy": verifier_package.get("source_policy") 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-artifacts-{digest[:16]}"
+
+
+def build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_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,
+) -> dict[str, Any]:
+    """Preview no-write verifier artifacts for retry exception closeout inputs."""
+    verifier_package = build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_input_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,
+    )
+    package = verifier_package.get("retry_exception_closeout_verifier_input_package") or {}
+    verifier_receipts = list(package.get("no_write_verifier_receipts") or [])
+    ready_receipts = [
+        receipt
+        for receipt in verifier_receipts
+        if receipt.get("receipt_status") == "NO_WRITE_VERIFIER_INPUT_READY"
+        and receipt.get("ready_for_no_write_verifier")
+    ]
+    blocked_receipts = [receipt for receipt in verifier_receipts if receipt not in ready_receipts]
+    summary = verifier_package.get("summary") or {}
+    preview_ready = bool(ready_receipts) and not blocked_receipts
+    preview_status = (
+        "DIRECT_MAPPING_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW_READY"
+        if preview_ready
+        else (
+            "DIRECT_MAPPING_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW_PARTIAL"
+            if ready_receipts
+            else "WAITING_FOR_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_INPUTS"
+        )
+    )
+    preview_id = _retry_exception_closeout_verifier_artifact_preview_id(verifier_package)
+    artifact_schemas = [
+        {
+            "key": "retry_exception_closeout_verifier_input_artifact",
+            "artifact_type": "no_write_verifier_input_receipts",
+            "artifact_path_template": "artifacts/pchome_growth/retry_exception_closeout/verifier_inputs/{run_id}.json",
+            "source_receipt_count": len(ready_receipts),
+            "required_fields": [
+                "run_id",
+                "preview_id",
+                "no_write_verifier_receipts",
+                "source_closeout_receipt_ids",
+                "verification_checks",
+                "created_at",
+                "safety",
+            ],
+            "required": True,
+            "writes_artifact_in_preview": False,
+            "writes_database": False,
+        },
+        {
+            "key": "retry_exception_identity_readback_artifact",
+            "artifact_type": "identity_readback_plan",
+            "artifact_path_template": "artifacts/pchome_growth/retry_exception_closeout/identity_readback/{run_id}.json",
+            "source_receipt_count": len(ready_receipts),
+            "required_fields": [
+                "run_id",
+                "preview_id",
+                "target_pchome_product_ids",
+                "momo_product_ids",
+                "identity_delta_status",
+                "created_at",
+                "safety",
+            ],
+            "required": True,
+            "writes_artifact_in_preview": False,
+            "writes_database": False,
+        },
+        {
+            "key": "retry_exception_controlled_apply_preflight_artifact",
+            "artifact_type": "controlled_apply_preflight",
+            "artifact_path_template": "artifacts/pchome_growth/retry_exception_closeout/controlled_apply_preflight/{run_id}.json",
+            "source_receipt_count": len(ready_receipts),
+            "required_fields": [
+                "run_id",
+                "preview_id",
+                "ready_no_write_verifier_input_count",
+                "blocked_no_write_verifier_input_count",
+                "rollback_plan_required",
+                "production_readback_required",
+                "created_at",
+                "safety",
+            ],
+            "required": True,
+            "writes_artifact_in_preview": False,
+            "writes_database": False,
+        },
+    ]
+    generation_steps = [
+        {
+            "name": "create_retry_exception_verifier_run_id",
+            "run_id_template": "pchome-retry-closeout-verifier-{utc_timestamp}-{preview_digest}",
+            "required": True,
+            "writes_artifact_in_preview": False,
+        },
+        {
+            "name": "render_no_write_verifier_input_artifact_schema",
+            "artifact_key": "retry_exception_closeout_verifier_input_artifact",
+            "required": True,
+            "writes_artifact_in_preview": False,
+        },
+        {
+            "name": "render_identity_readback_artifact_schema",
+            "artifact_key": "retry_exception_identity_readback_artifact",
+            "required": True,
+            "writes_artifact_in_preview": False,
+        },
+        {
+            "name": "render_controlled_apply_preflight_artifact_schema",
+            "artifact_key": "retry_exception_controlled_apply_preflight_artifact",
+            "required": True,
+            "writes_artifact_in_preview": False,
+        },
+        {
+            "name": "link_artifacts_to_retry_exception_closeout_verifier_inputs",
+            "source_ready_receipt_count": len(ready_receipts),
+            "required": True,
+            "writes_artifact_in_preview": False,
+        },
+    ]
+    verifier_manifest = {
+        "pre_apply_checks": [
+            "production_truth_fresh_within_300_seconds",
+            "all_ready_no_write_verifier_inputs_have_subject",
+            "retry_candidate_pending_count_is_zero",
+            "blocked_verifier_input_count_is_zero",
+            "database_write_locked",
+        ],
+        "artifact_integrity_checks": [
+            "all_artifacts_include_run_id",
+            "all_artifacts_include_preview_id",
+            "all_source_receipts_have_verification_checks",
+            "controlled_apply_preflight_references_rollback_and_readback",
+        ],
+        "post_preview_checks": [
+            "ready_inputs_can_enter_verifier_artifact_preview",
+            "no_artifact_written_in_preview",
+            "no_database_write_in_preview",
+        ],
+        "failure_handlers": [
+            "route_blocked_inputs_back_to_retry_candidate_decision",
+            "route_missing_identity_back_to_exception_closeout",
+            "abort_controlled_apply_if_artifact_integrity_fails",
+        ],
+        "verifier_check_count": 15,
+        "executes_in_preview": False,
+        "writes_artifact_in_preview": False,
+        "writes_database": False,
+    }
+
+    return {
+        "policy": DIRECT_MAPPING_RETRY_CANDIDATE_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW_POLICY,
+        "result": preview_status,
+        "success": bool(verifier_package.get("success")),
+        "generated_at": verifier_package.get("generated_at"),
+        "source_policy": verifier_package.get("policy"),
+        "stats": verifier_package.get("stats") or {},
+        "backlog": verifier_package.get("backlog") or {},
+        "summary": {
+            "verifier_artifact_preview_ready_count": 1 if preview_ready else 0,
+            "closeout_no_write_verifier_input_count": int(
+                summary.get("closeout_no_write_verifier_input_count") or 0
+            ),
+            "ready_closeout_no_write_verifier_input_count": len(ready_receipts),
+            "blocked_closeout_no_write_verifier_input_count": len(blocked_receipts),
+            "retry_candidate_pending_count": int(summary.get("retry_candidate_pending_count") or 0),
+            "artifact_schema_count": len(artifact_schemas),
+            "artifact_generation_step_count": len(generation_steps),
+            "verifier_manifest_check_count": verifier_manifest["verifier_check_count"],
+            "writes_artifact_count": 0,
+            "writes_database_count": 0,
+            "persists_candidate_count": 0,
+        },
+        "retry_exception_closeout_verifier_artifact_preview": {
+            "preview_id": preview_id,
+            "stage": "P2_retry_exception_closeout_verifier_artifact_preview",
+            "status": preview_status,
+            "ready_for_future_artifact_generation": preview_ready,
+            "ready_to_write_artifacts_now": False,
+            "ready_for_controlled_apply_now": False,
+            "source_ready_receipt_count": len(ready_receipts),
+            "source_blocked_receipt_count": len(blocked_receipts),
+            "writes_artifact_in_preview": False,
+            "writes_database_in_preview": False,
+            "manual_review_mode": "exception_only",
+        },
+        "artifact_schemas": artifact_schemas,
+        "artifact_generation_plan": {
+            "mode": "future_controlled_apply_run_only",
+            "generation_steps": generation_steps,
+            "generation_step_count": len(generation_steps),
+            "writes_artifact_in_preview": False,
+            "writes_database": False,
+        },
+        "verifier_manifest": verifier_manifest,
+        "source_verifier_input_summary": summary,
+        "next_actions": [
+            "Use ready artifact preview as the input to controlled apply preflight only after fresh production truth.",
+            "Keep artifact writing disabled in preview; future apply run must write artifacts with rollback and readback.",
+            "Route any blocked verifier inputs back to retry candidate decision or exception closeout automatically.",
+        ],
+        "safety": {
+            "read_only_preview": True,
+            "executes_search": bool(execute_search),
+            "executes_retry_search": bool(execute_retry_search),
+            "writes_artifact_in_preview": False,
+            "writes_database": False,
+            "persists_candidate": False,
+            "syncs_external_offers": False,
+            "dispatches_telegram": False,
+            "llm_calls_in_preview": 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_preview_package,
     build_pchome_direct_mapping_retry_candidate_exception_closeout_verifier_input_package,
     build_pchome_direct_mapping_retry_candidate_exception_resolution_closeout_package,
     build_pchome_growth_ai_automation_readiness,
@@ -799,6 +800,86 @@ def test_direct_mapping_retry_candidate_exception_closeout_verifier_input_packag
     assert call_count["search"] == 3
 
 
+def test_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_package_builds_manifest():
+    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_preview_package(
+        _payload(),
+        batch_size=1,
+        execute_search=True,
+        execute_retry_search=True,
+        max_terms_per_product=6,
+        search_func=fake_search,
+    )
+
+    preview = package["retry_exception_closeout_verifier_artifact_preview"]
+    artifact_keys = [schema["key"] for schema in package["artifact_schemas"]]
+    assert package["policy"] == (
+        "read_only_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview"
+    )
+    assert package["result"] == "DIRECT_MAPPING_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_ARTIFACT_PREVIEW_READY"
+    assert package["summary"]["verifier_artifact_preview_ready_count"] == 1
+    assert package["summary"]["ready_closeout_no_write_verifier_input_count"] == 2
+    assert package["summary"]["blocked_closeout_no_write_verifier_input_count"] == 0
+    assert package["summary"]["artifact_schema_count"] == 3
+    assert package["summary"]["artifact_generation_step_count"] == 5
+    assert package["summary"]["verifier_manifest_check_count"] == 15
+    assert package["summary"]["writes_artifact_count"] == 0
+    assert package["summary"]["writes_database_count"] == 0
+    assert preview["preview_id"].startswith("pchome-retry-closeout-verifier-artifacts-")
+    assert preview["ready_for_future_artifact_generation"] is True
+    assert preview["ready_to_write_artifacts_now"] is False
+    assert preview["ready_for_controlled_apply_now"] is False
+    assert "retry_exception_closeout_verifier_input_artifact" in artifact_keys
+    assert "retry_exception_identity_readback_artifact" in artifact_keys
+    assert "retry_exception_controlled_apply_preflight_artifact" in artifact_keys
+    assert package["artifact_generation_plan"]["writes_artifact_in_preview"] is False
+    assert package["verifier_manifest"]["writes_artifact_in_preview"] is False
+    assert package["safety"]["writes_artifact_in_preview"] is False
+    assert package["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)
 
@@ -15221,6 +15302,40 @@ def test_direct_mapping_retry_candidate_exception_closeout_verifier_input_route_
     assert payload["safety"]["writes_database"] is False
 
 
+def test_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_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 preview 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-preview-package?batch_size=1"
+    ):
+        response = routes.api_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview_package.__wrapped__()
+
+    payload = response.get_json()
+    assert payload["success"] is True
+    assert payload["policy"] == (
+        "read_only_pchome_growth_direct_mapping_retry_candidate_exception_closeout_verifier_artifact_preview"
+    )
+    assert payload["source_endpoint"] == (
+        "/api/ai/pchome-growth/mapping-backlog/direct-mapping-retry-candidate-exception-closeout-verifier-input-package"
+    )
+    assert payload["result"] == "WAITING_FOR_RETRY_EXCEPTION_CLOSEOUT_VERIFIER_INPUTS"
+    assert payload["summary"]["artifact_schema_count"] == 3
+    assert payload["retry_exception_closeout_verifier_artifact_preview"]["ready_to_write_artifacts_now"] is False
+    assert payload["safety"]["writes_artifact_in_preview"] is False
+    assert payload["safety"]["executes_search"] is False
+    assert payload["safety"]["executes_retry_search"] is False
+    assert payload["safety"]["writes_database"] 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