FR-056.4 執行編排 + 結果轉證據 + 通知 + 歷史 Implementation Plan

-- Date: 2026-07-26
-- FR-056.4 job_evidences.source 加 DETECTION_TOOL
ALTER TABLE compliance.job_evidences DROP CONSTRAINT IF EXISTS chk_job_evidences_source;
ALTER TABLE compliance.job_evidences ADD CONSTRAINT chk_job_evidences_source
    CHECK (source IN ('SYSTEM_UPLOAD','DRIVE_SYNC','DETECTION_TOOL'));
INSERT INTO public.schema_migrations(filename, note) VALUES
  ('2026-07-26-fr056-4-job-evidences-detection-source.sql', 'FR-056.4 job_evidences source 加 DETECTION_TOOL') ON CONFLICT (filename) DO NOTHING;

-- Date: 2026-07-26
-- FR-056.4 檢測執行歷史（一次執行一筆，可查可下載）
CREATE TABLE compliance.detection_executions (
    id                 BIGSERIAL PRIMARY KEY,
    uid                VARCHAR(36)  NOT NULL UNIQUE,
    tenant_id          BIGINT       NOT NULL,
    agent_task_uid     VARCHAR(36),                         -- soft-ref → compliance.agent_tasks.uid
    job_execution_uid  VARCHAR(50)  NOT NULL,               -- soft-ref → job_executions.uid
    detection_tool_id  BIGINT       NOT NULL,
    started_at         TIMESTAMPTZ, finished_at TIMESTAMPTZ,
    status             VARCHAR(20)  NOT NULL DEFAULT 'running',  -- running/succeeded/failed
    summary            JSONB,                               -- 摘要（發現幾項等）
    report_file_id     BIGINT,                              -- soft-ref → upload_files.id（原始報告，供下載）
    evidence_id        BIGINT,                              -- soft-ref → job_evidences.id（轉出的證據）
    error_message      TEXT,
    created_user       VARCHAR(255), updated_user VARCHAR(255),
    created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);
COMMENT ON TABLE compliance.detection_executions IS 'FR-056.4 檢測執行歷史（每次執行一筆，重掃不覆蓋）';
GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.detection_executions TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.detection_executions_id_seq TO cm_app;
ALTER TABLE compliance.detection_executions ENABLE ROW LEVEL SECURITY;
CREATE POLICY detection_executions_tenant_isolation ON compliance.detection_executions
    USING (current_setting('app.is_super_admin', TRUE) = 'true'
           OR tenant_id = ANY (string_to_array(current_setting('app.allowed_tenant_paths', TRUE), ',')::BIGINT[]));
INSERT INTO public.schema_migrations(filename, note) VALUES
  ('2026-07-26-fr056-4-detection-executions.sql', 'FR-056.4 檢測執行歷史表') ON CONFLICT (filename) DO NOTHING;

DETECTION_AGENT_USER = "detection-agent@system"

class DetectionResultHandler:
    def __init__(self, file_upload_service, job_evidence_domain_service,
                 detection_execution_domain_service, job_execution_domain_service):
        ...

    @transaction
    def handle_result(self, agent_task, report_file_bytes, summary):
        """agent 回報成功後呼叫：報告存 Minio → 寫 job_evidences(DETECTION_TOOL) → detection_executions 落史。"""
        job = self._job_exec.get_job_execution(JobExecutionQueryEntity(uid=agent_task.job_execution_uid))
        # (1) 存 Minio（mirror ImportDriveFileHandler）
        fs = FileStorage(stream=io.BytesIO(report_file_bytes), filename=f"detection_report_{agent_task.uid}.xml",
                         content_type="application/xml")
        save_dir = f"JOB_EVIDENCES/{job.uid}"
        uploaded = self._file_upload.upload_files([fs], DETECTION_AGENT_USER, save_dir)[0]
        # (2) 寫 job_evidences（source=DETECTION_TOOL）
        evidence = self._evidence.add(JobEvidenceEntity(
            main_workflow_execution_id=job.main_workflow_execution_id,
            workflow_execution_id=job.workflow_execution_id,
            job_execution_id=job.id,
            evidence_type="FILE",            # D11 定案：用 FILE（REPORT 改動面大，未來另開需求）
            source="DETECTION_TOOL",
            file_id=uploaded.id,
            content_hash=getattr(uploaded, "checksum", None), hash_algorithm="MD5",
            description=f"[檢測工具] {agent_task.uid}",
            created_user=DETECTION_AGENT_USER, updated_user=DETECTION_AGENT_USER,
        ))
        # (3) detection_executions 落史
        self._exec.write_success(agent_task.uid, job.uid, report_file_id=uploaded.id,
                                 evidence_id=evidence.id, summary=summary, user=DETECTION_AGENT_USER)
        return evidence

git commit -m "feat(fr056): detection result → evidence handler + execution history (T-4.1)"

@transaction
def start_execution(self, job_uid, curr_user, tenant_id):
    binding = self._jedt_domain.get_one(job_execution_uid=job_uid)   # FR-056.2 綁定
    if not binding:
        raise BadRequestError(DetectionToolsErrorCode.DETECTION_TOOL_NOT_BOUND)
    # 選一台有 detection_scan capability 的 agent（tenant 內）
    agent = self._pick_agent(tenant_id)
    # 解密該租戶工具憑證，隨派工下發（走 mTLS，見 FR-056.3 憑證下發決策）
    creds = self._resolve_credentials(binding, tenant_id)
    task = self._agent_task_domain.create(AgentTaskEntity(
        uid=str(uuid.uuid4()), tenant_id=tenant_id, agent_id=agent.id,
        job_execution_uid=job_uid, detection_tool_id=binding.detection_tool_id,
        params={**binding.tool_params, "_credentials": creds}, status="pending",
        created_user=curr_user, updated_user=curr_user))
    self._exec_domain.create(DetectionExecutionEntity(
        uid=str(uuid.uuid4()), tenant_id=tenant_id, agent_task_uid=task.uid,
        job_execution_uid=job_uid, detection_tool_id=binding.detection_tool_id,
        status="running", started_at=datetime.now(), created_user=curr_user))
    return {"agent_task_uid": task.uid}

def _on_scan_succeeded(self, agent_task, report_bytes, summary):
    evidence = self._result_handler.handle_result(agent_task, report_bytes, summary)  # Task 1
    binding = self._jedt_domain.get_one(job_execution_uid=agent_task.job_execution_uid)
    self._notify_owner(agent_task.job_execution_uid, evidence)                          # 發信
    if binding.completion_mode == "auto":
        self._workflow_execution_service.complete_job(...)   # 既有 complete_job，PROCESSING→COMPLETED
    # manual：什麼都不做，任務留 PROCESSING，等人工手動完成

def _notify_owner(self, job_uid, evidence):
    targets = self._get_job_notify_targets(job_uid)   # 查 task_assignees / ParticipantRole email
    subject = _("detection_scan_completed_subject")
    for info in targets:
        if info["email"]:
            content = _("detection_scan_completed_content") % {"nickname": info["nickname"]}
            threading.Thread(target=notification_service.send_mail_notification,
                             kwargs={"to": info["email"], "subject": subject, "content": content, "is_html": True}).start()

git commit -m "feat(fr056): execution orchestration + completion mode + notify (T-4.2)

開始執行串派工；掃完轉證據 + 發信；completion_mode=auto 呼叫既有 complete_job，manual 留任務 PROCESSING 等人工。零新增 JobStatus。"

git commit -m "feat(fr056): detection task execution drawer (T-4.3)"