Spec 3「AP 套用流程」Implementation Plan

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
grep -rn "get_default_main_workflow_template" --include="*.py"

grep -rn "get_builtin_by_name" --include="*.py"

grep -rn "DEFAULT_MAIN_WORKFLOW_TEMPLATE_NAME" --include="*.py"

grep -rn "GRC_FLOW_MAIN_TEMPLATE_NOT_FOUND" --include="*.py"

grep -rn "_bind_main_workflow_to_ap" --include="*.py"

poetry show jedi-flow-engine | grep -i location

ls ~/Projects/Billows/Audit-Manager/compliance-manager-fe/docs/changelog/ 2>/dev/null | head -3

grep -n "profile_uid\|profileUid\|compliance.*資源" ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/views/project/ProjectCreateView.vue ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ProjectBasicInfoForm.vue 2>/dev/null

sed -n '195,205p' common/code/grc_error_code.py

# 刪除這行
GRC_FLOW_MAIN_TEMPLATE_NOT_FOUND   = ("找不到預設主流程範本（seed 缺失）", "GRC_412022")

# Before
GRC_AR_DATA_MISSING                = ("找不到稽核回合資料",           "GRC_500001")
# After
GRC_AR_DATA_MISSING                = ("找不到稽核回合資料",           "GRC_412024")

grep -rn "GRC_FLOW_MAIN_TEMPLATE_NOT_FOUND" --include="*.py"

python -c "from common.code.grc_error_code import GrcErrorCode; print(GrcErrorCode.GRC_AR_DATA_MISSING)"

---
type: tweak
modules: [common.code.grc_error_code]
issue: docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md (§9.7)
---

# GRC error code 清理：刪 412022 + fix 500001 編號

## 變更
- 刪除 `GRC_FLOW_MAIN_TEMPLATE_NOT_FOUND` (412022)
- `GRC_AR_DATA_MISSING` 編號從 500001 改 412024

## 原因
- 412022: Spec 3 拔除 hardcode default lookup 後不再需要
- 500001: HTTP 412 配 500 編號違反 CLAUDE.md error code 命名規則

git add common/code/grc_error_code.py docs/changelog/2026-05-13-tweak-grc-error-code-cleanup.md
git commit -m "tweak(spec3 M1): GRC error code 清理 — 刪 412022 + fix 500001→412024"

grep -n "get_assessment_plans_menu\|get_assessment_plan_detail" app/grc/service/*.py

"""Spec 3 M2 — FlowTemplateEnricher unit tests."""
import pytest
from unittest.mock import MagicMock

from app.grc.service._flow_template_enricher import FlowTemplateEnricher


class TestFlowTemplateEnricher:
    def test_enrich_returns_full_payload_when_all_layers_exist(self):
        ext_service = MagicMock()
        engine_service = MagicMock()
        master_service = MagicMock()

        ext_service.get_by_assessment_plan_ids.return_value = {
            1: MagicMock(flow_template_snapshot_uid="snap-uid-1")
        }
        engine_service.get_many_by_uids.return_value = {
            "snap-uid-1": MagicMock(source_template_uid="master-uid-1")
        }
        master_service.get_many_by_uids.return_value = {
            "master-uid-1": MagicMock(name="完整稽核流程", is_active=True)
        }

        enricher = FlowTemplateEnricher(ext_service, engine_service, master_service)
        result = enricher.enrich_many(ap_ids=[1])

        assert result[1] == {
            "snapshot_uid": "snap-uid-1",
            "master_uid": "master-uid-1",
            "master_name": "完整稽核流程",
            "is_master_active": True,
        }

    def test_enrich_returns_none_when_ext_missing(self):
        ext_service = MagicMock()
        engine_service = MagicMock()
        master_service = MagicMock()
        ext_service.get_by_assessment_plan_ids.return_value = {}

        enricher = FlowTemplateEnricher(ext_service, engine_service, master_service)
        result = enricher.enrich_many(ap_ids=[1])

        assert result[1] is None

    def test_enrich_marks_master_inactive_when_soft_deleted(self):
        ext_service = MagicMock()
        engine_service = MagicMock()
        master_service = MagicMock()

        ext_service.get_by_assessment_plan_ids.return_value = {
            1: MagicMock(flow_template_snapshot_uid="snap-uid-1")
        }
        engine_service.get_many_by_uids.return_value = {
            "snap-uid-1": MagicMock(source_template_uid="master-uid-1")
        }
        master_service.get_many_by_uids.return_value = {
            "master-uid-1": MagicMock(name="Deleted", is_active=False)
        }

        enricher = FlowTemplateEnricher(ext_service, engine_service, master_service)
        result = enricher.enrich_many(ap_ids=[1])

        assert result[1]["is_master_active"] is False

    def test_enrich_uses_batch_queries(self):
        """避免 N+1：N 個 AP 應該只觸發 3 次 query（ext / engine / master）"""
        ext_service = MagicMock()
        engine_service = MagicMock()
        master_service = MagicMock()
        ext_service.get_by_assessment_plan_ids.return_value = {}

        enricher = FlowTemplateEnricher(ext_service, engine_service, master_service)
        enricher.enrich_many(ap_ids=[1, 2, 3, 4, 5])

        # 即使 5 個 AP 也只該 call 一次 ext_service.get_by_assessment_plan_ids
        ext_service.get_by_assessment_plan_ids.assert_called_once_with([1, 2, 3, 4, 5])

pytest test/test_flow_template_enricher.py -v

"""Spec 3 M2 — AP `flow_template` enrichment helper.

DDD note: 純 app service 層 helper，不直接碰 ORM。透過注入的 domain service 取資料。
"""
from typing import Dict, List, Optional


class FlowTemplateEnricher:
    """把 N 個 AP id batch enrich 成 `flow_template` payload dict。

    Caller 已在 `@transaction` scope 內。
    """

    def __init__(
        self,
        ap_extension_domain_service,
        workflow_template_service,
        flow_template_domain_service,
    ):
        self._ext = ap_extension_domain_service
        self._engine = workflow_template_service
        self._master = flow_template_domain_service

    def enrich_many(self, ap_ids: List[int]) -> Dict[int, Optional[dict]]:
        """Return {ap_id: flow_template_payload | None}.

        Lenient：任一層缺失就回 None / `is_master_active=False`，不 raise。
        """
        if not ap_ids:
            return {}

        # 一段 query：取所有 ext
        exts_by_ap_id = self._ext.get_by_assessment_plan_ids(ap_ids)
        if not exts_by_ap_id:
            return {ap_id: None for ap_id in ap_ids}

        # 二段 query：取所有 snapshot（engine 表）
        snapshot_uids = [
            ext.flow_template_snapshot_uid for ext in exts_by_ap_id.values()
            if ext and ext.flow_template_snapshot_uid
        ]
        snapshots_by_uid = self._engine.get_many_by_uids(snapshot_uids)

        # 三段 query：取所有 master
        master_uids = [
            snap.source_template_uid for snap in snapshots_by_uid.values()
            if snap and snap.source_template_uid
        ]
        masters_by_uid = self._master.get_many_by_uids(master_uids)

        # 組裝
        result = {}
        for ap_id in ap_ids:
            ext = exts_by_ap_id.get(ap_id)
            if not ext or not ext.flow_template_snapshot_uid:
                result[ap_id] = None
                continue
            snap = snapshots_by_uid.get(ext.flow_template_snapshot_uid)
            if not snap or not snap.source_template_uid:
                result[ap_id] = None
                continue
            master = masters_by_uid.get(snap.source_template_uid)
            if not master:
                # snapshot 還在但 master 連 row 都沒了 — 回部分資料
                result[ap_id] = {
                    "snapshot_uid": ext.flow_template_snapshot_uid,
                    "master_uid": snap.source_template_uid,
                    "master_name": None,
                    "is_master_active": False,
                }
                continue
            result[ap_id] = {
                "snapshot_uid": ext.flow_template_snapshot_uid,
                "master_uid": snap.source_template_uid,
                "master_name": master.name,
                "is_master_active": bool(master.is_active),
            }
        return result

pytest test/test_flow_template_enricher.py -v

git add app/grc/service/_flow_template_enricher.py test/test_flow_template_enricher.py
git commit -m "feat(spec3 M2): FlowTemplateEnricher helper for AP flow_template enrichment"

grep -rn "AssessmentPlanExtensionDomainService\|assessment_plan_extensions" --include="*.py" -l | head -5

import pytest
from unittest.mock import MagicMock
from domain.flow_engine.service.flow_template_domain_service import FlowTemplateDomainService


def test_get_many_by_uids_returns_dict_keyed_by_uid():
    repo = MagicMock()
    repo.get_many_by_uids.return_value = {
        "uid-1": MagicMock(uid="uid-1", name="A"),
        "uid-2": MagicMock(uid="uid-2", name="B"),
    }
    service = FlowTemplateDomainService(repo)
    result = service.get_many_by_uids(["uid-1", "uid-2"])
    assert list(result.keys()) == ["uid-1", "uid-2"]
    assert result["uid-1"].name == "A"

def test_get_many_by_uids_empty_list_returns_empty_dict():
    repo = MagicMock()
    service = FlowTemplateDomainService(repo)
    assert service.get_many_by_uids([]) == {}
    repo.get_many_by_uids.assert_not_called()  # 短路：空 list 不打 repo

def test_get_many_by_uids_missing_uids_omitted():
    repo = MagicMock()
    repo.get_many_by_uids.return_value = {"uid-1": MagicMock()}
    service = FlowTemplateDomainService(repo)
    result = service.get_many_by_uids(["uid-1", "uid-2"])  # uid-2 不存在
    assert "uid-2" not in result

def test_get_by_assessment_plan_ids_returns_dict_keyed_by_ap_id():
    repo = MagicMock()
    repo.get_by_assessment_plan_ids.return_value = {
        1: MagicMock(assessment_plan_id=1, flow_template_snapshot_uid="snap-1"),
        2: MagicMock(assessment_plan_id=2, flow_template_snapshot_uid="snap-2"),
    }
    service = AssessmentPlanExtensionDomainService(repo)
    result = service.get_by_assessment_plan_ids([1, 2, 3])
    assert set(result.keys()) == {1, 2}
    assert result[1].flow_template_snapshot_uid == "snap-1"

def test_get_by_assessment_plan_ids_empty_list_short_circuits():
    repo = MagicMock()
    service = AssessmentPlanExtensionDomainService(repo)
    assert service.get_by_assessment_plan_ids([]) == {}
    repo.get_by_assessment_plan_ids.assert_not_called()

def test_get_many_by_uids_returns_dict():
    # 套件層級加 method，測試與上述同 pattern
    ...

pytest test/test_flow_template_domain_service.py -v
pytest test/test_ap_extension_domain_service.py -v
pytest test/test_workflow_template_service.py -v

# repo interface
def get_many_by_uids(self, uids: List[str]) -> Dict[str, EntityT]: ...

# repo impl
def get_many_by_uids(self, uids):
    if not uids:
        return {}
    rows = self.session.query(self._model).filter(self._model.uid.in_(uids)).all()
    return {str(row.uid): self._mapper.to_entity(row) for row in rows}

# domain service
def get_many_by_uids(self, uids):
    return self._repo.get_many_by_uids(uids)

def get_by_assessment_plan_ids(self, ap_ids):
    if not ap_ids:
        return {}
    rows = self.session.query(...).filter(model.assessment_plan_id.in_(ap_ids)).all()
    return {row.assessment_plan_id: mapper.to_entity(row) for row in rows}

git add domain/ infra/ test/
git commit -m "feat(spec3 M2): batch query methods for FlowTemplate / AP extension / WorkflowTemplate"

# api/grc/serializers/assessment_plan.py

class FlowTemplateEnrichmentSchema(Schema):
    snapshot_uid = fields.String(allow_none=True)
    master_uid = fields.String(allow_none=True)
    master_name = fields.String(allow_none=True)
    is_master_active = fields.Boolean(allow_none=True)


class AssessmentPlanMenuResponseSchema(Schema):
    uid = fields.String()
    # ...既有欄位...
    ssp_uid = fields.String(allow_none=True)
    flow_template = fields.Nested(FlowTemplateEnrichmentSchema, allow_none=True)  # 新增

git add api/grc/serializers/assessment_plan.py
git commit -m "feat(spec3 M2): add flow_template enrichment field to AssessmentPlanMenuResponseSchema"

def test_get_assessment_plans_menu_returns_flow_template_enrichment(
    app_client, blsit_headers, project_with_two_aps
):
    """AP list endpoint 必須回 flow_template enrichment（FE default 帶值依賴）。"""
    resp = app_client.get(
        f"/grc/project/{project_with_two_aps.uid}/assessment-plans/menu",
        headers=blsit_headers,
    )
    assert resp.status_code == 200
    aps = resp.json["data"]
    assert len(aps) == 2
    for ap in aps:
        assert "flow_template" in ap
        assert ap["flow_template"]["master_uid"] is not None
        assert ap["flow_template"]["snapshot_uid"] is not None
        assert ap["flow_template"]["master_name"] is not None
        assert ap["flow_template"]["is_master_active"] is True

def test_get_assessment_plan_detail_returns_flow_template_enrichment(
    app_client, blsit_headers, ap_fixture
):
    resp = app_client.get(
        f"/grc/project/{ap_fixture.project_uid}/ap/{ap_fixture.uid}",
        headers=blsit_headers,
    )
    assert resp.status_code == 200
    assert resp.json["data"]["flow_template"]["master_name"] == "完整稽核流程"

class ProjectService:
    def __init__(
        self,
        # ...既有 deps...
        flow_template_enricher: FlowTemplateEnricher = None,  # 新增
    ):
        self._flow_template_enricher = flow_template_enricher

    @transaction
    def get_assessment_plans_menu(self, project_uid):
        aps = self._existing_logic(project_uid)
        ap_ids = [ap.id for ap in aps]
        enrichments = self._flow_template_enricher.enrich_many(ap_ids)
        for ap in aps:
            ap.flow_template = enrichments.get(ap.id)
        return aps

flow_template_enricher = providers.Factory(
    FlowTemplateEnricher,
    ap_extension_domain_service=...,
    workflow_template_service=...,
    flow_template_domain_service=...,
)
project_service = providers.Factory(
    ProjectService,
    # ...
    flow_template_enricher=flow_template_enricher,
)

pytest test/test_grc_assessment_plan_api.py -v

# Kill stale (memory: backend_restart_orphan_pids)
lsof -i :8000  # 確認 listener
pkill -9 -f main_socketio.py
python main_socketio.py > /dev/null 2>&1 &

curl -s -H "Authorization: Bearer <token>" http://localhost:8000/grc/project/<uid>/assessment-plans/menu | jq '.data[0].flow_template'

git add app/grc/service/project_service.py di_containers/grc/grc_container.py test/test_grc_assessment_plan_api.py
git commit -m "feat(spec3 M2): AP list/detail API enrich with flow_template payload"

---
type: feat
modules: [grc, flow_engine]
issue: docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md (§9.6)
---

# AP list + detail API 新增 flow_template enrichment

## 變更
- `GET /grc/project/<uid>/assessment-plans/menu` 回 `flow_template: {snapshot_uid, master_uid, master_name, is_master_active}`（每筆 AP）
- `GET /grc/project/<uid>/ap/<ap_uid>` 同上
- 行為 lenient：master 軟刪後 `is_master_active=false` 不擋 API（進行中 AP 仍可跑完）
- 加 `FlowTemplateEnricher` 共用 helper + 三段 batch query 防 N+1

## API 差異
（before / after JSON 範例）

## 測試
- 2 integration test + 4 unit test 全 pass

git add docs/changelog/2026-05-13-feat-ap-flow-template-enrichment.md
git commit -m "docs(spec3 M2): changelog for AP flow_template enrichment"

"""Spec 3 M3 carry-forward — WorkflowTemplateSnapshotService unit tests."""
import pytest
from unittest.mock import MagicMock
from app.flow_engine.service.workflow_template_snapshot_service import (
    WorkflowTemplateSnapshotService,
)


class TestWorkflowTemplateSnapshotService:
    def test_clone_master_as_snapshot_returns_new_uid(self):
        engine_service = MagicMock()
        engine_service.add_workflow_template.return_value = MagicMock(uid="new-uid-1", id=99)
        service = WorkflowTemplateSnapshotService(engine_service)

        result = service.clone_master_as_snapshot(
            master_uid="master-uid-1",
            master_name="完整稽核流程",
            xml="<bpmn>...</bpmn>",
            description="desc",
            curr_user="test-user",
        )

        assert result.uid == "new-uid-1"
        engine_service.add_workflow_template.assert_called_once()
        kwargs = engine_service.add_workflow_template.call_args.kwargs
        assert kwargs["type"] == "MAIN_PROCESS"
        assert kwargs["version"] == "1.0.0"
        assert kwargs["provider"] == "snapshot"
        assert kwargs["source_template_uid"] == "master-uid-1"
        assert kwargs["xml"] == "<bpmn>...</bpmn>"

    def test_clone_two_times_returns_different_uids(self):
        engine_service = MagicMock()
        engine_service.add_workflow_template.side_effect = [
            MagicMock(uid="snap-1"),
            MagicMock(uid="snap-2"),
        ]
        service = WorkflowTemplateSnapshotService(engine_service)

        r1 = service.clone_master_as_snapshot(
            master_uid="m", master_name="n", xml="<x/>", curr_user="u"
        )
        r2 = service.clone_master_as_snapshot(
            master_uid="m", master_name="n", xml="<x/>", curr_user="u"
        )

        assert r1.uid != r2.uid

    def test_clone_uses_master_name_as_prefix(self):
        engine_service = MagicMock()
        engine_service.add_workflow_template.return_value = MagicMock()
        service = WorkflowTemplateSnapshotService(engine_service)

        service.clone_master_as_snapshot(
            master_uid="m-uid", master_name="完整稽核流程",
            xml="<x/>", curr_user="u"
        )

        kwargs = engine_service.add_workflow_template.call_args.kwargs
        assert kwargs["name"].startswith("完整稽核流程 (snapshot ")

pytest test/test_workflow_template_snapshot_service.py -v

git add test/test_workflow_template_snapshot_service.py
git commit -m "test(spec3 M3): WorkflowTemplateSnapshotService unit tests (carry-forward from Spec 2)"

grep -n "def " app/flow_engine/service/stage_advance_service.py | grep -v "^.*def _"

"""Spec 3 M3 carry-forward — StageAdvanceService unit tests."""
import pytest
from unittest.mock import MagicMock
from app.flow_engine.service.stage_advance_service import StageAdvanceService


class TestStageAdvanceService:
    def test_advance_calls_on_complete_handler(self):
        # arrange: mock workflow_execution / handlers / preconditions
        # act: service.advance(ap_uid, stage_code, ...)
        # assert: handler 被叫到、status 推進
        ...

    def test_advance_raises_when_precondition_fails(self):
        # arrange: precondition returns False
        # act + assert: raise PreconditionFailedError(GRC_STAGE_PRECONDITION_FAILED)
        ...

    def test_advance_raises_when_no_next_node(self):
        # arrange: BPMN parser returns no outgoing flow
        # act + assert: raise BadRequest(GRC_STAGE_NO_NEXT_NODE)
        ...

pytest test/test_stage_advance_service.py -v
git add test/test_stage_advance_service.py
git commit -m "test(spec3 M3): StageAdvanceService unit tests (carry-forward from Spec 2)"

grep -n "^def " app/flow_engine/service/oscal_stage_preconditions.py

def test_all_tasks_completed_true_when_all_closed():
    ap = MagicMock(tasks=[MagicMock(status="closed"), MagicMock(status="closed")])
    assert all_tasks_completed(ap) is True

def test_all_tasks_completed_false_when_any_pending():
    ap = MagicMock(tasks=[MagicMock(status="closed"), MagicMock(status="pending")])
    assert all_tasks_completed(ap) is False

def test_activate_handler_calls_oscal_api(...):
    ...

def test_activate_handler_raises_when_oscal_returns_error(...):
    ...

def test_upsert_creates_when_not_exists(): ...
def test_upsert_updates_when_exists(): ...
def test_get_by_assessment_plan_id_returns_none_when_missing(): ...
def test_get_by_assessment_plan_ids_batch_returns_dict(): ...

---
type: tweak
modules: [flow_engine, infra.flow_engine]
issue: docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md (§13 M3)
---

# 補 Spec 2 carry-forward 5 service test gap

## 變更
- 新增 5 個測試檔，覆蓋 Spec 2 review 標的 5 service
- 為 M4 改動鋪測試安全網

## 測試
- WorkflowTemplateSnapshotService: 3 tests
- StageAdvanceService: N tests
- oscal_stage_preconditions: N tests
- oscal_stage_handlers: N tests
- AssessmentPlanExtensionRepoImpl: N tests

@dataclass
class StartProjectDto:
    # ...既有欄位...
    flow_template_uid: str = ""   # required by route schema；service 內檢查非空

def test_start_oscal_project_raises_when_flow_template_uid_empty(...):
    dto = StartProjectDto(name="x", profile_uid="p", flow_template_uid="")
    with pytest.raises(BadRequestError) as exc:
        service.start_oscal_project(dto, ...)
    assert "flow_template_uid" in str(exc.value)

@transaction
def start_oscal_project(
    self,
    start_project_dto: StartProjectDto,
    curr_user: str,
    curr_user_uid: str,
    curr_user_id: int = None,
    locale: str = None,
) -> ProjectDTO:
    if not start_project_dto.flow_template_uid:
        raise BadRequestError(GrcErrorCode.GRC_FLOW_TEMPLATE_UID_REQUIRED)
    # ...既有 steps...

GRC_FLOW_TEMPLATE_UID_REQUIRED = ("缺少流程範本參數",      "GRC_400054")
GRC_FLOW_BINDING_DI_MISSING    = ("流程綁定服務未注入（部署錯誤）", "GRC_412025")

git add app/project/dto/project_dto.py app/project/service/oscal_project_service.py common/code/grc_error_code.py test/test_oscal_project_service_flow_template.py
git commit -m "feat(spec3 M4): StartProjectDto + start_oscal_project 加 flow_template_uid required validation"

grep -rn "StartProjectRequestSchema\|class.*StartProject.*Schema" api/project/

class StartProjectRequestSchema(Schema):
    name = fields.String(required=True)
    profile_uid = fields.String(required=True)
    # ...
    flow_template_uid = fields.UUID(required=True)  # 新增

def test_post_oscal_projects_start_400_when_no_flow_template_uid(app_client, blsit_headers):
    resp = app_client.post(
        "/oscal/projects/start",
        json={"name": "x", "profile_uid": "...", ...},  # 無 flow_template_uid
        headers=blsit_headers,
    )
    assert resp.status_code == 400

pytest test/test_post_oscal_projects_start.py -v
git add api/project/routes/project_route.py test/
git commit -m "feat(spec3 M4): /oscal/projects/start 必填 flow_template_uid"

class LaunchNewRoundRequestSchema(Schema):
    title = fields.String(required=True)
    flow_template_uid = fields.UUID(required=True)  # 新增
    start_date = fields.Date(load_default=None, allow_none=True)
    end_date = fields.Date(load_default=None, allow_none=True)

@transaction
def launch_new_round(
    self,
    project_uid: str,
    user_id: int,
    title: str,
    flow_template_uid: str,   # 新增
    start_date=None,
    end_date=None,
    curr_user: str = None,
    locale: str = None,
) -> dict:
    if not flow_template_uid:
        raise BadRequestError(GrcErrorCode.GRC_FLOW_TEMPLATE_UID_REQUIRED)
    # ...既有 steps 1–9 不動...
    # step 10 - to be added in M4.4

def test_post_launch_new_round_400_when_no_flow_template_uid(...):
    resp = app_client.post(
        f"/grc/project/{uid}/launch-new-round",
        json={"title": "Round 2"},
        headers=blsit_headers,
    )
    assert resp.status_code == 400

git add api/grc/ app/project/service/oscal_project_service.py test/
git commit -m "feat(spec3 M4): /grc/project/<uid>/launch-new-round 必填 flow_template_uid"

def test_start_oscal_project_binds_main_workflow_with_user_specified_template(
    app_client, blsit_headers, profile_fixture, flow_template_a
):
    resp = app_client.post(
        "/oscal/projects/start",
        json={
            "name": "Test Project",
            "profile_uid": profile_fixture.uid,
            "flow_template_uid": flow_template_a.uid,
        },
        headers=blsit_headers,
    )
    assert resp.status_code == 200
    project_uid = resp.json["data"]["uid"]

    # 驗 ap_extensions.flow_template_snapshot_uid 存在且不等於 master uid
    ext = session.query(AssessmentPlanExtension).filter_by(...).first()
    assert ext.flow_template_snapshot_uid is not None
    assert ext.flow_template_snapshot_uid != flow_template_a.uid

    # 驗 snapshot.source_template_uid == master uid
    snap = session.query(WorkflowTemplate).filter_by(uid=ext.flow_template_snapshot_uid).first()
    assert snap.source_template_uid == flow_template_a.uid

def test_launch_new_round_binds_main_workflow_independently(
    app_client, blsit_headers, project_with_closed_ap1, flow_template_b
):
    """Spec 2 gap fix — launch_new_round 也要綁 main workflow，跟第一輪 snapshot 不同。"""
    resp = app_client.post(
        f"/grc/project/{project_with_closed_ap1.uid}/launch-new-round",
        json={"title": "Round 2", "flow_template_uid": flow_template_b.uid},
        headers=blsit_headers,
    )
    assert resp.status_code == 200
    ap2_uid = resp.json["data"]["ap_uid"]

    ap1_ext = session.query(AssessmentPlanExtension).filter_by(assessment_plan_id=ap1_id).first()
    ap2_ext = session.query(AssessmentPlanExtension).filter_by(assessment_plan_id=ap2_id).first()

    assert ap1_ext.flow_template_snapshot_uid != ap2_ext.flow_template_snapshot_uid
    assert ap1_ext.workflow_execution_uid != ap2_ext.workflow_execution_uid

def test_invalid_flow_template_uid_returns_404(...):
    resp = app_client.post(
        "/oscal/projects/start",
        json={"name": "x", "profile_uid": "p", "flow_template_uid": "00000000-0000-0000-0000-000000000000"},
        headers=blsit_headers,
    )
    assert resp.status_code == 404
    assert resp.json["msg"].startswith("流程範本不存在")

def test_soft_deleted_flow_template_returns_404(...):
    # arrange: flow_template_a is_active=False
    # ...
    assert resp.status_code == 404

def _bind_main_workflow_to_ap(
    self,
    ap,
    project_uid: str,
    flow_template_uid: str,   # 新增 required
    curr_user: str,
) -> None:
    """Spec 3 — 用 caller 指定的 flow_template_uid 取 master，clone 一份 per-AP
    凍結 snapshot 到 engine 表，啟動 workflow_execution，寫 assessment_plan_extensions。

    Caller 已開 @transaction scope；本 helper 不再加。
    """
    # DI 缺失視為 server misconfig（部署錯）— 不該 silent skip 讓 AP 建得起來但
    # Banner 後續永遠 404。沿用 Spec 2 step 22 review fix H2 的做法 raise 412
    # 讓 user / dev 立刻看到 root cause。
    # 用既有 GRC_AP_NO_WORKFLOW_BINDING (404029) 不準確（語意是「AP 沒綁 workflow」
    # 而非「部署層 DI 壞」）。Spec 3 新增專用 code：
    if (self._flow_template_domain_service is None
            or self._ap_extension_domain_service is None
            or self._workflow_template_snapshot_service is None):
        raise PreconditionFailedError(GrcErrorCode.GRC_FLOW_BINDING_DI_MISSING)

    master = self._flow_template_domain_service.get_by_uid(flow_template_uid)
    if master is None or not master.is_active:
        raise NotFound(GrcErrorCode.GRC_FLOW_TEMPLATE_NOT_FOUND)

    snapshot = self._workflow_template_snapshot_service.clone_master_as_snapshot(
        master_uid=str(master.uid),
        master_name=master.name,
        xml=master.bpmn_xml,
        description=master.description,
        curr_user=curr_user,
    )

    main_wf = self.workflow_execution_service.start_workflow_execution(
        template_id=snapshot.id,
        name=f"AP-{ap.uid}-main",
        params={"ap_uid": str(ap.uid), "project_uid": project_uid},
        created_user=curr_user,
        description=f"AP main workflow for {ap.title}",
    )

    self._ap_extension_domain_service.upsert(
        assessment_plan_id=ap.id,
        workflow_execution_uid=str(main_wf.uid),
        flow_template_snapshot_uid=str(snapshot.uid),
        curr_user=curr_user,
    )
    logger.info(
        f"[bind_main_workflow] ap_uid={ap.uid} bound to "
        f"workflow_execution_uid={main_wf.uid} snapshot_uid={snapshot.uid} "
        f"master_uid={master.uid}"
    )

self._bind_main_workflow_to_ap(
    ap=ap,
    project_uid=str(project.uid),
    flow_template_uid=start_project_dto.flow_template_uid,  # 新增
    curr_user=curr_user,
)

# Step 10 (Spec 3) - 補 Spec 2 漏蓋：launch_new_round 也要綁 main workflow snapshot
self._bind_main_workflow_to_ap(
    ap=ap,
    project_uid=str(project_entity.uid),
    flow_template_uid=flow_template_uid,
    curr_user=curr_user,
)

pytest test/test_oscal_project_service_flow_template.py -v

pkill -9 -f main_socketio.py && python main_socketio.py > /dev/null 2>&1 &
tail -f log/app.log
# 另開 terminal 試 curl

git add app/project/service/oscal_project_service.py test/
git commit -m "feat(spec3 M4): _bind_main_workflow_to_ap 接 flow_template_uid + launch_new_round 補綁 main workflow"

grep -rn "get_default_main_workflow_template\|get_builtin_by_name\|DEFAULT_MAIN_WORKFLOW_TEMPLATE_NAME" --include="*.py"

pytest test/ -v 2>&1 | tail -30

python -c "from app.project.service.oscal_project_service import OscalProjectService; print('ok')"

git add domain/flow_engine/ infra/flow_engine/
git commit -m "tweak(spec3 M4): 拔除 Spec 2 過渡 hardcode default workflow lookup"

---
type: feat
breaking: true
modules: [project, grc, flow_engine]
issue: docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md (§9.1-9.5)
---

# Spec 3：兩條 entry 必填 flow_template_uid + launch_new_round 補綁 main workflow

## 變更
- POST /oscal/projects/start 必填 `flow_template_uid` (UUID)
- POST /grc/project/<uid>/launch-new-round 必填 `flow_template_uid` (UUID)
- launch_new_round 現在會綁 main workflow snapshot（補 Spec 2 漏蓋）
- 拔除 hardcode default lookup（FlowTemplateDomainService.get_default_main_workflow_template / DEFAULT_MAIN_WORKFLOW_TEMPLATE_NAME / IFlowTemplateRepo.get_builtin_by_name 全刪）

## Breaking
- 既有 FE 呼叫不帶 `flow_template_uid` 會 400；本 commit 與 FE M5/M6 必須一起部署
- 若 dev DB 既有 round-1 AP 有效運作（snapshot 已建好），不需 backfill；舊 AP 仍用舊 snapshot

## 測試
- 4 integration test 全 pass（含跨 round snapshot 隔離驗證）

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

grep -rn "flow-engine/flow-templates" src/ | head -5

# 用瀏覽器 DevTool 在 /flow/template-manage 頁面手動觀察 list API call

import { ref, computed, onMounted } from 'vue'
import FlowTemplateService from '@/service/FlowTemplateService'
import FlowTemplatePreviewDialog from '@/views/flow-template/components/FlowTemplatePreviewDialog.vue'

const flowTemplates = ref([])
const loadingTemplates = ref(false)
const previewVisible = ref(false)

const loadFlowTemplates = async () => {
  loadingTemplates.value = true
  try {
    const res = await FlowTemplateService.getList({ is_active: true })
    flowTemplates.value = res.data || []
  } finally {
    loadingTemplates.value = false
  }
}

onMounted(loadFlowTemplates)

const rules = computed(() => ({
  // ...
  flowTemplateUid: { required: helpers.withMessage(t('project.flowTemplate.requiredError'), required) },
}))

await ProjectService.createProject({
  name: form.name,
  profile_uid: form.profileUid,
  // ...
  flow_template_uid: form.flowTemplateUid,  // 新增
})

"project": {
  "flowTemplate": {
    "label": "流程範本",
    "firstRoundLabel": "第一輪稽核計畫流程範本",
    "placeholder": "請選擇流程範本",
    "detailBtn": "詳細選擇",
    "requiredError": "請選擇流程範本",
    "inheritedHint": "預設沿用上一輪稽核計畫的流程範本"
  }
}

npm run dev
# 開 http://localhost:5173/project/projects/new
# 走完整 wizard，看 dropdown / 預覽 Dialog
# 提交 → 確認後端 200 + ap_extensions 有 row

git add src/views/project/ src/components/grc/ src/i18n/
git commit -m "feat(spec3 M5): ProjectCreateView 加流程範本 dropdown + 預覽 Dialog + i18n"

grep -n "新增稽核計畫\|newRound\|launchNewRound\|launch-new-round\|launch_new_round" src/views/project/ProjectApListView.vue | head

import FlowTemplateService from '@/service/FlowTemplateService'
import FlowTemplatePreviewDialog from '@/views/flow-template/components/FlowTemplatePreviewDialog.vue'

const flowTemplates = ref([])
const previewVisible = ref(false)
const newRoundForm = ref({
  title: '',
  flowTemplateUid: null,
  startDate: null,
  endDate: null,
})

// Default 帶值（依賴 M2 — apList[0].flow_template enrichment）
const defaultFlowTemplateUid = computed(() => {
  const latest = props.apList?.[0]
  return latest?.flow_template?.master_uid ?? null
})

watch(() => dialogVisible.value, (v) => {
  if (v) {
    newRoundForm.value.flowTemplateUid = defaultFlowTemplateUid.value
  }
})

onMounted(async () => {
  flowTemplates.value = (await FlowTemplateService.getList({ is_active: true })).data
})

await ProjectApService.launchNewRound(projectUid, {
  title: newRoundForm.value.title,
  flow_template_uid: newRoundForm.value.flowTemplateUid,
  start_date: newRoundForm.value.startDate,
  end_date: newRoundForm.value.endDate,
})

# /project/projects/<uid> 開啟 → 新增稽核計畫 Dialog
# 確認 dropdown default 帶到「最新一輪 AP 範本」
# 提交 → 後端 200 + ap_extensions 第二筆 row（不同 snapshot uid）

git add src/views/project/ProjectApListView.vue
git commit -m "feat(spec3 M6): ProjectApListView 新增稽核計畫 Dialog 加流程範本 dropdown + default 帶值"

# BE
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
pkill -9 -f main_socketio.py && python main_socketio.py > /dev/null 2>&1 &
tail -f log/app.log &  # 監看
# FE
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
npm run dev

-- 兩列 ap_extensions
SELECT assessment_plan_id, flow_template_snapshot_uid, workflow_execution_uid
FROM compliance.assessment_plan_extensions
WHERE assessment_plan_id IN (
  SELECT id FROM oscal.assessment_plans WHERE project_id = <project_id>
);
-- → 兩 row，flow_template_snapshot_uid 互不相同

-- 兩列 snapshot
SELECT id, uid, name, source_template_uid, provider, version
FROM public.workflow_templates
WHERE uid IN (
  SELECT flow_template_snapshot_uid FROM compliance.assessment_plan_extensions
  WHERE assessment_plan_id IN (<ap1_id>, <ap2_id>)
);
-- → 兩 row，provider='snapshot'，source_template_uid 分別指向 master A / B

-- 兩個 workflow_executions
SELECT uid, name, template_id, status
FROM public.workflow_executions
WHERE uid IN (
  SELECT workflow_execution_uid FROM compliance.assessment_plan_extensions
  WHERE assessment_plan_id IN (<ap1_id>, <ap2_id>)
);
-- → 兩 row，互不相關

-- 改 master A 的 BPMN XML（模擬 admin 編輯）
UPDATE compliance.flow_templates SET bpmn_xml = '<bpmn>...modified...</bpmn>'
WHERE name = '完整稽核流程';

-- 驗 snapshot row 不變
SELECT xml FROM public.workflow_templates WHERE uid = '<ap1_snapshot_uid>';
-- → 仍是 build 時的原 XML，不被 master 變更影響

## 驗證結果（M7 smoke）
- Round 1（範本 A，4 stages 全跑）：✅
- Round 2（範本 B，跳 poam）：✅
- Snapshot 隔離（改 master 不影響 AP）：✅
- DB 驗證（兩 row ext / 兩 row snapshot / 兩 row workflow_execution）：✅

git add docs/changelog/2026-05-13-feat-spec3-flow-template-required.md
git commit -m "docs(spec3 M7): smoke 驗證結果補進 changelog"