新增市場情報 review decision writer run receipt
All checks were successful
CD Pipeline / deploy (push) Successful in 1m4s

This commit is contained in:
OoO
2026-05-19 18:04:31 +08:00
parent 75390f8495
commit 45eb0d8464
10 changed files with 1071 additions and 70 deletions

View File

@@ -0,0 +1,437 @@
"""候選審核 queue review_state writer operator run receipt preview。
本模組只審核 CLI 更新 review_state 後由操作員貼回的 writer output 與
post-write smoke 結果;不讀 approval token、不執行 CLI、不開 DB
connection、不更新 review_state、不 commit、不掛 scheduler。
"""
FORBIDDEN_TOKEN_KEYWORDS = (
"approval_token",
"approval-token",
"market_intel_queue_write_approval",
)
SAFE_TOKEN_METADATA_KEYS = {
"approval_token_present",
"approval_token_valid",
"approval_token_secret_configured",
}
SAFE_APPROVAL_ENV_VAR = "MARKET_INTEL_QUEUE_WRITE_APPROVAL"
EXPECTED_WRITER_MODE = "candidate_queue_review_decision_writer_cli_executed"
EXPECTED_SMOKE_MODE = "candidate_queue_review_decision_writer_postwrite_smoke_read_only"
def _as_dict(value):
return value if isinstance(value, dict) else {}
def _as_list(value):
if value is None:
return []
if isinstance(value, (list, tuple, set)):
return list(value)
return [value]
def _safe_int(value):
try:
return int(value or 0)
except (TypeError, ValueError):
return 0
def _has_text(value):
return bool(isinstance(value, str) and value.strip())
def _contains_forbidden_token_key(value):
if isinstance(value, dict):
for key, nested in value.items():
normalized_key = str(key).lower()
if normalized_key in SAFE_TOKEN_METADATA_KEYS and isinstance(nested, bool):
continue
if normalized_key == "approval_env_var" and nested == SAFE_APPROVAL_ENV_VAR:
continue
if any(token_key in normalized_key for token_key in FORBIDDEN_TOKEN_KEYWORDS):
return True
if _contains_forbidden_token_key(nested):
return True
elif isinstance(value, list):
return any(_contains_forbidden_token_key(item) for item in value)
return False
def _expected_updates_from_transaction(transaction_preview):
updates = []
for statement in _as_list(_as_dict(transaction_preview).get("statements")):
statement = _as_dict(statement)
lookup = _as_dict(statement.get("lookup"))
parameter_preview = _as_dict(statement.get("parameter_preview"))
dedupe_key = lookup.get("dedupe_key") or parameter_preview.get("dedupe_key")
next_state = (
parameter_preview.get("next_review_state")
or statement.get("next_review_state")
)
current_state = (
parameter_preview.get("expected_current_review_state")
or statement.get("expected_current_review_state")
)
if dedupe_key:
updates.append(
{
"dedupe_key": str(dedupe_key),
"expected_current_review_state": current_state,
"expected_review_state": next_state,
"idempotency_key": statement.get("idempotency_key"),
"parameter_payload_hash": statement.get(
"parameter_payload_hash"
),
}
)
return updates
def _keys_from_writer_output(writer_output):
writer_output = _as_dict(writer_output)
execution_result = _as_dict(writer_output.get("execution_result"))
affected = (
writer_output.get("affected_dedupe_keys")
or writer_output.get("updated_dedupe_keys")
or execution_result.get("affected_dedupe_keys")
or execution_result.get("updated_dedupe_keys")
or []
)
skipped = (
writer_output.get("skipped_dedupe_keys")
or execution_result.get("skipped_dedupe_keys")
or []
)
return {
"affected": sorted(set(str(key) for key in _as_list(affected) if key)),
"skipped": sorted(set(str(key) for key in _as_list(skipped) if key)),
}
def _keys_match_expected(expected_keys, observed_keys):
if not expected_keys:
return False
return set(expected_keys).issubset(set(observed_keys))
def _operator_evidence_summary(operator_evidence):
return {
"provided_keys": sorted(operator_evidence.keys()),
"writer_output_json_path_recorded": _has_text(
operator_evidence.get("review_state_writer_output_json_path")
or operator_evidence.get("writer_output_json_path")
),
"postwrite_smoke_json_path_recorded": _has_text(
operator_evidence.get("review_state_postwrite_smoke_json_path")
or operator_evidence.get("postwrite_smoke_json_path")
),
"operator_confirmed_no_token_in_artifacts": bool(
operator_evidence.get("operator_confirmed_no_token_in_artifacts")
),
"receipt_notes_recorded": _has_text(operator_evidence.get("receipt_notes")),
"approval_token_submitted_to_api": _contains_forbidden_token_key(
operator_evidence
),
}
def _writer_summary(writer_output, expected_keys):
writer_output = _as_dict(writer_output)
writer_keys = _keys_from_writer_output(writer_output)
observed_keys = sorted(set(writer_keys["affected"] + writer_keys["skipped"]))
return {
"provided": bool(writer_output),
"mode": writer_output.get("mode"),
"exit_code": writer_output.get("exit_code"),
"writes_executed": bool(writer_output.get("writes_executed")),
"would_write_database": bool(writer_output.get("would_write_database")),
"database_connection_opened": bool(
writer_output.get("database_connection_opened")
),
"explicit_transaction_opened": bool(
writer_output.get("explicit_transaction_opened")
),
"database_write_executed": bool(writer_output.get("database_write_executed")),
"database_commit_executed": bool(writer_output.get("database_commit_executed")),
"database_rollback_executed": bool(
writer_output.get("database_rollback_executed")
),
"external_network_executed": bool(writer_output.get("external_network_executed")),
"scheduler_attached": bool(writer_output.get("scheduler_attached")),
"api_updates_review_state": bool(writer_output.get("api_updates_review_state")),
"review_state_update_executed": bool(
writer_output.get("review_state_update_executed")
),
"updated_count": _safe_int(
writer_output.get("updated_count")
or writer_output.get("affected_count")
or writer_output.get("inserted_count")
),
"skipped_count": _safe_int(writer_output.get("skipped_count")),
"affected_dedupe_keys": writer_keys["affected"],
"skipped_dedupe_keys": writer_keys["skipped"],
"observed_dedupe_keys": observed_keys,
"dedupe_keys_match_expected": _keys_match_expected(expected_keys, observed_keys),
"approval_token_key_detected": _contains_forbidden_token_key(writer_output),
}
def _smoke_summary(postwrite_smoke_result, expected_keys):
postwrite_smoke_result = _as_dict(postwrite_smoke_result)
found_keys = sorted(
set(
str(key)
for key in _as_list(postwrite_smoke_result.get("found_dedupe_keys"))
if key
)
)
missing_keys = sorted(
set(
str(key)
for key in _as_list(postwrite_smoke_result.get("missing_dedupe_keys"))
if key
)
)
return {
"provided": bool(postwrite_smoke_result),
"mode": postwrite_smoke_result.get("mode"),
"postwrite_smoke_passed": bool(
postwrite_smoke_result.get("postwrite_smoke_passed")
),
"review_state_update_verified": bool(
postwrite_smoke_result.get("review_state_update_verified")
),
"ready_for_operator_review": bool(
postwrite_smoke_result.get("ready_for_operator_review")
),
"read_only_query_executed": bool(
postwrite_smoke_result.get("read_only_query_executed")
),
"database_connection_opened": bool(
postwrite_smoke_result.get("database_connection_opened")
),
"database_write_executed": bool(
postwrite_smoke_result.get("database_write_executed")
),
"database_commit_executed": bool(
postwrite_smoke_result.get("database_commit_executed")
),
"external_network_executed": bool(
postwrite_smoke_result.get("external_network_executed")
),
"scheduler_attached": bool(postwrite_smoke_result.get("scheduler_attached")),
"expected_dedupe_key_count": _safe_int(
postwrite_smoke_result.get("expected_dedupe_key_count")
),
"found_count": _safe_int(postwrite_smoke_result.get("found_count")),
"missing_count": _safe_int(postwrite_smoke_result.get("missing_count")),
"state_mismatch_count": _safe_int(
postwrite_smoke_result.get("state_mismatch_count")
),
"found_dedupe_keys": found_keys,
"missing_dedupe_keys": missing_keys,
"state_mismatches": _as_list(postwrite_smoke_result.get("state_mismatches")),
"dedupe_keys_match_expected": _keys_match_expected(expected_keys, found_keys)
and not missing_keys,
"approval_token_key_detected": _contains_forbidden_token_key(
postwrite_smoke_result
),
}
def _receipt_gates(
*,
expected_keys,
run_readiness,
writer_summary,
smoke_summary,
evidence_summary,
):
return [
{
"key": "run_readiness_passed_before_cli",
"label": "CLI 更新前 run readiness 必須已通過",
"passed": bool(run_readiness.get("ready_for_cli_operator_run")),
},
{
"key": "expected_dedupe_keys_present",
"label": "review_state transaction preview 必須有 dedupe key",
"passed": bool(expected_keys),
},
{
"key": "writer_output_provided",
"label": "操作員需貼回 CLI review_state writer output",
"passed": writer_summary["provided"],
},
{
"key": "writer_output_executed_and_committed",
"label": "writer output 必須顯示 CLI 已更新 review_state 並 commit",
"passed": bool(
writer_summary["mode"] == EXPECTED_WRITER_MODE
and writer_summary["writes_executed"]
and writer_summary["review_state_update_executed"]
and writer_summary["database_write_executed"]
and writer_summary["database_commit_executed"]
),
},
{
"key": "writer_output_dedupe_keys_match_expected",
"label": "writer output 的 affected/skipped dedupe key 必須符合 transaction preview",
"passed": writer_summary["dedupe_keys_match_expected"],
},
{
"key": "writer_output_safe_runtime_boundaries",
"label": "writer output 不得顯示 scheduler、外部網路或 rollback error",
"passed": bool(
not writer_summary["scheduler_attached"]
and not writer_summary["external_network_executed"]
and not writer_summary["database_rollback_executed"]
and not writer_summary["api_updates_review_state"]
),
},
{
"key": "writer_output_no_approval_token_key",
"label": "writer output 不得包含 approval token key",
"passed": not writer_summary["approval_token_key_detected"],
},
{
"key": "postwrite_smoke_result_provided",
"label": "操作員需貼回 review_state post-write smoke 結果",
"passed": smoke_summary["provided"],
},
{
"key": "postwrite_smoke_read_only_passed",
"label": "post-write smoke 必須是只讀查詢且通過",
"passed": bool(
smoke_summary["mode"] == EXPECTED_SMOKE_MODE
and smoke_summary["read_only_query_executed"]
and smoke_summary["postwrite_smoke_passed"]
and smoke_summary["review_state_update_verified"]
),
},
{
"key": "postwrite_smoke_no_database_write",
"label": "post-write smoke 不得寫 DB 或 commit",
"passed": bool(
not smoke_summary["database_write_executed"]
and not smoke_summary["database_commit_executed"]
),
},
{
"key": "postwrite_smoke_dedupe_keys_match_expected",
"label": "post-write smoke 找到的 queue row 必須符合 transaction preview",
"passed": smoke_summary["dedupe_keys_match_expected"],
},
{
"key": "postwrite_smoke_no_state_mismatch",
"label": "post-write smoke 不得出現 review_state mismatch",
"passed": bool(not smoke_summary["state_mismatch_count"]),
},
{
"key": "postwrite_smoke_no_approval_token_key",
"label": "post-write smoke 結果不得包含 approval token key",
"passed": not smoke_summary["approval_token_key_detected"],
},
{
"key": "receipt_artifact_paths_recorded",
"label": "操作員需記錄 writer output 與 post-write smoke artifact 路徑",
"passed": bool(
evidence_summary["writer_output_json_path_recorded"]
and evidence_summary["postwrite_smoke_json_path_recorded"]
),
},
{
"key": "operator_confirmed_no_token_in_artifacts",
"label": "操作員確認 artifact 不含一次性 token",
"passed": bool(
evidence_summary["operator_confirmed_no_token_in_artifacts"]
and not evidence_summary["approval_token_submitted_to_api"]
),
},
]
def build_candidate_queue_review_decision_writer_run_receipt(
*,
transaction_preview,
run_readiness,
writer_output=None,
postwrite_smoke_result=None,
operator_evidence=None,
):
"""建立 review_state CLI 更新後 receipt review不執行任何副作用。"""
expected_updates = _expected_updates_from_transaction(transaction_preview)
expected_keys = sorted({item["dedupe_key"] for item in expected_updates})
operator_evidence = _as_dict(operator_evidence)
evidence_summary = _operator_evidence_summary(operator_evidence)
writer_summary = _writer_summary(writer_output, expected_keys)
smoke_summary = _smoke_summary(postwrite_smoke_result, expected_keys)
gates = _receipt_gates(
expected_keys=expected_keys,
run_readiness=_as_dict(run_readiness),
writer_summary=writer_summary,
smoke_summary=smoke_summary,
evidence_summary=evidence_summary,
)
blocked_reasons = [gate["key"] for gate in gates if not gate["passed"]]
receipt_passed = bool(not blocked_reasons)
return {
"mode": "candidate_queue_review_decision_writer_run_receipt_preview",
"target_table": "market_alert_review_queue",
"target_operation": "update_review_state",
"receipt_reviewed": True,
"receipt_passed": receipt_passed,
"ready_for_next_manual_phase": receipt_passed,
"ready_for_api_review_state_update": False,
"ready_for_api_database_write": False,
"ready_for_scheduler_attach": False,
"api_executes_cli": False,
"api_reads_approval_token": False,
"api_writes_file": False,
"api_writes_database": False,
"api_updates_review_state": False,
"approval_record_written": False,
"decision_record_written": False,
"review_state_update_executed": False,
"database_connection_opened": False,
"database_session_created": False,
"explicit_transaction_opened": False,
"transaction_opened": False,
"transaction_committed": False,
"database_write_executed": False,
"database_commit_executed": False,
"database_rollback_executed": False,
"external_network_executed": False,
"scheduler_attached": False,
"writes_executed": False,
"would_write_database": False,
"expected_dedupe_keys": expected_keys,
"expected_review_state_updates": expected_updates,
"blocked_reasons": blocked_reasons,
"gates": gates,
"operator_evidence_summary": evidence_summary,
"writer_output_summary": writer_summary,
"postwrite_smoke_summary": smoke_summary,
"next_operator_steps": [
"保存 review_state writer output 與 post-write smoke artifact",
"人工確認每個 dedupe_key 的 review_state 已符合 transaction preview",
"只在 receipt 通過後才進入 review_state closeout 與後續 read-only inventory",
"不得從 UI/API 補寫、重跑 CLI 或自動掛 scheduler",
],
"safe_boundaries": [
"do_not_execute_review_state_writer_from_receipt_api",
"do_not_read_approval_token_from_receipt_api",
"do_not_echo_operator_receipt_payload",
"do_not_open_database_connection_from_review_state_receipt",
"do_not_update_review_state_from_review_state_receipt",
"do_not_commit_review_state_receipt",
"do_not_attach_scheduler_from_review_state_receipt",
"no_remove_orphans",
"no_momo_db_lifecycle_change",
],
}

View File

@@ -22,10 +22,11 @@ from services.market_intel.candidate_queue_review_decision_writer_postwrite_smok
from services.market_intel.candidate_queue_review_decision_writer_operator_drill import build_candidate_queue_review_decision_writer_operator_drill
from services.market_intel.candidate_queue_review_decision_writer_run_package import build_candidate_queue_review_decision_writer_run_package
from services.market_intel.candidate_queue_review_decision_writer_run_readiness import build_candidate_queue_review_decision_writer_run_readiness
from services.market_intel.candidate_queue_review_decision_writer_run_receipt import build_candidate_queue_review_decision_writer_run_receipt
BLOCKED_RUN_REVIEW_KEYS = ("ready_for_api_database_write", "ready_for_scheduler_attach", "api_executes_cli", "api_reads_approval_token", "api_writes_file", "api_writes_database", "api_updates_review_state", "approval_record_written", "decision_record_written", "review_state_update_executed", "database_connection_opened", "database_session_created", "explicit_transaction_opened", "transaction_opened", "transaction_committed", "database_write_executed", "database_commit_executed", "database_rollback_executed", "scheduler_attached", "writes_executed", "would_write_database")
PRODUCTION_SMOKE_TARGETS = ("/health", "/market_intel", "/api/market_intel/status", "/api/market_intel/deployment_readiness", "/api/market_intel/schema_smoke", "/api/market_intel/schema_db_probe", "/api/market_intel/platform_seed_db_diff", "/api/market_intel/legacy_source_bridge", "/api/market_intel/mcp_readiness", "/api/market_intel/mcp_tool_contract", "/api/market_intel/mcp_deploy_preflight", "/api/market_intel/mcp_activation_runbook", "/api/market_intel/mcp_fetch_gate", "/api/market_intel/scheduler_plan", "/api/market_intel/manual_sample_plan", "/api/market_intel/manual_sample_acceptance", "/api/market_intel/manual_sample_review", "/api/market_intel/match_review_plan", "/api/market_intel/opportunity_plan", "/api/market_intel/opportunity_scoring_plan", "/api/market_intel/opportunity_evidence_plan", "/api/market_intel/opportunity_alert_plan", "/api/market_intel/migration_apply_drill", "/api/market_intel/migration_catalog_review", "/api/market_intel/migration_live_smoke", "/api/market_intel/live_db_inventory", "/api/market_intel/manual_sample_review/candidate_queue_writer_postwrite_smoke", "/api/market_intel/manual_sample_review/candidate_queue_writer_operator_drill", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_package", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_readiness", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_receipt", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_closeout", "/api/market_intel/manual_sample_review/candidate_queue_review_handoff", "/api/market_intel/manual_sample_review/candidate_queue_review_inventory", "/api/market_intel/manual_sample_review/candidate_queue_review_decision", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_approval", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_transaction", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_preflight", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_postwrite_smoke", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_operator_drill", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_package", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_readiness", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_status")
PRODUCTION_SMOKE_TARGETS = ("/health", "/market_intel", "/api/market_intel/status", "/api/market_intel/deployment_readiness", "/api/market_intel/schema_smoke", "/api/market_intel/schema_db_probe", "/api/market_intel/platform_seed_db_diff", "/api/market_intel/legacy_source_bridge", "/api/market_intel/mcp_readiness", "/api/market_intel/mcp_tool_contract", "/api/market_intel/mcp_deploy_preflight", "/api/market_intel/mcp_activation_runbook", "/api/market_intel/mcp_fetch_gate", "/api/market_intel/scheduler_plan", "/api/market_intel/manual_sample_plan", "/api/market_intel/manual_sample_acceptance", "/api/market_intel/manual_sample_review", "/api/market_intel/match_review_plan", "/api/market_intel/opportunity_plan", "/api/market_intel/opportunity_scoring_plan", "/api/market_intel/opportunity_evidence_plan", "/api/market_intel/opportunity_alert_plan", "/api/market_intel/migration_apply_drill", "/api/market_intel/migration_catalog_review", "/api/market_intel/migration_live_smoke", "/api/market_intel/live_db_inventory", "/api/market_intel/manual_sample_review/candidate_queue_writer_postwrite_smoke", "/api/market_intel/manual_sample_review/candidate_queue_writer_operator_drill", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_package", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_readiness", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_receipt", "/api/market_intel/manual_sample_review/candidate_queue_writer_run_closeout", "/api/market_intel/manual_sample_review/candidate_queue_review_handoff", "/api/market_intel/manual_sample_review/candidate_queue_review_inventory", "/api/market_intel/manual_sample_review/candidate_queue_review_decision", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_approval", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_transaction", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_preflight", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_postwrite_smoke", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_operator_drill", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_package", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_readiness", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_receipt", "/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_status")
def _run_review_preview_safe(payload, mode):
@@ -150,6 +151,10 @@ def build_deployment_readiness_preview(
operator_drill=candidate_queue_review_decision_writer_operator_drill,
run_package=candidate_queue_review_decision_writer_run_package,
)
candidate_queue_review_decision_writer_run_receipt = build_candidate_queue_review_decision_writer_run_receipt(
transaction_preview=candidate_queue_review_decision_transaction,
run_readiness=candidate_queue_review_decision_writer_run_readiness,
)
checks = {
"schema_smoke_passed": bool(schema_smoke["passed"]),
"feature_flags_default_safe": bool(
@@ -408,6 +413,10 @@ def build_deployment_readiness_preview(
candidate_queue_review_decision_writer_run_readiness,
"candidate_queue_review_decision_writer_run_readiness_preview",
),
"candidate_queue_review_decision_writer_run_receipt_preview_safe": _run_review_preview_safe(
candidate_queue_review_decision_writer_run_receipt,
"candidate_queue_review_decision_writer_run_receipt_preview",
),
"candidate_queue_review_decision_writer_cli_status_safe": _run_review_preview_safe(
candidate_queue_review_decision_writer_status,
"candidate_queue_review_decision_writer_cli_blocked",
@@ -649,6 +658,7 @@ def build_deployment_readiness_preview(
"candidate_queue_review_decision_writer_operator_drill": candidate_queue_review_decision_writer_operator_drill,
"candidate_queue_review_decision_writer_run_package": candidate_queue_review_decision_writer_run_package,
"candidate_queue_review_decision_writer_run_readiness": candidate_queue_review_decision_writer_run_readiness,
"candidate_queue_review_decision_writer_run_receipt": candidate_queue_review_decision_writer_run_receipt,
"candidate_queue_review_decision_writer_status": candidate_queue_review_decision_writer_status,
"match_review_plan": match_review_plan,
"opportunity_plan": opportunity_plan,

View File

@@ -1,3 +1,3 @@
"""市場情報 rollout phase 單一來源。"""
MARKET_INTEL_PHASE = "phase_74_candidate_queue_review_decision_writer_run_readiness"
MARKET_INTEL_PHASE = "phase_75_candidate_queue_review_decision_writer_run_receipt"