chore: document project-wide soft delete pattern and add deleted_by column to all tables

devplacepy/services/devii/tasks/store.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from datetime import datetime, timezone
 from typing import Any
 
 import dataset
@@ -34,6 +35,10 @@ class TaskStore:
         if TABLE not in self._db.tables:
             return
         table = self._db[TABLE]
+        if not table.has_column("deleted_at"):
+            table.create_column_by_example("deleted_at", "")
+        if not table.has_column("deleted_by"):
+            table.create_column_by_example("deleted_by", "")
         for columns in INDEXED_COLUMNS:
             table.create_index(columns)
 
@@ -46,7 +51,9 @@ class TaskStore:
         return {"owner_kind": self._owner_kind, "owner_id": self._owner_id}
 
     def create(self, record: dict[str, Any]) -> None:
-        self._table.insert({**record, **self._scope})
+        self._table.insert(
+            {"deleted_at": None, "deleted_by": None, **record, **self._scope}
+        )
         logger.info(
             "Task created uid=%s owner=%s/%s",
             record.get("uid"),
@@ -55,12 +62,13 @@ class TaskStore:
         )
 
     def get(self, uid: str) -> dict[str, Any] | None:
-        return self._table.find_one(uid=uid, **self._scope)
+        return self._table.find_one(uid=uid, deleted_at=None, **self._scope)
 
     def list(
         self, enabled_only: bool = False, status: str | None = None
     ) -> list[dict[str, Any]]:
         criteria: dict[str, Any] = dict(self._scope)
+        criteria["deleted_at"] = None
         if enabled_only:
             criteria["enabled"] = True
         if status:
@@ -73,14 +81,25 @@ class TaskStore:
         logger.debug("Task updated uid=%s changes=%s", uid, list(changes))
 
     def delete(self, uid: str) -> bool:
-        deleted = self._table.delete(uid=uid, **self._scope)
-        logger.info("Task deleted uid=%s ok=%s", uid, deleted)
-        return bool(deleted)
+        row = self._table.find_one(uid=uid, deleted_at=None, **self._scope)
+        if not row:
+            return False
+        self._table.update(
+            {
+                "uid": uid,
+                "deleted_at": datetime.now(timezone.utc).isoformat(),
+                "deleted_by": f"{self._owner_kind}:{self._owner_id}",
+                **self._scope,
+            },
+            ["uid", "owner_kind", "owner_id"],
+        )
+        logger.info("Task soft-deleted uid=%s", uid)
+        return True
 
     def recover_running(self) -> int:
         if TABLE not in self._db.tables:
             return 0
-        stuck = list(self._table.find(status="running", **self._scope))
+        stuck = list(self._table.find(status="running", deleted_at=None, **self._scope))
         for row in stuck:
             self._table.update(
                 {"uid": row["uid"], "status": "pending", **self._scope},
@@ -91,7 +110,9 @@ class TaskStore:
         return len(stuck)
 
     def due(self, now_iso: str) -> list[dict[str, Any]]:
-        rows = self._table.find(enabled=True, status="pending", **self._scope)
+        rows = self._table.find(
+            enabled=True, status="pending", deleted_at=None, **self._scope
+        )
         return [
             row
             for row in rows