feat(trash): services/trash.py — delete() + cascade-stamp by batch

src/fabledassistant/services/trash.py

@@ -0,0 +1,96 @@
+"""Soft-delete / trash service — single source of truth for recoverable deletes.
+
+A delete stamps `deleted_at` + a shared `deleted_batch_id` on the target row and
+its descendants (cascade). Restore clears the batch; purge hard-deletes it; the
+retention cron purges rows older than the configured window. Live reads exclude
+trashed rows via `alive()`.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import select, update
+
+from fabledassistant.models import async_session
+from fabledassistant.models.note import Note
+from fabledassistant.models.event import Event
+from fabledassistant.models.project import Project
+from fabledassistant.models.milestone import Milestone
+from fabledassistant.models.rulebook import Rulebook, RulebookTopic, Rule
+
+# entity_type -> (Model, owner_column_name or None). Used by the existence check.
+_OWNER = {
+    "note": (Note, "user_id"),
+    "task": (Note, "user_id"),
+    "event": (Event, "user_id"),
+    "project": (Project, "user_id"),
+    "milestone": (Milestone, "user_id"),
+    "rulebook": (Rulebook, "owner_user_id"),
+    "topic": (RulebookTopic, None),
+    "rule": (Rule, None),
+}
+
+
+async def _set(session, model, where, batch, now) -> None:
+    """Stamp deleted_at + batch on live rows matching `where`."""
+    await session.execute(
+        update(model)
+        .where(*where, model.deleted_at.is_(None))
+        .values(deleted_at=now, deleted_batch_id=batch)
+    )
+
+
+async def _exists_alive(session, user_id: int, etype: str, eid: int) -> bool:
+    model, owner = _OWNER[etype]
+    where = [model.id == eid, model.deleted_at.is_(None)]
+    if owner:
+        where.append(getattr(model, owner) == user_id)
+    return (await session.execute(select(model.id).where(*where))).first() is not None
+
+
+async def _cascade(session, user_id: int, etype: str, eid: int, batch: str, now) -> None:
+    if etype == "project":
+        await _set(session, Note, [Note.user_id == user_id, Note.project_id == eid], batch, now)
+        await _set(session, Milestone, [Milestone.user_id == user_id, Milestone.project_id == eid], batch, now)
+        await _set(session, Project, [Project.user_id == user_id, Project.id == eid], batch, now)
+    elif etype == "milestone":
+        await _set(session, Note, [Note.user_id == user_id, Note.milestone_id == eid], batch, now)
+        await _set(session, Milestone, [Milestone.user_id == user_id, Milestone.id == eid], batch, now)
+    elif etype in ("note", "task"):
+        await _set(session, Note, [Note.user_id == user_id, Note.parent_id == eid], batch, now)  # sub-tasks
+        await _set(session, Note, [Note.user_id == user_id, Note.id == eid], batch, now)
+    elif etype == "event":
+        await _set(session, Event, [Event.user_id == user_id, Event.id == eid], batch, now)
+    elif etype == "rulebook":
+        topic_ids = (await session.execute(
+            select(RulebookTopic.id)
+            .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
+            .where(Rulebook.id == eid, Rulebook.owner_user_id == user_id)
+        )).scalars().all()
+        if topic_ids:
+            await _set(session, Rule, [Rule.topic_id.in_(topic_ids)], batch, now)
+        await _set(session, RulebookTopic, [RulebookTopic.rulebook_id == eid], batch, now)
+        await _set(session, Rulebook, [Rulebook.id == eid, Rulebook.owner_user_id == user_id], batch, now)
+    elif etype == "topic":
+        await _set(session, Rule, [Rule.topic_id == eid], batch, now)
+        await _set(session, RulebookTopic, [RulebookTopic.id == eid], batch, now)
+    elif etype == "rule":
+        await _set(session, Rule, [Rule.id == eid], batch, now)
+    else:
+        raise ValueError(f"unknown entity_type: {etype!r}")
+
+
+async def delete(user_id: int, entity_type: str, entity_id: int) -> str | None:
+    """Soft-delete an entity + its descendants under one batch_id.
+
+    Returns the batch_id, or None if the entity wasn't found / not owned.
+    """
+    batch = str(uuid.uuid4())
+    now = datetime.now(timezone.utc)
+    async with async_session() as session:
+        if not await _exists_alive(session, user_id, entity_type, entity_id):
+            return None
+        await _cascade(session, user_id, entity_type, entity_id, batch, now)
+        await session.commit()
+    return batch