Define tenant lifecycle event contract

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

@@ -32,6 +32,13 @@ from govoplan_core.tenancy.service import (
     tenant_counts,
 )
 from govoplan_tenancy.backend.db.models import Tenant
+from govoplan_tenancy.backend.lifecycle import (
+    TENANT_EVENT_CREATED,
+    TENANT_EVENT_DELETION_REQUESTED,
+    TENANT_EVENT_ERASURE_COMPLETED,
+    tenant_lifecycle_event,
+    tenant_lifecycle_event_type,
+)
 
 from .schemas import (
     TenantAdminItem,
@@ -457,11 +464,19 @@ def create_tenant(
         session,
         tenant_id=tenant.id,
         user_id=principal.user.id,
-        action="tenant.created",
+        action=TENANT_EVENT_CREATED,
         object_type="tenant",
         object_id=tenant.id,
         scope="system",
-        details={"slug": tenant.slug, "name": tenant.name, "creator_account_id": principal.account_id, "owner_account_id": owner_account_id},
+        details=tenant_lifecycle_event(
+            "created",
+            tenant_id=tenant.id,
+            tenant_slug=tenant.slug,
+            tenant_name=tenant.name,
+            actor_account_id=principal.account_id,
+            requested_by_account_id=owner_account_id,
+            details={"creator_account_id": principal.account_id, "owner_account_id": owner_account_id},
+        ).audit_details(),
     )
     _record_tenant_list_change(session, tenant=tenant, operation="created", principal=principal)
     session.commit()
@@ -483,6 +498,7 @@ def update_tenant(
     tenant = session.get(Tenant, tenant_id)
     if tenant is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tenant not found")
+    was_active = tenant.is_active
     before_sections = _tenant_settings_sections(_tenant_settings_item(session, tenant))
     if payload.name is not None:
         tenant.name = payload.name.strip()
@@ -522,6 +538,25 @@ def update_tenant(
         object_id=tenant.id,
         details=payload.model_dump(exclude_unset=True),
     )
+    if payload.is_active is not None and payload.is_active != was_active:
+        lifecycle_phase = "resumed" if payload.is_active else "suspended"
+        audit_event(
+            session,
+            tenant_id=tenant.id,
+            user_id=principal.user.id,
+            action=tenant_lifecycle_event_type(lifecycle_phase),
+            scope="system",
+            object_type="tenant",
+            object_id=tenant.id,
+            details=tenant_lifecycle_event(
+                lifecycle_phase,
+                tenant_id=tenant.id,
+                tenant_slug=tenant.slug,
+                tenant_name=tenant.name,
+                actor_account_id=principal.account_id,
+                details={"previous_is_active": was_active, "is_active": tenant.is_active},
+            ).audit_details(),
+        )
     after_sections = _tenant_settings_sections(_tenant_settings_item(session, tenant))
     _record_tenant_settings_section_changes(session, tenant_id=tenant.id, before=before_sections, after=after_sections, principal=principal)
     _record_tenant_list_change(session, tenant=tenant, operation="updated", principal=principal)
@@ -562,6 +597,26 @@ def retire_tenant(
 
     if request.mode == "destroy":
         deleted_item = _tenant_item(session, tenant)
+        deletion_event = tenant_lifecycle_event(
+            "deletion_requested",
+            tenant_id=tenant.id,
+            tenant_slug=tenant.slug,
+            tenant_name=tenant.name,
+            actor_account_id=principal.account_id,
+            reason=request.reason,
+            counts=plan.counts,
+            details={"mode": request.mode},
+        )
+        audit_event(
+            session,
+            tenant_id=tenant.id,
+            user_id=principal.user.id,
+            action=TENANT_EVENT_DELETION_REQUESTED,
+            scope="system",
+            object_type="tenant",
+            object_id=tenant.id,
+            details=deletion_event.audit_details(),
+        )
         audit_event(
             session,
             tenant_id=tenant.id,
@@ -572,6 +627,25 @@ def retire_tenant(
             object_id=tenant.id,
             details={"reason": request.reason, "counts": plan.counts},
         )
+        audit_event(
+            session,
+            tenant_id=tenant.id,
+            user_id=principal.user.id,
+            action=TENANT_EVENT_ERASURE_COMPLETED,
+            scope="system",
+            object_type="tenant",
+            object_id=tenant.id,
+            details=tenant_lifecycle_event(
+                "erasure_completed",
+                tenant_id=tenant.id,
+                tenant_slug=tenant.slug,
+                tenant_name=tenant.name,
+                actor_account_id=principal.account_id,
+                reason=request.reason,
+                counts=plan.counts,
+                details={"mode": request.mode},
+            ).audit_details(),
+        )
         _record_tenant_list_change(session, tenant=tenant, operation="deleted", principal=principal)
         session.delete(tenant)
         session.commit()
@@ -590,6 +664,25 @@ def retire_tenant(
     tenant.settings = settings_payload
     tenant.is_active = False
     session.add(tenant)
+    audit_event(
+        session,
+        tenant_id=tenant.id,
+        user_id=principal.user.id,
+        action=TENANT_EVENT_DELETION_REQUESTED,
+        scope="system",
+        object_type="tenant",
+        object_id=tenant.id,
+        details=tenant_lifecycle_event(
+            "deletion_requested",
+            tenant_id=tenant.id,
+            tenant_slug=tenant.slug,
+            tenant_name=tenant.name,
+            actor_account_id=principal.account_id,
+            reason=request.reason,
+            counts=plan.counts,
+            details={"mode": request.mode},
+        ).audit_details(),
+    )
     audit_event(
         session,
         tenant_id=tenant.id,