sysnet-soft-delete 0.2.0

Soft-delete mixin a repository pro Beanie ODM

sysnet-soft-delete

Sdílená knihovna poskytující konzistentní, bezpečný a snadno použitelný soft-delete mechanismus pro mikroservisy postavené na FastAPI + Beanie + MongoDB.

pip install sysnet-soft-delete

---

Dokumentace

Dokument	Popis
Uživatelská příručka	Instalace, API reference, příklady integrace s FastAPI, auditní logging
Technická dokumentace	Architektura, designová rozhodnutí, testovací strategie, jak přispívat
Manažerský přehled	Přínosy, rizika, roadmap, migrace
Changelog	Historie verzí

Repozitář: github.com/sysnet-cz/sysnet-soft-delete

---

Problém, který knihovna řeší

Problém	Řešení
Nekonzistentní filtrování is_deleted	SoftDeleteRepository vynucuje filtr vždy
Opakovaný boilerplate kód	Jeden mixin, jeden import
Chybějící audit (deleted_at, deleted_by)	Součást mixinu, volitelný audit port
Riziko návratu smazaných dokumentů	find_active() / get_active() jako primární API
Konflikty s unikátními indexy	Vzor partialFilterExpression (viz dokumentace)

---

Rychlý start

1. Model

from beanie import Document
from sysnet_soft_delete import SoftDeleteMixin

class Article(SoftDeleteMixin, Document):
    title: str
    author: str

    class Settings:
        name = "articles"

Pořadí dědičnosti: SoftDeleteMixin musí být před Document v MRO.

2. Repository

from sysnet_soft_delete import SoftDeleteRepository

class ArticleRepository(SoftDeleteRepository[Article]):
    pass

repo = ArticleRepository(Article)

3. Použití

# Vytvoření
article = Article(title="Hello World", author="Jan")
await article.insert()

# Soft delete
await article.soft_delete(deleted_by="[e-mail]")
# article.is_deleted == True
# article.deleted_at  == datetime(...)
# article.deleted_by  == "[e-mail]"

# Dotazy — smazaný článek se neobjeví
active = await repo.find_active()                        # []
one    = await repo.get_active(article.id)               # None
one    = await repo.find_one_active({"author": "Jan"})   # None (smazaný)
count  = await repo.count_active()                       # 0

# Obnovení
await article.restore(restored_by="[e-mail]")
# article.is_deleted == False

# Explicitní opt-in pro smazané záznamy
all_docs = await repo.find_all_including_deleted()

---

API — přehled

SoftDeleteMixin

async def soft_delete(self, deleted_by: str | None = None) -> None
async def restore(self, restored_by: str | None = None) -> None

Pole: is_deleted: bool, deleted_at: datetime | None, deleted_by: str | None

SoftDeleteRepository[D]

await repo.find_active(*conditions, sort=None, limit=None, skip=None)
await repo.find_one_active(*conditions)          # v0.2.0+
await repo.get_active(document_id)
await repo.count_active(*conditions)
await repo.find_all_including_deleted(*conditions, ...)

Auditní port

from sysnet_soft_delete import configure_audit_logger

configure_audit_logger(SysnetAuditAdapter())  # volat jednou při startu

Adapter musí implementovat: async def log(action, entity, entity_id, actor, metadata, timestamp).

Výjimky

from sysnet_soft_delete import AlreadyDeletedException, NotDeletedException

Kompletní API reference → docs/user-guide.md

---

Verzování

Projekt dodržuje Semantic Versioning. AuditLogger Protocol je veřejné API — breaking změna = major verze.

Viz CHANGELOG.md pro historii změn.

---

Vývoj a testování

pip install -e ".[dev]"
pytest

Testy běží proti real MongoDB instanci (žádné mocky). Výchozí URL: mongodb://root:s3cr3t@localhost:27017. Přepíšete přes proměnnou prostředí:

TEST_MONGO_URL="mongodb://user:pass@host:27017" pytest

---

Licence

AGPLv3+ — SYSNET s.r.o.