FR-050 稽核輪次階段回退（Stage Rollback）— Implementation Plan

-- Date: 2026-07-19
-- FR-050 稽核輪次階段回退（Stage Rollback）— 階段歷程時間軸表
-- 新建 compliance.round_stage_transitions：advance / rollback 皆落表，UI 時間軸資料源。
-- 不含 tenant_id / org_unit_id / RLS — 比照 compliance.project_audit_rounds 軟隔離慣例
-- （round_id soft-ref project_audit_rounds.id，租戶隔離由上層 project 把關；見 plan §1 D1）。

CREATE TABLE compliance.round_stage_transitions (
    id             BIGSERIAL PRIMARY KEY,
    uid            VARCHAR(36)  NOT NULL UNIQUE,                       -- 2026-07-19
    round_id       BIGINT       NOT NULL,                              -- 2026-07-19 → compliance.project_audit_rounds.id（soft ref，比照母表慣例不建 FK constraint，避免 CASCADE）
    from_stage     VARCHAR(50)  NOT NULL,                              -- 2026-07-19 stage_objects.code
    to_stage       VARCHAR(50)  NOT NULL,                              -- 2026-07-19 stage_objects.code
    direction      VARCHAR(10)  NOT NULL,                              -- 2026-07-19 advance | rollback
    operator       VARCHAR(255) NOT NULL,                              -- 2026-07-19 login_name（curr_user）
    operator_nickname VARCHAR(255),                                    -- 2026-07-19 顯示用快照（審計欄位規範：response 需 *_name）
    reason         TEXT,                                               -- 2026-07-19 rollback 必填；advance 恆 NULL
    created_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW(),                -- 2026-07-19
    CONSTRAINT ck_round_stage_transitions_direction
        CHECK (direction IN ('advance', 'rollback')),
    CONSTRAINT ck_round_stage_transitions_reason_required_on_rollback
        CHECK (direction <> 'rollback' OR (reason IS NOT NULL AND btrim(reason) <> ''))
);
COMMENT ON TABLE compliance.round_stage_transitions IS
  'FR-050 稽核輪次階段歷程時間軸（advance + rollback 皆落表）：UI「階段歷程」資料源，rollback 必含 reason';
COMMENT ON COLUMN compliance.round_stage_transitions.round_id IS
  '→ compliance.project_audit_rounds.id（soft ref，比照母表慣例）';
COMMENT ON COLUMN compliance.round_stage_transitions.direction IS
  'advance（推進）｜rollback（退回）— decision==''reject''的 review 退回不算本表 rollback（那是 BPMN reject 分支，非 stage 邊界回退），本表 direction=rollback 專指 FR-050 的相鄰上一步回退';
COMMENT ON COLUMN compliance.round_stage_transitions.reason IS
  'rollback 必填（DB CHECK 強制）；advance 恆 NULL';

CREATE INDEX idx_round_stage_transitions_round_id
  ON compliance.round_stage_transitions (round_id, created_at);

GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.round_stage_transitions TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.round_stage_transitions_id_seq TO cm_app;

INSERT INTO public.schema_migrations(filename, note) VALUES
  ('2026-07-19-fr050-round-stage-transitions.sql',
   'FR-050 新建 compliance.round_stage_transitions（階段歷程時間軸，advance+rollback 皆落表）')
ON CONFLICT (filename) DO NOTHING;

PGPASSWORD='<查 .env DB_SECRET>' psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
  --single-transaction -v ON_ERROR_STOP=1 -f scripts/sql/2026-07-19-fr050-round-stage-transitions.sql

from dataclasses import dataclass
from datetime import datetime
from typing import Optional


@dataclass
class RoundStageTransitionEntity:
    id: Optional[int] = None
    uid: Optional[str] = None
    round_id: Optional[int] = None
    from_stage: Optional[str] = None
    to_stage: Optional[str] = None
    direction: Optional[str] = None  # "advance" | "rollback"
    operator: Optional[str] = None
    operator_nickname: Optional[str] = None
    reason: Optional[str] = None
    created_at: Optional[datetime] = None

from dataclasses import dataclass
from typing import Optional


@dataclass
class RoundStageTransitionQueryEntity:
    round_id: Optional[int] = None
    direction: Optional[str] = None

from abc import ABC, abstractmethod
from typing import List, Optional

from domain.grc.entities.round_stage_transition_entity import RoundStageTransitionEntity


class IRoundStageTransitionRepo(ABC):
    @abstractmethod
    def add(self, entity: RoundStageTransitionEntity) -> RoundStageTransitionEntity: ...

    @abstractmethod
    def list_by_round(self, round_id: int) -> List[RoundStageTransitionEntity]: ...

class RoundStageTransitionDomainService:
    def __init__(self, repo):
        self._repo = repo

    def add(self, entity):
        return self._repo.add(entity)

    def list_by_round(self, round_id: int):
        return self._repo.list_by_round(round_id)

    def __init__(self):
        self._handlers: dict[str, IStageCompletionHandler] = {}
        self._preconditions: dict[str, IStagePreconditionCheck] = {}
        self._rollback_handlers: dict[str, "IStageRollbackHandler"] = {}  # 新增

    def register_rollback_handler(self, handler: "IStageRollbackHandler") -> None:
        if handler.key in self._rollback_handlers:
            logger.warning(
                f"StageRegistry: rollback handler key {handler.key!r} 已存在，將被覆蓋 "
                f"(old={type(self._rollback_handlers[handler.key]).__name__}, "
                f"new={type(handler).__name__})"
            )
        self._rollback_handlers[handler.key] = handler

    def get_rollback_handler(self, key: str) -> Optional["IStageRollbackHandler"]:
        return self._rollback_handlers.get(key)

    def has_rollback_handler(self, key: str) -> bool:
        return key in self._rollback_handlers

class IStageRollbackHandler(ABC):
    """副作用復原 handler — stage 回退時觸發（FR-050）。

    key 慣例＝「當前 stage code」（要退出的那個 stage），例如 key="ap_authoring" 代表
    「從 ap_authoring 退回 planning」的復原邏輯。與 IStageCompletionHandler 的 key（handler_key，
    綁 stage_objects.complete_handler_key）不是同一命名空間，各自查各自的 dict。
    """

    @property
    @abstractmethod
    def key(self) -> str:
        """對應要退出的 stage_objects.code"""

    @abstractmethod
    def execute(
        self,
        round_uid: str,
        project_uid: str,
        user_id: int,
        curr_user: str,
        reason: str,
    ) -> dict:
        """執行副作用復原（作廢標記，不物理刪）。回傳 dict 拼進 rollback response。"""

"""Round stage rollback handlers（FR-050 稽核輪次階段回退）。

每個 handler 的 key＝要退出的 round.status 值（非 stage_object.code——兩者命名不 1:1，
見 plan §4.1 說明）。由 grc DI container 啟動時註冊到 flow_engine StageRegistry 的
rollback 分支。回退鐵則：絕不物理刪資料，一律「作廢/superseded 標記 + 留痕」（design §3）。
"""
from domain.flow_engine.service.stage_completion_registry import IStageRollbackHandler


class RollbackApAuthoringHandler(IStageRollbackHandler):
    """audit_planning → planning：frozen SSP + AP 草稿標 superseded；round.status 回 planning。

    對應推進時的 launch_audit（snapshot living SSP + clone 程序書池 + 建 AP 草稿）。
    living SSP 本未動（snapshot 是另建一份），不需處理。
    """

    def __init__(self, audit_round_app_service):
        self._rounds = audit_round_app_service

    @property
    def key(self) -> str:
        return "audit_planning"  # round.status（此 status 下要回退到 planning）

    def execute(self, round_uid, project_uid, user_id, curr_user, reason) -> dict:
        return self._rounds.rollback_to_planning(
            round_uid=round_uid, curr_user=curr_user, curr_user_id=user_id, reason=reason,
        )


class RollbackAuditingHandler(IStageRollbackHandler):
    """auditing → audit_planning：AR 矩陣保留 + 標記（決策 3，不刪不重建）；round.status 回 audit_planning。

    對應推進時的 start_auditing（建 AR 全量矩陣 + ar_result_id 回填）。
    """

    def __init__(self, audit_round_app_service):
        self._rounds = audit_round_app_service

    @property
    def key(self) -> str:
        return "auditing"  # round.status

    def execute(self, round_uid, project_uid, user_id, curr_user, reason) -> dict:
        return self._rounds.rollback_to_audit_planning(
            round_uid=round_uid, curr_user=curr_user, curr_user_id=user_id, reason=reason,
        )


class RollbackRemediationHandler(IStageRollbackHandler):
    """remediation → auditing：POA&M 標作廢 + 已有整改紀錄保留；round.status 回 auditing。

    對應推進時的 finalize_audit（AR 定版 + not_met 生 POA&M）。
    """

    def __init__(self, audit_round_app_service):
        self._rounds = audit_round_app_service

    @property
    def key(self) -> str:
        return "remediation"  # round.status

    def execute(self, round_uid, project_uid, user_id, curr_user, reason) -> dict:
        return self._rounds.rollback_to_auditing(
            round_uid=round_uid, curr_user=curr_user, curr_user_id=user_id, reason=reason,
        )

    @transaction
    def rollback_to_planning(self, round_uid: str, curr_user: str, curr_user_id: int,
                             reason: str, locale=None) -> dict:
        """audit_planning → planning：frozen SSP / AP 草稿標 superseded，回填清空。

        前置：status == audit_planning（否則 GRC_ROUND_ROLLBACK_INVALID_STATE）。
        manager only（決策 4）。reason 必填（route schema 層已擋，這裡防呆再檢一次）。
        """
        e = self._rounds.get_by_uid(round_uid)
        if e is None:
            raise NotFound(GrcErrorCode.GRC_ROUND_NOT_FOUND)
        self._check_role(e.project_id, curr_user_id, "manager")
        if not (reason or "").strip():
            raise BadRequestError(GrcErrorCode.GRC_ROUND_ROLLBACK_REASON_REQUIRED)
        if e.status != STATUS_AUDIT_PLANNING:
            raise PreconditionFailedError(GrcErrorCode.GRC_ROUND_ROLLBACK_INVALID_STATE)

        # frozen SSP 標 superseded（不物理刪；deep_clone 出來的獨立副本，標記後 UI 濾掉）
        if e.ssp_id and self._oscal_snapshot_service is not None:
            self._oscal_snapshot_service.mark_ssp_superseded(e.ssp_id, curr_user)
        # AP 草稿標 superseded（PublishStatus 無此值域 — 見 Task 4.4 套件異動）
        if e.assessment_plan_id and self._ap_app_service is not None:
            self._ap_app_service.mark_ap_superseded(e.assessment_plan_id, curr_user)

        e.ssp_id = None
        e.assessment_plan_id = None
        e.status = STATUS_PLANNING
        e.updated_user = curr_user
        updated = self._rounds.update(e)
        self._record_transition(e.id, from_stage="ap_authoring", to_stage="planning",
                                curr_user=curr_user, reason=reason)
        logger.info("rollback_to_planning round=%s -> planning (superseded ssp/ap)", round_uid)
        self._sync_project_status(e.project_id, curr_user)
        return self._to_dto(updated)

    @transaction
    def rollback_to_audit_planning(self, round_uid: str, curr_user: str, curr_user_id: int,
                                   reason: str, locale=None) -> dict:
        """auditing → audit_planning：AR 矩陣保留 + 標記（決策 3），round.status 回 audit_planning。"""
        e = self._rounds.get_by_uid(round_uid)
        if e is None:
            raise NotFound(GrcErrorCode.GRC_ROUND_NOT_FOUND)
        self._check_role(e.project_id, curr_user_id, "manager")
        if not (reason or "").strip():
            raise BadRequestError(GrcErrorCode.GRC_ROUND_ROLLBACK_REASON_REQUIRED)
        if e.status != STATUS_AUDITING:
            raise PreconditionFailedError(GrcErrorCode.GRC_ROUND_ROLLBACK_INVALID_STATE)

        if e.ar_result_id and self._ar_app_service is not None:
            self._ar_app_service.mark_ar_superseded(e.ar_result_id, curr_user)

        e.status = STATUS_AUDIT_PLANNING
        e.updated_user = curr_user
        updated = self._rounds.update(e)
        self._record_transition(e.id, from_stage="auditing", to_stage="ap_authoring",
                                curr_user=curr_user, reason=reason)
        logger.info("rollback_to_audit_planning round=%s -> audit_planning (ar retained+marked)",
                    round_uid)
        self._sync_project_status(e.project_id, curr_user)
        return self._to_dto(updated)

    @transaction
    def rollback_to_auditing(self, round_uid: str, curr_user: str, curr_user_id: int,
                             reason: str, locale=None) -> dict:
        """remediation → auditing：POA&M 標作廢 + 已有整改紀錄保留，round.status 回 auditing。"""
        e = self._rounds.get_by_uid(round_uid)
        if e is None:
            raise NotFound(GrcErrorCode.GRC_ROUND_NOT_FOUND)
        self._check_role(e.project_id, curr_user_id, "manager")
        if not (reason or "").strip():
            raise BadRequestError(GrcErrorCode.GRC_ROUND_ROLLBACK_REASON_REQUIRED)
        if e.status != STATUS_REMEDIATION:
            raise PreconditionFailedError(GrcErrorCode.GRC_ROUND_ROLLBACK_INVALID_STATE)

        if e.poam_id and self._poam_app_service is not None:
            self._poam_app_service.mark_poam_superseded(e.poam_id, curr_user)

        e.status = STATUS_AUDITING
        e.poam_id = None
        e.updated_user = curr_user
        updated = self._rounds.update(e)
        self._record_transition(e.id, from_stage="poam", to_stage="audit",
                                curr_user=curr_user, reason=reason)
        logger.info("rollback_to_auditing round=%s -> auditing (poam superseded)", round_uid)
        self._sync_project_status(e.project_id, curr_user)
        return self._to_dto(updated)

    def _record_transition(self, round_id: int, from_stage: str, to_stage: str,
                           curr_user: str, reason: Optional[str]) -> None:
        """落 round_stage_transitions 一行（advance/rollback 共用）。caller 須在 @transaction scope。"""
        from uuid import uuid4
        from domain.grc.entities.round_stage_transition_entity import RoundStageTransitionEntity
        nickname = None
        if self._user_domain_service is not None:
            users = self._user_domain_service.get_users(
                UserQueryEntity(_in_login_name=[curr_user])
            )
            nickname = users[0].nickname if users else None
        self._transitions.add(RoundStageTransitionEntity(
            uid=str(uuid4()), round_id=round_id,
            from_stage=from_stage, to_stage=to_stage,
            direction="rollback" if reason else "advance",
            operator=curr_user, operator_nickname=nickname, reason=reason,
        ))

        # 6.5 落階段歷程（FR-050 D4：advance 也記，UI 時間軸資料源）
        if self._round_stage_transition_domain_service is not None:
            self._round_stage_transition_domain_service.add(RoundStageTransitionEntity(
                uid=str(uuid4()),
                round_id=wf_ctx["round"].id,
                from_stage=stage_object.code,
                to_stage=next_stage_code or stage_object.code,
                direction="advance",
                operator=curr_user,
                operator_nickname=ctx.get("user_nickname"),
                reason=None,
            ))

GRC_ROUND_ROLLBACK_INVALID_STATE   = ("目前輪次狀態不允許回退到此階段", "GRC_412029")
GRC_ROUND_ROLLBACK_REASON_REQUIRED = ("回退原因為必填",                 "GRC_400077")
GRC_ROUND_ROLLBACK_NOT_ALLOWED     = ("此邊界不允許回退（closed 輪次或無對應 handler）", "GRC_412030")
GRC_ROUND_ROLLBACK_HANDLER_NOT_REGISTERED = ("rollback handler 未註冊", "GRC_400078")

    # Flow Engine — Stage Rollback（FR-050，log handler 寫進 public.system_logs.event_code）
    STAGE_ROLLBACK_REQUESTED = 6090  # 回退 API 收到請求
    STAGE_ROLLBACK_SUCCESS   = 6091  # 回退成功
    STAGE_ROLLBACK_DENIED    = 6092  # 各種被擋（reason 由 message 內 reason= 區分）

"""Stage rollback service（FR-050 稽核輪次階段回退）。

「返回上一階段」按鈕的 BE 入口。設計：
- 只允許退回相鄰上一步（決策 1）；跨階段＝連按多次，每次各留一筆 round_stage_transitions
- closed 輪次不可回退（決策 2，DB CHECK 之外此處也業務層擋，防呆雙保險）
- manager only（決策 4）
- BPMN 回退委派 jedi-flow-engine WorkflowExecutionService.revert_job
- 副作用復原委派 stage_registry 查到的 IStageRollbackHandler（AuditRoundAppService 對應方法）
"""
from __future__ import annotations

import logging
from typing import Optional

from jedi_common.handler.exception import (
    BadRequestError,
    ForbiddenError,
    NotFound,
    PreconditionFailedError,
)
from jedi_common.session.database.db import transaction
from jedi_flow_engine.common.utils.bpmn_uilts import BpmnUtils
from jedi_flow_engine.domain.entity.workflow_execution_query_entity import (
    WorkflowExecutionQueryEntity,
)

from common.code.grc_error_code import GrcErrorCode
from common.enum.event_code import EventCode
from common.enum.participant_enum import ParticipantRole
from domain.participant.entity.project_participant_query_entity import (
    ProjectParticipantQueryEntity,
)

logger = logging.getLogger(__name__)

# 決策 1/2/3（design §3）：允許回退的 round.status 白名單，一律退回相鄰上一步
# （跨階段靠連按達成，不做多級跳轉）。三欄：
#   status_key      = rnd.status 現值（決定走哪個 rollback handler，見 handler.key）
#   from_stage_code = 目前活躍的 BPMN stage_object.code（revert_job 的 job_id 來源）
#   to_stage_code   = 回退目標的 BPMN stage_object.code（revert_job 的 revert_to_job_id 來源）
# status code 與 stage_object.code 命名不是 1:1（§0 已用 DEV DB 核對 stage_objects seed），
# 兩者關係在此表一次性對照清楚，避免散落各處各自猜測導致錯位。
_ROLLBACK_BOUNDARIES = {
    "audit_planning": {"from_stage_code": "ap_authoring", "to_stage_code": "planning"},
    "auditing":        {"from_stage_code": "audit",        "to_stage_code": "ap_authoring"},
    "remediation":     {"from_stage_code": "poam",         "to_stage_code": "audit"},
}


class StageRollbackService:
    def __init__(
        self,
        stage_registry,
        audit_round_domain_service,
        workflow_execution_service,
        workflow_execution_domain_service,
        project_domain_service,
        project_participant_domain_service,
    ):
        self._stage_registry = stage_registry
        self._audit_round_domain_service = audit_round_domain_service
        self._workflow_execution_service = workflow_execution_service
        self._workflow_execution_domain_service = workflow_execution_domain_service
        self._project_domain_service = project_domain_service
        self._participant_domain_service = project_participant_domain_service

    @transaction
    def rollback_stage(
        self,
        project_uid: str,
        round_uid: str,
        user_id: int,
        curr_user: str,
        reason: str,
        ctx: Optional[dict] = None,
    ) -> dict:
        ctx = dict(ctx or {})
        logger.info(
            "[AUDIT:STAGE_ROLLBACK] requested user_id=%s curr_user=%s project_uid=%s "
            "round_uid=%s reason=%r",
            user_id, curr_user, project_uid, round_uid, (reason or "")[:200],
            extra={'event_code': EventCode.STAGE_ROLLBACK_REQUESTED},
        )

        rnd = self._audit_round_domain_service.get_by_uid(round_uid)
        if rnd is None:
            raise NotFound(GrcErrorCode.GRC_ROUND_NOT_FOUND)

        # 1. manager only（決策 4；不做 role fallback，精確查該專案 participant）
        user_role = self._get_user_role(project_uid, user_id)
        if user_role != ParticipantRole.MANAGER:
            logger.warning(
                "[AUDIT:STAGE_ROLLBACK] denied reason=not_manager user_id=%s round_uid=%s",
                user_id, round_uid, extra={'event_code': EventCode.STAGE_ROLLBACK_DENIED},
            )
            raise ForbiddenError(GrcErrorCode.GRC_NOT_MANAGER)

        # 2. reason 必填（決策 5 前提）
        if not (reason or "").strip():
            raise BadRequestError(GrcErrorCode.GRC_ROUND_ROLLBACK_REASON_REQUIRED)

        # 3. closed 不可退（決策 2，業務層雙保險；round.status CHECK 本身不擋「從哪個態轉」）
        if rnd.status == "closed":
            raise PreconditionFailedError(GrcErrorCode.GRC_ROUND_ROLLBACK_NOT_ALLOWED)

        # 4. 依 round.status 判斷這是哪個回退邊界（round.status 是 canonical 真相；
        #    handler registry key＝round.status 本身，見 §4.1 handler 定義 + _ROLLBACK_BOUNDARIES）
        boundary = _ROLLBACK_BOUNDARIES.get(rnd.status)
        if boundary is None:
            raise PreconditionFailedError(GrcErrorCode.GRC_ROUND_ROLLBACK_NOT_ALLOWED)

        handler = self._stage_registry.get_rollback_handler(rnd.status)
        if handler is None:
            logger.error(
                "[AUDIT:STAGE_ROLLBACK] denied reason=handler_not_registered "
                "round_uid=%s status=%s",
                round_uid, rnd.status,
                extra={'event_code': EventCode.STAGE_ROLLBACK_DENIED},
            )
            raise PreconditionFailedError(GrcErrorCode.GRC_ROUND_ROLLBACK_HANDLER_NOT_REGISTERED)

        # 5. 副作用復原（AuditRoundAppService.rollback_to_* — 標記 superseded + round.status 回寫
        #    + 落 round_stage_transitions；見 app/grc/service/audit_round_app_service.py）
        handler_result = handler.execute(
            round_uid=round_uid, project_uid=project_uid,
            user_id=user_id, curr_user=curr_user, reason=reason,
        )

        # 6. BPMN 回退（jedi-flow-engine revert_job；目標 job 設回 PROCESSING、清 end_time，
        #    其後 job 依 job_execution_order 設回 TODO）
        if rnd.workflow_execution_uid:
            wf = self._workflow_execution_domain_service.get_workflow_execution(
                WorkflowExecutionQueryEntity(uid=str(rnd.workflow_execution_uid))
            )
            if wf is not None:
                bpmn_util = BpmnUtils(wf.workflow_template_xml)
                curr_job = self._find_job_by_stage_code(
                    bpmn_util, boundary["from_stage_code"]
                )
                target_job = self._find_job_by_stage_code(
                    bpmn_util, boundary["to_stage_code"]
                )
                if target_job is not None and curr_job is not None:
                    self._workflow_execution_service.revert_job(
                        workflow_execution_uid=str(rnd.workflow_execution_uid),
                        job_id=curr_job.id,
                        revert_to_job_id=target_job.id,
                        comment=reason,
                        user=curr_user,
                        user_nickname=ctx.get("user_nickname") or curr_user,
                    )

        logger.info(
            "[AUDIT:STAGE_ROLLBACK] success user_id=%s curr_user=%s round_uid=%s "
            "from_status=%s",
            user_id, curr_user, round_uid, rnd.status,
            extra={'event_code': EventCode.STAGE_ROLLBACK_SUCCESS},
        )
        return {"rolled_back": True, "handler_result": handler_result}

    def _get_user_role(self, project_uid: str, user_id: int) -> Optional[str]:
        from jedi_project.domain.entity.project_query_entity import ProjectQueryEntity
        project = self._project_domain_service.get_one(ProjectQueryEntity(uid=project_uid))
        if project is None:
            raise NotFound(GrcErrorCode.GRC_PROJECT_NOT_FOUND)
        participant = self._participant_domain_service.get_one(
            ProjectParticipantQueryEntity(project_id=project.id, user_id=user_id)
        )
        return participant.role if participant is not None else None

    def _find_job_by_stage_code(self, bpmn_util: BpmnUtils, stage_code: Optional[str]):
        if not stage_code:
            return None
        for job in bpmn_util.jobs:
            if (job.properties or {}).get("stage_object_code") == stage_code:
                return job
        return None

from marshmallow import Schema, fields, validate


class StageRollbackRequestSchema(Schema):
    """POST /project/<uid>/audit-round/<uid>/stage/rollback body."""
    reason = fields.Str(required=True, validate=validate.Length(min=1))
    ctx = fields.Dict(load_default=dict)


class StageRollbackResponseSchema(Schema):
    rolled_back = fields.Bool(required=True)
    handler_result = fields.Dict(allow_none=True)


class RoundStageTransitionEntrySchema(Schema):
    uid = fields.Str(required=True)
    from_stage = fields.Str(required=True)
    to_stage = fields.Str(required=True)
    direction = fields.Str(required=True)  # advance | rollback
    operator = fields.Str(required=True)
    operator_nickname = fields.Str(allow_none=True)
    reason = fields.Str(allow_none=True)
    created_at = fields.DateTime(required=True)


class RoundStageTransitionsResponseSchema(Schema):
    """GET /project/<uid>/audit-round/<uid>/stage/transitions response body."""
    data = fields.List(fields.Nested(RoundStageTransitionEntrySchema), load_default=list)

from dependency_injector.wiring import Provide, inject
from flask import request
from flask_jwt_extended import jwt_required
from flask_restful import Resource
from jedi_common.session.auth.auth_context import get_user_context

from api.flow_engine.serializers.stage_rollback import (
    StageRollbackRequestSchema,
    StageRollbackResponseSchema,
    RoundStageTransitionsResponseSchema,
)
from app.flow_engine.service.stage_rollback_service import StageRollbackService
from app.grc.service.audit_round_app_service import AuditRoundAppService
from common.util.response_util import return_response
from di_containers.containers import Containers


class StageRollbackResource(Resource):
    method_decorators = [jwt_required()]

    @inject
    def post(
        self,
        project_uid: str,
        round_uid: str,
        service: StageRollbackService = Provide[
            Containers.grc_container.stage_rollback_service
        ],
    ):
        body = StageRollbackRequestSchema().load(request.get_json(silent=True) or {})
        user_ctx = get_user_context()
        ctx = dict(body.get("ctx") or {})
        ctx.setdefault("user_nickname", user_ctx.nickname)

        result = service.rollback_stage(
            project_uid=project_uid,
            round_uid=round_uid,
            user_id=user_ctx.id,
            curr_user=user_ctx.login_name,
            reason=body["reason"],
            ctx=ctx,
        )
        return return_response(True, StageRollbackResponseSchema().dump(result))


class RoundStageTransitionsResource(Resource):
    method_decorators = [jwt_required()]

    @inject
    def get(
        self,
        project_uid: str,
        round_uid: str,
        audit_round_app_service: AuditRoundAppService = Provide[
            Containers.grc_container.audit_round_app_service
        ],
    ):
        transitions = audit_round_app_service.list_stage_transitions(round_uid)
        return return_response(
            True, RoundStageTransitionsResponseSchema().dump({"data": transitions})
        )

    from api.flow_engine.routes.stage_rollback_route import (
        StageRollbackResource, RoundStageTransitionsResource,
    )

    api.add_resource(
        StageRollbackResource,
        '/project/<string:project_uid>/audit-round/<string:round_uid>/stage/rollback',
    )
    api.add_resource(
        RoundStageTransitionsResource,
        '/project/<string:project_uid>/audit-round/<string:round_uid>/stage/transitions',
    )

    # ── Stage Rollback Service（FR-050，round-scoped）──────────────────────
    round_stage_transition_repo = providers.Factory(RoundStageTransitionRepoImpl)
    round_stage_transition_domain_service = providers.Factory(
        RoundStageTransitionDomainService,
        repo=round_stage_transition_repo,
    )
    stage_rollback_service = providers.Factory(
        StageRollbackService,
        stage_registry=flow_template_container.stage_registry,
        audit_round_domain_service=project_audit_round_domain_service,
        workflow_execution_service=workflow_execution_container.workflow_execution_service,
        workflow_execution_domain_service=workflow_execution_container.workflow_execution_domain_service,
        project_domain_service=project_container.project_domain_service,
        project_participant_domain_service=project_participant_container.project_participant_domain_service,
    )

    _safe_register("rollback_handler", grc_container.rollback_ap_authoring_handler)
    _safe_register("rollback_handler", grc_container.rollback_auditing_handler)
    _safe_register("rollback_handler", grc_container.rollback_remediation_handler)

from datetime import datetime
from typing import Optional

from sqlalchemy import BigInteger, DateTime, String, Text
from sqlalchemy.orm import Mapped, mapped_column

from jedi_common.session.database.declarative_base import Base


class RoundStageTransition(Base):
    """compliance.round_stage_transitions — 階段歷程時間軸（FR-050）。"""

    __tablename__ = "round_stage_transitions"
    __table_args__ = {"schema": "compliance", "comment": "FR-050 階段歷程時間軸"}

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    uid: Mapped[str] = mapped_column(String(36), nullable=False, unique=True)
    round_id: Mapped[int] = mapped_column(BigInteger, nullable=False, comment="→ compliance.project_audit_rounds.id（soft ref）")
    from_stage: Mapped[str] = mapped_column(String(50), nullable=False)
    to_stage: Mapped[str] = mapped_column(String(50), nullable=False)
    direction: Mapped[str] = mapped_column(String(10), nullable=False)
    operator: Mapped[str] = mapped_column(String(255), nullable=False)
    operator_nickname: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
    reason: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)

from typing import List

from domain.grc.entities.round_stage_transition_entity import RoundStageTransitionEntity
from domain.grc.repository.i_round_stage_transition_repo import IRoundStageTransitionRepo
from infra.grc.mapper.round_stage_transition_mapper import RoundStageTransitionMapper
from infra.grc.model.round_stage_transition import RoundStageTransition


class RoundStageTransitionRepoImpl(IRoundStageTransitionRepo):
    """CLAUDE.md session 規範：session 必須 lazy — @property，不在 __init__ 存 self.session。"""

    @property
    def session(self):
        from jedi_common.session.database.db import get_session
        return get_session()

    def add(self, entity: RoundStageTransitionEntity) -> RoundStageTransitionEntity:
        from datetime import datetime
        model = RoundStageTransitionMapper.to_model(entity)
        model.created_at = model.created_at or datetime.utcnow()
        self.session.add(model)
        self.session.flush()
        self.session.refresh(model)
        return RoundStageTransitionMapper.to_entity(model)

    def list_by_round(self, round_id: int) -> List[RoundStageTransitionEntity]:
        rows = (
            self.session.query(RoundStageTransition)
            .filter(RoundStageTransition.round_id == round_id)
            .order_by(RoundStageTransition.created_at.asc())
            .all()
        )
        return [RoundStageTransitionMapper.to_entity(r) for r in rows]