feat(themen): count documents across the whole sub-topic tree (#698) #701

Merged

marcel merged 8 commits from worktree-feat+issue-698-themen-subtree-count into main 2026-05-31 12:58:10 +02:00

Conversation 0 Commits 8 Files Changed 18 +415 -41

marcel commented 2026-05-31 12:32:40 +02:00

Owner

Copy Link

Closes #698.

Each /themen box now counts documents across its whole sub-topic tree (distinct), so the number matches what /documents?tag=X actually returns. Implements Option B: a new subtreeDocumentCount field — reader surfaces read the rollup, admin surfaces keep the direct documentCount.

What changed

Backend

• TagTreeNodeDTO gains subtreeDocumentCount; getTagTree() maps both counts onto each node from two aggregate queries (no N+1 — NFR-PERF-THEMEN-01).
• New TagRepository.findSubtreeDocumentCountsPerTag(): one recursive-CTE tag closure (depth guard ≤50) joined to document_tags, GROUP BY ancestor_id with COUNT(DISTINCT document_id) (REQ-THEMEN-01/02/03/06). Direct documentCount is unchanged.
• Corrected the stale getTagTree() JavaDoc + tag/README.md.

Frontend

• hasAnyDocuments keys on subtreeDocumentCount > 0 (single field read).
• /themen page (header, child rows, aria-labels) and the dashboard ThemenWidget display subtreeDocumentCount. A parent with 0 direct docs but populated children now shows a non-zero total.
• Admin sidebar, merge preview and delete-impact guard are unchanged (still direct documentCount).

Tests

• Real-Postgres (postgres:16-alpine, Testcontainers) integration tests: leaf = direct (AC#4), shared doc counted once (AC#1+#2), full grandchild depth (AC#3), empty subtree absent (REQ-THEMEN-05), cycle terminates via the guard (REQ-THEMEN-06), and rollup == distinct documents from the real search expansion (AC#7 parity).
• Service unit tests for the two-query wiring; frontend hasAnyDocuments tests; AC#5 component test; admin characterization tests pinning previews to the direct count (AC#8).

Notes for the reviewer

• generated/api.ts was hand-edited to match generate:api output (codegen needs a live dev backend); re-running it should be byte-equivalent.
• Browser-mode component tests are validated on CI, not locally (project convention).

🤖 Generated with Claude Code

Closes #698. Each `/themen` box now counts documents across its **whole sub-topic tree** (distinct), so the number matches what `/documents?tag=X` actually returns. Implements **Option B**: a new `subtreeDocumentCount` field — reader surfaces read the rollup, admin surfaces keep the direct `documentCount`. ## What changed **Backend** - `TagTreeNodeDTO` gains `subtreeDocumentCount`; `getTagTree()` maps **both** counts onto each node from two aggregate queries (no N+1 — **NFR-PERF-THEMEN-01**). - New `TagRepository.findSubtreeDocumentCountsPerTag()`: one recursive-CTE tag closure (depth guard ≤50) joined to `document_tags`, `GROUP BY ancestor_id` with `COUNT(DISTINCT document_id)` (REQ-THEMEN-01/02/03/06). Direct `documentCount` is unchanged. - Corrected the stale `getTagTree()` JavaDoc + `tag/README.md`. **Frontend** - `hasAnyDocuments` keys on `subtreeDocumentCount > 0` (single field read). - `/themen` page (header, child rows, aria-labels) and the dashboard `ThemenWidget` display `subtreeDocumentCount`. A parent with 0 direct docs but populated children now shows a non-zero total. - Admin sidebar, merge preview and delete-impact guard are **unchanged** (still direct `documentCount`). ## Tests - **Real-Postgres** (`postgres:16-alpine`, Testcontainers) integration tests: leaf = direct (AC#4), shared doc counted once (AC#1+#2), full grandchild depth (AC#3), empty subtree absent (REQ-THEMEN-05), cycle terminates via the guard (REQ-THEMEN-06), and rollup == distinct documents from the real search expansion (AC#7 parity). - Service unit tests for the two-query wiring; frontend `hasAnyDocuments` tests; AC#5 component test; admin characterization tests pinning previews to the direct count (AC#8). ## Notes for the reviewer - `generated/api.ts` was **hand-edited** to match `generate:api` output (codegen needs a live dev backend); re-running it should be byte-equivalent. - Browser-mode component tests are validated on CI, not locally (project convention). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

marcel added 8 commits 2026-05-31 12:57:43 +02:00

feat(tag): add subtree document-count rollup to tag tree (#698) ... 138bf446e4

Add subtreeDocumentCount to TagTreeNodeDTO, populated by a new recursive-CTE
aggregate query that builds a tag closure and counts distinct documents per
ancestor subtree. The direct documentCount is unchanged; getTagTree now maps
both counts onto each node from two aggregate queries (no N+1).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(tag): validate subtree rollup CTE against real Postgres (#698) ... 2f1538754e

Cover AC#1-4 (leaf=direct, distinct overlap counted once, full descendant
depth), REQ-THEMEN-05 (empty subtree absent), REQ-THEMEN-06 (cycle terminates
via the 50-level guard) and AC#7 (rollup equals distinct documents found by the
real tag-search expansion — count↔destination parity). Testcontainers
postgres:16-alpine since the recursive CTE + COUNT(DISTINCT) needs real PG.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs(tag): document the dual document counts on the tag tree (#698) ... 5ea47d4ec7

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 <noreply@anthropic.com>

feat(themen): key reader tag visibility on the subtree rollup (#698) ... 16f1fe7616

Regenerate the TagTreeNodeDTO type with subtreeDocumentCount and switch
hasAnyDocuments to read it directly — the backend rollup already includes all
descendants, so the recursive children walk is no longer needed. Reader
surfaces now hide a topic only when its whole subtree is empty.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(themen): show the subtree rollup count on reader surfaces (#698) ... 29ea27319a

The /themen page (box header, child rows, aria-labels) and the dashboard
ThemenWidget now display subtreeDocumentCount instead of the direct
documentCount, so a topic's number reflects its whole sub-topic tree and
matches what /documents?tag=X actually returns. A parent with 0 direct
documents but documents under its children now shows a non-zero total.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(tag): add subtreeDocumentCount to admin tree fixtures (#698) ... 1fc74f8892

TagTreeNodeDTO now requires subtreeDocumentCount, so the admin sidebar test
fixtures (TagTreeNode, TagsListPanel) need the field to type-check. The admin
sidebar still renders the direct documentCount — these fixtures only gain the
new field, no behaviour change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(admin-tags): pin merge/delete previews to the direct count (#698) ... 6d4aa8bd5c

Characterization tests for AC#8: the merge preview and the delete-impact
warning describe direct-document operations, so they must report the tag's
direct documentCount, never a subtree rollup. Both tests pass a stray
subtreeDocumentCount and assert it does not leak into the preview, so a future
change can't silently desync a destructive-action preview.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(tag): explicitly stub the subtree rollup query in getTagTree tests (#698) ... a76999c3d4

Address review nit: the older getTagTree tests relied on Mockito's default
empty-list return for findSubtreeDocumentCountsPerTag. Stub it explicitly so
the two-query contract is self-documenting.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

marcel force-pushed worktree-feat+issue-698-themen-subtree-count from fc2c726961 to a76999c3d4 2026-05-31 12:57:43 +02:00 Compare

marcel merged commit a76999c3d4 into main 2026-05-31 12:58:10 +02:00

marcel deleted branch worktree-feat+issue-698-themen-subtree-count 2026-05-31 12:58:11 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0-critical

Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.

P1-high

Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.

P2-medium

Noticeable improvement; doesn't block anything; schedule opportunistically.

P3-later

Cosmetic or parking-lot work; fine to stay open indefinitely.

audit

Read-only audit / assessment work; produces a report rather than changing code

bug

Something isn't working

cleanup

Removal of dead code, vague comments, naming violations, and scratch artifacts

collaboration

We want to extend the family archive to have more collaboration tools

conversation

descoped

We will do that later

devops

documentation

README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs

epic

Marker for epic-level issues that group multiple child issues

feature

file-upload

legibility

Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction

needs-discussion

Has an open decision or design question that must be resolved before implementation can start.

notification

person

phase-1: security

Security hygiene — must be done first

phase-2: container-images

Production-ready multi-stage Docker images

phase-3: prod-compose

Production compose overlay + Caddy reverse proxy

phase-4: spring-prod-profile

Spring Boot production configuration profile

phase-5: backups

Database and object storage backup strategy

phase-6: deployment-docs

.env.example, DEPLOYMENT.md, runbook

phase-7: monitoring

Prometheus, Loki, Grafana, Alertmanager

refactor

Code restructuring without behaviour change

security

test

ui

UI/UX and accessibility issues

user

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

Jens marcel

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#701