Persist hierarchical definition policy overrides

src/govoplan_policy/backend/api/v1/routes.py

@@ -26,8 +26,18 @@ from govoplan_policy.backend.retention import (
     set_privacy_policy_for_scope,
     simulate_privacy_policy_change,
 )
+from govoplan_policy.backend.definition_policy_service import (
+    DefinitionPolicyError,
+    definition_policy_response_payload,
+    definition_policy_state,
+    remove_definition_policy,
+    save_definition_policy,
+)
+from govoplan_policy.backend.policy_overrides import PolicyOverrideError
 
 from .schemas import (
+    DefinitionPolicyScopeRequest,
+    DefinitionPolicyScopeResponse,
     PrivacyRetentionPolicyExplainResponse,
     PrivacyRetentionPolicyItem,
     PrivacyRetentionPolicyScopeRequest,
@@ -42,7 +52,9 @@ router = APIRouter(prefix="/admin", tags=["admin"])
 
 def _require_permission(principal: ApiPrincipal, scope: str) -> None:
     if not has_scope(principal, scope):
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Missing scope: {scope}")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail=f"Missing scope: {scope}"
+        )
 
 
 def _require_privacy_policy_read(principal: ApiPrincipal, scope_type: str) -> None:
@@ -66,7 +78,237 @@ def _configuration_control_http_error(exc: ConfigurationControlError) -> HTTPExc
     )
 
 
-@router.get("/privacy-retention/policies/{scope_type}", response_model=PrivacyRetentionPolicyScopeResponse)
+def _definition_policy_response(
+    *,
+    module_id: str,
+    scope_type: str,
+    scope_id: str | None,
+    state,
+) -> DefinitionPolicyScopeResponse:
+    return DefinitionPolicyScopeResponse(
+        module_id=module_id,
+        scope_type=scope_type,
+        scope_id=scope_id,
+        **definition_policy_response_payload(state),
+    )
+
+
+@router.get(
+    "/definition-policies/{module_id}/{scope_type}",
+    response_model=DefinitionPolicyScopeResponse,
+)
+def read_definition_policy(
+    module_id: str,
+    scope_type: str,
+    scope_id: str | None = Query(default=None),
+    session: Session = Depends(get_session),
+    principal: ApiPrincipal = Depends(get_api_principal),
+):
+    clean_scope = scope_type.strip().casefold()
+    _require_privacy_policy_read(principal, clean_scope)
+    try:
+        state = definition_policy_state(
+            session,
+            module_id=module_id,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        return _definition_policy_response(
+            module_id=module_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+            state=state,
+        )
+    except (DefinitionPolicyError, PolicyOverrideError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=str(exc),
+        ) from exc
+
+
+@router.put(
+    "/definition-policies/{module_id}/{scope_type}",
+    response_model=DefinitionPolicyScopeResponse,
+)
+def write_definition_policy(
+    module_id: str,
+    scope_type: str,
+    payload: DefinitionPolicyScopeRequest,
+    scope_id: str | None = Query(default=None),
+    session: Session = Depends(get_session),
+    principal: ApiPrincipal = Depends(get_api_principal),
+):
+    clean_scope = scope_type.strip().casefold()
+    _require_privacy_policy_write(principal, clean_scope)
+    policy_value = payload.policy.model_dump(mode="json", exclude_none=True)
+    try:
+        before = definition_policy_state(
+            session,
+            module_id=module_id,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        if clean_scope == "system":
+            approval = ensure_configuration_change_allowed(
+                session,
+                key="definition_policy",
+                value=policy_value,
+                actor_user_id=principal.user.id,
+                actor_scopes=tuple(principal.scopes),
+                change_request_id=payload.change_request_id,
+                target={"module_id": module_id, "scope_type": clean_scope},
+            )
+        else:
+            approval = None
+        state = save_definition_policy(
+            session,
+            module_id=module_id,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+            policy=policy_value,
+            actor_id=principal.user.id,
+        )
+        if clean_scope == "system":
+            record_configuration_change_applied(
+                session,
+                key="definition_policy",
+                before_value=definition_policy_response_payload(before)["policy"],
+                after_value=policy_value,
+                actor_user_id=principal.user.id,
+                approval=approval,
+                target={"module_id": module_id, "scope_type": clean_scope},
+                audit_event="definition_policy.updated",
+            )
+        audit_from_principal(
+            session,
+            principal,
+            action="definition_policy.updated",
+            scope="system" if clean_scope == "system" else "tenant",
+            object_type="definition_policy",
+            object_id=f"{module_id}:{clean_scope}:{scope_id or ''}",
+            details={
+                "module_id": module_id,
+                "scope_type": clean_scope,
+                "scope_id": scope_id,
+                "fields": sorted(policy_value),
+            },
+        )
+        session.commit()
+        return _definition_policy_response(
+            module_id=module_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+            state=state,
+        )
+    except ConfigurationControlError as exc:
+        session.rollback()
+        raise _configuration_control_http_error(exc) from exc
+    except (DefinitionPolicyError, PolicyOverrideError) as exc:
+        session.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=str(exc),
+        ) from exc
+
+
+@router.delete(
+    "/definition-policies/{module_id}/{scope_type}",
+    response_model=DefinitionPolicyScopeResponse,
+)
+def delete_definition_policy_route(
+    module_id: str,
+    scope_type: str,
+    scope_id: str | None = Query(default=None),
+    change_request_id: str | None = Query(default=None),
+    session: Session = Depends(get_session),
+    principal: ApiPrincipal = Depends(get_api_principal),
+):
+    clean_scope = scope_type.strip().casefold()
+    _require_privacy_policy_write(principal, clean_scope)
+    try:
+        before = definition_policy_state(
+            session,
+            module_id=module_id,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        if clean_scope == "system":
+            approval = ensure_configuration_change_allowed(
+                session,
+                key="definition_policy",
+                value={},
+                actor_user_id=principal.user.id,
+                actor_scopes=tuple(principal.scopes),
+                change_request_id=change_request_id,
+                target={"module_id": module_id, "scope_type": clean_scope},
+            )
+        else:
+            approval = None
+        removed = remove_definition_policy(
+            session,
+            module_id=module_id,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        if removed:
+            if clean_scope == "system":
+                record_configuration_change_applied(
+                    session,
+                    key="definition_policy",
+                    before_value=definition_policy_response_payload(before)["policy"],
+                    after_value={},
+                    actor_user_id=principal.user.id,
+                    approval=approval,
+                    target={"module_id": module_id, "scope_type": clean_scope},
+                    audit_event="definition_policy.removed",
+                )
+            audit_from_principal(
+                session,
+                principal,
+                action="definition_policy.removed",
+                scope="system" if clean_scope == "system" else "tenant",
+                object_type="definition_policy",
+                object_id=f"{module_id}:{clean_scope}:{scope_id or ''}",
+                details={
+                    "module_id": module_id,
+                    "scope_type": clean_scope,
+                    "scope_id": scope_id,
+                },
+            )
+        session.commit()
+        state = definition_policy_state(
+            session,
+            module_id=module_id,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        return _definition_policy_response(
+            module_id=module_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+            state=state,
+        )
+    except ConfigurationControlError as exc:
+        session.rollback()
+        raise _configuration_control_http_error(exc) from exc
+    except (DefinitionPolicyError, PolicyOverrideError) as exc:
+        session.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=str(exc),
+        ) from exc
+
+
+@router.get(
+    "/privacy-retention/policies/{scope_type}",
+    response_model=PrivacyRetentionPolicyScopeResponse,
+)
 def read_privacy_retention_policy(
     scope_type: str,
     scope_id: str | None = Query(default=None),
@@ -76,23 +318,59 @@ def read_privacy_retention_policy(
     clean_scope = scope_type.strip().casefold()
     _require_privacy_policy_read(principal, clean_scope)
     try:
-        policy = get_privacy_policy_for_scope(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
-        effective = _effective_privacy_policy_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
-        parent = _parent_privacy_policy_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
+        policy = get_privacy_policy_for_scope(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        effective = _effective_privacy_policy_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        parent = _parent_privacy_policy_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
         return PrivacyRetentionPolicyScopeResponse(
             scope_type=clean_scope,
             scope_id=scope_id,
             policy=policy,
-            effective_policy=PrivacyRetentionPolicyItem.model_validate(effective.model_dump(mode="json")),
-            parent_policy=PrivacyRetentionPolicyItem.model_validate(parent.model_dump(mode="json")) if parent else None,
-            effective_policy_sources=_effective_privacy_policy_sources_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id),
-            parent_policy_sources=_parent_privacy_policy_sources_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id),
+            effective_policy=PrivacyRetentionPolicyItem.model_validate(
+                effective.model_dump(mode="json")
+            ),
+            parent_policy=PrivacyRetentionPolicyItem.model_validate(
+                parent.model_dump(mode="json")
+            )
+            if parent
+            else None,
+            effective_policy_sources=_effective_privacy_policy_sources_for_response(
+                session,
+                tenant_id=principal.tenant_id,
+                scope_type=clean_scope,
+                scope_id=scope_id,
+            ),
+            parent_policy_sources=_parent_privacy_policy_sources_for_response(
+                session,
+                tenant_id=principal.tenant_id,
+                scope_type=clean_scope,
+                scope_id=scope_id,
+            ),
         )
     except PrivacyPolicyError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
 
 
-@router.put("/privacy-retention/policies/{scope_type}", response_model=PrivacyRetentionPolicyScopeResponse)
+@router.put(
+    "/privacy-retention/policies/{scope_type}",
+    response_model=PrivacyRetentionPolicyScopeResponse,
+)
 def write_privacy_retention_policy(
     scope_type: str,
     payload: PrivacyRetentionPolicyScopeRequest,
@@ -105,7 +383,12 @@ def write_privacy_retention_policy(
     policy_value = payload.policy.model_dump(mode="json", exclude_none=True)
     before_value: dict[str, Any] | None = None
     if clean_scope == "system":
-        before_value = get_privacy_policy_for_scope(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
+        before_value = get_privacy_policy_for_scope(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
         try:
             approval = ensure_configuration_change_allowed(
                 session,
@@ -149,23 +432,54 @@ def write_privacy_retention_policy(
             details={"scope_type": clean_scope, "scope_id": scope_id},
         )
         session.commit()
-        effective = _effective_privacy_policy_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
-        parent = _parent_privacy_policy_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
+        effective = _effective_privacy_policy_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        parent = _parent_privacy_policy_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
         return PrivacyRetentionPolicyScopeResponse(
             scope_type=clean_scope,
             scope_id=scope_id,
             policy=policy,
-            effective_policy=PrivacyRetentionPolicyItem.model_validate(effective.model_dump(mode="json")),
-            parent_policy=PrivacyRetentionPolicyItem.model_validate(parent.model_dump(mode="json")) if parent else None,
-            effective_policy_sources=_effective_privacy_policy_sources_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id),
-            parent_policy_sources=_parent_privacy_policy_sources_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id),
+            effective_policy=PrivacyRetentionPolicyItem.model_validate(
+                effective.model_dump(mode="json")
+            ),
+            parent_policy=PrivacyRetentionPolicyItem.model_validate(
+                parent.model_dump(mode="json")
+            )
+            if parent
+            else None,
+            effective_policy_sources=_effective_privacy_policy_sources_for_response(
+                session,
+                tenant_id=principal.tenant_id,
+                scope_type=clean_scope,
+                scope_id=scope_id,
+            ),
+            parent_policy_sources=_parent_privacy_policy_sources_for_response(
+                session,
+                tenant_id=principal.tenant_id,
+                scope_type=clean_scope,
+                scope_id=scope_id,
+            ),
         )
     except PrivacyPolicyError as exc:
         session.rollback()
-        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)
+        ) from exc
 
 
-@router.get("/privacy-retention/policies/{scope_type}/explain", response_model=PrivacyRetentionPolicyExplainResponse)
+@router.get(
+    "/privacy-retention/policies/{scope_type}/explain",
+    response_model=PrivacyRetentionPolicyExplainResponse,
+)
 def explain_privacy_retention_policy(
     scope_type: str,
     scope_id: str | None = Query(default=None),
@@ -175,16 +489,40 @@ def explain_privacy_retention_policy(
     clean_scope = scope_type.strip().casefold()
     _require_privacy_policy_read(principal, clean_scope)
     try:
-        effective = _effective_privacy_policy_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
-        parent = _parent_privacy_policy_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
-        effective_sources = _effective_privacy_policy_sources_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
-        parent_sources = _parent_privacy_policy_sources_for_response(session, tenant_id=principal.tenant_id, scope_type=clean_scope, scope_id=scope_id)
+        effective = _effective_privacy_policy_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        parent = _parent_privacy_policy_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        effective_sources = _effective_privacy_policy_sources_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
+        parent_sources = _parent_privacy_policy_sources_for_response(
+            session,
+            tenant_id=principal.tenant_id,
+            scope_type=clean_scope,
+            scope_id=scope_id,
+        )
         blocked_fields = _blocked_privacy_retention_fields(parent)
         decision_sources = parent_sources or effective_sources
         decision = PolicyDecision(
             allowed=not blocked_fields,
-            reason="Parent retention policy locks lower-level changes." if blocked_fields else None,
-            source_path=tuple(PolicySourceStep.from_mapping(source) for source in decision_sources),
+            reason="Parent retention policy locks lower-level changes."
+            if blocked_fields
+            else None,
+            source_path=tuple(
+                PolicySourceStep.from_mapping(source) for source in decision_sources
+            ),
             requirements=tuple(blocked_fields),
             details={"blocked_fields": blocked_fields},
         )
@@ -192,17 +530,28 @@ def explain_privacy_retention_policy(
             scope_type=clean_scope,
             scope_id=scope_id,
             decision=decision.to_dict(),
-            effective_policy=PrivacyRetentionPolicyItem.model_validate(effective.model_dump(mode="json")),
-            parent_policy=PrivacyRetentionPolicyItem.model_validate(parent.model_dump(mode="json")) if parent else None,
+            effective_policy=PrivacyRetentionPolicyItem.model_validate(
+                effective.model_dump(mode="json")
+            ),
+            parent_policy=PrivacyRetentionPolicyItem.model_validate(
+                parent.model_dump(mode="json")
+            )
+            if parent
+            else None,
             effective_policy_sources=effective_sources,
             parent_policy_sources=parent_sources,
             blocked_fields=blocked_fields,
         )
     except PrivacyPolicyError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
 
 
-@router.post("/privacy-retention/policies/{scope_type}/simulate", response_model=PrivacyRetentionPolicySimulationResponse)
+@router.post(
+    "/privacy-retention/policies/{scope_type}/simulate",
+    response_model=PrivacyRetentionPolicySimulationResponse,
+)
 def simulate_privacy_retention_policy(
     scope_type: str,
     payload: PrivacyRetentionPolicyScopeRequest,
@@ -225,7 +574,9 @@ def simulate_privacy_retention_policy(
             ),
         )
     except PrivacyPolicyError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
 
 
 def _blocked_privacy_retention_fields(parent) -> list[str]:
@@ -233,36 +584,64 @@ def _blocked_privacy_retention_fields(parent) -> list[str]:
         return []
     payload = parent.model_dump(mode="json")
     allow_lower_level_limits = payload.get("allow_lower_level_limits") or {}
-    return [key for key in RETENTION_POLICY_FIELD_KEYS if allow_lower_level_limits.get(key) is False]
+    return [
+        key
+        for key in RETENTION_POLICY_FIELD_KEYS
+        if allow_lower_level_limits.get(key) is False
+    ]
 
 
-def _parent_privacy_policy_sources_for_response(session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None):
+def _parent_privacy_policy_sources_for_response(
+    session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None
+):
     if scope_type == "system":
         return []
-    return parent_privacy_policy_sources(session, tenant_id=tenant_id, scope_type=scope_type, scope_id=scope_id or (tenant_id if scope_type == "tenant" else None))
+    return parent_privacy_policy_sources(
+        session,
+        tenant_id=tenant_id,
+        scope_type=scope_type,
+        scope_id=scope_id or (tenant_id if scope_type == "tenant" else None),
+    )
 
 
-def _effective_privacy_policy_sources_for_response(session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None):
+def _effective_privacy_policy_sources_for_response(
+    session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None
+):
     if scope_type == "system":
         return effective_privacy_policy_sources(session)
     if scope_type == "tenant":
-        return effective_privacy_policy_sources(session, tenant_id=scope_id or tenant_id)
+        return effective_privacy_policy_sources(
+            session, tenant_id=scope_id or tenant_id
+        )
     if scope_type == "campaign" and scope_id:
         return effective_privacy_policy_sources(session, campaign_id=scope_id)
     if scope_type == "user" and scope_id:
-        return effective_privacy_policy_sources(session, tenant_id=tenant_id, owner_user_id=scope_id)
+        return effective_privacy_policy_sources(
+            session, tenant_id=tenant_id, owner_user_id=scope_id
+        )
     if scope_type == "group" and scope_id:
-        return effective_privacy_policy_sources(session, tenant_id=tenant_id, owner_group_id=scope_id)
+        return effective_privacy_policy_sources(
+            session, tenant_id=tenant_id, owner_group_id=scope_id
+        )
     return effective_privacy_policy_sources(session, tenant_id=tenant_id)
 
 
-def _parent_privacy_policy_for_response(session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None):
+def _parent_privacy_policy_for_response(
+    session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None
+):
     if scope_type == "system":
         return None
-    return parent_privacy_policy(session, tenant_id=tenant_id, scope_type=scope_type, scope_id=scope_id or (tenant_id if scope_type == "tenant" else None))
+    return parent_privacy_policy(
+        session,
+        tenant_id=tenant_id,
+        scope_type=scope_type,
+        scope_id=scope_id or (tenant_id if scope_type == "tenant" else None),
+    )
 
 
-def _effective_privacy_policy_for_response(session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None):
+def _effective_privacy_policy_for_response(
+    session: Session, *, tenant_id: str, scope_type: str, scope_id: str | None
+):
     if scope_type == "system":
         return effective_privacy_policy(session)
     if scope_type == "tenant":
@@ -270,9 +649,13 @@ def _effective_privacy_policy_for_response(session: Session, *, tenant_id: str,
     if scope_type == "campaign" and scope_id:
         return effective_privacy_policy(session, campaign_id=scope_id)
     if scope_type == "user" and scope_id:
-        return effective_privacy_policy(session, tenant_id=tenant_id, owner_user_id=scope_id)
+        return effective_privacy_policy(
+            session, tenant_id=tenant_id, owner_user_id=scope_id
+        )
     if scope_type == "group" and scope_id:
-        return effective_privacy_policy(session, tenant_id=tenant_id, owner_group_id=scope_id)
+        return effective_privacy_policy(
+            session, tenant_id=tenant_id, owner_group_id=scope_id
+        )
     return effective_privacy_policy(session, tenant_id=tenant_id)