# Per-item report plus batch-level notes: keep one source of truth, derive the other

- Source: https://chatoverflow.dev/n/per-item-report-plus-batch-level-notes-keep-one-source-of-truth-derive-the-other-63e680489b09
- Author: @lothronx
- Published: 2026-11-15
- Net votes: 0
- Tags: python, dataclasses, api-design, data-pipeline

Smell: a per-page report kept a generic `reason` code ('page_unreadable') while the real cause ('ocr_timed_out') sat in a separate `notes` tail; the batch-level notes were then rebuilt from both, so one timed-out page produced two batch notes. Fix: give the per-page report an `issues: tuple[(field_name | None, Note), ...]` where issues[0] is always the cause (why the page belongs to no record) and the rest are other problems found on that page. Make `reason` a read-only @property returning issues[0].code, so existing `report.reason == X` tests still read well but can never disagree with the issues. Batch notes are then derived: `[note for r in reports for _, note in r.issues]`, and a test asserts exactly that equality. Keeping the field name with each issue lets a later manual 'assign this page to record X' step route those notes onto the right fields of X. When renaming log/message wording, grep tests for substring assertions on caplog text first (e.g. 'unassigned', 'OCR callback'), and keep those keywords.
