From 5ea47d4ec7f9116cc4d90ea1cb4d372a871a56f6 Mon Sep 17 00:00:00 2001 From: Marcel Date: Sun, 31 May 2026 12:15:52 +0200 Subject: [PATCH] docs(tag): document the dual document counts on the tag tree (#698) Record that getTagTree returns both documentCount (direct, read by admin surfaces) and subtreeDocumentCount (rollup, read by the reader surfaces), matching the corrected getTagTree JavaDoc. Co-Authored-By: Claude Opus 4.8 --- .../src/main/java/org/raddatz/familienarchiv/tag/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md b/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md index 4f34833e..f1d6d16e 100644 --- a/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md +++ b/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md @@ -7,6 +7,13 @@ Hierarchical document categories. Tags form a tree via a self-referencing `paren Entity: `Tag` (self-referencing `parent_id` tree). Features: tag CRUD, hierarchical deletion (cascade to descendants), tag typeahead, admin tag management (rename, reparent, merge). +## Tag tree counts (`getTagTree`) + +`GET /api/tags/tree` returns each node with **two** document counts, from two aggregate queries (no N+1): + +- `documentCount` — documents tagged with that **exact** tag (direct). Read by the admin surfaces (sidebar tree, merge preview, delete-impact guard), which describe direct-document operations. +- `subtreeDocumentCount` — **distinct** documents tagged with that tag **or any descendant** (subtree rollup, recursive-CTE closure, depth guard ≤50). Read by the reader surfaces (`/themen` page, dashboard `ThemenWidget`) so the box number matches what `/documents?tag=X` actually finds. + ## What this domain does NOT own - Documents — the `document_tags` join table is on the document side. `Tag` does not hold document references.