Spec 2：階段抽象整合 — 實作計畫

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be

# 1. OscalAuditService 4 個 method 簽名仍存在
grep -n "def activate_project\|def launch_audit\|def confirm_audit\|def close_round" \
     app/project/service/oscal_audit_service.py
# 預期：line 77 / 169 / 323 / 419，簽名 (project_uid, [user_id,] ap_uid, [force,] curr_user)

# 2. WorkflowExecutionService.start_workflow_execution / complete_job 仍存在
grep -n "def start_workflow_execution\|def complete_job" \
     app/flow_engine/service/workflow_execution_service.py
# 預期：line 129 / 419

# 3. Stage object schema 已 seed 4 個
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
     -c "SELECT code, name_zh, complete_handler_key, precondition_key FROM compliance.stage_objects ORDER BY id;"
# 預期：planning / task_execution / audit / poam 4 列

# 4. Spec 2 預留 error code 序號未被佔
grep -E "GRC_412021|GRC_403050|GRC_400050|GRC_404029|GRC_400051|GRC_400052" \
     common/code/grc_error_code.py
# 預期：6 個都查不到

# 5. compliance.assessment_plan_extensions 表還沒建
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
     -c "\d compliance.assessment_plan_extensions"
# 預期：Did not find any relation

-- Date: 2026-05-XX
-- Spec 2 階段抽象整合 — AP extension table + RLS

-- 1. assessment_plan_extensions 延伸表 (1:1 of oscal.assessment_plans) (2026-05-XX)
CREATE TABLE compliance.assessment_plan_extensions (
    id                           SERIAL PRIMARY KEY,
    assessment_plan_id           INTEGER UNIQUE NOT NULL,
    workflow_execution_uid       UUID,
    flow_template_snapshot_uid   UUID,
    created_at                   TIMESTAMPTZ DEFAULT NOW() NOT NULL,
    updated_at                   TIMESTAMPTZ DEFAULT NOW() NOT NULL,
    created_user                 VARCHAR(50),
    updated_user                 VARCHAR(50),
    CONSTRAINT fk_ape_assessment_plan
        FOREIGN KEY (assessment_plan_id)
        REFERENCES oscal.assessment_plans(id)
        ON DELETE CASCADE
);

-- 2. 索引 (2026-05-XX)
CREATE INDEX ix_ape_workflow_execution_uid
    ON compliance.assessment_plan_extensions(workflow_execution_uid);
CREATE INDEX ix_ape_flow_template_snapshot_uid
    ON compliance.assessment_plan_extensions(flow_template_snapshot_uid);

-- 3. 權限授予（CLAUDE.md 規範）(2026-05-XX)
GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.assessment_plan_extensions TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.assessment_plan_extensions_id_seq TO cm_app;

-- 4. RLS policy — 跟著 assessment_plans 走（tenant 透過 AP JOIN 過濾） (2026-05-XX)
--    不開 RLS：本表純為 AP 1:1 延伸欄位，無獨立 tenant 隔離需求；
--    AP 本身在 oscal schema 由 jedi_common.session_scope 透過 GUC 處理 RLS。
--    若未來需 RLS：可考慮 EXISTS subquery 比對 oscal.assessment_plans 的 metadata。

-- 5. 補既有 AP 的 ext 列（dev/stg 既有資料 backfill） (2026-05-XX)
INSERT INTO compliance.assessment_plan_extensions (assessment_plan_id, created_user, updated_user)
SELECT id, COALESCE(created_user, 'system'), COALESCE(updated_user, 'system')
FROM oscal.assessment_plans
WHERE id NOT IN (SELECT assessment_plan_id FROM compliance.assessment_plan_extensions)
ON CONFLICT (assessment_plan_id) DO NOTHING;

# Spec 2 Stage Integration (2026-05-XX)
GRC_STAGE_PRECONDITION_FAILED        = ("階段推進前置條件未滿足",       "GRC_412021")
GRC_STAGE_ROLE_FORBIDDEN             = ("使用者不具備此階段推進權限",   "GRC_403050")
GRC_STAGE_NO_NEXT_NODE               = ("流程推進失敗：找不到下一節點", "GRC_400050")
GRC_AP_NO_WORKFLOW_BINDING           = ("稽核計畫未綁定流程實例",       "GRC_404029")
GRC_STAGE_HANDLER_NOT_REGISTERED     = ("stage handler 未註冊",         "GRC_400051")
GRC_STAGE_OBJECT_NOT_BOUND           = ("BPMN UserTask 未綁定階段物件", "GRC_400052")

"""Stage completion registry — flow_engine domain abstraction.

flow_engine 不知道 OSCAL business logic 存在。具體 handler 在 app/grc/ 註冊。
"""
from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Optional


@dataclass
class PreconditionResult:
    passed: bool
    reason_i18n_key: Optional[str] = None
    context: dict = field(default_factory=dict)


class IStageCompletionHandler(ABC):
    """副作用 handler — stage 推進時呼叫。"""

    @property
    @abstractmethod
    def key(self) -> str:
        """對應 stage_objects.complete_handler_key"""
        ...

    @abstractmethod
    def execute(
        self,
        ap_uid: str,
        project_uid: str,
        user_id: int,
        curr_user: str,
        ctx: dict,
    ) -> dict:
        """執行副作用；ctx 含 force / loopback_decision 等選用參數。
        回傳 dict 直接送回 stage_advance API 的 response data。
        """
        ...


class IStagePreconditionCheck(ABC):
    """前置條件檢查 — stage 推進前呼叫。"""

    @property
    @abstractmethod
    def key(self) -> str:
        """對應 stage_objects.precondition_key"""
        ...

    @abstractmethod
    def check(
        self, ap_uid: str, project_uid: str, ctx: dict
    ) -> PreconditionResult:
        ...


class StageRegistry:
    """Singleton — 啟動時 DI container 註冊 handler / precondition instance。

    flow_engine app service 透過此 registry 查 handler，不直接 import grc。
    """

    def __init__(self):
        self._handlers: dict[str, IStageCompletionHandler] = {}
        self._preconditions: dict[str, IStagePreconditionCheck] = {}

    def register_handler(self, handler: IStageCompletionHandler) -> None:
        self._handlers[handler.key] = handler

    def register_precondition(self, check: IStagePreconditionCheck) -> None:
        self._preconditions[check.key] = check

    def get_handler(self, key: str) -> Optional[IStageCompletionHandler]:
        return self._handlers.get(key)

    def get_precondition(self, key: str) -> Optional[IStagePreconditionCheck]:
        return self._preconditions.get(key)

stage_registry = providers.Singleton(StageRegistry)

"""OSCAL stage completion handlers — bridge between flow_engine and OSCAL audit lifecycle.

每個 handler key 對應 stage_objects.complete_handler_key，由 DI container 啟動時註冊到 StageRegistry。
"""
from domain.flow_engine.service.stage_completion_registry import IStageCompletionHandler


class PlanningOnCompleteHandler(IStageCompletionHandler):
    """planning stage 推進 → 呼叫 OscalAuditService.activate_project."""

    def __init__(self, oscal_audit_service):
        self._oscal_audit_service = oscal_audit_service

    @property
    def key(self) -> str:
        return "oscal.planning.activate"

    def execute(self, ap_uid, project_uid, user_id, curr_user, ctx) -> dict:
        force = ctx.get("force", False)
        return self._oscal_audit_service.activate_project(
            project_uid=project_uid, ap_uid=ap_uid, user_id=user_id,
            force=force, curr_user=curr_user,
        )


class TaskExecutionOnCompleteHandler(IStageCompletionHandler):
    key = "oscal.task_execution.launch_audit"  # 同上 pattern, 略

class AuditOnCompleteHandler(IStageCompletionHandler):
    key = "oscal.audit.confirm_audit"

class PoamOnCompleteHandler(IStageCompletionHandler):
    key = "oscal.poam.close_round"

class TasksThresholdCheck(IStagePreconditionCheck):
    """task_execution → audit 推進前檢查未完成 task 數。

    與 launch_audit 內既有 unassigned/incomplete 檢查邏輯 align；
    若 force=true 由 caller 在 StageAdvanceService 跳過此 check。
    """
    @property
    def key(self): return "oscal.tasks_threshold_check"

    def check(self, ap_uid, project_uid, ctx):
        incomplete = self._oscal_audit_query.get_incomplete_task_count(ap_uid)
        if incomplete > 0:
            return PreconditionResult(
                passed=False,
                reason_i18n_key="flow_engine.precondition.tasks_not_complete",
                context={"incomplete": incomplete},
            )
        return PreconditionResult(passed=True)


class AllControlsVerdictedWithFinding(IStagePreconditionCheck):
    key = "oscal.all_controls_verdicted_with_finding"
    # 對應 GRC_412003 + GRC_412011 既有檢查


class AllPoamClosed(IStagePreconditionCheck):
    key = "oscal.all_poam_closed"
    # 對應 GRC_412005 既有檢查

class StageAdvanceService:
    def __init__(
        self,
        stage_registry,
        stage_object_domain_service,
        ap_extension_domain_service,
        workflow_execution_service,
        flow_template_domain_service,
        project_participant_domain_service,
        grc_project_domain_service,
        user_domain_service,
    ):
        ...

    @transaction
    def get_current_stage_info(self, ap_uid: str, user_id: int) -> dict:
        """Banner 用：回傳當前 stage code + name + progress bar + 推進按鈕 metadata.

        Response:
        {
            "current_stage": {
                "code": "planning",
                "name_i18n": "規劃",
                "complete_button_label_i18n": "啟動專案",
                "complete_handler_key": "oscal.planning.activate",
                "precondition_key": null,
                "main_roles": ["manager"]
            },
            "user_can_advance": true,
            "precondition": {"passed": true, "reason_i18n_key": null, "context": {}},
            "progress": [
                {"code": "planning", "name_i18n": "規劃", "status": "done"},
                {"code": "task_execution", "name_i18n": "執行任務", "status": "current"},
                {"code": "audit", "name_i18n": "稽核", "status": "pending"},
                {"code": "poam", "name_i18n": "缺失改善", "status": "pending"}
            ],
            "ap_status": "active",
            "workflow_execution_uid": "<uuid>"
        }
        """
        # 1. 查 AP extension 拿 workflow_execution_uid + flow_template_snapshot_uid
        # 2. 查 workflow_execution 當前 user task → 找到對應 stage_object
        # 3. 查 user 的 participant role → 判 user_can_advance
        # 4. 跑 precondition check（不 raise，回 PreconditionResult）
        # 5. 解 flow_template snapshot BPMN 取出 stage sequence 算 progress
        ...

    @transaction
    def advance_stage(self, ap_uid: str, user_id: int, curr_user: str, force: bool = False, ctx: dict = None) -> dict:
        """推進當前 stage：
        1. 查 AP extension → workflow_execution
        2. 查 current user task → stage_object
        3. 主要角色驗證（manager / auditor / reviewer / viewer，依 stage default_main_roles 或 BPMN UserTask 覆寫）
        4. precondition.check()；若 fail 且 not force：raise PreconditionFailedError(GRC_STAGE_PRECONDITION_FAILED)
        5. handler.execute() ← 副作用呼叫 OscalAuditService（包 force / ctx）
        6. workflow_execution_service.complete_job() ← 推進 BPMN 到下個節點
        7. 若 BPMN 已到 EndEvent → 由 close_round handler 已處理（不額外動）
        8. 回傳新 stage info（recursive call get_current_stage_info）
        """
        ...

{ "force": false, "ctx": {} }

# Step 22 — 建 AP Extension + 啟動 main workflow_execution
from app.flow_engine.service.flow_template_app_service import ...
from app.flow_engine.service.workflow_execution_service import ...

# 22.1 取 hardcode default 範本（Spec 2）：builtin-full-audit
default_template = self._flow_template_app_service.get_by_code("builtin-full-audit")

# 22.2 啟動 main workflow_execution（依範本 BPMN）
main_wf = self._workflow_execution_service.start_workflow_execution(
    template_id=default_template.id,
    name=f"AP-{ap.uid}-main",
    params={"ap_uid": str(ap.uid), "project_uid": project_uid},
    created_user=curr_user,
)

# 22.3 寫 AP extension
self._ap_extension_domain_service.add(
    AssessmentPlanExtensionEntity(
        assessment_plan_id=ap.id,
        workflow_execution_uid=main_wf.uid,
        flow_template_snapshot_uid=default_template.uid,
        created_user=curr_user,
        updated_user=curr_user,
    )
)

-- Spec 2 — 補 stage_objects 的 handler key 與 precondition key (2026-05-XX)
UPDATE compliance.stage_objects SET complete_handler_key = 'oscal.planning.activate',
       precondition_key = NULL WHERE code = 'planning';
UPDATE compliance.stage_objects SET complete_handler_key = 'oscal.task_execution.launch_audit',
       precondition_key = 'oscal.tasks_threshold_check' WHERE code = 'task_execution';
UPDATE compliance.stage_objects SET complete_handler_key = 'oscal.audit.confirm_audit',
       precondition_key = 'oscal.all_controls_verdicted_with_finding' WHERE code = 'audit';
UPDATE compliance.stage_objects SET complete_handler_key = 'oscal.poam.close_round',
       precondition_key = 'oscal.all_poam_closed' WHERE code = 'poam';

STAGE_INFO: '/project/:projectUid/ap/:apUid/stage/info',
STAGE_ADVANCE: '/project/:projectUid/ap/:apUid/stage/advance',

export function useStageInfo(projectUid, apUid) {
  const stageInfo = ref(null)
  const loading = ref(false)
  const error = ref(null)

  async function fetchStageInfo() { ... }
  async function advance({ force = false, ctx = {} } = {}) { ... }

  return { stageInfo, loading, error, fetchStageInfo, advance }
}