From eca9f28f7eaa1b0e9d641a7d86f6ac216173b1cb Mon Sep 17 00:00:00 2001 From: Marcel Date: Tue, 5 May 2026 23:21:42 +0200 Subject: [PATCH] docs(legibility): fix four more signature/accuracy blockers in domain READMEs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - notification: remove phantom NotificationPreferenceRepository entity; fix notifyReply signature (DocumentComment + Set, not parentComment/reply) - tag: correct delete(UUID) description — TagService.delete() is called BY DocumentService.deleteTagCascading(), not the other way around - person: fix findOrCreateByAlias to single-String signature; type classification is internal to PersonTypeClassifier - dashboard: replace fabricated cross-domain calls with verified ones (removed NotificationService + GeschichteService; added TranscriptionService, UserService, CommentService per actual DashboardService imports) Co-Authored-By: Claude Sonnet 4.6 --- .../org/raddatz/familienarchiv/dashboard/README.md | 12 +++++++----- .../raddatz/familienarchiv/notification/README.md | 8 ++++---- .../java/org/raddatz/familienarchiv/person/README.md | 2 +- .../java/org/raddatz/familienarchiv/tag/README.md | 2 +- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/backend/src/main/java/org/raddatz/familienarchiv/dashboard/README.md b/backend/src/main/java/org/raddatz/familienarchiv/dashboard/README.md index 6e1c53ea..952ceb42 100644 --- a/backend/src/main/java/org/raddatz/familienarchiv/dashboard/README.md +++ b/backend/src/main/java/org/raddatz/familienarchiv/dashboard/README.md @@ -26,11 +26,13 @@ None of the underlying data — it reads from `document/`, `person/`, `audit/`, ## Cross-domain dependencies -- `DocumentService.count()` / `findWeeklyStats()` / `findReadyToReadQueue()` / `findSegmentationQueue()` — document metrics -- `PersonService.count()` / `findAll()` / `findAllFamilyMembers()` — person metrics -- `AuditLogQueryService.findRecentActivity()` — activity feed events -- `NotificationService.getNotifications()` — per-user notifications for the activity feed -- `GeschichteService.list()` / `count()` — story metrics +- `DocumentService.count()` — total document count (StatsService) +- `DocumentService.getDocumentById(UUID)` / `getDocumentsByIds(List)` — document enrichment for activity feed (DashboardService) +- `PersonService.count()` — total person count (StatsService) +- `TranscriptionService.listBlocks(UUID)` — transcription block lookup for resume widget (DashboardService) +- `UserService.getById(UUID)` — actor name resolution in activity feed (DashboardService) +- `CommentService.findAnnotationIdsByIds(...)` — annotation context lookup for activity feed (DashboardService) +- `AuditLogQueryService.findMostRecentDocumentForUser()` / `getPulseStats()` / `findActivityFeed()` — audit-sourced feed rows (DashboardService) ## Frontend counterpart diff --git a/backend/src/main/java/org/raddatz/familienarchiv/notification/README.md b/backend/src/main/java/org/raddatz/familienarchiv/notification/README.md index 840d6a61..5694df58 100644 --- a/backend/src/main/java/org/raddatz/familienarchiv/notification/README.md +++ b/backend/src/main/java/org/raddatz/familienarchiv/notification/README.md @@ -4,8 +4,8 @@ In-app messages delivered in real time via SSE and persisted in the bell-icon dr ## What this domain owns -Entity: `Notification`, `NotificationPreference`. -Features: create and deliver notifications, unread count, mark-read, SSE real-time push, per-user delivery preferences. +Entity: `Notification`. +Features: create and deliver notifications, unread count, mark-read, SSE real-time push, per-user delivery preferences (stored as fields on `AppUser`, managed by `user/`). ## What this domain does NOT own @@ -17,7 +17,7 @@ Features: create and deliver notifications, unread count, mark-read, SSE real-ti | Method | Consumer | Purpose | |---|---|---| | `notifyMentions(mentionedUserIds, comment)` | document (comment) | Push mention notifications when a comment contains @mentions | -| `notifyReply(parentComment, reply)` | document (comment) | Push reply notification to the thread author | +| `notifyReply(reply, participantIds)` | document (comment) | Push reply notification to all thread participants | | `countUnread(userId)` | user session | Unread badge count in the nav bar | | `getNotifications(userId)` | dashboard / activity | Notification list for bell dropdown | | `markRead(id)` / `markAllRead(userId)` | notification controller | User-driven read-state updates | @@ -29,7 +29,7 @@ Features: create and deliver notifications, unread count, mark-read, SSE real-ti - `NotificationService` — create, query, mark-read - `SseEmitterRegistry` — runtime-stateful component that keeps one `SseEmitter` per connected user. On `notifyMentions()` / `notifyReply()`, the service writes to `SseEmitterRegistry` to push real-time events. SSE connections go **backend → browser directly**, not via the SvelteKit SSR layer. - `NotificationRepository` — persisted notification rows -- `NotificationPreferenceRepository` — per-user preference rows +- `NotificationPreferenceDTO` — read/write DTO for preference endpoints (prefs stored on `AppUser`) ## Cross-domain dependencies diff --git a/backend/src/main/java/org/raddatz/familienarchiv/person/README.md b/backend/src/main/java/org/raddatz/familienarchiv/person/README.md index 58b22207..2e9098bd 100644 --- a/backend/src/main/java/org/raddatz/familienarchiv/person/README.md +++ b/backend/src/main/java/org/raddatz/familienarchiv/person/README.md @@ -21,7 +21,7 @@ Features: person CRUD, name alias management, person merge (deduplication), fami | `getAllById(List)` | document | Bulk fetch for sender/receiver resolution | | `findAll()` | document, dashboard | List all persons | | `findByName(String)` | document | Typeahead search | -| `findOrCreateByAlias(String, PersonType)` | importing | Idempotent create during mass import | +| `findOrCreateByAlias(String rawName)` | importing | Idempotent create during mass import; type classification happens internally | | `findAllFamilyMembers()` | dashboard | Family member list for stats | | `findCorrespondents()` | document | Correspondent list for conversation filter | | `count()` | dashboard | Total person count for stats | 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 d12643d2..4f34833e 100644 --- a/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md +++ b/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md @@ -16,7 +16,7 @@ Features: tag CRUD, hierarchical deletion (cascade to descendants), tag typeahea | Method | Consumer | Purpose | |---|---|---| -| `delete(UUID)` | document | Remove a tag; triggers `DocumentService.deleteTagCascading()` first | +| `delete(UUID)` | document | Remove the tag record; called by `DocumentService.deleteTagCascading()` after all document references are unlinked | | `deleteWithDescendants(UUID)` | admin tag UI | Recursive subtree deletion | | `expandTagNamesToDescendantIdSets(List)` | document | Expand tag filter to include descendant tags |