00a00b2c87
Records the architectural commitment for the timeline domain: views-not- entities for issue 3 (ADR-036 rationale), DatePrecision import coupling (ADR-025), the UNKNOWN-forbidden / SEASON-APPROX-legal precision contract, the strict biconditional RANGE CHECK as a deliberate divergence from Document, the @Version + NOT NULL audit-trail decisions, the optimistic- lock-to-conflict translation contract (CWE-209), the server-populated-only createdBy/updatedBy forgery guard (CWE-639), and the EventType stable frontend styling contract. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
113 lines
6.5 KiB
Markdown
113 lines
6.5 KiB
Markdown
# ADR-040 — Timeline domain data model
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-06-12
|
|
**Issue:** #774 (Zeitstrahl milestone, foundational)
|
|
|
|
## Context
|
|
|
|
The Zeitstrahl (family timeline) needs a home for *curated* events — births,
|
|
weddings, moves, and world-historical context a curator types in by hand, distinct
|
|
from the OCR-derived `Document` letters. This ADR commits the new `timeline` domain's
|
|
data model: the `TimelineEvent` entity, the `EventType` enum, a repository, and the
|
|
V77 migration. No service, controller, or DTO ships here — those land in later issues.
|
|
|
|
A `TimelineEvent` carries the same date block as `Document` (`eventDate` +
|
|
`precision` + `eventDateEnd`) so events and letters render through one path, but its
|
|
audit footprint deliberately diverges (see below).
|
|
|
|
## Decisions
|
|
|
|
### 1. New `timeline` domain package, separate from `geschichte`
|
|
|
|
Curated timeline events are their own concern, not a Lesereise/`Geschichte` subtype.
|
|
The domain owns `TimelineEvent`, `EventType`, and `TimelineEventRepository`.
|
|
|
|
### 2. Responses (issue 3) will be views, not serialized entities
|
|
|
|
`TimelineEvent` has two LAZY `ManyToMany` collections (`persons`, `documents`) and
|
|
`open-in-view` is `false` — exactly the shape that motivated ADR-036 for `geschichte`.
|
|
Issue 3 must assemble `TimelineEventView`/`TimelineEventSummary` inside the service
|
|
transaction; a serialized entity is a 500 waiting to happen. Decided up front so it is
|
|
not retrofitted later.
|
|
|
|
### 3. `precision` reuses `document.DatePrecision` — imported, not duplicated
|
|
|
|
The `timeline` package imports `org.raddatz.familienarchiv.document.DatePrecision`
|
|
directly, the same cross-domain value-type sharing ADR-039 established for `person`.
|
|
An enum has no behaviour and no persistence side effects, so the layering rule
|
|
(services → own repository) does not govern it. The enum stays a verbatim mirror of the
|
|
import normalizer's `Precision` values (ADR-025); changes must stay in sync with
|
|
`tools/import-normalizer/dates.py`. Moving `DatePrecision` into a shared package is a
|
|
wider refactor (touching `Document`, `importing`, `person`) and its own future ADR.
|
|
|
|
### 4. `precision = UNKNOWN` is forbidden; every other value is legal
|
|
|
|
`eventDate` is NOT NULL — a curated event always has at least a year, so only OCR letters
|
|
fall into the "Ohne Datum" bucket. The CHECK `chk_timeline_event_precision`
|
|
(`date_precision <> 'UNKNOWN'`) forbids exactly that one value. `SEASON` ("Sommer 1914")
|
|
and `APPROX` ("ca. 1914") are explicitly legal — family memory is full of both, and the
|
|
spec's rendering table covers them. Do not narrow the CHECK to an allow-list; an
|
|
over-tight constraint would force curators to fake `YEAR` and render dishonest dates.
|
|
|
|
### 5. RANGE invariant is a strict biconditional at the DB, intentionally tighter than `Document`
|
|
|
|
`chk_timeline_event_range` enforces `(date_precision = 'RANGE') = (event_date_end IS NOT
|
|
NULL)` — `eventDateEnd` is non-null **iff** precision is `RANGE`, both directions. This is
|
|
*stricter* than `Document`'s open-ended ranges (which allow a null end on a RANGE) because a
|
|
curated event always has a known, closed end when it spans a range — it is authored, not
|
|
inferred. This divergence is deliberate: a future "bug fix" must not relax it to match
|
|
`Document`.
|
|
|
|
### 6. Audit trail: `@Version` + NOT NULL `createdBy`/`updatedBy`, diverging from `Document`
|
|
|
|
`Document` has neither a version nor a creator. A curated entity edited by multiple curators
|
|
warrants real protection, so `TimelineEvent` adds:
|
|
|
|
- `@Version Long version` — optimistic locking for the multi-curator edit flow (issue 3).
|
|
Object `Long` (not primitive) so it is `null` before first persist; Hibernate sets `0` on
|
|
insert. The service **must** catch `ObjectOptimisticLockingFailureException` and translate
|
|
it to `DomainException.conflict(...)`. Without that translation a concurrent-write conflict
|
|
surfaces as HTTP 500 with Hibernate internals in the body — information disclosure (CWE-209).
|
|
- `createdBy`/`updatedBy` as bare `UUID`, `NOT NULL`, no FK to `app_users` (sidecar pattern,
|
|
matching `DocumentAnnotation`/`OcrJob`; keeps `timeline` decoupled from `user`, avoids
|
|
lazy-load surprises in the read-heavy assembly path). NOT NULL makes a curated event with no
|
|
author impossible — an audit gap closed at the schema level. `DocumentAnnotation.createdBy`
|
|
is nullable and has no `updatedBy`; the escalation here is deliberate because curated events
|
|
are multi-author. Curator display names resolve through `UserService` at render time.
|
|
|
|
`updatedBy` is **not** advanced by `@UpdateTimestamp` — the service must set it from the
|
|
session principal before every `save()`, or the timestamp moves while the "who" goes stale.
|
|
|
|
### 7. `createdBy`/`updatedBy` are server-populated only — never bound from client input
|
|
|
|
Both are set from the session principal in the service, never from a request body. Binding
|
|
them from client input is an authorship-forgery / mass-assignment vector (CWE-639). Issue 3's
|
|
regression suite must include forgery cases on **both** write paths (`POST` body with
|
|
`createdBy`, `PUT` body with `updatedBy`) — create and update are separate binding paths, so
|
|
testing only one leaves half the vector open. The update test must assert `updatedBy` equals
|
|
the *second* editor's UUID, not merely non-null.
|
|
|
|
### 8. `EventType` string values are a stable frontend styling contract
|
|
|
|
The Tailwind class map in the timeline Svelte components hard-codes `PERSONAL` (family accent)
|
|
and `HISTORICAL` (muted world accent) as strings. There is no mapping layer — renaming either
|
|
value requires a coordinated frontend change. Recorded here to prevent a silent regression.
|
|
|
|
### 9. Explicit `@JoinTable` on both ManyToMany fields
|
|
|
|
Without explicit `@JoinTable(name, joinColumns, inverseJoinColumns)`, Hibernate's naming
|
|
strategy could diverge from the V77 DDL's explicit table/column names. Explicit mapping
|
|
guarantees alignment and makes future column renames a deliberate, visible change. All four FK
|
|
columns are `ON DELETE CASCADE`: deleting a Person or Document drops the join row and leaves
|
|
the event intact (V71/ADR-032 hardening — a person delete must never 500).
|
|
|
|
## Consequences
|
|
|
|
- V77 is forward-only; rollback is manual DDL (`DROP TABLE` the two join tables, then
|
|
`timeline_events`). No rollback script, no rollback test.
|
|
- The `timeline → document.DatePrecision` compile coupling is permanent until a shared-package
|
|
refactor; precedent already exists (`importing/DocumentImporter`, `person`).
|
|
- The service/controller/DTO layer (issue 3) inherits the view-assembly, optimistic-lock
|
|
translation, forgery-guard, and permission obligations recorded above.
|